Runtime

## org.eclipse.gmf.runtime.common.ui.action
Class AbstractContributionItem

    java.lang.Object
      org.eclipse.jface.action.ContributionItem
          org.eclipse.gmf.runtime.common.ui.action.AbstractContributionItem

All Implemented Interfaces:
  IActionWithProgress, IContributionItem, IOperationHistoryListener, ISelectionChangedListener

public abstract class AbstractContributionItem
extends ContributionItem
implements ISelectionChangedListener, IOperationHistoryListener, IActionWithProgress

A custom contribution item that goes into a workbenchpart's toolbar

Nested Class Summary

Nested classes inherited from class org.eclipse.gmf.runtime.common.ui.action.IActionWithProgress
`IActionWithProgress.WorkIndicatorType`

Constructor Summary
`AbstractContributionItem(IWorkbenchPage workbenchPage)` Creates a new WorkbenchPartContributionItem
`AbstractContributionItem(IWorkbenchPage workbenchPage, java.lang.String id)` Creates a new WorkbenchPartContributionItem

Method Summary
`protected abstract boolean` `calculateEnabled()` Calculates enablement of the widget.
`protected int` `computeWidth(Control cont)` Method is being called when there control created by subclasses is not null.
`protected Control` `createControl(Composite parent)` Creates the control of this contributor - override only if a custom control is needed.
`protected MenuItem` `createMenuItem(Menu parent, int index)` Creates the menuitem with the given parent and index.
`protected ToolItem` `createToolItem(ToolBar parent, int index)` Creates the `ToolItem` with the given parent and index.
`void` `dispose()` Dispose should only clean up what was done in the `fill` methods It is not meant to clean up what was done in constructors
`protected abstract void` `doRun(IProgressMonitor progressMonitor)` Performs the actual work when this action handler is run.
`protected void` `execute(ICommand command)` Executes the given `ommand`.
`void` `fill(Composite parent)` The control item implementation of this `IContributionItem` method calls the `createControl` framework method.
`void` `fill(Menu parent, int index)` The control item implementation of this `IContributionItem` method throws an exception since controls cannot be added to menus.
`void` `fill(ToolBar parent, int index)` The control item implementation of this `IContributionItem` method calls the `createControl` framework method to create a control under the given parent, and then creates a new tool item to hold it.
`protected ActionManager` `getActionManager()` Retrieves the action manager for this action delegate from its workbench part.
`protected Control` `getControl()` Gets the item control
`protected Item` `getItem()` Gets the item widget
`protected Listener` `getItemListener()` Returns the item listenr
`java.lang.String` `getLabel()` Gets the control tooltip text
`protected MenuItem` `getMenuItem()` Gets the tool item widget
`protected IOperationHistory` `getOperationHistory()` Returns the operation history for this contribution item from its action manager.
`protected ISelection` `getSelection()` Retrieves the current selection.
`protected IStructuredSelection` `getStructuredSelection()` Retrieves the current structured selection.
`protected ToolItem` `getToolItem()` Gets the tool item widget
`protected IUndoContext` `getUndoContext()` Gets the undo context from my workbench part.
`protected IWorkbenchPart` `getWorkbenchPart()` Gets the current workbench part.
`IActionWithProgress.WorkIndicatorType` `getWorkIndicatorType()` Gets type of work indicator (progress monitor, hourglass, or none).
`protected void` `handle(java.lang.Exception exception)` Handles the specified exception.
`protected void` `handleWidgetDispose(Event e)` Handles a widget dispose event for the widget corresponding to this item.
`protected void` `handleWidgetEvent(Event e)` Handles an event from the widget (forwarded from nested listener).

`void`

`historyNotification(OperationHistoryEvent event)`
Refreshes me if the history event has my workbench part's context, and the event is one of: `OperationHistoryEvent.UNDONE` `OperationHistoryEvent.REDONE` `OperationHistoryEvent.OPERATION_ADDED` `OperationHistoryEvent.OPERATION_CHANGED` `OperationHistoryEvent.OPERATION_NOT_OK` `OperationHistoryEvent.OPERATION_REMOVED` The other operation history events are ignored because they are intermediate events that will be followed by one of those listed above.

