Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.jface.action
Interface IAction

All Known Subinterfaces:
  ActionFactory.IWorkbenchAction

All Known Implementing Classes:
  Action, ExportResourcesAction, GlobalBuildAction, ImportResourcesAction, NewWizardAction, OpenInNewWindowAction, QuickStartAction, RetargetAction

public interface IAction

An action represents the non-UI side of a command which can be triggered by the end user. Actions are typically associated with buttons, menu items, and items in tool bars. The controls for a command are built by some container, which furnished the context where these controls appear and configures them with data from properties declared by the action. When the end user triggers the command via its control, the action's `run` method is invoked to do the real work.

Actions support a predefined set of properties (and possibly others as well). Clients of an action may register property change listeners so that they get notified whenever the value of a property changes.

Clients should subclass the abstract base class `Action` to define concrete actions rather than implementing `IAction` from scratch.

This interface exists only to define the API for actions. It is not intended to be implemented by clients.

See Also:
  `Action`

Field Summary
`static int` | `AS_CHECK_BOX` Action style constant (value `2`) indicating action is a check box (or a toggle button).
`static int` | `AS_DROP_DOWN_MENU` Action style constant (value `4`) indicating action is a drop down menu.
`static int` | `AS_PUSH_BUTTON` Action style constant (value `1`) indicating action is a simple push button.
`static int` | `AS_RADIO_BUTTON` Action style constant (value `8`) indicating action is a radio button.
`static int` | `AS_UNSPECIFIED` Action style constant (value `0`) indicating action style is not specified yet.
`static String` | `CHECKED` Property name of an action's checked status (value `"checked"`).
`static String` | `DESCRIPTION` Property name of an action's description (value `"description"`).
`static String` | `ENABLED` Property name of an action's enabled state (value `"enabled"`).
`static String` | `IMAGE` Property name of an action's image (value `"image"`).
`static String` | `RESULT` Property name of an action's success/fail result (value `"result"`).
`static String` | `TEXT` Property name of an action's text (value `"text"`).
`static String` | `TOOL_TIP_TEXT` Property name of an action's tooltip text (value `"toolTipText"`).

Method Summary
`void` | `addPropertyChangeListener(IPropertyChangeListener listener)` Adds a property change listener to this action.
`int` | `getAccelerator()` Returns the accelerator keycode for this action.
`String` | `getActionDefinitionId()` Returns the action definition id of this action.
`String` | `getDescription()` Returns the action's description if it has one.
`ImageDescriptor` | `getDisabledImageDescriptor()` Returns the disabled image for this action as an image descriptor.
`HelpListener` | `getHelpListener()` Returns a help listener for this action.
`ImageDescriptor` | `getHoverImageDescriptor()` Returns the hover image for this action as an image descriptor.
`String` | `getId()` Returns a unique identifier for this action, or `null` if it has none.
`ImageDescriptor` | `getImageDescriptor()` Returns the image for this action as an image descriptor.
`IMenuCreator` | `getMenuCreator()` Returns the menu creator for this action.
`int` | `getStyle()` Return this action's style.
`String` | `getText()` Returns the text for this action.
`String` | `getToolTipText()` Returns the tool tip text for this action.
`boolean` | `isChecked()` Returns the checked status of this action.
`boolean` | `isEnabled()` Returns whether this action is enabled.
`void` | `removePropertyChangeListener(IPropertyChangeListener listener)` Removes the given listener from this action.
`void` | `run()` Runs this action.
`void` | `runWithEvent(Event event)` Runs this action, passing the triggering SWT event.
`void` | `setAccelerator(int keycode)` Sets the accelerator keycode that this action maps to.
`void` | `setActionDefinitionId(String id)` Sets the action definition id of this action.
`void` | `setChecked(boolean checked)` Sets the checked status of this action.
`void` | `setDescription(String text)` Sets this action's description.
`void` | `setDisabledImageDescriptor(ImageDescriptor newImage)` Sets the disabled image for this action, as an image descriptor.
`void` | `setEnabled(boolean enabled)` Sets the enabled state of this action.
`void` | `setHelpListener(HelpListener listener)` Sets a help listener for this action.
`void` | `setHoverImageDescriptor(ImageDescriptor newImage)` Sets the hover image for this action, as an image descriptor.
`void` | `setId(String id)` Sets the unique identifier for this action.
`void` | `setImageDescriptor(ImageDescriptor newImage)` Sets the image for this action, as an image descriptor.
`void` | `setMenuCreator(IMenuCreator creator)` Sets the menu creator for this action.
`void` | `setText(String text)` Sets the text for this action.
`void` | `setToolTipText(String text)` Sets the tool tip text for this action.

