Class Actions

java.lang.Object
org.openide.awt.Actions
public class Actions extends Object
Supporting class for manipulation with menu and toolbar presenters.

  • Field Details

  • Constructor Details

    • Actions

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

  • Method Details

    • findKey

      public static String findKey(org.openide.util.actions.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, org.openide.util.actions.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

      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, org.openide.util.actions.BooleanStateAction action, boolean popup)
      Deprecated.
      Please use 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, org.openide.util.actions.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 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, org.openide.util.actions.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"/>
   <!-- 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 org.openide.util.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"/> <!-- 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
      fallback - action to delegate to when no key found. Use null to make the action disabled if delegate assigned to key is missing
      surviveFocusChange - true to remember action provided by previously active component even some other component is currently active
      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 org.openide.util.ContextAwareAction context(Class<?> type, boolean single, boolean surviveFocusChange, org.openide.util.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"/>
 
   <!--
      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"/> -->
   <!-- since 7.33: <attr name="context" newvalue="org.my.own.LookupImpl"/> -->
 </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">
   <!-- Enable on certain type in Lookup -->
   <attr name="enableOnType" stringvalue="qualified.type.name"/>
 
   <!-- Monitor specific property in that type -->
   <attr name="enableOnProperty" stringvalue="propertyName"/>
 
   <!-- The property value, which corresponds to enabled action.
           Values "#null" and "#non-null" are treated specially.
   -->
   <attr name="enableOnValue" stringvalue="propertyName"/>
 
   <!-- Name of custom listener interface -->
   <attr name="enableOnChangeListener" stringvalue="qualifier.listener.interface"/>
 
   <!-- Name of listener method that triggers state re-evaluation  -->
   <attr name="enableOnMethod" stringvalue="methodName"/>
 
   <!-- Delegate to the action instance for final decision -->
   <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 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