`protected void` `init()` `init` is used to initialize the common part of filling this item in a contribution manager.
`boolean` `isEnabled()`
`protected boolean` `isOperationHistoryListener()` Retrieves a Boolean indicating whether this contribution item is interested in operation history changed events.
`boolean` `isRunnable()` Retrieves a Boolean indicating whether this action can be run.
`protected boolean` `isSelectionListener()` Retrieves a Boolean indicating whether this action handler is interested in selection events.
`boolean` `isSetup()` Returns the setup state of this action.
`protected boolean` `needsSetup()` Answers whether or not this action should be setup before it is run.
`protected void` `openErrorDialog(IStatus status)` Opens an error dialog for the specified status object.
`void` `refresh()` refreshed the properties of this contribution item This method should not be called directly, instead `update` method should be called.
`protected void` `refreshItem()` Refreshes the item's GUI
`void` `run(IProgressMonitor progressMonitor)` Runs this action.
`protected void` `runWithEvent(Event event)` A generalized convinience method.
`void` `selectionChanged(SelectionChangedEvent event)`
`protected void` `setEnabled(boolean enabled)` Method setEnabled.
`void` `setItem(Item item)`
`protected void` `setLabel(java.lang.String label)` Sets the control label
`protected void` `setSetup(boolean setup)` Sets the setup state of this action.
`boolean` `setup()` Sets up the action.
`protected void` `setWorkbenchPart(IWorkbenchPart workbenchPart)` Sets the current workbench part
`void` `update()` updates the properties of this contribution item Subclasses should call this method when an update is requested This method is not intended to be overriden.

Methods inherited from class org.eclipse.jface.action.ContributionItem
`fill, getId, getParent, isDirty, isDynamic, isGroupMarker, isSeparator, isVisible, saveWidgetState, setParent, setVisible, toString, update`

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

Constructor Detail

### AbstractContributionItem

    public AbstractContributionItem(IWorkbenchPage workbenchPage)

  Creates a new WorkbenchPartContributionItem

Parameters:
  `workbenchPage` - The workbench Page

### AbstractContributionItem

    public AbstractContributionItem(IWorkbenchPage workbenchPage,
                                    java.lang.String id)

  Creates a new WorkbenchPartContributionItem

Parameters:
  `workbenchPage` - The workbench Page
  `id` - The id of the contribution item

Method Detail

### init

    protected void init()

  `init` is used to initialize the common part of filling this item in a contribution manager. The `dispose` method is later called to clean up what has been initialized in the `fill` and `init` methods

### dispose

    public void dispose()

  Dispose should only clean up what was done in the `fill` methods It is not meant to clean up what was done in constructors

  Specified by:
    `dispose` in interface `IContributionItem`

### getWorkbenchPart

    protected IWorkbenchPart getWorkbenchPart()

  Gets the current workbench part.

  Returns:
    The current workbench part.

### getUndoContext

    protected IUndoContext getUndoContext()

  Gets the undo context from my workbench part.

  Returns:
    the undo context

### getControl

    protected Control getControl()

  Gets the item control

  Returns:
    The item control

### getItem

    protected Item getItem()

  Gets the item widget

  Returns:
    The item widget

### getToolItem

    protected ToolItem getToolItem()

  Gets the tool item widget

  Returns:
    The tool item widget

### getMenuItem

    protected MenuItem getMenuItem()

  Gets the tool item widget

  Returns:
    The tool item widget

### getLabel

    public java.lang.String getLabel()

  Gets the control tooltip text

  Specified by:
    `getLabel` in interface `IActionWithProgress`
  Returns:
    The control tooltip text

### setItem

    public void setItem(Item item)

  Parameters:
    `item` - widget

### setLabel

    protected void setLabel(java.lang.String label)

  Sets the control label

  Parameters:
    `label` - The control label

### setWorkbenchPart

    protected void setWorkbenchPart(IWorkbenchPart workbenchPart)

  Sets the current workbench part

  Parameters:
    `workbenchPart` - The current workbench part

