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
Class Action

    java.lang.Object
      org.eclipse.jface.action.Action

All Implemented Interfaces:
  IAction

Direct Known Subclasses:
  BaseSelectionListenerAction, BooleanPropertyAction, ClearOutputAction, CreateProjectAction, FrameAction, GlobalBuildAction, LaunchAction, LaunchAsAction, NavigationAction, NewExampleAction, NewProjectAction, NewWizardAction, OpenCheatSheetAction, OpenInNewWindowAction, OpenLaunchDialogAction, PartEventAction, QuickStartAction, ResourceAction, SelectionProviderAction, TextNavigationAction, TextViewerAction

public abstract class Action
extends Object
implements IAction

The standard abstract implementation of an action.

Subclasses must implement the `IAction.run` method to carry out the action's semantics.

Field Summary

Fields inherited from interface org.eclipse.jface.action.IAction
`AS_CHECK_BOX, AS_DROP_DOWN_MENU, AS_PUSH_BUTTON, AS_RADIO_BUTTON, AS_UNSPECIFIED, CHECKED, DESCRIPTION, ENABLED, IMAGE, RESULT, TEXT, TOOL_TIP_TEXT`

Constructor Summary
`protected` | `Action()` Creates a new action with no text and no image.
`protected` | `Action(String text)` Creates a new action with the given text and no image.
`protected` | `Action(String text, ImageDescriptor image)` Creates a new action with the given text and image.
`protected` | `Action(String text, int style)` Creates a new action with the given text and style.

Method Summary
`void` | `addPropertyChangeListener(IPropertyChangeListener listener)` Adds a property change listener to this action.
`static String` | `convertAccelerator(int keyCode)` Converts an accelerator key code to a string representation.
`static int` | `convertAccelerator(String acceleratorText)` Parses the given accelerator text, and converts it to an accelerator key code.
`static int` | `findKeyCode(String token)` Maps a standard keyboard key name to an SWT key code.
`static String` | `findKeyString(int keyCode)` Maps an SWT key code to a standard keyboard key name.
`static int` | `findModifier(String token)` Maps standard keyboard modifier key names to the corresponding SWT modifier bit.
`static String` | `findModifierString(int keyCode)` Returns a string representation of an SWT modifier bit (SWT.CTRL, SWT.ALT, SWT.SHIFT, and SWT.COMMAND).
`protected void` | `firePropertyChange(PropertyChangeEvent event)` Notifies any property change listeners that a property has changed.
`protected void` | `firePropertyChange(String propertyName, Object oldValue, Object newValue)` Notifies any property change listeners that a property has changed.
`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` | `notifyResult(boolean success)` Reports the outcome of the running of this action via the `IAction.RESULT` property.
`static String` | `removeAcceleratorText(String text)` Convenience method for removing any optional accelerator text from the given string.
`static String` | `removeMnemonics(String text)` Convenience method for removing any mnemonics from the given string.
`void` | `removePropertyChangeListener(IPropertyChangeListener listener)` Removes the given listener from this action.
`void` | `run()` The default implementation of this `IAction` method does nothing.
`void` | `runWithEvent(Event event)` The default implementation of this `IAction` method ignores the event argument, and simply calls `run()`.
`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 toolTipText)` Sets the tool tip text for this action.

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

Constructor Detail

### Action

    protected Action()

  Creates a new action with no text and no image.

  Configure the action later using the set methods.

### Action

    protected Action(String text)

  Creates a new action with the given text and no image. Calls the zero-arg constructor, then `setText`.

Parameters:
  `text` - the string used as the text for the action, or `null` if there is no text
See Also:
  `setText(java.lang.String)`

### Action

    protected Action(String text,
                     ImageDescriptor image)

  Creates a new action with the given text and image. Calls the zero-arg constructor, then `setText` and `setImageDescriptor`.

Parameters:
  `text` - the action's text, or `null` if there is no text
  `image` - the action's image, or `null` if there is no image
See Also:
  `setText(java.lang.String)`, `setImageDescriptor(org.eclipse.jface.resource.ImageDescriptor)`

### Action

    protected Action(String text,
                     int style)

  Creates a new action with the given text and style.

Parameters:
  `text` - the action's text, or `null` if there is no text
  `style` - one of `AS_PUSH_BUTTON`, `AS_CHECK_BOX`, `AS_DROP_DOWN_MENU`, `AS_RADIO_BUTTON`, and `AS_UNSPECIFIED`.

Method Detail

