ActionBarAdvisor


1   /*******************************************************************************
2    * Copyright (c) 2005, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui.application;
12  
13  import java.util.HashMap  ;
14  import java.util.Iterator  ;
15  import java.util.Map  ;
16  
17  import org.eclipse.core.runtime.Assert;
18  import org.eclipse.core.runtime.IStatus;
19  import org.eclipse.core.runtime.Status;
20  import org.eclipse.jface.action.IAction;
21  import org.eclipse.jface.action.ICoolBarManager;
22  import org.eclipse.jface.action.IMenuManager;
23  import org.eclipse.jface.action.IStatusLineManager;
24  import org.eclipse.ui.IMemento;
25  import org.eclipse.ui.IWorkbenchWindow;
26  import org.eclipse.ui.PlatformUI;
27  import org.eclipse.ui.actions.ActionFactory;
28  
29  /**
30   * Public base class for configuring the action bars of a workbench window.
31   * <p>
32   * An application should declare a subclass of <code>ActionBarAdvisor</code>
33   * and override methods to configure a window's action bars to suit the needs of the
34   * particular application.
35   * </p>
36   * <p>
37   * The following advisor methods are called at strategic points in the
38   * workbench's lifecycle (all occur within the dynamic scope of the call
39   * to {@link PlatformUI#createAndRunWorkbench PlatformUI.createAndRunWorkbench}):
40   * <ul>
41   * <li><code>fillActionBars</code> - called after <code>WorkbenchWindowAdvisor.preWindowOpen</code>
42   * to configure a window's action bars</li>
43   * </ul>
44   * </p>
45   * 
46   * @see WorkbenchWindowAdvisor#createActionBarAdvisor(IActionBarConfigurer)
47   * 
48   * @since 3.1
49   */
50  public class ActionBarAdvisor {
51  
52      /**
53       * Bit flag for {@link #fillActionBars fillActionBars} indicating that the
54       * operation is not filling the action bars of an actual workbench window,
55       * but rather a proxy (used for perspective customization).
56       */
57      public static final int FILL_PROXY = 0x01;
58  
59      /**
60       * Bit flag for {@link #fillActionBars fillActionBars} indicating that the
61       * operation is supposed to fill (or describe) the workbench window's menu
62       * bar.
63       */
64      public static final int FILL_MENU_BAR = 0x02;
65  
66      /**
67       * Bit flag for {@link #fillActionBars fillActionBars} indicating that the
68       * operation is supposed to fill (or describe) the workbench window's cool
69       * bar.
70       */
71      public static final int FILL_COOL_BAR = 0x04;
72  
73      /**
74       * Bit flag for {@link #fillActionBars fillActionBars} indicating that the
75       * operation is supposed to fill (or describe) the workbench window's status
76       * line.
77       */
78      public static final int FILL_STATUS_LINE = 0x08;
79  
80      
81      private IActionBarConfigurer actionBarConfigurer;
82      
83      private Map   actions = new HashMap  ();
84      
85      /**
86       * Creates a new action bar advisor to configure a workbench
87       * window's action bars via the given action bar configurer.
88       * 
89       * @param configurer the action bar configurer
90       */
91      public ActionBarAdvisor(IActionBarConfigurer configurer) {
92          Assert.isNotNull(configurer);
93          actionBarConfigurer = configurer;
94      }
95      
96      /**
97       * Returns the action bar configurer.
98       * 
99       * @return the action bar configurer
100      */
101     protected IActionBarConfigurer getActionBarConfigurer() {
102         return actionBarConfigurer;
103     }
104 
105     /**
106      * Configures the action bars using the given action bar configurer.
107      * Under normal circumstances, <code>flags</code> does not include
108      * <code>FILL_PROXY</code>, meaning this is a request to fill the action
109      * bars of the corresponding workbench window; the
110      * remaining flags indicate which combination of
111      * the menu bar (<code>FILL_MENU_BAR</code>),
112      * the tool bar (<code>FILL_COOL_BAR</code>),
113      * and the status line (<code>FILL_STATUS_LINE</code>) are to be filled.
114      * <p>
115      * If <code>flags</code> does include <code>FILL_PROXY</code>, then this
116      * is a request to describe the actions bars of the given workbench window
117      * (which will already have been filled);
118      * again, the remaining flags indicate which combination of the menu bar,
119      * the tool bar, and the status line are to be described.
120      * The actions included in the proxy action bars can be the same instances
121      * as in the actual window's action bars. Calling <code>ActionFactory</code>
122      * to create new action instances is not recommended, because these
123      * actions internally register listeners with the window and there is no
124      * opportunity to dispose of these actions.
125      * </p>
126      * <p>
127      * This method is called just after {@link WorkbenchWindowAdvisor#preWindowOpen()}.
128      * Clients must not call this method directly (although super calls are okay).
129      * The default implementation calls <code>makeActions</code> if
130      * <code>FILL_PROXY</code> is specified, then calls <code>fillMenuBar</code>, 
131      * <code>fillCoolBar</code>, and <code>fillStatusLine</code>
132      * if the corresponding flags are specified.
133      * </p>
134      * <p> 
135      * Subclasses may override, but it is recommended that they override the
136      * methods mentioned above instead.
137      * </p>
138      * 
139      * @param flags bit mask composed from the constants
140      * {@link #FILL_MENU_BAR FILL_MENU_BAR},
141      * {@link #FILL_COOL_BAR FILL_COOL_BAR},
142      * {@link #FILL_STATUS_LINE FILL_STATUS_LINE},
143      * and {@link #FILL_PROXY FILL_PROXY}
144      */
145     public void fillActionBars(int flags) {
146         if ((flags & FILL_PROXY) == 0) {
147             makeActions(actionBarConfigurer.getWindowConfigurer().getWindow());
148         }
149         if ((flags & FILL_MENU_BAR) != 0) {
150             fillMenuBar(actionBarConfigurer.getMenuManager());
151         }
152         if ((flags & FILL_COOL_BAR) != 0) {
153             fillCoolBar(actionBarConfigurer.getCoolBarManager());
154         }
155         if ((flags & FILL_STATUS_LINE) != 0) {
156             fillStatusLine(actionBarConfigurer.getStatusLineManager());
157         }
158     }
159         
160     /**
161      * Instantiates the actions used in the fill methods.
162      * Use {@link #register(IAction)} to register the action with the key binding service
163      * and add it to the list of actions to be disposed when the window is closed.
164      * 
165      * @param window the window containing the action bars
166      */
167     protected void makeActions(IWorkbenchWindow window) {
168         // do nothing
169     }
170 
171     /**
172      * Registers the given action with the key binding service 
173      * (by calling {@link IActionBarConfigurer#registerGlobalAction(IAction)}),
174      * and adds it to the list of actions to be disposed when the window is closed.
175      * <p>
176      * In order to participate in key bindings, the action must have an action
177      * definition id (aka command id), and a corresponding command extension.
178      * See the <code>org.eclipse.ui.commands</code> extension point documentation
179      * for more details. 
180      * </p>
181      * 
182      * @param action the action to register
183      * 
184      * @see IAction#setActionDefinitionId(String)
185      * @see #disposeAction(IAction)
186      */
187     protected void register(IAction action) {
188         String   id = action.getId();
189         Assert.isNotNull(id, "Action must not have null id"); //$NON-NLS-1$
190         getActionBarConfigurer().registerGlobalAction(action);
191         actions.put(id, action);
192     }
193     
194     /**
195      * Returns the action with the given id, or <code>null</code> if not found.
196      * 
197      * @param id the action id
198      * @return the action with the given id, or <code>null</code> if not found
199      * @see IAction#getId()
200      */
201     protected IAction getAction(String   id) {
202         return (IAction) actions.get(id);
203     }
204     
205     /**
206      * Fills the menu bar with the main menus for the window.
207      * <p>
208      * The default implementation does nothing.
209      * Subclasses may override.
210      * </p>
211      * 
212      * @param menuBar the menu manager for the menu bar
213      */
214     protected void fillMenuBar(IMenuManager menuBar) {
215         // do nothing
216     }
217     
218     /**
219      * Fills the cool bar with the main toolbars for the window.
220      * <p>
221      * The default implementation does nothing.
222      * Subclasses may override.
223      * </p>
224      * 
225      * @param coolBar the cool bar manager
226      */
227     protected void fillCoolBar(ICoolBarManager coolBar) {
228         // do nothing
229     }
230     
231     /**
232      * Fills the status line with the main status line contributions 
233      * for the window.
234      * <p>
235      * The default implementation does nothing.
236      * Subclasses may override.
237      * </p>
238      * 
239      * @param statusLine the status line manager
240      */
241     protected void fillStatusLine(IStatusLineManager statusLine) {
242         // do nothing
243     }    
244 
245     /**
246      * Returns whether the menu with the given id is an application menu of the
247      * given window. This is used during OLE "in place" editing.  Application
248      * menus should be preserved during menu merging. All other menus may be
249      * removed from the window.
250      * <p>
251      * The default implementation returns false. Subclasses may override.
252      * </p>
253      * 
254      * @param menuId the menu id
255      * @return <code>true</code> for application menus, and <code>false</code>
256      * for part-specific menus
257      */
258     public boolean isApplicationMenu(String   menuId) {
259         // default: not an application menu
260         return false;
261     }
262 
263     /**
264      * Disposes this action bar advisor.
265      * Called when the window is being closed.
266      * This should dispose any allocated resources and remove any added listeners.
267      * <p>
268      * The default implementation calls <code>disposeActions()</code>.
269      * Subclasses may extend.
270      * </p>
271      */
272     public void dispose() {
273         disposeActions();
274     }
275     
276     /**
277      * Disposes all actions added via <code>register(IAction)</code>
278      * using <code>disposeAction(IAction)</code>.
279      */
280     protected void disposeActions() {
281         for (Iterator   i = actions.values().iterator(); i.hasNext();) {
282             IAction action = (IAction) i.next();
283             disposeAction(action);
284         }
285         actions.clear();
286     }
287     
288     /**
289      * Disposes the given action.
290      * <p>
291      * The default implementation checks whether the action is an instance
292      * of <code>ActionFactory.IWorkbenchAction</code> and calls its 
293      * <code>dispose()</code> method if so.
294      * Subclasses may extend.
295      * </p>
296      * 
297      * @param action the action to dispose
298      */
299     protected void disposeAction(IAction action) {
300         if (action instanceof ActionFactory.IWorkbenchAction) {
301             ((ActionFactory.IWorkbenchAction) action).dispose();
302         }
303     }
304     
305     /**
306      * Saves arbitrary application-specific state information
307      * for this action bar advisor.
308      * <p>
309      * The default implementation simply returns an OK status.
310      * Subclasses may extend or override.
311      * </p>
312      * 
313      * @param memento the memento in which to save the advisor's state
314      * @return a status object indicating whether the save was successful
315      * @since 3.1
316      */
317     public IStatus saveState(IMemento memento) {
318         return Status.OK_STATUS;
319     }
320     
321     /**
322      * Restores arbitrary application-specific state information
323      * for this action bar advisor.
324      * <p>
325      * The default implementation simply returns an OK status.
326      * Subclasses may extend or override.
327      * </p>
328      * 
329      * @param memento the memento from which to restore the advisor's state
330      * @return a status object indicating whether the restore was successful
331      * @since 3.1
332      */
333     public IStatus restoreState(IMemento memento) {
334         return Status.OK_STATUS;
335     }
336 
337 }
338
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags