Rcp Command FrameWork (Reprinted)

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 # 223,445.

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

Copyright © 2008 Mountainminds GmbH & Co. KG

DRAFT - September, 2008

Contents

  • 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:

  1. Unified concept for contributions to the workbench
  2. 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 eg 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"
               />
     <command name="Login"
              description="Login a new user"
             
              categoryId="com.mountainminds.eclipse.examples.sessions" />
     <command name="Logout"
              description="Logout the current user"
             
              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 EditDelete 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 (eg 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 (eg 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 IServiceLocator s 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

More Topics

  • Using Commands in Help Contents
  • Commands for non-UI applications
  • Stateful contribution items (toggle, check, radio)

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

Feedback


Please use bug entry 223445 to report any issues with this article.
  • del.icio.us
  • StumbleUpon
  • Digg
  • TwitThis
  • Mixx
  • Technorati
  • Facebook
  • NewsVine
  • Reddit
  • Google
  • LinkedIn
  • YahooMyWeb

Related Posts of Rcp Command FrameWork (Reprinted)

  • eclipse3.4 about hibernate tools BUG solution

    Publication and its connecting people: sys53 http://sys53.javaeye.com/ If you violate the copyright, please contact me promptly. eclipse3.4 about hibernate tools when used in error java.lang.NoClassDefFoundError: org / eclipse / ui / internal / util ...

  • Why do you need to Ruby

    The hardship of this we say that C, and C + + is a group, because they do not have a virtual execution environment, for the real computer environment, C can make C + + to do all the things, but the C demand for large-scale development should not sign ...

  • Rails caused by the speed of Session storage problem

    At. / Config / environment.rb to remove the following Note: Session storage allows the use of active_record_store way to test a very simple request: After testing will: Comment out this sentence, and then test the method. Same deployment, the same pr ...

  • What we all namespaces (namespace) deal with mechanisms to deal with the javascript?

    Project needs, the requirements of the JS's namespace management, so the Internet looking for relevant information at the relevant forums mootools find a: Now what kind of U.S. approach to the JS namespace realize the problem? Can share released ...

  • Robbin on the PHP / Ruby some concluding

    Robbin forward to the PHP forum on some conclusion, it is not picky:) collection of Quote PHP and Python / Ruby operating mechanism has an essential difference between: PHP are each HTTP request coming after the initialization of all resources (such ...

  • Ten most widely Javascript framework

    Reprint: CSDN Recently, the well-known technology development SYS-CON Media website lists the ten most widely Javascript framework, the article said, Javascript library has become a basic site design excellence, today almost all sites with Javascript or A

  • Understanding of JavaScript closures

    Understanding of JavaScript closures To become advanced JavaScript programmers, it is necessary to understand the closure. In this paper, ECMA 262 specification explain the closure of the internal working mechanism for JavaScript programmers understanding

  • ROR troubled long Axis2 web service calls to be initially resolved

    Problem: ROR how Axis2 call the web service Currently experiencing this problem, Google and Baidu found at numerous times, both at home and abroad have seen virtually no valuable information, the only help is a call ROR about. Net Services article (http:

  • Built environment using appfuse2.0 Express (myeclipse)

    http://blog.csdn.net/ljah/archive/2008/06/06/2516187.aspx Usually we use APPFUSE2.0 project into eclipse, the compiler can not be normal, can only use maven I feel very uncomfortable, after exploring and found that after such a configuration, it will make

  • Java technology: Eclipse explain the use of techniques

    Editor settings: Window -> Preferences -> Java-> Editor appearance: Display line number, emphasizing symmetry shown in square brackets, to emphasize that the existing line to show Print Margins its check, Tab width set 4, print made from the fiel

blog comments powered by Disqus
Recent
Recent Entries
Tag Cloud
Random Entries