Rcp Command FrameWork (转载)-优快云博客

本文链接：https://blog.youkuaiyun.com/dadi5200/article/details/83677857

Summary

From beginning on the Eclipse platform was designed for extensibility. Therefore nearly every aspect of the workbench's user interface has a corresponding contribution mechanism. While the Eclipse workbench has evolved from a pure IDE to the RCP platform a big zoo of of extension APIs was created for plug-in provider to facilitate the growing user interface capabilities. Eclipse 3.3 introduced a new and consolidated framework for user interaction with the Eclipse workbench which obsoletes several former extension points and interfaces. The glue within this framework are so called commands. This comprehensive article is targeted towards new Eclipse RCP developers as well as "pre 3.3 Eclipse developers" who want to catch up with new RCP patterns. Due to the included references and examples it may also serve as a companion for day-to-day development tasks.

This article applies to the Eclipse Project, release 3.4. For corrections and other issues with this article please use bugzilla entry #223445.

Draft by Marc R. Hoffmann, Mountainminds GmbH & Co. KG

DRAFT - September, 2008

TODO

Introduction

The Eclipse command framework is the result of long-term effort to streamline the way how user interaction is contributed to the Eclipse workbench. While Eclipse RCP has outgrown the extensible IDE towards a universal platform for all kind of technical and business applications more and more UI capabilities came into picture. The original APIs for facilitating all these capabilities became cumbersome and bloated.

The Original Action Contribution Design

To understand the reasons for introducing a new framework we will take a quick tour through the original contribution mechanisms. A good example for lack of required flexibility is JFace's interface, which abstracts a particular user action from specific widgets like menu items and tool bar buttons:

  interface IAction {
  
    void setText(String text);
    void setImageDescriptor(ImageDescriptor image);
    void setAccelerator(int keycode);
    void setEnabled(boolean enabled);
    void run();
    
    // ... more setters and getters
  }

Note what aspects are tightly coupled by this type definition: The textual label and menu icon, an keyboard accelerator, the enabled state as well as a particular implementation of the action which is directly included in the run() method. So what if you have different implementations of for the same user action depending on the context or even want to allow plug-in providers to supply their own specific implementations? What if you need to maintain several customizable keyboard accelerator schemes? How can the action's enablement dynamically get computed from some properties of the selected elements?

The extension points of the Eclipse workbench UI separate visual aspects from the actual action implementation. While icons and labels are declared in the extension attributes the actual execution is delegated to IActionDelegate implementations. Depending on the placement and activation context different extension points must be used:

org.eclipse.ui.actionSets: Action sets are contributions to the main menu and tool bar. Some abstraction from the implementation is possible by declaring a contributed action as retargetable. In this case parts can register local handlers via API.
org.eclipse.ui.editorActions: This extension point also allows contributions to the main menu and tool bar which are bound to a particular editor type.
org.eclipse.ui.actionSetPartAssociations: While the former extension point allows editor specific contributions to the main menu and tool bar this one provides a similar functionality for all parts including views: It controls the visibility of action sets depending whether a particular editor or part is active within the workbench window.
org.eclipse.ui.viewActions: Each view may have a local tool bar and pull-down menu. This is the extension point to populate them for particular view types.
org.eclipse.ui.popupMenus: For additions to context menus, either for specific views (viewerContribution) or for particular objects wherever they appear in the views (objectContribution).

Placing menu items or tool bar buttons requires the plug-in developer to pick the right extension points out of this list. On the other hand workbench locations like the status line can not be populated open at all with these extension points.

Moving to a new Architecture

The deficiencies with the original action framework were well identified long time ago. In 2003 bug #36968 ("Improve action contributions") has been opened stating that "the current action contribution story is diverse and complex, and the interactions between key bindings and retargetable actions, unclear". This bug has a reference to a even older issue filed at times when Eclipse bugzilla entries had four digit ids only: Bug #1989 from 2001 is about controlling visibility of menu items.

In 2005 a request for comments by Douglas Pollock named – among a long list of other important requirements – the main properties a new action framework should come with:

Unified concept for contributions to the workbench
Clear separation between behavior and presentation in the user interface

