org.openide.awt 7.23.1

org.openide.awt
Class Actions

java.lang.Object
  extended by org.openide.awt.Actions

public class Actions
extends Object

Supporting class for manipulation with menu and toolbar presenters.


Nested Class Summary
static interface Actions.ButtonActionConnector
          SPI for supplying alternative implementation of connection between actions and presenters.
static class Actions.CheckboxMenuItem
          CheckboxMenuItem extends the java.awt.CheckboxMenuItem and adds a connection to boolean state actions.
static class Actions.MenuItem
          Extension of Swing menu item with connection to system actions.
static class Actions.SubMenu
          Deprecated. extends deprecated JMenuPlus
static interface Actions.SubMenuModel
          Deprecated. used by deprecated Actions.SubMenu
static class Actions.ToolbarButton
          Deprecated. extends deprecated ToolbarButton
static class Actions.ToolbarToggleButton
          Deprecated. extends deprecated ToolbarToggleButton
 
Constructor Summary
Actions()
          Deprecated. should not be used
 
Method Summary
static Action alwaysEnabled(ActionListener delegate, String displayName, String iconBase, boolean noIconInMenu)
          Creates new action which is always enabled.
static ContextAwareAction callback(String key, Action fallback, boolean surviveFocusChange, String displayName, String iconBase, boolean noIconInMenu)
          Creates new "callback" action.
static Action checkbox(String preferencesNode, String preferencesKey, String displayName, String iconBase, boolean noIconInMenu)
          Creates action which represents a boolean value in Preferences.
static void connect(AbstractButton button, Action action)
          Connects buttons to action.
static void connect(AbstractButton button, BooleanStateAction action)
          Connects buttons to action.
static void connect(AbstractButton button, SystemAction action)
          Deprecated. Use connect(AbstractButton, Action) instead.
static void connect(JCheckBoxMenuItem item, BooleanStateAction action, boolean popup)
          Attaches checkbox menu item to boolean state action.
static void connect(JMenuItem item, Action action, boolean popup)
          Attaches menu item to an action.
static void connect(JMenuItem item, SystemAction action, boolean popup)
          Deprecated. Use connect(JMenuItem, Action, boolean) instead.
static ContextAwareAction context(Class<?> type, boolean single, boolean surviveFocusChange, ContextAwareAction delegate, String key, String displayName, String iconBase, boolean noIconInMenu)
          Creates new "context" action, an action that observes the current selection for a given type and enables if instances of given type are present.
static String cutAmpersand(String text)
          Removes an ampersand from a text string; commonly used to strip out unneeded mnemonics.
static String findKey(SystemAction action)
          Method that finds the keydescription assigned to this action.
static void setMenuText(AbstractButton item, String text, boolean useMnemonic)
          Deprecated. Use either AbstractButton.setText(java.lang.String) or Mnemonics.setLocalizedText(AbstractButton, String) as appropriate.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Actions

@Deprecated
public Actions()
Deprecated. should not be used

Method Detail

findKey

public static String findKey(SystemAction action)
Method that finds the keydescription assigned to this action.

Parameters:
action - action to find key for
Returns:
the text representing the key or null if there is no text assigned

connect

@Deprecated
public static void connect(JMenuItem item,
                                      SystemAction action,
                                      boolean popup)
Deprecated. Use connect(JMenuItem, Action, boolean) instead.

Attaches menu item to an action.

Parameters:
item - menu item
action - action
popup - create popup or menu item

connect

public static void connect(JMenuItem item,
                           Action action,
                           boolean popup)
Attaches menu item to an action. You can supply an alternative implementation for this method by implementing method Actions.ButtonActionConnector.connect(JMenuItem, Action, boolean) and registering an instance of Actions.ButtonActionConnector in the default lookup.

Since version 7.1 the action can also provide properties "menuText" and "popupText" if one wants to use other text on the JMenuItem than the name of the action taken from Action.NAME. The popupText is checked only if the popup parameter is true and takes the biggest precedence. The menuText is tested everytime and takes precedence over standard Action.NAME

