1. © 2009 IBM Corporation 1 Commands in Eclipse 4: Understanding who does what Paul Webster – IBM Rational Canada Remy Suen – IBM Rational Canada 23 March 2011

2. © 2011 IBM Corporation. Licensed under EPL, v1.0 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 –Eclipse 4 compatibility ■ Remy Suen –Software Developer, Platform UI Committer –Works for IBM Rational Software since he joined the Eclipse TM Platform UI team in July 2009 –Works on everything.... Source If Applicable Commands in Eclipse 4: Understanding who does what

3. © 2011 IBM Corporation. Licensed under EPL, v1.0 3 Overview ■ Deep dive under the covers of the Eclipse 4 command framework ■ How handlers work in the system ■ Where handlers get their information Commands in Eclipse 3.x: the 10 most common patterns

4. © 2011 IBM Corporation. Licensed under EPL, v1.0 4 Commands ■ The concepts for commands in Eclipse 4 are similar to 3.x ■ A command is an abstraction of some semantic behaviour. – id, name, description, parameters ■ A command is not an implementation of that behaviour. ■ A command is not the visual presentation of that behaviour. Source If Applicable Commands in Eclipse 4: Understanding who does what

5. © 2011 IBM Corporation. Licensed under EPL, v1.0 5 Handlers ■ To do something, we need an implementation of that behaviour –A method we can execute ■ Has access to variables –activePart, selection, activeContexts ■ Has access to services –EModelService, ESelectionService ■ We need to understand where the handler gets its information Source If Applicable Commands in Eclipse 4: Understanding who does what

6. © 2011 IBM Corporation. Licensed under EPL, v1.0 6 Handlers – Pick One ■ In Eclipse 4 there is basic containment relationship of the “moving parts” ■ Workbench: Window: Perspective: View/Editor Source If Applicable Commands in Eclipse 4: Understanding who does what

7. © 2011 IBM Corporation. Licensed under EPL, v1.0 7 Handlers – Pick One ■ In Eclipse 4 model based applications, handlers can be contributed at most levels ■ There is one handler per command per level ■ The handler is either there, or it's not ■ When executing a command, a part is active ■ To find the appropriate handler –First we check the part –Then we check the window –Then we check the application Source If Applicable Commands in Eclipse 4: Understanding who does what

8. © 2011 IBM Corporation. Licensed under EPL, v1.0 8 Handlers – Do Something ■ Or as we say in the business, @Execute ■ All handlers must provide an @Execute method ■ @Execute public void execute(@Optional IStylingEngine engine, @Named(IServiceConstants.ACTIVE_SHELL) Shell shell) {... } ■ Parameter lookup follows our rules for Dependeny Injection... IEclipseContext ■ Invocation is treated differently than Injection Source If Applicable Commands in Eclipse 4: Understanding who does what

9. © 2011 IBM Corporation. Licensed under EPL, v1.0 9 Handlers – Do Something ■ @Execute public void execute(@Optional IStylingEngine engine, @Named(IServiceConstants.ACTIVE_SHELL) Shell shell) {... } ■ Ask for services by parameter type ■ Ask for variables using the @Named annotation –“activeShell” ■ Use @Optional if a null value is permitted Source If Applicable Commands in Eclipse 4: Understanding who does what

10. © 2011 IBM Corporation. Licensed under EPL, v1.0 10 Handlers – Can I do something? ■ A handler may provide a @CanExecute method ■ @CanExecute boolean canExecute(@Optional @Named(IServiceConstants.ACTIVE_SELECTION) Contact contact) { return contact != null; } ■ If no method is supplied, the answer defaults to true ■ Called by the framework when needed –Menu about to show –Toolbar items are a special case Source If Applicable Commands in Eclipse 4: Understanding who does what

11. © 2011 IBM Corporation. Licensed under EPL, v1.0 11 Handlers – What is available from the context? ■ We're still collecting variables and services that would be of interested in Eclipse 4 RCP applications –http://wiki.eclipse.org/E4/Contexts#Available_Services_in_Eclipse_e4http://wiki.eclipse.org/E4/Contexts#Available_Services_in_Eclipse_e4 –http://wiki.eclipse.org/E4/EAShttp://wiki.eclipse.org/E4/EAS ■ Examples of Services that are available –org.eclipse.e4.core.commands.EHandlerService –org.eclipse.e4.workbench.modeling.EPartService –org.eclipse.e4.workbench.modeling.EModelService –org.eclipse.e4.workbench.modeling.ESelectionService –org.eclipse.e4.ui.services.EContextService –org.eclipse.e4.core.services.StatusReporter –org.eclipse.e4.core.services.Logger –org.eclipse.e4.core.services.events.IEventBroker –org.eclipse.e4.workbench.ui.IPresentationEngine ■ Some services provide 2 levels of access, like EContextService and ACTIVE_CONTEXTS Source If Applicable Commands in Eclipse 4: Understanding who does what