The same RFC proposes a framework centered around so called commands, which was adopted in several steps. While the resulting command framework is a clean and powerful solution it took some time to integrate all aspects into the Eclipse workbench. Starting with Eclipse 3.3 it became possible to rely on the new framework for most action contributions. Eclipse 3.4 opened the framework itself for custom extensions. And happily the 4-digit bug could finally set to resolved fixed in 2007.

The Command Framework

Involved Services
Structure of the article with links

The essential idea of the new approach for user interface contributions is an abstraction layer between the UI presentation and the behavior implementation. This abstraction manifests in so called commands. A command is neither the presentation nor a particular behavior implementation; it is an abstract representation of some semantical behavior. This diagram shows how the command sits between the UI presentation and different behavior implementations:

Figure xxx: The Command Abstraction

A good example for this concept is the copy to clipboard command found in nearly every desktop application. On the presentation side we may have a menu item for it in the Edit window menu, a tool bar button, occurrences in several context menus and the user will expect a short key like CTRL+C. On the other side we will need very different handler implementations for the copy command depending on the context: A file navigator will put the currently selected file references to the clip board, a text editor pieces of formatted text and an image viewer might deliver bitmap data to the clipboard. Other examples where the advantage of an abstraction becomes obvious are commands like delete, refresh or select all.

The command framework provides powerful and consistent contribution mechanisms for the presentation side as well as for handler implementations. Therefore every user action in new Eclipse applications should be implemented based on commands.

Commands

APIs Querying Commands
Command icons

As described in the introduction commands are a abstract representation representation of some semantical behavior only. For this purpose a command declaration comes with just a few properties:

Unique Identifier: A unique identifier allows references to the command.
Name: A display name for the user which also serves as the default label for associated menu items and default tool tip for tool bar buttons derived from this command.
Description: User readable description of the command.
Category Id: Commands are organized in categories, therefore every command should be assigned to one. The primary purpose is to help the user navigating the commands e.g. when creating custom key bindings.
Help Context Id: To interlink directly with the Eclipse help system commands might declare a help context id.

While there is a optional default handler property, the command is not required to have a reference to a particular implementation of its behavior. Commands may also declare parameters which can be passed at execution time. See section Parameterized Commands below for details.

Declaring Commands

Due to the abstract concept of commands they are typically declared globally via extension definitions in plugin.xml files. Therefore most commands are available for the entire life cycle of the workbench in all contexts. The corresponding extension point org.eclipse.ui.commands allows declaring commands and group them into categories:

  <extension point="org.eclipse.ui.commands">
     <category name="User Sessions"
               description="Management of user sessions"
               id="com.mountainminds.eclipse.examples.sessions" />
     <command name="Login"
              description="Login a new user"
              id="com.mountainminds.eclipse.examples.login"
              categoryId="com.mountainminds.eclipse.examples.sessions" />
     <command name="Logout"
              description="Logout the current user"
              id="com.mountainminds.eclipse.examples.logout"
              categoryId="com.mountainminds.eclipse.examples.sessions" />
  </extension>

As you can see a command definition consists of a name and description, a unique identifier and an optional category. There is no reference to an specific implementation and no reference to menu items or key bindings for the command. See the online documentation for a complete reference of the optional attributes of the extension point org.eclipse.ui.commands. As the command framework has been refined over the time this extension point carries several deprecated elements and attributes. If you follow the patterns described in this article there is no need to rely on any of the deprecated declaration mechanisms.

Before creating your own command always double-check whether one of the existing commands already provides the required semantic. You'll find a full list of the command predefined by the org.eclipse.ui bundle below.

Defining Commands Programmatically

In special situations you might also use the command service API to define commands programmatically. This can be useful if you retrieve the definitions from some other source than Eclipse' declarative XML based extensions. Due to the abstract nature of commands they typically exist for the entire life time of the contributing bundle and will not change dynamically. Therefore the plugin.xml based declaration described above is the typical approach for Eclipse applications. Anyway, here is an example how the ICommandService can be used to declare our sample category and commands.

  // Retrieve the Command Service
  ICommandService cs = (ICommandService) serviceLocator.getService(ICommandService.class);

  // Define Our Category
  Category category = cs.getCategory("com.mountainminds.eclipse.examples.sessions");
  category.define("User Sessions", "Management of user sessions");

  // Define Login Command
  Command login = cs.getCommand("com.mountainminds.eclipse.examples.login");
  login.define("Login", "Login a new user", category);

  // Define Logout Command
  Command logout = cs.getCommand("com.mountainminds.eclipse.examples.logout");
  logout.define("Logout", "Logout the current user", category);

