$Revision: 1.5 $
Changes: available in CVS
Status: issue 25980

Main definitions and requirements for actions from user point of view

Kinds of actions

there are three different kinds of actions that the user may work with (reflected by the use cases).

• 1. stock actions. the user may not customize any part of this action other than the location. example: open file, save, cut/copy/paste, etc.
• 2. customizable actions. the user can customize the name of the action and the location. there may be other aspect of the action that the user can customize. example given, ant task where the user would customize build target.
• 3. scripted actions. user specifies name and location and the script that runs when the action is selected. example: recording an ide macro then making it accessible through button or menu.

Identity of actions

There can be many of the same action present in a menu or toolbar, but these presentations have the same properties like name, icon, shortcut.

Action mnemonics

Each action may have mnemonic, but it can also live without mnemonic set.
Resolving mnemonics conflicts (sorted in preferability order):

• get the swing bug fixed so pressing the letter key for items with the same mnemonic cycles through those items (enter selects).
• menu will detect duplicate and remove mnemonic from new item. (the current tools menu solution)
• menu will detect conflicts and try resolve. if no free letter is found then no mnemonic is used. (most desirable)

Context actions

User is able to add and customize also context actions, user can decide under which types of nodes action will appear.

Project sensitivity of actions

Some kinds of actions such as ant task actions may make sense only in context of some projects, they may be useless in others. Therefore, there should be a way how to define action in project context.
As a result, toolbar and ? perhaps also menu ? content can be different for different projects.

Reset possibilties

The user will be able to go back to default settings either [menu/tool]bar at a time or whole hog.

---

Use cases and scenarios for various users of actions system

Module writer creating and plugging new action into system

• 1. Create and implement action class, preferrably implementing javax.swing.event.ActionListener, or subclassing javax.swing.Action.
• 2. Modify layer of module, creating xml file with extension .action, which declaratively describes action. This file is placed under Templates/Actions/ folder using common layering technique. This file is referenced below as ActionDescr.action.
• 3. Link action implementation (created in step 1) to ActionDescr.action using string class or method identification.
• 4. Add references linking ActionDescr.action with menu, toolbar, popup menu folders to indicate where action should be placed.

• 3.1. Specify actions' icon and localizable display name in ActionDescr.action file.
• 3.2. Specify enable/disable logic, using list of cookies and fine grained attributes, into ActionDescr.action file.

Associating action with own component

In some cases different components share the same shortcut, menu item or toolbar button for completely different purposes. E. g. copy in editor differs a lot from a copy in explorer.

When a writer wants to associate its own action with a shared shortcut, he should implement its own javax.swing.Action and place it into the components ActionMap with a key of the shared shortcut (in case of copy string "copy").

Whenever the shortcut is activated from the context of the component, the dispatch looks for any association with key ("copy" in our case), finds the user action and invokes it.

This guarantees that any component can have its own reaction to shortcut/menu/toolbar item.

User wants to add new non-stock (parametrizable) action to the menu or toolbar

Please look at the original document to see why and how we should support following use case.

• 1. Cruise into Tools/Options, go to action templates pool area
• 2. Choose some category of templates (ant script, editor macro), invoke "Add action" action
• a. System shows special wizard for given category, used for specifying name, icon of of action and all other customizations.
• 4. Go through first part of wizard - choose name, icon, specify other properties like script, target (ant actions), help bookmark (help link actions)
• b. system prepares to create your action into a special "custom actions" pool, probably a section of the action templates hierarchy designated for this purpose in the UI.
• 5. Go through second part of wizard - add (install) action anywhere in menu, toolbar (possibly on more places), finish wizard
• c. System finally creates prepared action into a special "custom actions" pool, copies created action from anywhere in the action templates hierarchy to a menu, toolbar

user searches if there is any functionality she is missing in displayed menus and/or toolbars

• 1. Go to Options area, selects actions pool consisting of real actions (not templates)
• a. System shows content of actions pool, allowing for hierarchical and also plain view of all actions
• 2. Search through actions, chooses some action(s)
• b. System somehow supports fast search for actions name
• 3. Installs chosen action(s) into any menu, toolbar or popupmenu
• c. System allows to drag and drop selected actions directly on menu or toolbar, but allows also for clipboard way - copy and paste link to actions to menu or toolbar or popup menu hierarchical representation

user wants to add new simple, stock type action to menu, toolbar

Following use case is very similar to previous one, differences are that user is searching in action templates, not actions themselves.

• 1. Options area, go to action templates pool (shows only templates, not functional actions)
• 2. Search through templates, chooses some action template, invokes "add action"
• 4. Installs created action into any menu, toolbar or popupmenu

1

user wants customize existing non-stock action

TBD - ideas welcomed

user wants to attach shortcut to existing action

? through customization of action ? (previous use case)

user wants to attach mnemonic to existing action

? through customization of action ? (previous use case)

user wants to add context sensitive action

??? TDB - ideas welcomed

the user wants to manipulate [menu/tool]bars order

Both toolbars and menus order can be manipulated using operations it Tools/Options:

• 1. Tools/Options, select menus or toolbars area, select menu or toolbar to reorder
• 2. Perform actual reorder using:
  a) Drag and drop
  b) Popup menu invocation, MoveUp,MoveDown actions c) Popup menu invocation, dialog for changing order

Toolbars allow direct reordering using drag and drop, without need to go to options, while menus refuse such reordering.

---

Send comments and patches to nbdev@netbeans.org or attach them to issue 25980. Please create the patches to current version of the document.