Field Detail

### AS_UNSPECIFIED

    public static final int AS_UNSPECIFIED

  Action style constant (value `0`) indicating action style is not specified yet. By default, the action will assume a push button style. If `setChecked` is called, then the style will change to a check box, or if `setMenuCreator` is called, then the style will change to a drop down menu.

  Since:
    2.1
  See Also:
    Constant Field Values

### AS_PUSH_BUTTON

    public static final int AS_PUSH_BUTTON

  Action style constant (value `1`) indicating action is a simple push button.

  See Also:
    Constant Field Values

### AS_CHECK_BOX

    public static final int AS_CHECK_BOX

  Action style constant (value `2`) indicating action is a check box (or a toggle button).

  See Also:
    Constant Field Values

### AS_DROP_DOWN_MENU

    public static final int AS_DROP_DOWN_MENU

  Action style constant (value `4`) indicating action is a drop down menu.

  See Also:
    Constant Field Values

### AS_RADIO_BUTTON

    public static final int AS_RADIO_BUTTON

  Action style constant (value `8`) indicating action is a radio button.

  Since:
    2.1
  See Also:
    Constant Field Values

### TEXT

    public static final String TEXT

  Property name of an action's text (value `"text"`).

  See Also:
    Constant Field Values

### ENABLED

    public static final String ENABLED

  Property name of an action's enabled state (value `"enabled"`).

  See Also:
    Constant Field Values

### IMAGE

    public static final String IMAGE

  Property name of an action's image (value `"image"`).

  See Also:
    Constant Field Values

### TOOL_TIP_TEXT

    public static final String TOOL_TIP_TEXT

  Property name of an action's tooltip text (value `"toolTipText"`).

  See Also:
    Constant Field Values

### DESCRIPTION

    public static final String DESCRIPTION

  Property name of an action's description (value `"description"`). Typically the description is shown as a (longer) help text in the status line.

  See Also:
    Constant Field Values

### CHECKED

    public static final String CHECKED

  Property name of an action's checked status (value `"checked"`). Applicable when the style is `AS_CHECK_BOX` or `AS_RADIO_BUTTON`.

  See Also:
    Constant Field Values

### RESULT

    public static final String RESULT

  Property name of an action's success/fail result (value `"result"`). The values are `Boolean.TRUE` if running the action succeeded and `Boolean.FALSE` if running the action failed or did not complete.

  Not all actions report whether they succeed or fail. This property is provided for use by actions that may be invoked by clients that can take advantage of this information when present (for example, actions used in cheat sheets). Clients should always assume that running the action succeeded in the absence of notification to the contrary.

  Since:
    3.0
  See Also:
    Constant Field Values

Method Detail

### addPropertyChangeListener

    public void addPropertyChangeListener(IPropertyChangeListener listener)

  Adds a property change listener to this action. Has no effect if an identical listener is already registered.

  Parameters:
    `listener` - a property change listener

### getAccelerator

    public int getAccelerator()

  Returns the accelerator keycode for this action. The result is the bit-wise OR of zero or more modifier masks and a key, as explained in `MenuItem.getAccelerator`.

  Returns:
    the accelerator keycode
  See Also:
    `MenuItem.getAccelerator()`

### getActionDefinitionId

    public String getActionDefinitionId()

  Returns the action definition id of this action.

  Returns:
    the action definition id of this action, or `null` if none
  Since:
    2.0

### getDescription

    public String getDescription()

  Returns the action's description if it has one. Otherwise it returns `getToolTipText()`.

