Package org.eclipse.ui.application

Class ActionBarAdvisor

java.lang.Object
org.eclipse.ui.application.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:

  • Field Details

    • 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:

    • 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:

    • 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:

    • 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:

  • Constructor Details

    • 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 Details

    • 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:

    • 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:

    • 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