KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > 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 JavaDoc 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 JavaDoc 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
Popular Tags