### getDisabledImageDescriptor

    public ImageDescriptor getDisabledImageDescriptor()

  Returns the disabled image for this action as an image descriptor.

  This method is associated with the `IMAGE` property; property change events are reported when its value changes.

  Returns:
    the image, or `null` if this action has no image
  See Also:
    `IMAGE`

### getHelpListener

    public HelpListener getHelpListener()

  Returns a help listener for this action.

  Returns:
    a help listener for this action

### getHoverImageDescriptor

    public ImageDescriptor getHoverImageDescriptor()

  Returns the hover image for this action as an image descriptor.

  Hover images will be used on platforms that support changing the image when the user hovers over the item. This method is associated with the `IMAGE` property; property change events are reported when its value changes.

  Returns:
    the image, or `null` if this action has no image
  See Also:
    `IMAGE`

### getId

    public String getId()

  Returns a unique identifier for this action, or `null` if it has none.

  Returns:
    the action id, or `null` if none

### getImageDescriptor

    public ImageDescriptor getImageDescriptor()

  Returns the image for this action as an image descriptor.

  This method is associated with the `IMAGE` property; property change events are reported when its value changes.

  Returns:
    the image, or `null` if this action has no image
  See Also:
    `IMAGE`

### getMenuCreator

    public IMenuCreator getMenuCreator()

  Returns the menu creator for this action.

  Returns:
    the menu creator, or `null` if none

### getStyle

    public int getStyle()

  Return this action's style.

  Returns:
    one of `AS_PUSH_BUTTON`, `AS_CHECK_BOX`, `AS_RADIO_BUTTON` and `AS_DROP_DOWN_MENU`.

### getText

    public String getText()

  Returns the text for this action.

  This method is associated with the `TEXT` property; property change events are reported when its value changes.

  Returns:
    the text, or `null` if none
  See Also:
    `TEXT`

### getToolTipText

    public String getToolTipText()

  Returns the tool tip text for this action.

  This method is associated with the `TOOL_TIP_TEXT` property; property change events are reported when its value changes.

  Returns:
    the tool tip text, or `null` if none
  See Also:
    `TOOL_TIP_TEXT`

### isChecked

    public boolean isChecked()

  Returns the checked status of this action. Applicable only if the style is `AS_CHECK_BOX` or `AS_RADIO_BUTTON`.

  This method is associated with the `CHECKED` property; property change events are reported when its value changes.

  Returns:
    the checked status
  See Also:
    `CHECKED`

### isEnabled

    public boolean isEnabled()

  Returns whether this action is enabled.

  This method is associated with the `ENABLED` property; property change events are reported when its value changes.

  Returns:
    `true` if enabled, and `false` if disabled
  See Also:
    `ENABLED`

### removePropertyChangeListener

    public void removePropertyChangeListener(IPropertyChangeListener listener)

  Removes the given listener from this action. Has no effect if an identical listener is not registered.

  Parameters:
    `listener` - a property change listener

### run

    public void run()

  Runs this action. Each action implementation must define the steps needed to carry out this action. The default implementation of this method in `Action` does nothing.

### runWithEvent

    public void runWithEvent(Event event)

  Runs this action, passing the triggering SWT event. As of 2.0, `ActionContributionItem` calls this method instead of `run()`. The default implementation of this method in `Action` simply calls `run()` for backwards compatibility.

  Parameters:
    `event` - the SWT event which triggered this action being run
  Since:
    2.0

### setActionDefinitionId

    public void setActionDefinitionId(String id)

  Sets the action definition id of this action.

  Parameters:
    `id` - the action definition id
  Since:
    2.0

### setChecked

    public void setChecked(boolean checked)

  Sets the checked status of this action. Applicable for the styles `AS_CHECK_BOX` or `AS_RADIO_BUTTON`.

  Fires a property change event for the `CHECKED` property if the checked status actually changes as a consequence.

  Parameters:
    `checked` - the new checked status
  See Also:
    `CHECKED`

