package org.eclipse.jface.action; | |
/* | |
* (c) Copyright IBM Corp. 2000, 2001. | |
* All Rights Reserved. | |
*/ | |
import org.eclipse.jface.resource.ImageDescriptor; | |
import org.eclipse.jface.util.IPropertyChangeListener; | |
import org.eclipse.swt.events.*; | |
/** | |
* 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 <code>run</code> | |
* method is invoked to do the real work. | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* Clients should subclass the abstract base class <code>Action</code> to define | |
* concrete actions rather than implementing <code>IAction</code> from scratch. | |
* </p> | |
* <p> | |
* This interface exists only to define the API for actions. | |
* It is not intended to be implemented by clients. | |
* </p> | |
* | |
* @see Action | |
*/ | |
public interface IAction { | |
/** | |
* Action style constant (value <code>1</code>) indicating action is | |
* a simple push button. | |
*/ | |
public static int AS_PUSH_BUTTON = 0x01; | |
/** | |
* Action style constant (value <code>2</code>) indicating action is | |
* a check box. | |
*/ | |
public static int AS_CHECK_BOX = 0x02; | |
/** | |
* Action style constant (value <code>4</code>) indicating action is | |
* a drop down menu. | |
*/ | |
public static int AS_DROP_DOWN_MENU = 0x04; | |
/** | |
* Property name of an action's text (value <code>"text"</code>). | |
*/ | |
public static final String TEXT= "text"; //$NON-NLS-1$ | |
/** | |
* Property name of an action's enabled state | |
* (value <code>"enabled"</code>). | |
*/ | |
public static final String ENABLED= "enabled"; //$NON-NLS-1$ | |
/** | |
* Property name of an action's image (value <code>"image"</code>). | |
*/ | |
public static final String IMAGE= "image"; //$NON-NLS-1$ | |
/** | |
* Property name of an action's tooltip text (value <code>"toolTipText"</code>). | |
*/ | |
public static final String TOOL_TIP_TEXT= "toolTipText"; //$NON-NLS-1$ | |
/** | |
* Property name of an action's description (value <code>"description"</code>). | |
* Typically the description is shown as a (longer) help text in the status line. | |
*/ | |
public static final String DESCRIPTION= "description"; //$NON-NLS-1$ | |
/** | |
* Property name of an action's checked status (value <code>"checked"</code>). | |
*/ | |
public static final String CHECKED= "checked"; //$NON-NLS-1$ | |
/** | |
* Adds a property change listener to this action. | |
* Has no effect if an identical listener is already registered. | |
* | |
* @param listener a property change listener | |
*/ | |
public void addPropertyChangeListener(IPropertyChangeListener listener); | |
/** | |
* 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 <code>MenuItem.getAccelerator</code>. | |
* | |
* @return the accelerator keycode | |
* @see org.eclipse.swt.widgets.MenuItem#getAccelerator | |
*/ | |
public int getAccelerator(); | |
/** | |
* Returns the action's description if it has one. | |
* Otherwise it returns <code>getToolTipText()</code>. | |
*/ | |
public String getDescription(); | |
/** | |
* Returns the disabled image for this action as an image descriptor. | |
* <p> | |
* This method is associated with the <code>IMAGE</code> property; | |
* property change events are reported when its value changes. | |
* </p> | |
* | |
* @return the image, or <code>null</code> if this action has no image | |
* @see #IMAGE | |
*/ | |
public ImageDescriptor getDisabledImageDescriptor(); | |
/** | |
* Returns a help listener for this action. | |
* | |
* @return a help listener for this action | |
*/ | |
public HelpListener getHelpListener(); | |
/** | |
* Returns the hover image for this action as an image descriptor. | |
* <p> | |
* 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 <code>IMAGE</code> property; | |
* property change events are reported when its value changes. | |
* </p> | |
* | |
* @return the image, or <code>null</code> if this action has no image | |
* @see #IMAGE | |
*/ | |
public ImageDescriptor getHoverImageDescriptor(); | |
/** | |
* Returns a unique identifier for this action, or <code>null</code> if it has | |
* none. | |
* | |
* @return the action id, or <code>null</code> if none | |
*/ | |
public String getId(); | |
/** | |
* Returns the image for this action as an image descriptor. | |
* <p> | |
* This method is associated with the <code>IMAGE</code> property; | |
* property change events are reported when its value changes. | |
* </p> | |
* | |
* @return the image, or <code>null</code> if this action has no image | |
* @see #IMAGE | |
*/ | |
public ImageDescriptor getImageDescriptor(); | |
/** | |
* Returns the menu creator for this action. | |
* | |
* @return the menu creator, or <code>null</code> if none | |
*/ | |
public IMenuCreator getMenuCreator(); | |
/** | |
* Return this action's style. | |
* | |
* @return one of <code>AS_PUSH_BUTTON</code>, <code>AS_CHECK_BOX</code>, | |
* and <code>AS_DROP_DOWN</code>. | |
*/ | |
public int getStyle(); | |
/** | |
* Returns the text for this action. | |
* <p> | |
* This method is associated with the <code>TEXT</code> property; | |
* property change events are reported when its value changes. | |
* </p> | |
* | |
* @return the text, or <code>null</code> if none | |
* @see #TEXT | |
*/ | |
public String getText(); | |
/** | |
* Returns the tool tip text for this action. | |
* <p> | |
* This method is associated with the <code>TOOL_TIP_TEXT</code> property; | |
* property change events are reported when its value changes. | |
* </p> | |
* | |
* @return the tool tip text, or <code>null</code> if none | |
* @see #TOOL_TIP_TEXT | |
*/ | |
public String getToolTipText(); | |
/** | |
* Returns the checked status of this action. | |
* <p> | |
* This method is associated with the <code>CHECKED</code> property; | |
* property change events are reported when its value changes. | |
* </p> | |
* | |
* @return the checked status | |
* @see #CHECKED | |
*/ | |
public boolean isChecked(); | |
/** | |
* Returns whether this action is enabled. | |
* <p> | |
* This method is associated with the <code>ENABLED</code> property; | |
* property change events are reported when its value changes. | |
* </p> | |
* | |
* @return <code>true</code> if enabled, and | |
* <code>false</code> if disabled | |
* @see #ENABLED | |
*/ | |
public boolean isEnabled(); | |
/** | |
* Removes the given listener from this action. | |
* Has no effect if an identical listener is not registered. | |
* | |
* @param listener a property change listener | |
*/ | |
public void removePropertyChangeListener(IPropertyChangeListener listener); | |
/** | |
* Runs this action. | |
* Each action implementation must define the steps needed to carry out this action. | |
*/ | |
public void run(); | |
/** | |
* Sets the checked status of this action. | |
* <p> | |
* Fires a property change event for the <code>CHECKED</code> property | |
* if the checked status actually changes as a consequence. | |
* </p> | |
* | |
* @param checked the new checked status | |
* @see #CHECKED | |
*/ | |
public void setChecked(boolean checked); | |
/** | |
* Sets this action's description. | |
* Typically the description is shown as a (longer) help text in the status line. | |
* <p> | |
* Fires a property change event for the <code>DESCRIPTION</code> property | |
* if the description actually changes as a consequence. | |
* </p> | |
* | |
* @param text the description, or <code>null</code> to clear the description | |
* @see #DESCRIPTION | |
*/ | |
public void setDescription(String text); | |
/** | |
* Sets the disabled image for this action, as an image descriptor. | |
* <p> | |
* Disabled images will be used on platforms that support changing the image | |
* when the item is disabled.Fires a property change event for | |
* the <code>IMAGE</code> property | |
* if the image actually changes as a consequence. | |
* </p> | |
* | |
* @param newImage the image, or <code>null</code> if this | |
* action should not have an image | |
* @see #IMAGE | |
*/ | |
public void setDisabledImageDescriptor(ImageDescriptor newImage); | |
/** | |
* Sets the enabled state of this action. | |
* <p> | |
* When an action is in the enabled state, the control associated with | |
* it is active; triggering it will end up inkoking this action's | |
* <code>run</code> method. | |
* </p> | |
* <p> | |
* Fires a property change event for the <code>ENABLED</code> property | |
* if the enabled state actually changes as a consequence. | |
* </p> | |
* | |
* @param enabled <code>true</code> to enable, and | |
* <code>false</code> to disable | |
* @see #ENABLED | |
*/ | |
public void setEnabled(boolean enabled); | |
/** | |
* Sets a help listener for this action. | |
* | |
* @param listener a help listener for this action | |
*/ | |
public void setHelpListener(HelpListener listener); | |
/** | |
* Sets the hover image for this action, as an image descriptor. | |
* <p> | |
* 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 <code>IMAGE</code> property | |
* if the image actually changes as a consequence. | |
* </p> | |
* | |
* @param newImage the image, or <code>null</code> if this | |
* action should not have an image | |
* @see #IMAGE | |
*/ | |
public void setHoverImageDescriptor(ImageDescriptor newImage); | |
/** | |
* 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. | |
* | |
* @param id the action id | |
* | |
* @see ActionContributionItem | |
* @see IContributionItem#getId | |
*/ | |
public void setId(String id); | |
/** | |
* Sets the image for this action, as an image descriptor. | |
* <p> | |
* Fires a property change event for the <code>IMAGE</code> property | |
* if the image actually changes as a consequence. | |
* </p> | |
* | |
* @param newImage the image, or <code>null</code> if this | |
* action should not have an image | |
* @see #IMAGE | |
*/ | |
public void setImageDescriptor(ImageDescriptor newImage); | |
/** | |
* Sets the text for this action. | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* Fires a property change event for the <code>TEXT</code> property | |
* if the text actually changes as a consequence. | |
* </p> | |
* | |
* @param text the text, or <code>null</code> if none | |
* @see #TEXT | |
* @see Action#findModifier | |
* @see Action#findKeyCode | |
*/ | |
public void setText(String text); | |
/** | |
* Sets the tool tip text for this action. | |
* <p> | |
* Fires a property change event for the <code>TOOL_TIP_TEXT</code> property | |
* if the tool tip text actually changes as a consequence. | |
* </p> | |
* | |
* @param text the tool tip text, or <code>null</code> if none | |
* @see #TOOL_TIP_TEXT | |
*/ | |
public void setToolTipText(String text); | |
} |