IActionBars


1   /*******************************************************************************
2    * Copyright (c) 2000, 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;
12  
13  import org.eclipse.jface.action.IAction;
14  import org.eclipse.jface.action.IMenuManager;
15  import org.eclipse.jface.action.IStatusLineManager;
16  import org.eclipse.jface.action.IToolBarManager;
17  import org.eclipse.ui.services.IServiceLocator;
18  
19  /**
20   * Used by a part to access its menu, toolbar, and status line managers.  
21   * <p>
22   * Within the workbench each part, editor or view, has a private set of action
23   * bars.  This set, which contains a menu, toolbar, and status line, appears
24   * in the local toolbar for a view and in the window for an editor.  The view
25   * may provide an implementation for pre-existing actions or add new actions to
26   * the action bars.
27   * </p><p>
28   * In a workbench window there are a number of actions which are applicable to
29   * all parts.  Some common examples are <code>CUT</code>, <code>COPY</code> and 
30   * <code>PASTE</code>. These actions, known as "global actions", are contributed to 
31   * the workbench window by the window itself and shared by all parts.  The
32   * presentation is owned by the window.  The implementation is delegated to the
33   * active part.  
34   * </p><p>
35   * To participate in the global action design an <code>IWorkbenchPart</code> should 
36   * register a handler for each global action which is implemented by the part.  This 
37   * can be done by calling <code>setGlobalActionHandler</code>.  For convenience, the 
38   * standard global actions are defined in 
39   * <code>org.eclipse.ui.IWorkbenchActionConstants</code>. 
40   * </p><p>
41   * Additional work is required for the <code>Delete</code> global action.  In
42   * this case the accelerator is defined in the menu item text but is not hooked 
43   * on the window.  This is to support text editors where the <code>Delete</code> 
44   * key is functional even when the <code>Delete</code> action is disabled (no text 
45   * is selected).  An implementation for this accelerator must be defined locally, 
46   * in each part, by listening for <code>Delete</code> key events.
47   * </p><p>
48   * A part may also contribute new actions to the action bars as required.  To do
49   * this, call <code>getMenuManager</code>, <code>getToolBarManager</code>, or
50   * <code>getStatusLineManager</code> as appropriate to get the action target.
51   * Add the action(s) to the target and call <code>update</code> to commit
52   * any changes to the underlying widgets.
53   * </p><p>
54   * This interface is not intended to be implemented by clients.
55   * </p>
56   */
57  public interface IActionBars {
58      /**
59       * Clears the global action handler list.
60       * <p>
61       * Note: Clients who manipulate the global action list are
62       * responsible for calling <code>updateActionBars</code> so that the changes
63       * can be propagated throughout the workbench.
64       * </p>
65       */
66      public void clearGlobalActionHandlers();
67  
68      /**
69       * Returns the global action handler for the action with the given id.  
70       *
71       * @param actionId an action id declared in the registry
72       * @return an action handler which implements the action id, or
73       *   <code>null</code> if none is registered
74       * @see IWorkbenchActionConstants
75       * @see #setGlobalActionHandler(String, IAction)
76       */
77      public IAction getGlobalActionHandler(String   actionId);
78  
79      /**
80       * Returns the menu manager.
81       * <p>
82       * Note: Clients who add or remove items from the returned menu manager are
83       * responsible for calling <code>updateActionBars</code> so that the changes
84       * can be propagated throughout the workbench.
85       * </p>
86       *
87       * @return the menu manager
88       */
89      public IMenuManager getMenuManager();
90      
91      /**
92       * Returns the service locator for these action bars. The locator is found
93       * by looking locally, and then ascending the action bar hierarchy.
94       * 
95       * @return The service locator; never <code>null</code>.
96       * @since 3.2
97       */
98      public IServiceLocator getServiceLocator();
99  
100     /**
101      * Returns the status line manager.
102      * <p>
103      * Note: Clients who add or remove items from the returned status line
104      * manager are responsible for calling <code>updateActionBars</code> so
105      * that the changes can be propagated throughout the workbench.
106      * </p>
107      * 
108      * @return the status line manager
109      */
110     public IStatusLineManager getStatusLineManager();
111 
112     /**
113      * Returns the tool bar manager.
114      * <p>
115      * Note: Clients who add or remove items from the returned tool bar manager are
116      * responsible for calling <code>updateActionBars</code> so that the changes
117      * can be propagated throughout the workbench.
118      * </p>
119      *
120      * @return the tool bar manager
121      */
122     public IToolBarManager getToolBarManager();
123 
124     /**
125      * Sets the global action handler for the action with the given id.
126      * <p>
127      * Note: Clients who manipulate the global action list are
128      * responsible for calling <code>updateActionBars</code> so that the changes
129      * can be propagated throughout the workbench.
130      * </p>
131      *
132      * @param actionId an action id declared in the registry
133      * @param handler an action which implements the action id, or
134      *  <code>null</code> to clear any existing handler
135      * @see IWorkbenchActionConstants
136      */
137     public void setGlobalActionHandler(String   actionId, IAction handler);
138 
139     /**
140      * Updates the action bars.
141      * <p>
142      * Clients who add or remove items from the menu, tool bar, or status line
143      * managers should call this method to propagated the changes throughout 
144      * the workbench.
145      * </p>
146      */
147     public void updateActionBars();
148 }
149
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags