1. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license Using Commands and Menu Contributions Understanding the Command Framework

2. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 2 About the Speaker Paul Webster  Senior Software Developer, Platform UI Committer  Works for IBM Rational Software since he joined the Eclipse TM Platform UI team in May 2005  Works with part lifecycle, commands/handlers, keybindings, and menu contributions

3. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 3 Tutorial – Person Information  Everybody needs to exist in a database somewhere!  An Eclipse RCP application can help.  The Eclipse framework already provides the concepts we need:  Perspective for layout  View (to see the People)  Editor (to update Person data)  Wizard (to add a Person to the database)  Commands (to do *anything*)  The implementation is in org.eclipse.ui.examples.contributions.

4. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 4 Tutorial – Person Information (cont.)  Code: org.eclipse.ui.examples.contributions in 3.4  This can be picked up from the I-build download page (as part of the examples zip), but not until 3.4 M6.  The latest version is available from HEAD in CVS: :pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse  The Info product can be launched by opening the info.product file and launching it as an eclipse app.

5. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 5 Command framework  A command is an abstraction of some semantic behaviour.  A command is not an implementation of that behaviour.  A command is not the visual presentation of that behaviour. <command categoryId="org.eclipse.ui.examples.contributions.commands.category" defaultHandler="org.eclipse.ui.examples.contributions.handlers.GlobalMenuHandler" id="org.eclipse.ui.examples.contributions.commands.globalCommand" name="%contributions.commands.globalCommand.name">

6. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 6 Handlers  A handler implements one behaviour for a command.  The active handler controls the command’s enabled state.  Handlers most commonly extend AbstractHandler.  Handlers are provided an application context in their execute(*) method. // © Copyright 2008 IBM Corp. All rights reserved. This source code // is made available under the terms of the Eclipse Public License, v1.0. // GlobalMenuHandler.java public Object execute(ExecutionEvent event) throws ExecutionException { IWorkbenchWindow window = HandlerUtil.getActiveWorkbenchWindowChecked(event); MessageDialog.openInformation(window.getShell(), ContributionMessages.SampleHandler_plugin_name, ContributionMessages.SampleHandler_hello_msg); return null; }

7. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 7 Handlers  The default handler case is useful, but also uninteresting.  Multiple handlers can register to handle behaviour for a command.  At any give time there can be either 0 or 1 active handlers for a command.  Handlers can be declaratively or programmatically activated. // © Copyright 2008 IBM Corp. All rights reserved. This source code is made available under the terms // of the Eclipse Public License, v1.0. // InfoView.java IHandlerService handlerService = (IHandlerService) getSite().getService(IHandlerService.class); countHandler = new AbstractHandler() { public Object execute(ExecutionEvent event) { // counting stuff in this view return null; } }; handlerService.activateHandler(VIEW_COUNT_ID, countHandler);

8. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 8 Handlers – pick one!  Say we want the refresh command to refresh information in the active view: RefreshRefreshFiles RefreshConnections Command Service Handler Service Source Application Context (activePartId == org.e.u.navigator) (activePartId == org.e.dtp.databases) activePartId

9. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 9 Handlers – more than one  The three most common handler contribution types are:  A default handler – this is a global handler, usually instantiated once  Handler for a part – this handler will deal with a specific type of view or editor  Handler for a selection – this handler is usually keyed off of the selection type  There are a couple of ways to contribute handlers at the different levels:  Declarative handlers use activeWhen and extract needed state from the application context.  Programmatic handlers are activated with part creation.

10. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 10 Now that we have commands …  … we need to execute them.  A keybinding allows key combinations to execute a command.  A number of factors determine if a keybinding is active:  Scheme, contexts, platform, and locale <key commandId="org.eclipse.ui.examples.contributions.view.edit" contextId="org.eclipse.ui.examples.contributions.view.context" sequence="M1+O" schemeId="org.eclipse.ui.examples.contributions.scheme">

11. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 11 Active Keybindings  Different workflows require that some keys operate differently, and in Eclipse that means execute different commands.  We don’t want our keybindings to be overly dynamic, however.  2 main ways that keybindings change are scheme and contexts:  A scheme is a group of keybindings … very static.  A context scopes a keybinding, and contexts change with the program’s focus.  For example, when editing text CTRL+D deletes a line. But when inputting in the Console view, CTRL+D produces the EOF

12. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 12 Active Keybindings (cont.)  The IBindingService gets the active contexts from the IContextService.  The IBindingService treats the contexts like an active tree.  The IBindingService prunes the tree depending on which component has focus.  This allows the binding service to look up the parameterized command for a key sequence. dialogAndWindow window textEditorScopejavaEditorScope debuggingjdt.debugging dialog

13. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 13 Questions  Questions?

14. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 14 Menu Contributions  Menus and Toolbars are also important for executing application functionality.  Menu Contributions create the menu and toolbar structures and insert them into the correct eclipse location. <command commandId="org.eclipse.ui.file.refresh" mnemonic="%command.refresh.mnemonic" style="push"> <command commandId="org.eclipse.ui.file.exit" mnemonic="%command.exit.mnemonic" style="push">

15. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 15 Menu Contribution Placement 1.Main Menu 2.Main Toolbar 3.View Toolbar 4.View Pulldown Menu 5.Context Menu 6.Trim Area 1 2 3 6 4 5

16. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 16 Menu Contribution Placement (cont.)  We call them Menu Contributions, but in eclipse there are 3 flavours:  menu – the main menu and the view dropdown menus (1 & 4)  popup – the view and editor context menus. These menus have special selection handling (5)  toolbar – view toolbars, the main coolbar, and the trim (2, 3, & 6)

17. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 17 Menu Contributions  The Menu Service and Menu Contributions were designed to deal with JFace based API.  ContributionManagers provide the update and dispose lifecycles for contribution items:  A ToolBarManager and MenuManager represent their corresponding SWT widgets  ContributionItems will render items into the menu or toolbar:  See ContributionItem#fill(Menu,int)  See ContributionItem#fill(ToolBar,int)  A ContributionItem belongs to only one ContributionManager.

18. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 18 Menu Contributions ElementTypeElementType menuMenuManagertoolbarToolBarManager separatorGroupMarker or Separator commandCommandContribution Item dynamicCompoundContribution Item controlWorkbenchWindow ControlContribution  org.eclipse.ui.menus elements are currently translated to:

19. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 19 Menu Contributions Lifecycle  Menu Contributions are generated on window creation  Menu Contributions are generated on IViewPart creation  Menu Contributions are generated on context menu SWT.Show IWorkbench Window ActionBarAdvisor Window SlaveMenuService PluginActionSet Builder IWorkbench Window ViewPart /IActionBars PartSite SlaveMenuService ViewActionBuilder IWorkbench Window WorkbenchPart PartSite SlaveMenuService ObjectAction ContributorManager

20. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 20 Menu Contribution Visibility  The IMenuService populates the MenuManagers and ToolBarManagers with ContributionItems.  The IMenuService works with the IEvaluationService to keep each ContributionItem’s visibility up to date.  The IEvaluationService is notified when variables change and re- evaluates any core expressions as needed.

21. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 21 Questions  Questions?

22. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 22 Services  All programmatic interaction with the menu/command framework is done through services.  The services are accessed through an IServiceLocator, which provides a localized access point.  The concept of a service locator was introduced in 3.2.  IWorkbench, IWorkbenchWindow, IPartSite, and IPageSite are all service locators.  These are not OSGi TM services.

23. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 23 Services  Services accessed through service locators usually provide “free” behaviours:  Scope the service provided if required  Clean up the service on dispose // © Copyright 2008 IBM Corp. All rights reserved. This source code is made available under the terms // of the Eclipse Public License, v1.0. // InfoView.java private void activateContext() { IContextService service = (IContextService) getSite().getService(IContextService.class); service.activateContext(MY_PART_CONTEXT); } // © Copyright 2008 IBM Corp. All rights reserved. This source code is made available under the terms // of the Eclipse Public License, v1.0. // InfoView.java public void createPartControl(Composite parent) { // creating my part as usual // then… IPersonService service = (IPersonService) getSite().getService(IPersonService.class); viewerInput = new ArrayList(service.getPeople()); service.addPersonChangeListener(personListener); }

24. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 24 Services  In 3.4 services can be contributed declaratively using org.eclipse.ui.services.  Services contributed this way tend to:  be hierarchical in nature.  scope aspects of their service to the local level.  clean up contributions at the local level when they are disposed. <serviceFactory factoryClass="org.eclipse.ui.examples.contributions.model.PersonServiceFactory">

25. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 25 Services  The service locator chain provides different service objects at each level: IWorkbenchServiceLocatorContextService IWorkbench Window ServiceLocator SlaveContext Service IWorkbench Part ServiceLocator SlaveContext Service ContextService Factory WorkbenchWindowExpression ActivePartExpression

26. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 26 Services  All programmatic interaction with the menu/command framework is done through services.  Common services used are:  IContextService – activate and deactivate contexts  ICommandService – defines and controls the command definitions  IHandlerService – manages handler activation and executes commands  IBindingService – performs lookups between commands and key sequences  IMenuService – populates the contribution managers and controls item visibility  IEvaluationService – public API in 3.4, evaluates core expressions against the application context

27. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 27 Sources  Variable sources are used in conjunction with core expressions for declarative enablement.  When a variable changes the source notifies any listeners that can then update their state.  In 3.4 source providers can be contributed declaratively using org.eclipse.ui.services.  Most of the workbench source providers are simply converting workbench events to variables. <variable name="org.eclipse.ui.examples.contributions.user" priorityLevel="activeSite">

28. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 28 Sources – variable priority level  Variables are assigned a priority level, loosely based on the priorities defined in org.eclipse.ui.ISources.  The IHandlerService uses these variable priorities to resolve conflicts between active handlers.  The general idea is that the most localized handler is appropriate over a more global one:  Global < Context < Active Editor < Active Part < Selection  When defining a variable, there are 7 “priority slots” to choose from.

29. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 29 Questions  Questions?

30. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 30 Evaluating Core Expressions  The IEvaluationService takes care of handlers activeWhen and enabledWhen, menus visibleWhen, and activities enabledWhen.  This service is one of the main listeners to source variable changes.  Expressions that use the changing variable are re-evaluated. <test property="org.eclipse.core.resources.contentTypeId" value="org.eclipse.ant.core.antBuildFile" />

31. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 31 Evaluating Core Expressions  The IEvaluationService fires a PropertyChangeEvent when the result of an expression changes.  In 3.4 expressions that use properties can be re-evaluated.  In general write core expressions using. <test property="org.eclipse.ui.examples.contributions.user.isAdmin" value="true" />

32. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 32 Evaluating Core Expressions - handlers  Change from an editor to a view; that changes activePart, activePartId, and activeSite.  PropertyChangeEvents update all changed IHandlerActivations.  When all changes have been updated, the IHandlerService resolves conflicts (using variable priority levels). RefreshRefreshFiles RefreshConnections Command Service Handler Service Source Application Context (activePartId == org.e.u.navigator) (activePartId == org.e.dtp.databases) activePartId

33. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 33 The End  Questions?

34. © Copyright 2008 IBM Corp. All rights reserved. This presentation is licensed under Creative Commons Att. Nc Nd 2.5 license 34 Legal Notices  IBM is a registered trademarks of International Business Corp. in the United States and other countries.  OSGi is a trademark or registered trademark of the OSGi Alliance in the United States and other countries.  Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.  Other company, product, or service names may be trademarks or service marks of others  This presentation is © Copyright 2008 IBM Corp. ; Source code in this presentation is made available under the EPL, v1.0, remainder of the presentation is licensed under Creative Commons Att. Nc Nd 2.5 license  THE INFORMATION DISCUSSED IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION, IT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, AND IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, SUCH INFORMATION. ANY INFORMATION CONCERNING IBM'S PRODUCT PLANS OR STRATEGY IS SUBJECT TO CHANGE BY IBM WITHOUT NOTICE.