Parameters:
item - menu item
action - action
popup - create popup or menu item
Since:
3.29

connect

public static void connect(JCheckBoxMenuItem item,
                           BooleanStateAction action,
                           boolean popup)
Attaches checkbox menu item to boolean state action.

Parameters:
item - menu item
action - action
popup - create popup or menu item

connect

@Deprecated
public static void connect(AbstractButton button,
                                      SystemAction action)
Deprecated. Use connect(AbstractButton, Action) instead.

Connects buttons to action.

Parameters:
button - the button
action - the action

connect

public static void connect(AbstractButton button,
                           Action action)
Connects buttons to action. If the action supplies value for "iconBase" key from getValue(String) with a path to icons the methods setIcon, setPressedIcon, setDisabledIcon and setRolloverIcon will be called on the button with loaded icons using the iconBase. E.g. if the value for "iconBase" will be "com/mycompany/myIcon.gif" following images will be tried "com/mycompany/myIcon.gif" for setIcon, "com/mycompany/myIcon_pressed.gif" for setPressedIcon, "com/mycompany/myIcon_disabled.gif" for setDisabledIcon and "com/mycompany/myIcon_rollover.gif" for setRolloverIcon. SystemAction has special support for iconBase - please check SystemAction.iconResource() for more details. You can supply an alternative implementation for this method by implementing method Actions.ButtonActionConnector.connect(AbstractButton, Action) and registering an instance of Actions.ButtonActionConnector in the default lookup.

Parameters:
button - the button
action - the action
Since:
3.29

connect

public static void connect(AbstractButton button,
                           BooleanStateAction action)
Connects buttons to action.

Parameters:
button - the button
action - the action

setMenuText

@Deprecated
public static void setMenuText(AbstractButton item,
                                          String text,
                                          boolean useMnemonic)
Deprecated. Use either AbstractButton.setText(java.lang.String) or Mnemonics.setLocalizedText(AbstractButton, String) as appropriate.

Sets the text for the menu item or other subclass of AbstractButton. Cut from the name '&' char.

Parameters:
item - AbstractButton
text - new label
useMnemonic - if true and '&' char found in new text, next char is used as Mnemonic.

cutAmpersand

