Actions (UI Utilities API)

java.lang.Object
- org.openide.awt.Actions

```
public class Actions
extends Object
```
Supporting class for manipulation with menu and toolbar presenters.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`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`. Instead create a regular `JMenu` and add items to it (or use `DynamicMenuContent`).
`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

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ACTION_VALUE_TOGGLE` Key for `Action.getValue(java.lang.String)` to indicate that the action should be presented as toggle, if possible.
`static String`	`ACTION_VALUE_VISIBLE` Action may `Action.putValue(java.lang.String, java.lang.Object)` this value to indicate that, if not enabled, it should not be visible at all.

Constructor Summary

Constructors
Constructor and Description

Actions()
Deprecated.
should not be used

Constructors
Constructor and Description
`Actions()` Deprecated. should not be used

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`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 `Actions.connect(AbstractButton, Action)` instead.
`static void`	`connect(JCheckBoxMenuItem item, Action action, boolean popup)` Attaches checkbox menu item to boolean state action.
`static void`	`connect(JCheckBoxMenuItem item, BooleanStateAction action, boolean popup)` Deprecated. Please use `Actions.connect(javax.swing.JCheckBoxMenuItem, javax.swing.Action, boolean)`. Have your action to implement properly `Action.getValue(java.lang.String)` for `Action.SELECTED_KEY`
`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 `Actions.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 Action`	`forID(String category, String id)` Locates a specific action programmatically.
`static String`	`keyStrokeToString(KeyStroke stroke)` Creates nice textual representation of KeyStroke.
`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

- Field Detail
  - ACTION_VALUE_VISIBLE
```
public static final String ACTION_VALUE_VISIBLE
```
    Action may Action.putValue(java.lang.String, java.lang.Object) this value to indicate that, if not enabled, it should not be visible at all. Presenters may honour the request by removing action's presenter from the UI.
    
    See Also:
    
    Constant Field Values
  - ACTION_VALUE_TOGGLE
```
public static final String ACTION_VALUE_TOGGLE
```
    Key for Action.getValue(java.lang.String) to indicate that the action should be presented as toggle, if possible. Presenters may create checkbox item, toggle button etc. This is to avoid accessing the Action.SELECTED_KEY actual value during presenter construction, as evaluation may be expensive.
    
    Since:
    
    7.71
    
    See Also:
    
    Constant Field Values
- 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
  - keyStrokeToString
```
public static String keyStrokeToString(KeyStroke stroke)
```
    Creates nice textual representation of KeyStroke. Modifiers and an actual key label are concated per the platform-specific convention
    
    Parameters:
    
    stroke - the KeyStroke to get description of
    
    Returns:
    
    String describing the KeyStroke
  - connect
```
@Deprecated
public static void connect(JMenuItem item,
                                       SystemAction action,
                                       boolean popup)
```
    Deprecated. Use Actions.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
    By default icons are not visible in popup menus. This can be configured via branding.
    
    Parameters:
    
    item - menu item
    
    action - action
    
    popup - create popup or menu item
    
    Since:
    
    3.29
  - connect
```
@Deprecated
public static void connect(JCheckBoxMenuItem item,
                                       BooleanStateAction action,
                                       boolean popup)
```
    Deprecated. Please use Actions.connect(javax.swing.JCheckBoxMenuItem, javax.swing.Action, boolean). Have your action to implement properly Action.getValue(java.lang.String) for Action.SELECTED_KEY
    
    Attaches checkbox menu item to boolean state action.
    
    Parameters:
    
    item - menu item
    
    action - action
    
    popup - create popup or menu item
  - connect
```
public static void connect(JCheckBoxMenuItem item,
                           Action action,
                           boolean popup)
```
    Attaches checkbox menu item to boolean state action. The presenter connects to the Action.SELECTED_KEY action value
    
    Parameters:
    
    item - menu item
    
    action - action
    
    popup - create popup or menu item
    
    Since:
    
    7.71
  - connect
```
@Deprecated
public static void connect(AbstractButton button,
                                       SystemAction action)
