Object
Represents the action service, which is responsible for managing all actions in the IDE. It provides a mechanism for extensions to declare actions and place them in menus, toolbars and other action containers. It also manages action scope to control their enabled state at a high-level. Actions may be scoped to particular document views, particular documents, and the focused view.
You add actions to the IDE through an extension-xml element in an extension.xml file. The ActionSvc provides an extension-xml-handler with an id of "urn:com-bea-ide:actions". The format for the action service XML is fairly complicated. This XML has two basic functions: declare the UI for actions (menus, toolbars, and so on) and declare the actions themselves.
Nearly all extensions will want to expose 'actions' to the user -- in the main menu, popup menus, toolbars, and/or keystroke combinations. The shell extension provides an XML handler, in conjunction with several 'com.bea.ide' interfaces to make this possible.
Similar to the XML for frames, the XML for actions contains a section where all actions supplied by an extension are declared as well as a section for the corresponding UI elements and the actions' position within those elements. Just as a view need not start out visible or in any specific layout, so actions also are not required to be anywhere in the UI. Toolbar, menu, and keyboard customization added in the future will allow users to expose otherwise hidden actions.
More importantly, you can also declare actions in a specific scope, or programmatically make them come and go from various UI elements (on top of the enabling and disabling found in most action UI frameworks, including Swing).
The XML to declare a set of actions in an extension.xml file looks like the following:
<extension-xml id="urn:com-bea-ide:actions"> <action-set> <action class="workshop.shell.action.FileOpenAction" label="&Open File...@ctrl+O" icon="workshop/shell/images/icons/open.gif"> <location priority="20" path="menu/file/file" /> </action> <action class="workshop.shell.action.FileNewAction" label="&New File..." tooltip="Create New File" icon="workshop/shell/images/icons/new.gif"> <location priority="10" path="menu/file/file" /> </action> </action-set> </extension-xml>
All actions must be declared inside a parent 'action-set' element. An extension may supply multiple action-sets. Action-sets support two attributes: 'scope' and 'extends'. Action-sets like the one above, with no 'scope' attribute, are given global scope. This means they may be accessible to the user regardless of the active view.
One example of a scoped action-set is the set of actions shown on the Service menu in version 1.0 of the IDE:
<action-set scope="jellybeans.modules.jws.JwsView"> <action class="jellybeans.modules.jws.action.AddMethodAction" label="Add Method" show-always="false"> <location priority="10" path="menu/service/add" /> </action> <action class="jellybeans.modules.jws.action.AddCallbackAction" label="Add Callback" show-always="false"> <location priority="20" path="menu/service/add" /> </action> </action-set>
The 'scope' attribute must contain the name for a class representing a document, document view or frame view. The Action Manager, Document Manager, and Frame Manager then work in conjunction to alter the UI based on the view that currently has focus. Currently, only document and document view scope are enabled.
In the preceding XML, the 'show-always' attribute on the action is set to 'false' (the default is 'true'). This means that when the scope is not visible, the actions are dynamically hidden on menus. When all menu items on a menu are hidden, the menu item that shows it is also hidden. For example, this scoping method makes the 'Services' menu appear only when the JWS design view is active.
If the 'show-always' attribute is left at its default of 'true', then UI elements will simply be grayed when the action is not in scope.
Regardless of the 'show-always' attribute's value, no methods on the action implementation will be called when the action is not in scope. In fact, the Action Manager will not create the action implementation class until it first comes into scope.
Finally, a scoped action-set may also extend another scoped action-set. Extending an action-set of an existing scope adds all the actions of the base scope into the extending scope. That is, the actions get shown or enabled just as they would for the base scope. For instance, a JWS source editor action-set might extend the Java source editor set:
<action-set scope="workshop.webservices.jws.editorkit.JwsView" extends="workshop.sourceeditor.java.editorkit.JavaView"> </action-set>
In this way, a JwsView can pick up all the commands provided by the JavaView, as well as add its own JWS-specific commands.
Drilling in on the 'action' element itself a little more, most of its attributes are fairly easy to understand:
IAction
.ResourceSvc
to load
the property named by the path.Finally, you can use the 'action' element's ‘location’ child element to specify an action's position in the UI. You can position actions in the UI in one of two ways: by using the 'location' element, or by using an action reference inside the UI definition, similar to the way frame-views are currently placed in a layout.
You specify an action's visible user interface (menus, popups, and toolbars) through the ‘action-ui’ element, as in the following example:
<action-ui> <action-group id="control" path="menu/view" priority="25" /> <menu id="service" priority="40" path="menu/main" label="&Service"> <action-group id="add" priority="10"> <menu id="addControl" priority="10" label="Add Con&trol"> <action-group id="availableControls" priority="10" /> </menu> </action-group> <action-group id="generate" priority="20" /> </menu> <toolbar id="service" priority="40" path="toolbar/main" label="Web Services"> <action-group id="main" priority="10"> <action-ref class="workshop.webservices.jws.actions.ExpandControlsAction" priority="10" /> </action-group> </toolbar> <popup id="jws-file" path="popup/main"> <action-group id="file" priority="10"> <action-ref class="workshop.shell.workspace.FileOpenAction" priority="10"/> </action-group> <action-group id="generate" priority="50"> <action-ref class="workshop.webservices.jws.actions.GenerateWSDLAction" priority="10" /> <action-ref class=" workshop.webservices.jws.actions.GenerateCTRLAction" priority="20" /> </action-group> </popup> </action-ui>
The ‘action-group’ element at the top adds a new action group to the ‘View’ menu, placing it with a priority of ‘25’. Action groups (and all other UI elements) are sorted with lowest priority numbers first. An action group is simply a place to put actions. If no actions are put in the action group, then it will not be visible in the UI. A separator will be shown between each visible command group.
Also, an action group is the only valid location for an action. These locations may be specified either using an ‘action’ reference element inside the specific group, or by using a ‘location’ element inside the action definition. A ‘location’ element, as shown above in the ‘action’ element, contains ‘path’ and ‘priority’ attributes. The path attribute specifies an action group in the hierarchy, and the priority attribute specifies the placement of the action item within that group.
Paths for actions specify a path through the UI hierarchy, followed by the final group in the last menu. For example, “menu/services/controls/add� would locate an action in the ‘add’ group, of the ‘controls’ sub-menu, of the ‘services’ menu, in the main menu; “popup/jws-file/generate� would locate an action in the ‘generate’ group, of the ‘jws-file’ popup.
Sub-menus and sub-popups may also specify a ‘path’ in order to be placed within a menu structure defined by another extension. These paths must also end with an action group.
Finally, action groups themselves may be similarly located using a path specification. These paths, however, should end with a menu, popup, or toolbar ID.
Palettes are also available; documentation will be forthcoming.
Object
ActionSvc
Nested Class Summary |
public static interface | ActionSvc.I
|
Field Summary |
protected static |
|
Constructor Summary |
Method Summary |
public static |
|
Methods from class java.lang. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
protected static ActionSvc.I
instance
Constructor Detail |
public ActionSvc()
Method Detail |
public static ActionSvc.I
get()
Obtains the service interface. This value is cached in the instance variable after the first use.