public static String cutAmpersand(String text)
Removes an ampersand from a text string; commonly used to strip out unneeded mnemonics. Replaces the first occurence of &? by ? or (&?? by the empty string where ? is a wildcard for any character. &? is a shortcut in English locale. (&?) is a shortcut in Japanese locale. Used to remove shortcuts from workspace names (or similar) when shortcuts are not supported.

The current implementation behaves in the same way regardless of locale. In case of a conflict it would be necessary to change the behavior based on the current locale.

Parameters:
text - a localized label that may have mnemonic information in it
Returns:
string without first & if there was any

alwaysEnabled

public static Action alwaysEnabled(ActionListener delegate,
                                   String displayName,
                                   String iconBase,
                                   boolean noIconInMenu)
Creates new action which is always enabled. This method can also be used from XML Layer directly by following XML definition:
 <file name="your-pkg-action-id.instance">
   <attr name="instanceCreate" methodvalue="org.openide.awt.Actions.alwaysEnabled"/>
   <attr name="delegate" methodvalue="your.pkg.YourAction.factoryMethod"/>
   <attr name="displayName" bundlevalue="your.pkg.Bundle#key"/>
   <attr name="iconBase" stringvalue="your/pkg/YourImage.png"/>
   <!-- if desired: <attr name="noIconInMenu" boolvalue="true"/> -->
   <!-- if desired: <attr name="asynchronous" boolvalue="true"/> -->
 </file>
 
In case the "delegate" is not just ActionListener, but also Action, the returned action acts as a lazy proxy - it defers initialization of the action itself, but as soon as it is created, it delegates all queries to it. This way one can create an action that looks statically enabled, and as soon as user really uses it, it becomes active - it can change its name, it can change its enabled state, etc.

Parameters:
delegate - the task to perform when action is invoked
displayName - the name of the action
iconBase - the location to the actions icon
noIconInMenu - true if this icon shall not have an item in menu
Since:
7.3

checkbox

public static Action checkbox(String preferencesNode,
                              String preferencesKey,
                              String displayName,
                              String iconBase,
                              boolean noIconInMenu)
Creates action which represents a boolean value in Preferences. When added to a menu the action is presented as a JCheckBox. This method can also be used from XML Layer directly by following XML definition:
 <file name="your-pkg-action-id.instance">
   <attr name="preferencesNode" methodvalue="method-returning-Preferences-instance" or
                                   methodvalue="method-returning-Lookup-that-contains-Preferences-instance" or
                                   stringvalue="see below for the preferencesNode parameter description"
 />
   <attr name="preferencesKey" stringvalue="preferences-key-name"/>
   <attr name="instanceCreate" methodvalue="org.openide.awt.Actions.checkbox"/>
   <attr name="displayName" bundlevalue="your.pkg.Bundle#key"/>
   <attr name="iconBase" stringvalue="your/pkg/YourImage.png"/>
   <!-- if desired: <attr name="noIconInMenu" boolvalue="true"/> -->
   <!-- if desired: <attr name="asynchronous" boolvalue="true"/> -->
 </file>
 

Parameters:
preferencesNode - It's one of:
  • Absolute path to preferences node under NbPreferences.root().
  • "system:" followed by absolute path to preferences node under Preferences.systemRoot().
  • "user:" followed by absolute path to preferences node under Preferences.userRoot().
preferencesKey - name of the preferences key.
displayName - the name of the action
iconBase - the location to the actions icon
noIconInMenu - true if this icon shall not have an item in menu
Since:
7.17

callback

public static ContextAwareAction callback(String key,
                                          Action fallback,
                                          boolean surviveFocusChange,
                                          String displayName,
                                          String iconBase,
                                          boolean noIconInMenu)
Creates new "callback" action. Such action has an assigned key which is used to find proper delegate in ActionMap of currently active component.

This action can be lazily declared in a layer file using following XML snippet:

 <file name="action-pkg-ClassName.instance">
   <attr name="instanceCreate" methodvalue="org.openide.awt.Actions.callback"/>
   <attr name="key" stringvalue="KeyInActionMap"/>
   <attr name="surviveFocusChange" boolvalue="false"/> <!-- defaults to false -->
   <attr name="fallback" newvalue="action.pkg.DefaultAction"/> <!-- may be missing -->
   <attr name="displayName" bundlevalue="your.pkg.Bundle#key"/>
   <attr name="iconBase" stringvalue="your/pkg/YourImage.png"/>
   <!-- if desired: <attr name="noIconInMenu" boolvalue="true"/> -->
   <!-- if desired: <attr name="asynchronous" boolvalue="true"/> -->
 </file>
 

Parameters:
key - the key to search for in an ActionMap
surviveFocusChange - true to remember action provided by previously active component even some other component is currently active
fallback - action to delegate to when no key found. Use null to make the action disabled if delegate assigned to key is missing
displayName - localized name of the action (including ampersand)
iconBase - the location to the action icon
noIconInMenu - true if this icon shall not have an item in menu
Returns:
creates new action associated with given key
Since:
7.10

context

public static ContextAwareAction context(Class<?> type,
                                         boolean single,
                                         boolean surviveFocusChange,
                                         ContextAwareAction delegate,
                                         String key,
                                         String displayName,
                                         String iconBase,
                                         boolean noIconInMenu)
Creates new "context" action, an action that observes the current selection for a given type and enables if instances of given type are present. Common interfaces to watch for include Openable, Editable, Closable, Viewable, and any interfaces defined and exposed by various other APIs.

Actions of this kind can be declared in layer file using following XML snippet:

 <file name="action-pkg-ClassName.instance">
   <attr name="instanceCreate" methodvalue="org.openide.awt.Actions.context"/>
   <attr name="type" stringvalue="org.netbeans.api.actions.Openable"/>
   <attr name="selectionType" stringvalue="ANY"/> <-- or EXACTLY_ONE -->
   <attr name="delegate" newvalue="action.pkg.YourAction"/>
 
   <!--
      Similar registration like in case of "callback" action.
      May be missing completely:
   -->
   <attr name="key" stringvalue="KeyInActionMap"/>
   <attr name="surviveFocusChange" boolvalue="false"/> 
   <attr name="displayName" bundlevalue="your.pkg.Bundle#key"/>
   <attr name="iconBase" stringvalue="your/pkg/YourImage.png"/>
   <!-- if desired: <attr name="noIconInMenu" boolvalue="true"/> -->
   <!-- if desired: <attr name="asynchronous" boolvalue="true"/> -->
 </file>
 
In the previous case there has to be a class with public default constructor named action.pkg.YourAction. It has to implement ContextAwareAction interface. Its ContextAwareAction.createContextAwareInstance(org.openide.util.Lookup) method is called when the action is invoked. The passed in Lookup contains instances of the type interface, actionPerformed is then called on the returned clone.

Alternatively one can use support for simple dependency injection by using following attributes:

 <file name="action-pkg-ClassName.instance">
   <attr name="instanceCreate" methodvalue="org.openide.awt.Actions.context"/>
   <attr name="type" stringvalue="org.netbeans.api.actions.Openable"/>
   <attr name="delegate" methodvalue="org.openide.awt.Actions.inject"/>
   <attr name="selectionType" stringvalue="EXACTLY_ONE"/>
   <attr name="injectable" stringvalue="pkg.YourClass"/>
   <attr name="displayName" bundlevalue="your.pkg.Bundle#key"/>
   <attr name="iconBase" stringvalue="your/pkg/YourImage.png"/>
   <!-- if desired: <attr name="noIconInMenu" boolvalue="true"/> -->
 </file>
 
where pkg.YourClass is defined with public constructor taking type:
 public final class YourClass implements ActionListener {
    Openable context;

    public YourClass(Openable context) {
      this.context = context;
    }

    public void actionPerformed(ActionEvent ev) {
       // do something with context
    }
 }
 
The instance of this class is created when the action is invoked and its constructor is fed with the instance of type inside the active context. actionPerformed method is called then.

To create action that handled multiselection one can use following XML snippet:

 <file name="action-pkg-ClassName.instance">
   <attr name="type" stringvalue="org.netbeans.api.actions.Openable"/>
   <attr name="delegate" methodvalue="org.openide.awt.Actions.inject"/>
   <attr name="selectionType" stringvalue="ANY"/>
   <attr name="injectable" stringvalue="pkg.YourClass"/>
   <attr name="displayName" bundlevalue="your.pkg.Bundle#key"/>
   <attr name="iconBase" stringvalue="your/pkg/YourImage.png"/>
   <!-- if desired: <attr name="noIconInMenu" boolvalue="true"/> -->
 </file>
 
Now the constructor of YourClass needs to have following form:
 public final class YourClass implements ActionListener {
    List<Openable> context;

    public YourClass(List<Openable> context) {
      this.context = context;
    }
  }
 

Parameters:
type - the object to seek for in the active context
single - shall there be just one or multiple instances of the object
surviveFocusChange - shall the action remain enabled and act on previous selection even if no selection is currently in context?
delegate - action to call when this action is invoked
key - alternatively an action can be looked up in action map (see callback(java.lang.String, javax.swing.Action, boolean, java.lang.String, java.lang.String, boolean))
displayName - localized name of the action (including ampersand)
iconBase - the location to the action icon
noIconInMenu - true if this icon shall not have an item in menu
Returns:
new instance of context aware action watching for type
Since:
7.10

org.openide.awt 7.23.1

Built on February 9 2011.  |  Portions Copyright 1997-2011 Sun Microsystems, Inc. All rights reserved.