```
    Deprecated. Use Actions.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 set*Icon will be called on the button with loaded icons using the iconBase. E.g. if the value for "iconBase" is "com/mycompany/myIcon.gif" then the following images are tried
    - setIcon with "com/mycompany/myIcon.gif"
    - setPressedIcon with "com/mycompany/myIcon_pressed.gif"
    - setDisabledIcon with "com/mycompany/myIcon_disabled.gif"
    - setRolloverIcon with "com/mycompany/myIcon_rollover.gif"
    - setSelectedIcon with "com/mycompany/myIcon_selected.gif"
    - setRolloverSelectedIcon with "com/mycompany/myIcon_rolloverSelected.gif"
    - setDisabledSelectedIcon with "com/mycompany/myIcon_disabledSelected.gif"
    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, 7.32 for set*SelectedIcon
  - 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. Rather than using this method directly, use ActionRegistration annotation:
```
 @ActionRegistration(displayName="#key")
 @ActionID(id="your.pkg.action.id", category="Tools")
 public final class Always implements ActionListener {
   public Always() {
   }
   public void actionPerformed(ActionEvent e) {
    // your code
   }
 }
 
```
    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"/>
   
   
 </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"/>
   
   
 </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. You can use ActionRegistration annotation to register your action:
```
 @ActionRegistration(displayName="#Key", key="KeyInActionMap")
 @ActionID(category="Tools", id = "action.pkg.ClassName")
 public final class Fallback implements ActionListener {
   public void actionPerformed(ActionEvent e) {
    // your code
   }
 }
 
```
    If you want to create callback action without any fallback implementation, you can annotate any string constant:
```
 @ActionRegistration(displayName = "#Key")
 @ActionID(category = "Edit", id = "my.field.action")
 public static final String ACTION_MAP_KEY = "KeyInActionMap";
 
```
    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"/> 
   <attr name="fallback" newvalue="action.pkg.DefaultAction"/> 
   <attr name="displayName" bundlevalue="your.pkg.Bundle#key"/>
   <attr name="iconBase" stringvalue="your/pkg/YourImage.png"/>
   
   
 </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. Use ActionRegistration annotation to register your action::
```
 @ActionRegistration(displayName="#Key")
 @ActionID(category="Tools", id = "action.pkg.YourClass")
 public final class YourClass implements ActionListener {
    Openable context;

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

    public void actionPerformed(ActionEvent ev) {
       // do something with context
    }
 }
 
```
    In case you are interested in creating multi selection action, just change parameters of your constructor:
```
 @ActionRegistration(displayName="#Key")
 @ActionID(category="Tools", id = "action.pkg.YourClass")
 public final class YourClass implements ActionListener {
    List<Openable> context;

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

    public void actionPerformed(ActionEvent ev) {
       // do something with context
    }
 }
 
```
    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"/>
 
   
   <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"/>
   
   
 </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"/>
   
 </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"/>
   
   
 </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;
    }
  }
 
```
    Further attributes are defined to control action's enabled and checked state. Attributes which control enable state are prefixed by "enableOn". Attributes controlling checked state have prefix "checkedOn":
```
 <file name="action-pkg-ClassName.instance">
   
   <attr name="enableOnType" stringvalue="qualified.type.name"/>
 
   
   <attr name="enableOnProperty" stringvalue="propertyName"/>
 
   
   <attr name="enableOnValue" stringvalue="propertyName"/>
 
   
   <attr name="enableOnChangeListener" stringvalue="qualifier.listener.interface"/>
 
   
   <attr name="enableOnMethod" stringvalue="methodName"/>
 
   
   <attr name="enableOnActionProperty" stringvalue="actionPropertyName"/>
 
   
 
 </file>
 
 
```
    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 Actions.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
  - forID
```
public static Action forID(String category,
                           String id)
                    throws IllegalArgumentException
```
    Locates a specific action programmatically. The action will typically have been registered using ActionRegistration.
    Normally an ActionReference will suffice to insert the action into various UI elements (typically using Utilities.actionsForPath(java.lang.String)), but in special circumstances you may need to find a single known action. This method is just a shortcut for using FileUtil.getConfigObject(java.lang.String, java.lang.Class<T>) with the correct arguments, plus using AcceleratorBinding.setAccelerator(javax.swing.Action, org.openide.filesystems.FileObject).
    
    Parameters:
    
    category - as in ActionID.category()
    
    id - as in ActionID.id()
    
    Returns:
    
    the action registered under that ID, or null
    
    Throws:
    
    IllegalArgumentException - if a corresponding ActionID would have been rejected
    
    Since:
    
    7.42

Class Actions

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ACTION_VALUE_VISIBLE

ACTION_VALUE_TOGGLE

Constructor Detail

Actions

Method Detail

findKey

keyStrokeToString

connect

connect

connect

connect

connect

connect

connect

setMenuText

cutAmpersand

alwaysEnabled

checkbox

callback

context

forID