### fill

    public final void fill(Composite parent)

  The control item implementation of this `IContributionItem` method calls the `createControl` framework method. Subclasses must implement `createControl` rather than overriding this method.

  Specified by:
    `fill` in interface `IContributionItem`
  Parameters:
    `parent` - The parent of the control to fill

### fill

    public final void fill(Menu parent,
                           int index)

  The control item implementation of this `IContributionItem` method throws an exception since controls cannot be added to menus.

  Specified by:
    `fill` in interface `IContributionItem`
  Parameters:
    `parent` - The menu
    `index` - Menu index

### fill

    public final void fill(ToolBar parent,
                           int index)

  The control item implementation of this `IContributionItem` method calls the `createControl` framework method to create a control under the given parent, and then creates a new tool item to hold it. Subclasses must implement `createControl` rather than overriding this method.

  Specified by:
    `fill` in interface `IContributionItem`
  Parameters:
    `parent` - The ToolBar to add the new control to
    `index` - Index

### createToolItem

    protected ToolItem createToolItem(ToolBar parent,
                                      int index)

  Creates the `ToolItem` with the given parent and index.

  Parameters:
    `parent` - The ToolBar to add the new control to
    `index` - Index
  Returns:
    `ToolItem` for specified `ToolBar` at specifiec index

### createMenuItem

    protected MenuItem createMenuItem(Menu parent,
                                      int index)

  Creates the menuitem with the given parent and index.

  Parameters:
    `parent` - The Menu to add the new control to
    `index` - Index
  Returns:
    created `MenuItem`

### createControl

    protected Control createControl(Composite parent)

  Creates the control of this contributor - override only if a custom control is needed.

  Parameters:
    `parent` - the parent `Composite`
  Returns:
    control for the specified parent `Composite`

### computeWidth

    protected int computeWidth(Control cont)

  Method is being called when there control created by subclasses is not null. Computes the width of the given control which is being added to a tool bar. This is needed to determine the width of the tool bar item containing the given control.

  Parameters:
    `cont` - the control being added
  Returns:
    the width of the control

### update

    public final void update()

  updates the properties of this contribution item Subclasses should call this method when an update is requested This method is not intended to be overriden. Instead override the `refresh()` method

  Specified by:
    `update` in interface `IContributionItem`

### refresh

    public void refresh()

  refreshed the properties of this contribution item This method should not be called directly, instead `update` method should be called. Subclasses could override this method to add to the refresh and at the end call `super.refresh()`

  Specified by:
    `refresh` in interface `IActionWithProgress`

### refreshItem

    protected void refreshItem()

  Refreshes the item's GUI

### calculateEnabled

    protected abstract boolean calculateEnabled()

  Calculates enablement of the widget. Subclasses must implement. The enablement will used every time the widget is refreshed. It is a resposcibility of the subclasses to call refresh() when it is appropriate.

  Returns:
    boolean

### setEnabled

    protected void setEnabled(boolean enabled)

  Method setEnabled.

  Parameters:
    `enabled` -

### isEnabled

    public boolean isEnabled()

  Specified by:
    `isEnabled` in interface `IContributionItem`

### execute

    protected void execute(ICommand command)

  Executes the given `ommand`.

  Parameters:
    `command` - `ICommand` to be executed

### getActionManager

    protected ActionManager getActionManager()

  Retrieves the action manager for this action delegate from its workbench part.

  Returns:
    The action manager for this action delegate.

### getOperationHistory

    protected IOperationHistory getOperationHistory()

  Returns the operation history for this contribution item from its action manager.

  Returns:
    the operation history

### runWithEvent

    protected void runWithEvent(Event event)

  A generalized convinience method. Should be called by subclasses whenever run() must be ivoked (e.g. whenever a button is pushed)

  Parameters:
    `event` - an optional associated SWT event

### doRun

    protected abstract void doRun(IProgressMonitor progressMonitor)

  Performs the actual work when this action handler is run. Subclasses must override this method to do some work.

  Parameters:
    `progressMonitor` - the progress monitor for tracking the progress of this action when it is run.

### handle

    protected void handle(java.lang.Exception exception)

  Handles the specified exception.

  Parameters:
    `exception` - The exception to be handled.

