Creating global actions - Netbeans Platform 6.9.1

Understand Netbeans Platform 6.9.1 : Working with Action first

Let’s start by creating an Action to add new TopLevelTasks. It will create a new Task and display it in theTaskEditorPanel. The wizard that you will use in this section will simply create a new ActionListener and register it in the layer.xml file.

1. Right-click the TaskEditor module project node and choose New | Action. Choose Always Enabled as the Action type as shown in the following screenshot. Click Next>.
   
   
2. Choose Edit as the category of the Action, which determines where in the Options window's Keymap section it will be displayed.
3. Check the Global Menu Item checkbox. Now you can specify where the Action should appear in the menu bar. Choose Edit and then choose any position you want within the Edit menu. ClickNext>.
   
   You do not need to insert the Action in the toolbar at this time, nor assign a keyboard shortcut.
   
4. Name the Action NewTaskAction, with New as the Display Name. Optionally, specify an icon.
   
   
5. The actionPerformed method of the generated class NewTaskAction should create a new task and display it in a TaskEditor. Therefore, implement the method as follows:
   

   public void actionPerformed(ActionEvent e) {
    TaskManager taskMgr =
     Lookup.getDefault().lookup(TaskManager.class);
    if (null != taskMgr) {
      Task task = taskMgr.createTask();
      TaskEditorTopComponent win =
        TaskEditorTopComponent.findInstance(task);
      win.open();
      win.requestActive();
     }
   }

6. Run the application again. In the Edit menu there is now a New menu item. When you select the menu item, a new task is created in the TaskEditor.

To summarize, you have used the New Action wizard to create and register a new global action.

Examining the created files

The wizard created a simple ActionListener and registered it declaratively in the layer.xml file. As a result, the Actions folder now has an Edit subfolder, with this content in the layer.xml file:

<folder name="Actions">
 <folder name="Edit">
  <file name="com-netbeansrcp-taskeditor-NewTaskAction.instance">
    <attr name="delegate"
            newvalue="com.netbeansrcp.taskeditor.NewTaskAction"/>
    <attr name="displayName" bundlevalue="com.netbeansrcp.
            taskeditor.Bundle#CTL_NewTaskAction"/>
    <attr name="iconBase"
            stringvalue="com/netbeansrcp/taskeditor/icon.png"/>
    <attr name="instanceCreate"
            methodvalue="org.openide.awt.Actions.alwaysEnabled"/>
    <attr name="noIconInMenu" boolvalue="false"/>
   </file>
 </folder>
</folder>

Below the Edit folder, you see that an .instance file has been registered. That file represents an instance of the class for which it is registered. A set of attributes have been defined for the file:

Attributes	Description
delegate	The task to be performed when the Action is invoked.
displayName	The name of the Action, optionally pointing to a key in a bundle file.
iconBase	The location of the icon displayed for the Action.
instanceCreate	The instance created by the Action registration.
noIconInMenu	True if the Action does not display an icon.

In addition to the Action registration, the wizard has also created a Menu registration in the layer.xml file:

<folder name="Menu">
 <folder name="Edit">
  <file name="com-netbeansrcp-taskeditor-NewTaskAction.shadow">
   <attr name="originalFile" stringvalue="Actions/Edit/
                             com-netbeansrcp-taskeditor-
                             NewTaskAction.instance"/>
   <attr name="position" intvalue="100"/>
  </file>
 </folder>
</folder>

Within the Edit menu, a shadow file has been registered. Shadow files do not represent an instance, but serve as a symbolic reference, which is a familiar concept from the Unix world. If the Action instance had been directly attached to the menu, deleting the menu registration would cause the removal of the Actionalso. Thanks to the shadow files, removing the menu registration does not mean that the Actionregistration itself is removed, as the Action is registered separately. Also, when you decide to let the user invoke the Action from a toolbar or keyboard shortcut, you will again use shadow files. The Action will then be instantiated once, not each time it is invoked from the various places where the user invokes it from.

Enabling Users to Invoke actions

Let us now allow the user to invoke the action from both a toolbar button and a keyboard shortcut. After all, you can connect Actions to a variety of places. Actions are often attached, for example, to context menus within Explorer views, files of certain MIME types, or the editor. Often these Actions only make sense if they react in a context-sensitive way to the element from whose context menu they are called. This too is supported by the NetBeans Platform.

In this case, though, you simply want to have the Action always enabled and present in the toolbar, as well as from the menu bar where it is already found.

Toolbar

You have already seen how Actions are attached to menus. All that is involved is registering the corresponding Action class in the appropriate position in the layer.xml file. The same approach applies to toolbar buttons, where a new toolbar button is registered within a subfolder of the Toolbars folder, as follows in the layer.xml file:

<folder name="Toolbars">
 <folder name="Edit">
  <file name="com-netbeansrcp-taskeditor-NewTaskAction.shadow">
   <attr name="originalFile" stringvalue="Actions/Edit/com
      netbeansrcp-taskeditor-NewTaskAction.instance"/>
  </file>
 </folder>
</folder>

Toolbar buttons must have an icon
For toolbar buttons, it is important that you register an Action for which an icon has been registered in the layer.xml file. Otherwise no icon will be shown for the Action in the toolbar.

Run the application. The Action is now visible in the Edit toolbar.

In summary, you have attached an Action declaratively to a toolbar. You simply had to add a shadow file entry to the relevant location in the layer.xml file.

Keyboard

Actions can be triggered by pressing key combinations on a keyboard. As with menus and toolbars, a keybinding is implemented within the NetBeans Platform declaratively. The relevant folder in this case isShortcuts, while the file that you need to register there is again a shadow file.

Consequently, the name of the shadow file does not relate to the name of the Action that is to be triggered, but instead indicates the key combination in an Emacs-like notation, consisting of a modifier followed by a key designator. A hyphen is required between the modifier and designator.

The valid modifiers are listed as follows:

C—Ctrl key
A—Alt key
S—Shift key
M—Meta key, for example, Command button

As the Ctrl key on the Mac is different to what it is on a conventional PC, the NetBeans Platform further provides us a wildcard, with a corresponding key that varies depending on the operating system:

D—Standard Acceleration Key(for example, PC: Ctrl Key, Mac: Command Key)
O—Alternative Acceleration Key(for example, PC: Alt Key, Mac: Ctrl Key)

As a key designator, the name of each key constant is derived from java.awt.event.KeyEvent, with the leading VK_ of the constant name removed.

You now want to bind your action to the key combination standard accelerator key-A, which on the Mac isCommand-A, while on the PC it is Ctrl-A.

Following the preceding description, register the Action to be invoked from a shortcut as follows in thelayer.xml file:

<folder name="Shortcuts">
 <file name="D-A.shadow">
  <attr name="originalFile" stringvalue="Actions/Edit/
         comnetbeansrcp-taskeditor-NewTaskAction.instance" />
 </file>
</folder>

Run the application again. Press Ctrl-A on a PC or Command-A on a Mac. When you do so, you should see that the TaskLog registers the creation of a new task.

In summary, you have now declaratively bound an Action to a keyboard shortcut.