### addPropertyChangeListener

    public void addPropertyChangeListener(IPropertyChangeListener listener)

  Description copied from interface: `IAction`
  Adds a property change listener to this action. Has no effect if an identical listener is already registered.

  Specified by:
    `addPropertyChangeListener` in interface `IAction`
  Parameters:
    `listener` - a property change listener

### convertAccelerator

    public static int convertAccelerator(String acceleratorText)

  Parses the given accelerator text, and converts it to an accelerator key code.

  Parameters:
    `acceleratorText` - the accelerator text
  Returns:
    the SWT key code, or 0 if there is no accelerator

### convertAccelerator

    public static String convertAccelerator(int keyCode)

  Converts an accelerator key code to a string representation.

  Parameters:
    `keyCode` - the key code to be translated
  Returns:
    a string representation of the key code

### findKeyCode

    public static int findKeyCode(String token)

  Maps a standard keyboard key name to an SWT key code. Key names are converted to upper case before comparison. If the key name is a single letter, for example "S", its character code is returned.

  The following key names are known (case is ignored):

  - `"BACKSPACE"`
  - `"TAB"`
  - `"RETURN"`
  - `"ENTER"`
  - `"ESC"`
  - `"ESCAPE"`
  - `"DELETE"`
  - `"SPACE"`
  - `"ARROW_UP"`, `"ARROW_DOWN"`, `"ARROW_LEFT"`, and `"ARROW_RIGHT"`
  - `"PAGE_UP"` and `"PAGE_DOWN"`
  - `"HOME"`
  - `"END"`
  - `"INSERT"`
  - `"F1"`, `"F2"` through `"F12"`

  Parameters:
    `token` - the key name
  Returns:
    the SWT key code, `-1` if no match was found
  See Also:
    `SWT`

### findKeyString

    public static String findKeyString(int keyCode)

  Maps an SWT key code to a standard keyboard key name. The key code is stripped of modifiers (SWT.CTRL, SWT.ALT, SWT.SHIFT, and SWT.COMMAND). If the key code is not an SWT code (for example if it a key code for the key 'S'), a string containing a character representation of the key code is returned.

  Parameters:
    `keyCode` - the key code to be translated
  Returns:
    the string representation of the key code
  Since:
    2.0
  See Also:
    `SWT`

### findModifier

    public static int findModifier(String token)

  Maps standard keyboard modifier key names to the corresponding SWT modifier bit. The following modifier key names are recognized (case is ignored): `"CTRL"`, `"SHIFT"`, `"ALT"`, and `"COMMAND"`. The given modifier key name is converted to upper case before comparison.

  Parameters:
    `token` - the modifier key name
  Returns:
    the SWT modifier bit, or `0` if no match was found
  See Also:
    `SWT`

### findModifierString

    public static String findModifierString(int keyCode)

  Returns a string representation of an SWT modifier bit (SWT.CTRL, SWT.ALT, SWT.SHIFT, and SWT.COMMAND). Returns `null` if the key code is not an SWT modifier bit.

  Parameters:
    `keyCode` - the SWT modifier bit to be translated
  Returns:
    the string representation of the SWT modifier bit, or `null` if the key code was not an SWT modifier bit
  Since:
    2.0
  See Also:
    `SWT`

### firePropertyChange

    protected void firePropertyChange(String propertyName,
                                      Object oldValue,
                                      Object newValue)

  Notifies any property change listeners that a property has changed. Only listeners registered at the time this method is called are notified. This method avoids creating an event object if there are no listeners registered, but calls `firePropertyChange(PropertyChangeEvent)` if there are.

  Parameters:
    `propertyName` - the name of the property that has changed
    `oldValue` - the old value of the property, or `null` if none
    `newValue` - the new value of the property, or `null` if none
  See Also:
    `IPropertyChangeListener.propertyChange(org.eclipse.jface.util.PropertyChangeEvent)`

### firePropertyChange

    protected void firePropertyChange(PropertyChangeEvent event)

  Notifies any property change listeners that a property has changed. Only listeners registered at the time this method is called are notified.

  Parameters:
    `event` - the property change event
  See Also:
    `IPropertyChangeListener.propertyChange(org.eclipse.jface.util.PropertyChangeEvent)`