### setDescription

    public void setDescription(String text)

  Sets this action's description. Typically the description is shown as a (longer) help text in the status line.

  Fires a property change event for the `DESCRIPTION` property if the description actually changes as a consequence.

  Parameters:
    `text` - the description, or `null` to clear the description
  See Also:
    `DESCRIPTION`

### setDisabledImageDescriptor

    public void setDisabledImageDescriptor(ImageDescriptor newImage)

  Sets the disabled image for this action, as an image descriptor.

  Disabled images will be used on platforms that support changing the image when the item is disabled.Fires a property change event for the `IMAGE` property if the image actually changes as a consequence.

  Parameters:
    `newImage` - the image, or `null` if this action should not have an image
  See Also:
    `IMAGE`

### setEnabled

    public void setEnabled(boolean enabled)

  Sets the enabled state of this action.

  When an action is in the enabled state, the control associated with it is active; triggering it will end up inkoking this action's `run` method.

  Fires a property change event for the `ENABLED` property if the enabled state actually changes as a consequence.

  Parameters:
    `enabled` - `true` to enable, and `false` to disable
  See Also:
    `ENABLED`

### setHelpListener

    public void setHelpListener(HelpListener listener)

  Sets a help listener for this action.

  Parameters:
    `listener` - a help listener for this action

### setHoverImageDescriptor

    public void setHoverImageDescriptor(ImageDescriptor newImage)

  Sets the hover image for this action, as an image descriptor.

  Hover images will be used on platforms that support changing the image when the user hovers over the item.Fires a property change event for the `IMAGE` property if the image actually changes as a consequence.

  Parameters:
    `newImage` - the image, or `null` if this action should not have an image
  See Also:
    `IMAGE`

### setId

    public void setId(String id)

  Sets the unique identifier for this action. This is used to identify actions when added to a contribution manager. It should be set when the action is created. It should not be modified once the action is part of an action contribution item.

  Parameters:
    `id` - the action id
  See Also:
    `ActionContributionItem`, `IContributionItem.getId()`

### setImageDescriptor

    public void setImageDescriptor(ImageDescriptor newImage)

  Sets the image for this action, as an image descriptor.

  Fires a property change event for the `IMAGE` property if the image actually changes as a consequence.

  Parameters:
    `newImage` - the image, or `null` if this action should not have an image
  See Also:
    `IMAGE`

### setMenuCreator

    public void setMenuCreator(IMenuCreator creator)

  Sets the menu creator for this action. Applicable for style `AS_DROP_DOWN_MENU`.

  Parameters:
    `creator` - the menu creator, or `null` if none

### setText

    public void setText(String text)

  Sets the text for this action.

  An accelerator specification may follow the actual text, separated from it by an '@' or a '\t' character. An accelerator specification consists of zero or more modifier tokens followed by a key code token. The tokens are separated by a '+' character.

  Fires a property change event for the `TEXT` property if the text actually changes as a consequence.

  Parameters:
    `text` - the text, or `null` if none
  See Also:
    `TEXT`, `Action.findModifier(java.lang.String)`, `Action.findKeyCode(java.lang.String)`

### setToolTipText

    public void setToolTipText(String text)

  Sets the tool tip text for this action.

  Fires a property change event for the `TOOL_TIP_TEXT` property if the tool tip text actually changes as a consequence.

  Parameters:
    `text` - the tool tip text, or `null` if none
  See Also:
    `TOOL_TIP_TEXT`

### setAccelerator

    public void setAccelerator(int keycode)

  Sets the accelerator keycode that this action maps to. This is a bitwise OR of zero or more SWT key modifier masks (i.e. SWT.CTRL or SWT.ALT) and a character code. For example, for Ctrl+Z, use `SWT.CTRL | 'Z'`. Use 0 for no accelerator.

  This method should no longer be used for actions in the Eclipse workbench. `IWorkbenchCommandSupport` and `IWorkbenchContextSupport` provide all the functionality required for key bindings. If you set an accelerator using this method, then it will not work in the workbench if it conflicts any existing key binding, or if there is a different key binding defined for this action's definition id. The definition id should be used instead -- referring to the command in the workbench from which the key binding should be retrieved.

  Parameters:
    `keycode` - the keycode to be accepted.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.