See the section about services below to learn where you can retrieve a ICommandService instance. As command definitions are declared globally, plug-ins that register commands programatically are also responsible for cleaning them up at the end of their live cycle. So let's behave like a good Eclipse citizen and undefine our examples again:

  cs.getCommand("com.mountainminds.eclipse.examples.login").undefine();
  cs.getCommand("com.mountainminds.eclipse.examples.logout").undefine();
  cs.getCategory("com.mountainminds.eclipse.examples.sessions").undefine();

Predefined Commands `ISaveablePart.doSave()` method of the active editor. Other commands might be re-used in local contexts to implement specific behavior for a common concept. For example a Order Items view might implement a local handler for the Delete (`org.eclipse.ui.edit.delete`) command to remove the selected item from the shopping basket. Re-using existing command definitions for semantically similar operations is a good coding practice as it will lead to applications with consistent user experience: Whenever a particular item can be deleted the according command has the same icon, the expected key binding (the `Delete` key) is active and global menu entries like Edit → Delete are automatically enabled.

The org.eclipse.ui bundle comes with a set of predefined commands in several categories. These commands form the basic user operations of the workbench like opening views or saving editors. Most of them are probably required by any custom RCP application and have already global command handlers associated to them. For example the handler of the Save command will delegate to the

The following table list all categories and commands defined by the org.eclipse.ui bundle along with the respective command ids. For historical reasons the id naming scheme and categorization isn't consistent in all places. Unfortunately there are no Java constants for the command ids in Eclipse 3.4 (Issue #54581).

