Eclipse Platform Release 3.7

## 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:
  `WorkbenchWindowAdvisor.createActionBarAdvisor(IActionBarConfigurer)`

Field Summary
`static int` `FILL_COOL_BAR` Bit flag for `fillActionBars` indicating that the operation is supposed to fill (or describe) the workbench window's cool bar.
`static int` `FILL_MENU_BAR` Bit flag for `fillActionBars` indicating that the operation is supposed to fill (or describe) the workbench window's menu bar.
`static 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).
`static int` `FILL_STATUS_LINE` Bit flag for `fillActionBars` indicating that the operation is supposed to fill (or describe) the workbench window's status line.

Constructor Summary
`ActionBarAdvisor(IActionBarConfigurer configurer)` Creates a new action bar advisor to configure a workbench window's action bars via the given action bar configurer.

Method Summary
`void` `dispose()` Disposes this action bar advisor.
`protected void` `disposeAction(IAction action)` Disposes the given action.
`protected void` `disposeActions()` Disposes all actions added via `register(IAction)` using `disposeAction(IAction)`.
`void` `fillActionBars(int flags)` Configures the action bars using the given action bar configurer.
`protected void` `fillCoolBar(ICoolBarManager coolBar)` Fills the cool bar with the main toolbars for the window.
`protected void` `fillMenuBar(IMenuManager menuBar)` Fills the menu bar with the main menus for the window.
`protected void` `fillStatusLine(IStatusLineManager statusLine)` Fills the status line with the main status line contributions for the window.
`protected IAction` `getAction(String id)` Returns the action with the given id, or `null` if not found.
`protected IActionBarConfigurer` `getActionBarConfigurer()` Returns the action bar configurer.
`boolean` `isApplicationMenu(String menuId)` Returns whether the menu with the given id is an application menu of the given window.
`protected void` `makeActions(IWorkbenchWindow window)` Instantiates the actions used in the fill methods.
`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.
`IStatus` `restoreState(IMemento memento)` Restores arbitrary application-specific state information for this action bar advisor.
`IStatus` `saveState(IMemento memento)` Saves arbitrary application-specific state information for this action bar advisor.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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()`. 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

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.