### getAccelerator

    public int getAccelerator()

  Description copied from interface: `IAction`
  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`.

  Specified by:
    `getAccelerator` in interface `IAction`
  Returns:
    the accelerator keycode
  See Also:
    `MenuItem.getAccelerator()`

### getActionDefinitionId

    public String getActionDefinitionId()

  Description copied from interface: `IAction`
  Returns the action definition id of this action.

  Specified by:
    `getActionDefinitionId` in interface `IAction`
  Returns:
    the action definition id of this action, or `null` if none

### getDescription

    public String getDescription()

  Description copied from interface: `IAction`
  Returns the action's description if it has one. Otherwise it returns `getToolTipText()`.

  Specified by:
    `getDescription` in interface `IAction`

### getDisabledImageDescriptor

    public ImageDescriptor getDisabledImageDescriptor()

  Description copied from interface: `IAction`
  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.

  Specified by:
    `getDisabledImageDescriptor` in interface `IAction`
  Returns:
    the image, or `null` if this action has no image
  See Also:
    `IAction.IMAGE`

### getHelpListener

    public HelpListener getHelpListener()

  Description copied from interface: `IAction`
  Returns a help listener for this action.

  Specified by:
    `getHelpListener` in interface `IAction`
  Returns:
    a help listener for this action

### getHoverImageDescriptor

    public ImageDescriptor getHoverImageDescriptor()

  Description copied from interface: `IAction`
  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.

  Specified by:
    `getHoverImageDescriptor` in interface `IAction`
  Returns:
    the image, or `null` if this action has no image
  See Also:
    `IAction.IMAGE`

### getId

    public String getId()

  Description copied from interface: `IAction`
  Returns a unique identifier for this action, or `null` if it has none.

  Specified by:
    `getId` in interface `IAction`
  Returns:
    the action id, or `null` if none

### getImageDescriptor

    public ImageDescriptor getImageDescriptor()

  Description copied from interface: `IAction`
  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.

  Specified by:
    `getImageDescriptor` in interface `IAction`
  Returns:
    the image, or `null` if this action has no image
  See Also:
    `IAction.IMAGE`

### getMenuCreator

    public IMenuCreator getMenuCreator()

  Description copied from interface: `IAction`
  Returns the menu creator for this action.

  Specified by:
    `getMenuCreator` in interface `IAction`
  Returns:
    the menu creator, or `null` if none

### getStyle

    public int getStyle()

  Description copied from interface: `IAction`
  Return this action's style.

  Specified by:
    `getStyle` in interface `IAction`
  Returns:
    one of `AS_PUSH_BUTTON`, `AS_CHECK_BOX`, `AS_RADIO_BUTTON` and `AS_DROP_DOWN_MENU`.

### getText

    public String getText()

  Description copied from interface: `IAction`
  Returns the text for this action.

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

  Specified by:
    `getText` in interface `IAction`
  Returns:
    the text, or `null` if none
  See Also:
    `IAction.TEXT`

### getToolTipText

    public String getToolTipText()

  Description copied from interface: `IAction`
  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.

  Specified by:
    `getToolTipText` in interface `IAction`
  Returns:
    the tool tip text, or `null` if none
  See Also:
    `IAction.TOOL_TIP_TEXT`

### isChecked

    public boolean isChecked()

  Description copied from interface: `IAction`
  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.

  Specified by:
    `isChecked` in interface `IAction`
  Returns:
    the checked status
  See Also:
    `IAction.CHECKED`

### isEnabled

    public boolean isEnabled()

  Description copied from interface: `IAction`
  Returns whether this action is enabled.

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

  Specified by:
    `isEnabled` in interface `IAction`
  Returns:
    `true` if enabled, and `false` if disabled
  See Also:
    `IAction.ENABLED`

### removeAcceleratorText

    public static String removeAcceleratorText(String text)

  Convenience method for removing any optional accelerator text from the given string. The accelerator text appears at the end of the text, and is separated from the main part by a single tab character `'\t'`.

  Parameters:
    `text` - the text
  Returns:
    the text sans accelerator

### removeMnemonics

    public static String removeMnemonics(String text)

  Convenience method for removing any mnemonics from the given string. For example, `removeMnemonics("&Open")` will return `"Open"`.

  Parameters:
    `text` - the text
  Returns:
    the text sans mnemonics
  Since:
    3.0

### removePropertyChangeListener

    public void removePropertyChangeListener(IPropertyChangeListener listener)

  Description copied from interface: `IAction`
  Removes the given listener from this action. Has no effect if an identical listener is not registered.

  Specified by:
    `removePropertyChangeListener` in interface `IAction`
  Parameters:
    `listener` - a property change listener

### run

    public void run()

  The default implementation of this `IAction` method does nothing. Subclasses should override this method if they do not need information from the triggering event, or override `runWithEvent(Event)` if they do.

  Specified by:
    `run` in interface `IAction`

### runWithEvent

    public void runWithEvent(Event event)

  The default implementation of this `IAction` method ignores the event argument, and simply calls `run()`. Subclasses should override this method if they need information from the triggering event, or override `run()` if not.

  Specified by:
    `runWithEvent` in interface `IAction`
  Parameters:
    `event` - the SWT event which triggered this action being run
  Since:
    2.0

### setActionDefinitionId

    public void setActionDefinitionId(String id)

  Description copied from interface: `IAction`
  Sets the action definition id of this action.

  Specified by:
    `setActionDefinitionId` in interface `IAction`
  Parameters:
    `id` - the action definition id

### setChecked

    public void setChecked(boolean checked)

  Description copied from interface: `IAction`
  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.

  Specified by:
    `setChecked` in interface `IAction`
  Parameters:
    `checked` - the new checked status
  See Also:
    `IAction.CHECKED`

### setDescription

    public void setDescription(String text)

  Description copied from interface: `IAction`
  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.

  Specified by:
    `setDescription` in interface `IAction`
  Parameters:
    `text` - the description, or `null` to clear the description
  See Also:
    `IAction.DESCRIPTION`

### setDisabledImageDescriptor

    public void setDisabledImageDescriptor(ImageDescriptor newImage)

  Description copied from interface: `IAction`
  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.

  Specified by:
    `setDisabledImageDescriptor` in interface `IAction`
  Parameters:
    `newImage` - the image, or `null` if this action should not have an image
  See Also:
    `IAction.IMAGE`

### setEnabled

    public void setEnabled(boolean enabled)

  Description copied from interface: `IAction`
  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.

  Specified by:
    `setEnabled` in interface `IAction`
  Parameters:
    `enabled` - `true` to enable, and `false` to disable
  See Also:
    `IAction.ENABLED`

### setHelpListener

    public void setHelpListener(HelpListener listener)

  Description copied from interface: `IAction`
  Sets a help listener for this action.

  Specified by:
    `setHelpListener` in interface `IAction`
  Parameters:
    `listener` - a help listener for this action

### setHoverImageDescriptor

    public void setHoverImageDescriptor(ImageDescriptor newImage)

  Description copied from interface: `IAction`
  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.

  Specified by:
    `setHoverImageDescriptor` in interface `IAction`
  Parameters:
    `newImage` - the image, or `null` if this action should not have an image
  See Also:
    `IAction.IMAGE`

### setId

    public void setId(String id)

  Description copied from interface: `IAction`
  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.

  Specified by:
    `setId` in interface `IAction`
  Parameters:
    `id` - the action id
  See Also:
    `ActionContributionItem`, `IContributionItem.getId()`

### setImageDescriptor

    public void setImageDescriptor(ImageDescriptor newImage)

  Description copied from interface: `IAction`
  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.

  Specified by:
    `setImageDescriptor` in interface `IAction`
  Parameters:
    `newImage` - the image, or `null` if this action should not have an image
  See Also:
    `IAction.IMAGE`

### setMenuCreator

    public void setMenuCreator(IMenuCreator creator)

  Sets the menu creator for this action.

  Note that if this method is called, it overrides the check status.

  Specified by:
    `setMenuCreator` in interface `IAction`
  Parameters:
    `creator` - the menu creator, or `null` if none

### setText

    public void setText(String text)

  Sets the text for this action.

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

  The accelerator is identified by the last index of a tab character. If there are no tab characters, then it is identified by the last index of a '@' character. If neither, then there is no accelerator text. Note that if you want to insert a '@' character into the text (but no accelerator, you can simply insert a '@' or a tab at the end of the text.

  Specified by:
    `setText` in interface `IAction`
  Parameters:
    `text` - the text, or `null` if none
  See Also:
    `IAction.TEXT`, `findModifier(java.lang.String)`, `findKeyCode(java.lang.String)`

### setToolTipText

    public void setToolTipText(String toolTipText)

  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.

  Specified by:
    `setToolTipText` in interface `IAction`
  Parameters:
    `toolTipText` - the tool tip text, or `null` if none
  See Also:
    `IAction.TOOL_TIP_TEXT`

### setAccelerator

    public void setAccelerator(int keycode)

  Description copied from interface: `IAction`

  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.

  Specified by:
    `setAccelerator` in interface `IAction`
  Parameters:
    `keycode` - the keycode to be accepted.

### notifyResult

    public final void notifyResult(boolean success)

  Reports the outcome of the running of this action via the `IAction.RESULT` property.

  Parameters:
    `success` - `true` if the action succeeded and `false` if the action failed or was not completed
  Since:
    3.0
  See Also:
    `IAction.RESULT`

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.