### openErrorDialog

    protected void openErrorDialog(IStatus status)

  Opens an error dialog for the specified status object.

  Parameters:
    `status` - The status object for which to open an error dialog.

### handleWidgetEvent

    protected void handleWidgetEvent(Event e)

  Handles an event from the widget (forwarded from nested listener).

  Parameters:
    `e` - `Event` to be handled by this method

### handleWidgetDispose

    protected void handleWidgetDispose(Event e)

  Handles a widget dispose event for the widget corresponding to this item.

  Parameters:
    `e` - widget dispose `Event`

### isSelectionListener

    protected boolean isSelectionListener()

  Retrieves a Boolean indicating whether this action handler is interested in selection events.

  Returns:
    `true` if this action handler is interested; `false` otherwise.

### isOperationHistoryListener

    protected boolean isOperationHistoryListener()

  Retrieves a Boolean indicating whether this contribution item is interested in operation history changed events.

  Returns:
    `true` if this action handler is interested; `false` otherwise.

### selectionChanged

    public final void selectionChanged(SelectionChangedEvent event)

  Specified by:
    `selectionChanged` in interface `ISelectionChangedListener`

### historyNotification

    public void historyNotification(OperationHistoryEvent event)

  Refreshes me if the history event has my workbench part's context, and the event is one of:
  - `OperationHistoryEvent.UNDONE`
  - `OperationHistoryEvent.REDONE`
  - `OperationHistoryEvent.OPERATION_ADDED`
  - `OperationHistoryEvent.OPERATION_CHANGED`
  - `OperationHistoryEvent.OPERATION_NOT_OK`
  - `OperationHistoryEvent.OPERATION_REMOVED`
  The other operation history events are ignored because they are intermediate events that will be followed by one of those listed above. We only want to refresh the action handler once for each change to the operation history.

  Specified by:
    `historyNotification` in interface `IOperationHistoryListener`

### getSelection

    protected ISelection getSelection()

  Retrieves the current selection.

  Returns:
    The current selection.

### getStructuredSelection

    protected IStructuredSelection getStructuredSelection()

  Retrieves the current structured selection.

  Returns:
    `IStructuredSelection` for current selection

### getItemListener

    protected Listener getItemListener()

  Returns the item listenr

  Returns:
    The item listener

### getWorkIndicatorType

    public IActionWithProgress.WorkIndicatorType getWorkIndicatorType()

  Description copied from interface: `IActionWithProgress`
  Gets type of work indicator (progress monitor, hourglass, or none).

  Specified by:
    `getWorkIndicatorType` in interface `IActionWithProgress`
  Returns:
    type of work indicator

### isRunnable

    public boolean isRunnable()

  Description copied from interface: `IActionWithProgress`
  Retrieves a Boolean indicating whether this action can be run.

  Specified by:
    `isRunnable` in interface `IActionWithProgress`
  Returns:
    `true` if this action can be run; `false` otherwise.

### run

    public void run(IProgressMonitor progressMonitor)

  Description copied from interface: `IActionWithProgress`
  Runs this action.

  Specified by:
    `run` in interface `IActionWithProgress`
  Parameters:
    `progressMonitor` - `IProgressMonitor` monitoring the execution of this action

### setup

    public boolean setup()

  Description copied from interface: `IActionWithProgress`
  Sets up the action. Should always be called before `IActionWithProgress.run(IProgressMonitor)` is called.

  Specified by:
    `setup` in interface `IActionWithProgress`
  Returns:
    `true` if the setup completed successfully, `false` otherwise.

### isSetup

    public boolean isSetup()

  Returns the setup state of this action.

  Returns:
    `true` if the action has been setup, `false` otherwise.

### setSetup

    protected void setSetup(boolean setup)

  Sets the setup state of this action.

  Parameters:
    `setup` - `true` if the action has been setup, `false` otherwise.

### needsSetup

    protected boolean needsSetup()

  Answers whether or not this action should be setup before it is run. Subclasses should override if they provide vital behaviour in the setup method.

  Returns:
    `true` if the action has a setup, `false` otherwise.

Runtime

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.