Java > Open Source Codes > org > eclipse > jface > action > Action


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.jface.action;
12
13 import org.eclipse.jface.resource.ImageDescriptor;
14 import org.eclipse.swt.events.HelpListener;
15 import org.eclipse.swt.widgets.Control;
16 import org.eclipse.swt.widgets.Event;
17 import org.eclipse.swt.widgets.Menu;
18
19 /**
20  * The standard abstract implementation of an action.
21  * <p>
22  * Subclasses must implement the <code>IAction.run</code> method to carry out
23  * the action's semantics.
24  * </p>
25  */
26 public abstract class Action extends AbstractAction implements IAction {
27
28     private static final IMenuCreator VAL_DROP_DOWN_MENU = new IMenuCreator() {
29         public void dispose() {
30             // do nothing
31 }
32
33         public Menu getMenu(Control parent) {
34             // do nothing
35 return null;
36         }
37
38         public Menu getMenu(Menu parent) {
39             // do nothing
40 return null;
41         }
42     };
43
44     /*
45      * The list of default values the action can have. These values will
46      * determine the style of the action.
47      */
48     private static final String VAL_PUSH_BTN = "PUSH_BTN"; //$NON-NLS-1$
49
50     private static final Integer VAL_RADIO_BTN_OFF = new Integer (0);
51
52     private static final Integer VAL_RADIO_BTN_ON = new Integer (1);
53
54     private static final Boolean VAL_TOGGLE_BTN_OFF = Boolean.FALSE;
55
56     private static final Boolean VAL_TOGGLE_BTN_ON = Boolean.TRUE;
57
58     /**
59      * Converts an accelerator key code to a string representation.
60      *
61      * @param keyCode
62      * the key code to be translated
63      * @return a string representation of the key code
64      */
65     public static String convertAccelerator(int keyCode) {
66         return LegacyActionTools.convertAccelerator(keyCode);
67     }
68
69     /**
70      * Parses the given accelerator text, and converts it to an accelerator key
71      * code.
72      *
73      * @param acceleratorText
74      * the accelerator text
75      * @return the SWT key code, or 0 if there is no accelerator
76      */
77     public static int convertAccelerator(String acceleratorText) {
78         return LegacyActionTools.convertAccelerator(acceleratorText);
79     }
80
81     /**
82      * Maps a standard keyboard key name to an SWT key code. Key names are
83      * converted to upper case before comparison. If the key name is a single
84      * letter, for example "S", its character code is returned.
85      * <p>
86      * The following key names are known (case is ignored):
87      * <ul>
88      * <li><code>"BACKSPACE"</code></li>
89      * <li><code>"TAB"</code></li>
90      * <li><code>"RETURN"</code></li>
91      * <li><code>"ENTER"</code></li>
92      * <li><code>"ESC"</code></li>
93      * <li><code>"ESCAPE"</code></li>
94      * <li><code>"DELETE"</code></li>
95      * <li><code>"SPACE"</code></li>
96      * <li><code>"ARROW_UP"</code>, <code>"ARROW_DOWN"</code>,
97      * <code>"ARROW_LEFT"</code>, and <code>"ARROW_RIGHT"</code></li>
98      * <li><code>"PAGE_UP"</code> and <code>"PAGE_DOWN"</code></li>
99      * <li><code>"HOME"</code></li>
100      * <li><code>"END"</code></li>
101      * <li><code>"INSERT"</code></li>
102      * <li><code>"F1"</code>, <code>"F2"</code> through <code>"F12"</code></li>
103      * </ul>
104      * </p>
105      *
106      * @param token
107      * the key name
108      * @return the SWT key code, <code>-1</code> if no match was found
109      * @see org.eclipse.swt.SWT
110      */
111     public static int findKeyCode(String token) {
112         return LegacyActionTools.findKeyCode(token);
113     }
114
115     /**
116      * Maps an SWT key code to a standard keyboard key name. The key code is
117      * stripped of modifiers (SWT.CTRL, SWT.ALT, SWT.SHIFT, and SWT.COMMAND). If
118      * the key code is not an SWT code (for example if it a key code for the key
119      * 'S'), a string containing a character representation of the key code is
120      * returned.
121      *
122      * @param keyCode
123      * the key code to be translated
124      * @return the string representation of the key code
125      * @see org.eclipse.swt.SWT
126      * @since 2.0
127      */
128     public static String findKeyString(int keyCode) {
129         return LegacyActionTools.findKeyString(keyCode);
130     }
131
132     /**
133      * Maps standard keyboard modifier key names to the corresponding SWT
134      * modifier bit. The following modifier key names are recognized (case is
135      * ignored): <code>"CTRL"</code>, <code>"SHIFT"</code>,
136      * <code>"ALT"</code>, and <code>"COMMAND"</code>. The given modifier
137      * key name is converted to upper case before comparison.
138      *
139      * @param token
140      * the modifier key name
141      * @return the SWT modifier bit, or <code>0</code> if no match was found
142      * @see org.eclipse.swt.SWT
143      */
144     public static int findModifier(String token) {
145         return LegacyActionTools.findModifier(token);
146     }
147
148     /**
149      * Returns a string representation of an SWT modifier bit (SWT.CTRL,
150      * SWT.ALT, SWT.SHIFT, and SWT.COMMAND). Returns <code>null</code> if the
151      * key code is not an SWT modifier bit.
152      *
153      * @param keyCode
154      * the SWT modifier bit to be translated
155      * @return the string representation of the SWT modifier bit, or
156      * <code>null</code> if the key code was not an SWT modifier bit
157      * @see org.eclipse.swt.SWT
158      * @since 2.0
159      */
160     public static String findModifierString(int keyCode) {
161         return LegacyActionTools.findModifierString(keyCode);
162     }
163
164     /**
165      * Convenience method for removing any optional accelerator text from the
166      * given string. The accelerator text appears at the end of the text, and is
167      * separated from the main part by a single tab character <code>'\t'</code>.
168      *
169      * @param text
170      * the text
171      * @return the text sans accelerator
172      */
173     public static String removeAcceleratorText(String text) {
174         return LegacyActionTools.removeAcceleratorText(text);
175     }
176
177     /**
178      * Convenience method for removing any mnemonics from the given string. For
179      * example, <code>removeMnemonics("&Open")</code> will return
180      * <code>"Open"</code>.
181      *
182      * @param text
183      * the text
184      * @return the text sans mnemonics
185      *
186      * @since 3.0
187      */
188     public static String removeMnemonics(String text) {
189         return LegacyActionTools.removeMnemonics(text);
190     }
191
192     /**
193      * This action's accelerator; <code>0</code> means none.
194      */
195     private int accelerator = 0;
196
197     /**
198      * This action's action definition id, or <code>null</code> if none.
199      */
200     private String actionDefinitionId;
201
202     /**
203      * This action's description, or <code>null</code> if none.
204      */
205     private String description;
206
207     /**
208      * This action's disabled image, or <code>null</code> if none.
209      */
210     private ImageDescriptor disabledImage;
211
212     /**
213      * Indicates this action is enabled.
214      */
215     private boolean enabled = true;
216
217     /**
218      * An action's help listener, or <code>null</code> if none.
219      */
220     private HelpListener helpListener;
221
222     /**
223      * This action's hover image, or <code>null</code> if none.
224      */
225     private ImageDescriptor hoverImage;
226
227     /**
228      * This action's id, or <code>null</code> if none.
229      */
230     private String id;
231
232     /**
233      * This action's image, or <code>null</code> if none.
234      */
235     private ImageDescriptor image;
236
237     /**
238      * This action's text, or <code>null</code> if none.
239      */
240     private String text;
241
242     /**
243      * This action's tool tip text, or <code>null</code> if none.
244      */
245     private String toolTipText;
246
247     /**
248      * Holds the action's menu creator (an IMenuCreator) or checked state (a
249      * Boolean for toggle button, or an Integer for radio button), or
250      * <code>null</code> if neither have been set.
251      * <p>
252      * The value of this field affects the value of <code>getStyle()</code>.
253      * </p>
254      */
255     private Object value = null;
256
257     /**
258      * Creates a new action with no text and no image.
259      * <p>
260      * Configure the action later using the set methods.
261      * </p>
262      */
263     protected Action() {
264         // do nothing
265 }
266
267     /**
268      * Creates a new action with the given text and no image. Calls the zero-arg
269      * constructor, then <code>setText</code>.
270      *
271      * @param text
272      * the string used as the text for the action, or
273      * <code>null</code> if there is no text
274      * @see #setText
275      */
276     protected Action(String text) {
277         this();
278         setText(text);
279     }
280
281     /**
282      * Creates a new action with the given text and image. Calls the zero-arg
283      * constructor, then <code>setText</code> and
284      * <code>setImageDescriptor</code>.
285      *
286      * @param text
287      * the action's text, or <code>null</code> if there is no text
288      * @param image
289      * the action's image, or <code>null</code> if there is no
290      * image
291      * @see #setText
292      * @see #setImageDescriptor
293      */
294     protected Action(String text, ImageDescriptor image) {
295         this(text);
296         setImageDescriptor(image);
297     }
298
299     /**
300      * Creates a new action with the given text and style.
301      *
302      * @param text
303      * the action's text, or <code>null</code> if there is no text
304      * @param style
305      * one of <code>AS_PUSH_BUTTON</code>,
306      * <code>AS_CHECK_BOX</code>, <code>AS_DROP_DOWN_MENU</code>,
307      * <code>AS_RADIO_BUTTON</code>, and
308      * <code>AS_UNSPECIFIED</code>.
309      */
310     protected Action(String text, int style) {
311         this(text);
312         switch (style) {
313         case AS_PUSH_BUTTON:
314             value = VAL_PUSH_BTN;
315             break;
316         case AS_CHECK_BOX:
317             value = VAL_TOGGLE_BTN_OFF;
318             break;
319         case AS_DROP_DOWN_MENU:
320             value = VAL_DROP_DOWN_MENU;
321             break;
322         case AS_RADIO_BUTTON:
323             value = VAL_RADIO_BTN_OFF;
324             break;
325         }
326     }
327
328     /*
329      * (non-Javadoc) Method declared on IAction.
330      */
331     public int getAccelerator() {
332         return accelerator;
333     }
334
335     /*
336      * (non-Javadoc) Method declared on IAction.
337      *
338      */
339     public String getActionDefinitionId() {
340         return actionDefinitionId;
341     }
342
343     /*
344      * (non-Javadoc) Method declared on IAction.
345      */
346     public String getDescription() {
347         if (description != null) {
348             return description;
349   &nb