001: /*******************************************************************************
002: * Copyright (c) 2003, 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.navigator;
011:
012: import org.eclipse.ui.IActionBars;
013: import org.eclipse.ui.IMemento;
014: import org.eclipse.ui.actions.ActionGroup;
015:
016: /**
017: * <p>
018: * Provides actions from extensions for menu and
019: * {@link org.eclipse.ui.IActionBars} contributions.
020: * </p>
021: * <p>
022: * This abstract class should be extended by clients of the
023: * <b>org.eclipse.ui.navigator.navigatorContent</b> extension point for
024: * top-level and nested <b>actionProvider </b> elements.
025: * </p>
026: * <p>
027: * {@link CommonActionProvider}s may be declared as top-level elements in the
028: * extension point (e.g. an <b>actionProvider</b> element at the root of the
029: * extension point). Alternatively, <b>actionProvider</b> elements may be
030: * nested under a <b>navigatorContent</b> element, in which case they are
031: * considered to be "associated" with that content extension. For more
032: * information, see the <b>org.eclipse.ui.navigator.navigatorContent</b>
033: * extension point.
034: * </p>
035: * <p>
036: * Each action provider will have the opportunity to contribute to the context
037: * menu when a user right clicks and also contribute to the {@link IActionBars}
038: * each time the selection changes. Clients should re-configure the
039: * {@link IActionBars} each time that {@link #fillActionBars(IActionBars)} is
040: * called (which is once per selection changes). {@link #updateActionBars()}
041: * will never be called from the {@link NavigatorActionService}. This behavior
042: * is required since each selection could determine a different set of
043: * retargetable actions. For instance, the "Delete" operation for a custom model
044: * element is likely to be different than for a resource.
045: * </p>
046: * <p>
047: * Therefore, each extension will have an opportunity to contribute to the
048: * IActionBars based on the <b>possibleChildren</b> expression of the enclosing
049: * <b>navigatorContent</b> extension or the <b>enablement</b> expression of
050: * the <b>actionProvider</b> (for both top-level <b>actionProvider</b>s and
051: * nested <b>actionProvider</b>s which only support a subset of the enclosing
052: * content extensions <b>possibleChildren</b> expression).
053: * <p>
054: * Clients may extend this class.
055: * </p>
056: *
057: * @since 3.2
058: */
059: public abstract class CommonActionProvider extends ActionGroup
060: implements IMementoAware {
061:
062: private ICommonActionExtensionSite actionSite;
063:
064: /**
065: * <p>
066: * Initialize the current ICommonActionProvider with the supplied
067: * information.
068: * </p>
069: * <p>
070: * init() is guaranteed to be called before any other method of the
071: * ActionGroup super class.
072: *
073: * @param aSite
074: * The configuration information for the instantiated Common
075: * Action Provider.
076: */
077: public void init(ICommonActionExtensionSite aSite) {
078: actionSite = aSite;
079: }
080:
081: /**
082: * <p>
083: * Restore the previous state of any actions using the flags in aMemento.
084: * This method allows the state of any actions that persist from session to
085: * session to be restored.
086: * </p>
087: *
088: * <p>
089: * The default behavior is to do nothing.
090: * </p>
091: *
092: * @param aMemento
093: * A memento that was given to the view part to restore its
094: * state.
095: */
096: public void restoreState(IMemento aMemento) {
097: }
098:
099: /**
100: * <p>
101: * Save flags in aMemento to remember the state of any actions that persist
102: * from session to session.
103: * </p>
104: * <p>
105: * Extensions should qualify any keys stored in the memento with their
106: * plugin id
107: * </p>
108: *
109: * <p>
110: * The default behavior is to do nothing.
111: * </p>
112: *
113: * @param aMemento
114: * A memento that was given to the view part to save its state.
115: */
116: public void saveState(IMemento aMemento) {
117: }
118:
119: /**
120: *
121: * @return The cached reference to the action site. Will only be non-null if
122: * the subclass calls super.init() first.
123: */
124: protected final ICommonActionExtensionSite getActionSite() {
125: return actionSite;
126: }
127:
128: }
|