001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui;
011:
012: import org.eclipse.jface.action.IAction;
013: import org.eclipse.jface.action.IMenuManager;
014: import org.eclipse.jface.action.IStatusLineManager;
015: import org.eclipse.jface.action.IToolBarManager;
016: import org.eclipse.ui.services.IServiceLocator;
017:
018: /**
019: * Used by a part to access its menu, toolbar, and status line managers.
020: * <p>
021: * Within the workbench each part, editor or view, has a private set of action
022: * bars. This set, which contains a menu, toolbar, and status line, appears
023: * in the local toolbar for a view and in the window for an editor. The view
024: * may provide an implementation for pre-existing actions or add new actions to
025: * the action bars.
026: * </p><p>
027: * In a workbench window there are a number of actions which are applicable to
028: * all parts. Some common examples are <code>CUT</code>, <code>COPY</code> and
029: * <code>PASTE</code>. These actions, known as "global actions", are contributed to
030: * the workbench window by the window itself and shared by all parts. The
031: * presentation is owned by the window. The implementation is delegated to the
032: * active part.
033: * </p><p>
034: * To participate in the global action design an <code>IWorkbenchPart</code> should
035: * register a handler for each global action which is implemented by the part. This
036: * can be done by calling <code>setGlobalActionHandler</code>. For convenience, the
037: * standard global actions are defined in
038: * <code>org.eclipse.ui.IWorkbenchActionConstants</code>.
039: * </p><p>
040: * Additional work is required for the <code>Delete</code> global action. In
041: * this case the accelerator is defined in the menu item text but is not hooked
042: * on the window. This is to support text editors where the <code>Delete</code>
043: * key is functional even when the <code>Delete</code> action is disabled (no text
044: * is selected). An implementation for this accelerator must be defined locally,
045: * in each part, by listening for <code>Delete</code> key events.
046: * </p><p>
047: * A part may also contribute new actions to the action bars as required. To do
048: * this, call <code>getMenuManager</code>, <code>getToolBarManager</code>, or
049: * <code>getStatusLineManager</code> as appropriate to get the action target.
050: * Add the action(s) to the target and call <code>update</code> to commit
051: * any changes to the underlying widgets.
052: * </p><p>
053: * This interface is not intended to be implemented by clients.
054: * </p>
055: */
056: public interface IActionBars {
057: /**
058: * Clears the global action handler list.
059: * <p>
060: * Note: Clients who manipulate the global action list are
061: * responsible for calling <code>updateActionBars</code> so that the changes
062: * can be propagated throughout the workbench.
063: * </p>
064: */
065: public void clearGlobalActionHandlers();
066:
067: /**
068: * Returns the global action handler for the action with the given id.
069: *
070: * @param actionId an action id declared in the registry
071: * @return an action handler which implements the action id, or
072: * <code>null</code> if none is registered
073: * @see IWorkbenchActionConstants
074: * @see #setGlobalActionHandler(String, IAction)
075: */
076: public IAction getGlobalActionHandler(String actionId);
077:
078: /**
079: * Returns the menu manager.
080: * <p>
081: * Note: Clients who add or remove items from the returned menu manager are
082: * responsible for calling <code>updateActionBars</code> so that the changes
083: * can be propagated throughout the workbench.
084: * </p>
085: *
086: * @return the menu manager
087: */
088: public IMenuManager getMenuManager();
089:
090: /**
091: * Returns the service locator for these action bars. The locator is found
092: * by looking locally, and then ascending the action bar hierarchy.
093: *
094: * @return The service locator; never <code>null</code>.
095: * @since 3.2
096: */
097: public IServiceLocator getServiceLocator();
098:
099: /**
100: * Returns the status line manager.
101: * <p>
102: * Note: Clients who add or remove items from the returned status line
103: * manager are responsible for calling <code>updateActionBars</code> so
104: * that the changes can be propagated throughout the workbench.
105: * </p>
106: *
107: * @return the status line manager
108: */
109: public IStatusLineManager getStatusLineManager();
110:
111: /**
112: * Returns the tool bar manager.
113: * <p>
114: * Note: Clients who add or remove items from the returned tool bar manager are
115: * responsible for calling <code>updateActionBars</code> so that the changes
116: * can be propagated throughout the workbench.
117: * </p>
118: *
119: * @return the tool bar manager
120: */
121: public IToolBarManager getToolBarManager();
122:
123: /**
124: * Sets the global action handler for the action with the given id.
125: * <p>
126: * Note: Clients who manipulate the global action list are
127: * responsible for calling <code>updateActionBars</code> so that the changes
128: * can be propagated throughout the workbench.
129: * </p>
130: *
131: * @param actionId an action id declared in the registry
132: * @param handler an action which implements the action id, or
133: * <code>null</code> to clear any existing handler
134: * @see IWorkbenchActionConstants
135: */
136: public void setGlobalActionHandler(String actionId, IAction handler);
137:
138: /**
139: * Updates the action bars.
140: * <p>
141: * Clients who add or remove items from the menu, tool bar, or status line
142: * managers should call this method to propagated the changes throughout
143: * the workbench.
144: * </p>
145: */
146: public void updateActionBars();
147: }
|