Name	ID
Category File	`org.eclipse.ui.category.file`
New	`org.eclipse.ui.newWizard`
Close	`org.eclipse.ui.file.close`
Close All	`org.eclipse.ui.file.closeAll`
Import	`org.eclipse.ui.file.import`
Export	`org.eclipse.ui.file.export`
Save	`org.eclipse.ui.file.save`
Save As	`org.eclipse.ui.file.saveAs`
Save All	`org.eclipse.ui.file.saveAll`
Print	`org.eclipse.ui.file.print`
Revert	`org.eclipse.ui.file.revert`
Restart	`org.eclipse.ui.file.restartWorkbench`
Refresh	`org.eclipse.ui.file.refresh`
Properties	`org.eclipse.ui.file.properties`
Exit	`org.eclipse.ui.file.exit`
Move...	`org.eclipse.ui.edit.move`
Rename	`org.eclipse.ui.edit.rename`
Close Others	`org.eclipse.ui.file.closeOthers`
Category Edit	`org.eclipse.ui.category.edit`
Undo	`org.eclipse.ui.edit.undo`
Redo	`org.eclipse.ui.edit.redo`
Cut	`org.eclipse.ui.edit.cut`
Copy	`org.eclipse.ui.edit.copy`
Paste	`org.eclipse.ui.edit.paste`
Delete	`org.eclipse.ui.edit.delete`
Content Assist	`org.eclipse.ui.edit.text.contentAssist.proposals`
Context Information	`org.eclipse.ui.edit.text.contentAssist.contextInformation`
Select All	`org.eclipse.ui.edit.selectAll`
Find and Replace	`org.eclipse.ui.edit.findReplace`
Add Bookmark	`org.eclipse.ui.edit.addBookmark`
Category Navigate	`org.eclipse.ui.category.navigate`
Go Into	`org.eclipse.ui.navigate.goInto`
Back	`org.eclipse.ui.navigate.back`
Forward	`org.eclipse.ui.navigate.forward`
Up	`org.eclipse.ui.navigate.up`
Next	`org.eclipse.ui.navigate.next`
Backward History	`org.eclipse.ui.navigate.backwardHistory`
Forward History	`org.eclipse.ui.navigate.forwardHistory`
Previous	`org.eclipse.ui.navigate.previous`
Toggle Link with Editor	`org.eclipse.ui.navigate.linkWithEditor`
Next Page	`org.eclipse.ui.part.nextPage`
Previous Page	`org.eclipse.ui.part.previousPage`
Collapse All	`org.eclipse.ui.navigate.collapseAll`
Show In	`org.eclipse.ui.navigate.showIn`
Category Window	`org.eclipse.ui.category.window`
New Window	`org.eclipse.ui.window.newWindow`
New Editor	`org.eclipse.ui.window.newEditor`
Quick Switch Editor	`org.eclipse.ui.window.openEditorDropDown`
Quick Access	`org.eclipse.ui.window.quickAccess`
Switch to Editor	`org.eclipse.ui.window.switchToEditor`
Show System Menu	`org.eclipse.ui.window.showSystemMenu`
Show View Menu	`org.eclipse.ui.window.showViewMenu`
Activate Editor	`org.eclipse.ui.window.activateEditor`
Maximize Active View or Editor	`org.eclipse.ui.window.maximizePart`
Minimize Active View or Editor	`org.eclipse.ui.window.minimizePart`
Next Editor	`org.eclipse.ui.window.nextEditor`
Previous Editor	`org.eclipse.ui.window.previousEditor`
Next View	`org.eclipse.ui.window.nextView`
Previous View	`org.eclipse.ui.window.previousView`
Next Perspective	`org.eclipse.ui.window.nextPerspective`
Previous Perspective	`org.eclipse.ui.window.previousPerspective`
Close All Perspectives	`org.eclipse.ui.window.closeAllPerspectives`
Close Perspective	`org.eclipse.ui.window.closePerspective`
Close Part	`org.eclipse.ui.file.closePart`
Customize Perspective	`org.eclipse.ui.window.customizePerspective`
Hide Editors	`org.eclipse.ui.window.hideShowEditors`
Lock the Toolbars	`org.eclipse.ui.window.lockToolBar`
Pin Editor	`org.eclipse.ui.window.pinEditor`
Preferences	`org.eclipse.ui.window.preferences`
Reset Perspective	`org.eclipse.ui.window.resetPerspective`
Save Perspective As	`org.eclipse.ui.window.savePerspective`
Show Key Assist	`org.eclipse.ui.window.showKeyAssist`
Toggle Toolbar Visibility	`org.eclipse.ui.ToggleCoolbarAction`
Category Help	`org.eclipse.ui.category.help`
Help Contents	`org.eclipse.ui.help.helpContents`
Help Search	`org.eclipse.ui.help.helpSearch`
Dynamic Help	`org.eclipse.ui.help.dynamicHelp`
Welcome	`org.eclipse.ui.help.quickStartAction`
Tips and Tricks	`org.eclipse.ui.help.tipsAndTricksAction`
About	`org.eclipse.ui.help.aboutAction`
Display Help	`org.eclipse.ui.help.displayHelp`
Category Views	`org.eclipse.ui.category.views`
Show View	`org.eclipse.ui.views.showView`
Category Perspectives	`org.eclipse.ui.category.perspectives`
Show Perspective	`org.eclipse.ui.perspectives.showPerspective`

Figure xxx: Commands defined in plug-in org.eclipse.ui

Parameterized Commands Key Bindings Handlers Services http://dev.eclipse.org/viewcvs/index.cgi/platform-ui-home/R3_1/contributions-proposal/requestForComments.html?revision=1.3

TODO

Menu Contributions

Example 1: "Hello World" command placed at all possible locations (base for screenshot above).
ui.menus extension point
Addressing scheme
Reference of all well known menu ids
Stateful items (toggle, check, radio)
Dynamic contributions, examples: history, customazible favourites, domain specific items (e.g. related Java types, calendar dates).
Creating custom controls in toolbars.
Image+Text Toolbars
Writing extensible plugins
In case you're project is an add-on to another product (e.g. the Eclipse IDE) try to be un-obtrusive and avoid prominent placement of menu items. If users installes several add-ons they would flood their workbench windows. Especially Command1, Command2 are most likely unapropriate places for add-in programs. Instead try to find appropriate locations where similar functionality can already be found and everybody will expect it. [TODO: Put on best practices list]
Eclipse Help Issue: "org.eclipse.ui.any.popup" must read "org.eclipse.ui.popup.any"