12. © 2011 IBM Corporation. Licensed under EPL, v1.0 12 Handlers – What is available from the context? ■ Useful Model information is also available – MApplication app = context.get(MApplication.class); ■ Some of the variables listed in org.eclipse.ui.ISources – activeContexts – activeShell – e4ActivePart (MPart) – selection ■ Preferences using the @Preference annotation ■ @Execute public void execute(@Preference("someKey") String pref) {... } Source If Applicable Commands in Eclipse 4: Understanding who does what

13. © 2011 IBM Corporation. Licensed under EPL, v1.0 13 Differences: Eclipse 3.x and Eclipse 4 ■ Commands in Eclipse 4 have no state attributes ■ Enabled is not a state of the command in Eclipse 4, it's a question in context –The user-visible element asks the question –The model determines the context starting point Main menu: Window View menu: view part View context menu: view context menu ■ Multiple handler contributions for one command are a simple lookup in Eclipse 4. In Eclipse 3.x, conflict resolution is applied to a set of active handlers for a given command. Source If Applicable Commands in Eclipse 4: Understanding who does what

14. © 2011 IBM Corporation. Licensed under EPL, v1.0 14 Contexts – Where a handler gets its information ■ As with most communication, it's all about context ■ Introducing the IEclipseContext –Sits between the contributed code and the framework –Brokers interactions with the framework –Provides variables and services ■ public interface IEclipseContext { public T get(Class clazz); public Object get(String name); public void remove(String name); public void set(String name, Object value); } Source If Applicable Commands in Eclipse 4: Understanding who does what

15. © 2011 IBM Corporation. Licensed under EPL, v1.0 15 Contexts – Variables ■ IRendererFactory factory = context.get(IRendererFactory.class); Collection ids = (Collection) context.get("activeContexts"); ■ Services are accessed through their FQCN. ■ Each variable can either be a POJO or an IContextFunction ■ An IContextFunction represents a strategy for calculating a variable's value ■ IContextFunctions are evaluated on a context.get(*) request ■ IContextFunctions can be used to delay potentially expensive calculations ■ IContextFunction results are cached unless a dependency changes Source If Applicable Commands in Eclipse 4: Understanding who does what

16. © 2011 IBM Corporation. Licensed under EPL, v1.0 16 Contexts – Lookup Hierarchy ■ Contexts are hierarchical – requests that cannot be satisfied are delegated to a parent context Source If Applicable Context Commands in Eclipse 4: Understanding who does what

17. © 2011 IBM Corporation. Licensed under EPL, v1.0 17 Contexts – Lookup Hierarchy ■ We create child contexts to tweak or override aspects of the parent context's behaviour ■ We can customize application code's view of the world by inserting another context ■ public interface IEclipseContext { public void activate(); public IEclipseContext createChild(); public void deactivate(); public IEclipseContext getActiveChild(); public IEclipseContext getActiveLeaf(); public IEclipseContext getParent(); } Source If Applicable Commands in Eclipse 4: Understanding who does what

18. © 2011 IBM Corporation. Licensed under EPL, v1.0 18 Contexts – Lookup Hierarchy ■ Parent chain is constant. Child chain constantly changes. ■ A handler executes in the most active context Source If Applicable Context Commands in Eclipse 4: Understanding who does what

19. © 2011 IBM Corporation. Licensed under EPL, v1.0 19 Handlers - Recap ■ To do something, we need a method we can execute ■ The handler must have access to the application state –Data –Services ■ The information comes from the IEclipseContext hierarchy. It provides application state while allowing that state to be customized within difference scopes of the application. Source If Applicable Commands in Eclipse 4: Understanding who does what

20. © 2011 IBM Corporation. Licensed under EPL, v1.0 20 More Information ■ You can get general information from the wiki: –http://wiki.eclipse.org/E4http://wiki.eclipse.org/E4 –http://wiki.eclipse.org/E4/EAShttp://wiki.eclipse.org/E4/EAS –http://wiki.eclipse.org/E4/Contextshttp://wiki.eclipse.org/E4/Contexts ■ You can contact us and ask questions: –On IRC: irc://freenode.net/#eclipse-e4 –On the mailing list: https://dev.eclipse.org/mailman/listinfo/e4- devhttps://dev.eclipse.org/mailman/listinfo/e4- dev –On the newsgroup: http://www.eclipse.org/forums/ Eclipse Projects > e4http://www.eclipse.org/forums/ Source If Applicable Commands in Eclipse 4: Understanding who does what

21. © 2011 IBM Corporation. Licensed under EPL, v1.0 21 Legal Notices ■ Copyright © IBM Corp., 2007-2011. All rights reserved. This presentation and the source code in it are made available under the EPL, v1.0. ■ Eclipse and the Eclipse logo are trademarks of Eclipse Foundation, Inc. ■ IBM and the IBM logo are trademarks or registered trademarks of IBM Corporation, in the United States, other countries or both. ■ Rational and the Rational logo are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries or both. ■ Other company, product, or service names may be trademarks or service marks of others. ■ 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 Source If Applicable Commands in Eclipse 4: Understanding who does what