Package org.eclipse.ui.application

Class ActionBarAdvisor

  • public class ActionBarAdvisor
extends Object
    Public base class for configuring the action bars of a workbench window.

    An application should declare a subclass of ActionBarAdvisor and override methods to configure a window's action bars to suit the needs of the particular application.

    The following advisor methods are called at strategic points in the workbench's lifecycle (all occur within the dynamic scope of the call to PlatformUI.createAndRunWorkbench):

    • fillActionBars - called after WorkbenchWindowAdvisor.preWindowOpen to configure a window's action bars
    Since:
    3.1
    See Also:
    WorkbenchWindowAdvisor.createActionBarAdvisor(IActionBarConfigurer)

    • Field Detail

      • FILL_PROXY

        public static final int FILL_PROXY
        Bit flag for fillActionBars indicating that the operation is not filling the action bars of an actual workbench window, but rather a proxy (used for perspective customization).
        See Also:
        Constant Field Values

      • FILL_MENU_BAR

        public static final int FILL_MENU_BAR
        Bit flag for fillActionBars indicating that the operation is supposed to fill (or describe) the workbench window's menu bar.
        See Also:
        Constant Field Values

      • FILL_COOL_BAR

        public static final int FILL_COOL_BAR
        Bit flag for fillActionBars indicating that the operation is supposed to fill (or describe) the workbench window's cool bar.
        See Also:
        Constant Field Values

      • FILL_STATUS_LINE

        public static final int FILL_STATUS_LINE
        Bit flag for fillActionBars indicating that the operation is supposed to fill (or describe) the workbench window's status line.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ActionBarAdvisor

        public ActionBarAdvisor​(IActionBarConfigurer configurer)
        Creates a new action bar advisor to configure a workbench window's action bars via the given action bar configurer.
        Parameters:
        configurer - the action bar configurer

    • Method Detail

      • getActionBarConfigurer

        protected IActionBarConfigurer getActionBarConfigurer()
        Returns the action bar configurer.
        Returns:
        the action bar configurer

      • fillActionBars

        public void fillActionBars​(int flags)
        Configures the action bars using the given action bar configurer. Under normal circumstances, flags does not include FILL_PROXY, meaning this is a request to fill the action bars of the corresponding workbench window; the remaining flags indicate which combination of the menu bar (FILL_MENU_BAR), the tool bar (FILL_COOL_BAR), and the status line (FILL_STATUS_LINE) are to be filled.

        If flags does include FILL_PROXY, then this is a request to describe the actions bars of the given workbench window (which will already have been filled); again, the remaining flags indicate which combination of the menu bar, the tool bar, and the status line are to be described. The actions included in the proxy action bars can be the same instances as in the actual window's action bars. Calling ActionFactory to create new action instances is not recommended, because these actions internally register listeners with the window and there is no opportunity to dispose of these actions.

        This method is called just after WorkbenchWindowAdvisor.preWindowOpen(). Clients must not call this method directly (although super calls are okay). The default implementation calls makeActions if FILL_PROXY is specified, then calls fillMenuBar, fillCoolBar, and fillStatusLine if the corresponding flags are specified.

        Subclasses may override, but it is recommended that they override the methods mentioned above instead.

        Parameters:
        flags - bit mask composed from the constants FILL_MENU_BAR, FILL_COOL_BAR, FILL_STATUS_LINE, and FILL_PROXY

      • makeActions

        protected void makeActions​(IWorkbenchWindow window)
        Instantiates the actions used in the fill methods. Use register(IAction) to register the action with the key binding service and add it to the list of actions to be disposed when the window is closed.
        Parameters:
        window - the window containing the action bars

      • register

        protected void register​(IAction action)
        Registers the given action with the key binding service (by calling IActionBarConfigurer.registerGlobalAction(IAction)), and adds it to the list of actions to be disposed when the window is closed.

        In order to participate in key bindings, the action must have an action definition id (aka command id), and a corresponding command extension. See the org.eclipse.ui.commands extension point documentation for more details.

        Parameters:
        action - the action to register, this cannot be null
        See Also:
        IAction.setActionDefinitionId(String), disposeAction(IAction)

      • getAction

        protected IAction getAction​(String id)
        Returns the action with the given id, or null if not found.
        Parameters:
        id - the action id
        Returns:
        the action with the given id, or null if not found
        See Also:
        IAction.getId()

      • fillMenuBar

        protected void fillMenuBar​(IMenuManager menuBar)
        Fills the menu bar with the main menus for the window.

        The default implementation does nothing. Subclasses may override.

        Parameters:
        menuBar - the menu manager for the menu bar

      • fillCoolBar

        protected void fillCoolBar​(ICoolBarManager coolBar)
        Fills the cool bar with the main toolbars for the window.

        The default implementation does nothing. Subclasses may override.

        Parameters:
        coolBar - the cool bar manager

      • fillStatusLine

        protected void fillStatusLine​(IStatusLineManager statusLine)
        Fills the status line with the main status line contributions for the window.

        The default implementation does nothing. Subclasses may override.

        Parameters:
        statusLine - the status line manager

      • isApplicationMenu

        public boolean isApplicationMenu​(String menuId)
        Returns whether the menu with the given id is an application menu of the given window. This is used during OLE "in place" editing. Application menus should be preserved during menu merging. All other menus may be removed from the window.

        The default implementation returns false. Subclasses may override.

        Parameters:
        menuId - the menu id
        Returns:
        true for application menus, and false for part-specific menus

      • dispose

        public void dispose()
        Disposes this action bar advisor. Called when the window is being closed. This should dispose any allocated resources and remove any added listeners.

        The default implementation calls disposeActions() and releases menu manager. Subclasses may extend.

      • disposeActions

        protected void disposeActions()
        Disposes all actions added via register(IAction) using disposeAction(IAction).

      • disposeAction

        protected void disposeAction​(IAction action)
        Disposes the given action.

        The default implementation checks whether the action is an instance of ActionFactory.IWorkbenchAction and calls its dispose() method if so. Subclasses may extend.

        Parameters:
        action - the action to dispose

      • saveState

        public IStatus saveState​(IMemento memento)
        Saves arbitrary application-specific state information for this action bar advisor.

        The default implementation simply returns an OK status. Subclasses may extend or override.

        Parameters:
        memento - the memento in which to save the advisor's state
        Returns:
        a status object indicating whether the save was successful
        Since:
        3.1

      • restoreState

        public IStatus restoreState​(IMemento memento)
        Restores arbitrary application-specific state information for this action bar advisor.

        The default implementation simply returns an OK status. Subclasses may extend or override.

        Parameters:
        memento - the memento from which to restore the advisor's state
        Returns:
        a status object indicating whether the restore was successful
        Since:
        3.1