An important simplification that comes with the new command framework is the way how menus and tool bars can be populated. Now we have a single extension mechanism to contribute action items as well as other widgets to all possible locations within the workbench window. The following screen shows many examples where items can be placed:

Figure xxx: Possible menu contributions to the Eclipse workbench

With the new contribution framework the extension point org.eclipse.ui.menus is the only mechanism you need to know to populate tool bars and menus of the RCP workbench.

Purpose and properties
Default handler, specific/local handers
Nested IHandlerService implementations, scope of handlers
Declaring handlers via extension point (for enablement check only instantiated, when the bundle is activated
Declaring handlers via API
Handler lifecycle
UI element updates

Expressions

Complete Reference Where Expressions are used in RCP Extension points.
Examples for Common Tasks

org.eclipse.core.expressions.definitions:
org.eclipse.debug.ui.detailPaneFactories:
org.eclipse.debug.ui.launchShortcuts:
org.eclipse.debug.ui.memoryRenderings:
org.eclipse.ltk.*:
org.eclipse.ui.actionSets:
org.eclipse.ui.activities:
org.eclipse.ui.console.consolePageParticipants:
org.eclipse.ui.console.consolePatternMatchListeners:
org.eclipse.ui.decorators:
org.eclipse.ui.editorActions:
org.eclipse.ui.handlers:
org.eclipse.ui.menus:
org.eclipse.ui.navigator.linkHelper:
org.eclipse.ui.navigator.navigatorContent:
org.eclipse.ui.popupMenus:
org.eclipse.ui.propertyPages:
org.eclipse.ui.viewActions:

Example: ActionSet is active

Example: One ore more elements selected

  <with variable="selection">
    <count value="+"/>
  </with>

Example: Only Elements selected that adapt to IResource

Example: Exactly one element selected that adapts to IResource

Sources

Custom sources

List of involved services
Where to find IServiceLocators in the workbench
Service Nesting
Custom Services

Contexts

Debugging

Migrating old Code to the Command Framework

Adapters for Legacy Actions
Migrating to the ui.menues extension point

Example Plug-ins

Sample plug-ins demonstrating different kind of contribution scenarios, check org.eclipse.ui.examples.contributions
Generic command browser plug-in to explore and debug an existing RCP application, Browser: Workbench, Window, Page, View for Service Location

Best Practices Check List

Use the new extension point org.eclipse.ui.menu in favour of the former org.eclipse.ui.editorActions, org.eclipse.ui.viewActions and org.eclipse.ui.popupMenus.
Before defining a new command check for semantically similar global command definitions that can be re-used in the specific context.
Consider using a parameterized command instead of multiple different commands in case these commands just describe variations of the same behaviour.
Always register the viewers within your workbench parts (views and editors) as selection provider to make the command framework aware of the current selection.

References

Douglas Pollock (2005). Improve Action Contributions. Request for Comments at dev.eclipse.org
Paul Webster et al (2007). Platform Command Framwork. wiki.eclipse.org
http://wiki.eclipse.org/Platform_Command_Framework
Paul Webster et al (2008). Command Core Expressions. wiki.eclipse.org
http://wiki.eclipse.org/Command_Core_Expressions
Paul Webster et al (2008). Menu Contributions. wiki.eclipse.org
http://wiki.eclipse.org/Menu_Contributions
Paul Webster (2007). Menu Extension Mapping. wiki.eclipse.org
http://wiki.eclipse.org/Menus_Extension_Mapping
Basic workbench extension points using commands. Eclipse 3.4 Online Help
http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/guide/workbench_cmd.htm
Tonny Madsen (2007). Working with the menus extension point. blog.rcp-company.com
http://blog.rcp-company.com/2007/06/working-with-menus-extension-point.html
Karsten Voigt (2008). Configuring and adding menu items in Eclipse V3.3. IBM developerWorks
http://www.ibm.com/developerworks/library/os-eclipse-3.3menu/index.html
Paul Webster (2008). Using Commands and Menu Contributions. Tutorial at EclipseCon 2008
http://www.eclipsecon.org/2008/?page=sub/&id=221