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         }
350         return getToolTipText();
351     }
352 
353     /*
354      * (non-Javadoc) Method declared on IAction.
355      */
356     public ImageDescriptor getDisabledImageDescriptor() {
357         return disabledImage;
358     }
359 
360     /*
361      * (non-Javadoc) Method declared on IAction.
362      */
363     public HelpListener getHelpListener() {
364         return helpListener;
365     }
366 
367     /*
368      * (non-Javadoc) Method declared on IAction.
369      */
370     public ImageDescriptor getHoverImageDescriptor() {
371         return hoverImage;
372     }
373 
374     /*
375      * (non-Javadoc) Method declared on IAction.
376      */
377     public String   getId() {
378         return id;
379     }
380 
381     /*
382      * (non-Javadoc) Method declared on IAction.
383      */
384     public ImageDescriptor getImageDescriptor() {
385         return image;
386     }
387 
388     /*
389      * (non-Javadoc) Method declared on IAction.
390      */
391     public IMenuCreator getMenuCreator() {
392         // The default drop down menu value is only used
393         // to mark this action requested style. So do not
394         // return it. For backward compatibility reasons.
395         if (value == VAL_DROP_DOWN_MENU) {
396             return null;
397         }
398         if (value instanceof IMenuCreator) {
399             return (IMenuCreator) value;
400         }
401         return null;
402     }
403 
404     /*
405      * (non-Javadoc) Method declared on IAction.
406      */
407     public int getStyle() {
408         // Infer the style from the value field.
409         if (value == VAL_PUSH_BTN || value == null) {
410             return AS_PUSH_BUTTON;
411         }
412         if (value == VAL_TOGGLE_BTN_ON || value == VAL_TOGGLE_BTN_OFF) {
413             return AS_CHECK_BOX;
414         }
415         if (value == VAL_RADIO_BTN_ON || value == VAL_RADIO_BTN_OFF) {
416             return AS_RADIO_BUTTON;
417         }
418         if (value instanceof IMenuCreator) {
419             return AS_DROP_DOWN_MENU;
420         }
421 
422         // We should never get to this line...
423         return AS_PUSH_BUTTON;
424     }
425 
426     /*
427      * (non-Javadoc) Method declared on IAction.
428      */
429     public String   getText() {
430         return text;
431     }
432 
433     /*
434      * (non-Javadoc) Method declared on IAction.
435      */
436     public String   getToolTipText() {
437         return toolTipText;
438     }
439 
440     /*
441      * (non-Javadoc) Method declared on IAction.
442      */
443     public boolean isChecked() {
444         return value == VAL_TOGGLE_BTN_ON || value == VAL_RADIO_BTN_ON;
445     }
446 
447     /*
448      * (non-Javadoc) Method declared on IAction.
449      */
450     public boolean isEnabled() {
451         return enabled;
452     }
453 
454     /*
455      * (non-Javadoc) Method declared on IAction.
456      */
457     public boolean isHandled() {
458         return true;
459     }
460 
461     /**
462      * Reports the outcome of the running of this action via the
463      * {@link IAction#RESULT} property.
464      * 
465      * @param success
466      *            <code>true</code> if the action succeeded and
467      *            <code>false</code> if the action failed or was not completed
468      * @see IAction#RESULT
469      * @since 3.0
470      */
471     public final void notifyResult(boolean success) {
472         // avoid Boolean.valueOf(boolean) to allow compilation against JCL
473         // Foundation (bug 80059)
474         firePropertyChange(RESULT, null, success ? Boolean.TRUE : Boolean.FALSE);
475     }
476 
477     /**
478      * The default implementation of this <code>IAction</code> method does
479      * nothing. Subclasses should override this method if they do not need
480      * information from the triggering event, or override
481      * <code>runWithEvent(Event)</code> if they do.
482      */
483     public void run() {
484         // do nothing
485     }
486 
487     /**
488      * The default implementation of this <code>IAction</code> method ignores
489      * the event argument, and simply calls <code>run()</code>. Subclasses
490      * should override this method if they need information from the triggering
491      * event, or override <code>run()</code> if not.
492      * 
493      * @param event
494      *            the SWT event which triggered this action being run
495      * @since 2.0
496      */
497     public void runWithEvent(Event event) {
498         run();
499     }
500 
501     /*
502      * @see IAction#setAccelerator(int)
503      */
504     public void setAccelerator(int keycode) {
505         this.accelerator = keycode;
506     }
507 
508     /*
509      * (non-Javadoc) Method declared on IAction.
510      */
511     public void setActionDefinitionId(String   id) {
512         actionDefinitionId = id;
513     }
514 
515     /*
516      * (non-Javadoc) Method declared on IAction.
517      */
518     public void setChecked(boolean checked) {
519         Object   newValue = null;
520 
521         // For backward compatibility, if the style is not
522         // set yet, then convert it to a toggle button.
523         if (value == null || value == VAL_TOGGLE_BTN_ON
524                 || value == VAL_TOGGLE_BTN_OFF) {
525             newValue = checked ? VAL_TOGGLE_BTN_ON : VAL_TOGGLE_BTN_OFF;
526         } else if (value == VAL_RADIO_BTN_ON || value == VAL_RADIO_BTN_OFF) {
527             newValue = checked ? VAL_RADIO_BTN_ON : VAL_RADIO_BTN_OFF;
528         } else {
529             // Some other style already, so do nothing.
530             return;
531         }
532 
533         if (newValue != value) {
534             value = newValue;
535             if (checked) {
536                 firePropertyChange(CHECKED, Boolean.FALSE, Boolean.TRUE);
537             } else {
538                 firePropertyChange(CHECKED, Boolean.TRUE, Boolean.FALSE);
539             }
540         }
541     }
542 
543     /*
544      * (non-Javadoc) Method declared on IAction.
545      */
546     public void setDescription(String   text) {
547 
548         if ((description == null && text != null)
549                 || (description != null && text == null)
550                 || (description != null && text != null && !text
551                         .equals(description))) {
552             String   oldDescription = description;
553             description = text;
554             firePropertyChange(DESCRIPTION, oldDescription, description);
555         }
556     }
557 
558     /*
559      * (non-Javadoc) Method declared on IAction.
560      */
561     public void setDisabledImageDescriptor(ImageDescriptor newImage) {
562         if (disabledImage != newImage) {
563             ImageDescriptor oldImage = disabledImage;
564             disabledImage = newImage;
565             firePropertyChange(IMAGE, oldImage, newImage);
566         }
567     }
568 
569     /*
570      * (non-Javadoc) Method declared on IAction.
571      */
572     public void setEnabled(boolean enabled) {
573         if (enabled != this.enabled) {
574             Boolean   oldVal = this.enabled ? Boolean.TRUE : Boolean.FALSE;
575             Boolean   newVal = enabled ? Boolean.TRUE : Boolean.FALSE;
576             this.enabled = enabled;
577             firePropertyChange(ENABLED, oldVal, newVal);
578         }
579     }
580 
581     /*
582      * (non-Javadoc) Method declared on IAction.
583      */
584     public void setHelpListener(HelpListener listener) {
585         helpListener = listener;
586     }
587 
588     /*
589      * (non-Javadoc) Method declared on IAction.
590      */
591     public void setHoverImageDescriptor(ImageDescriptor newImage) {
592         if (hoverImage != newImage) {
593             ImageDescriptor oldImage = hoverImage;
594             hoverImage = newImage;
595             firePropertyChange(IMAGE, oldImage, newImage);
596         }
597     }
598 
599     /*
600      * (non-Javadoc) Method declared on IAction.
601      */
602     public void setId(String   id) {
603         this.id = id;
604     }
605 
606     /*
607      * (non-Javadoc) Method declared on IAction.
608      */
609     public void setImageDescriptor(ImageDescriptor newImage) {
610         if (image != newImage) {
611             ImageDescriptor oldImage = image;
612             image = newImage;
613             firePropertyChange(IMAGE, oldImage, newImage);
614         }
615     }
616 
617     /**
618      * Sets the menu creator for this action.
619      * <p>
620      * Note that if this method is called, it overrides the check status.
621      * </p>
622      * 
623      * @param creator
624      *            the menu creator, or <code>null</code> if none
625      */
626     public void setMenuCreator(IMenuCreator creator) {
627         // For backward compatibility, if the style is not
628         // set yet, then convert it to a drop down menu.
629         if (value == null) {
630             value = creator;
631             return;
632         }
633 
634         if (value instanceof IMenuCreator) {
635             value = creator == null ? VAL_DROP_DOWN_MENU : creator;
636         }
637     }
638 
639     /**
640      * Sets the text for this action.
641      * <p>
642      * Fires a property change event for the <code>TEXT</code> property if the
643      * text actually changes as a consequence.
644      * </p>
645      * <p>
646      * The accelerator is identified by the last index of a tab character. If
647      * there are no tab characters, then it is identified by the last index of a
648      * '@' character. If neither, then there is no accelerator text. Note that
649      * if you want to insert a '@' character into the text (but no accelerator,
650      * you can simply insert a '@' or a tab at the end of the text.
651      * </p>
652      * 
653      * @param text
654      *            the text, or <code>null</code> if none
655      */
656     public void setText(String   text) {
657         String   oldText = this.text;
658         int oldAccel = this.accelerator;
659         this.text = text;
660         if (text != null) {
661             String   acceleratorText = LegacyActionTools
662                     .extractAcceleratorText(text);
663             if (acceleratorText != null) {
664                 int newAccelerator = LegacyActionTools
665                         .convertLocalizedAccelerator(acceleratorText);
666                 // Be sure to not wipe out the accelerator if nothing found
667                 if (newAccelerator > 0) {
668                     setAccelerator(newAccelerator);
669                 }
670             }
671         }
672         if (!(this.accelerator == oldAccel && (oldText == null ? this.text == null
673                 : oldText.equals(this.text)))) {
674             firePropertyChange(TEXT, oldText, this.text);
675         }
676     }
677 
678     /**
679      * Sets the tool tip text for this action.
680      * <p>
681      * Fires a property change event for the <code>TOOL_TIP_TEXT</code>
682      * property if the tool tip text actually changes as a consequence.
683      * </p>
684      * 
685      * @param toolTipText
686      *            the tool tip text, or <code>null</code> if none
687      */
688     public void setToolTipText(String   toolTipText) {
689         String   oldToolTipText = this.toolTipText;
690         if (!(oldToolTipText == null ? toolTipText == null : oldToolTipText
691                 .equals(toolTipText))) {
692             this.toolTipText = toolTipText;
693             firePropertyChange(TOOL_TIP_TEXT, oldToolTipText, toolTipText);
694         }
695     }
696 
697 }
698
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags