Section 4.2.  Tour of the Code

4.2. Tour of the Code Since the template did all the work of creating the code, you don't really know what it's doing. In this section, we walk through the generated code and point out the interesting bits. In fact, all the generated code is included hereit's pretty small. 4.2.1. Application The RCP SDK target you are using contains only framework libraries; you can't even run them. It's like having a JRE installedlots of great code, but it still needs to be told what to do. In regular Java systems, this is done by writing a class that has a main() method. In Eclipse, you write an application. An application is the entry point to a program or product. The application is run when the Runtime starts up, and when the application exits, Eclipse shuts down. The PDE wizard used the Hello RCP template to generate the org.eclipsercp.hyperbola.Application application below. Applications must implement IPlatformRunnable and thus a run() method. Think of this as your main() method. org.eclipsercp.hyperbola/Application public class Application implements IPlatformRunnable { public Object run(Object args) throws Exception { Display display = PlatformUI.createDisplay(); try { int returnCode = PlatformUI.createAndRunWorkbench( display, new ApplicationWorkbenchAdvisor()); if (returnCode == PlatformUI.RETURN_RESTART) { return IPlatformRunnable.EXIT_RESTART; return IPlatformRunnable.EXIT_OK; } finally { display.dispose(); } } } The critical code is marked in bold. The application creates a Display and then starts an Eclipse Workbench by calling PlatformUI.createAnd RunWorkbench(Display, WorkbenchWindowAdvisor). This opens a window and simply loops forever, handling user-generated events such as mouse clicks, key presses, and mouse moves. The event loop finally returns when the last window is closed or when it is explicitly told to exit. Before returning from the application, the created Display must be disposed to free any allocated system resources. Note You can do just about anything you want in your application. In our example, we start up a UI, but you could just as well start a server of some sort. In other words, the Eclipse RCP can also be used for non-graphical applications. The application class must be linked into the Eclipse Runtime's applications extension point, as shown in Figure 4-7, thus making the Runtime aware of the application. Just as many Java JARs on a classpath may contribute classes that have a main() method, many Eclipse plug-ins in a system may contribute application extensions. In fact, one plug-in can contribute many applications. When Eclipse is started, one and only one application is identified as the application to run. Again, this is directly analogous to standard Java, where you specify exactly one class to run on the command line. More on this in the section on running and debugging. 4.2.2. WorkbenchAdvisor In the application code shown above, we glossed over the Application WorkbenchAdvisor that was instantiated and passed into PlatformUI.createAndRunWorkbench(). In fact, this is the most important part of the story. As the name implies, a WorkbenchAdvisor tells the Workbench how to behavehow to draw, what to draw, etc. In particular, our Application WorkbenchAdvisor identifies two things: The initial perspective to be shown. The WorkbenchWindowAdvisor to be used. org.eclipsercp.hyperbola/ApplicationWorkbenchAdvisor public class ApplicationWorkbenchAdvisor extends WorkbenchAdvisor { private static final String PERSPECTIVE_ID = "org.eclipsercp.hyperbola.perspective"; public WorkbenchWindowAdvisor createWorkbenchWindowAdvisor( IWorkbenchWindowConfigurer configurer) { return new ApplicationWorkbenchWindowAdvisor(configurer); } public String getInitialWindowPerspectiveId() { return PERSPECTIVE_ID; } } 4.2.3. Perspective The initial perspective is identified by its extension identifier, as shown at the top right of Figure 4-7. The extension gives the perspective a human-readable name and specifies a class that defines the layout of the perspective. The given class must implement the IPerspectiveFactory interface and the createInitial Layout(IPageLayout) method. The org.eclipsercp.hyperbola.Perspective perspective is a trivial implementation that simply does nothing. This perspective is added in later chapters. org.eclipsercp.hyperbola/Perspective public class Perspective implements IPerspectiveFactory { public void createInitialLayout(IPageLayout layout) { } } Note As with applications, there may be many perspectives in the system. The application's WorkbenchAdvisor identifies only one of these as the initial perspective. While WorkbenchAdvisors must define an initial perspective, that setting can be overridden using preferences. This is detailed in Chapter 16, "Perspectives, Views, and Editors." 4.2.4. WorkbenchWindowAdvisor Every window in your application has a WorkbenchWindowAdvisor that guides the UI in rendering the window. Window advisors are consulted at various points in the lifecycle of a window (e.g., preWindowOpen() and postWindowCreate()) and have the opportunity to control the creation of the window's contents. You will visit Hyperbola's window advisor often as you update the look and feel of the application. The ApplicationWorkbenchWindowAdvisor customizes Hyperbola windows. In the preWindowOpen() method, it sets the initial size and title of the window and hides the status line and toolbar. While we are looking at preWindowOpen(), go ahead and change the initial size of the window to make it a bit smaller than the default. Don't forget to save the file when you are done. org.eclipsercp.hyperbola/ApplicationWorkbenchWindowAdvisor public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor { public ApplicationWorkbenchWindowAdvisor( IWorkbenchWindowConfigurer configurer) { super(configurer); } public ActionBarAdvisor createActionBarAdvisor( IActionBarConfigurer configurer) { return new ApplicationActionBarAdvisor(configurer); } public void preWindowOpen() { IWorkbenchWindowConfigurer configurer = getWindowConfigurer(); configurer.setInitialSize(new Point(250, 350)); configurer.setShowCoolBar(false); configurer.setShowStatusLine(false); configurer.setTitle("Hyperbola"); } } 4.2.5. ActionBarAdvisor ActionBarAdvisors create the actions needed for a window and position them in the window. They are instantiated using createActionBarAdvisor() on WorkbenchWindowAdvisor. Since we are just starting out and have no actions, the ActionBarAdvisor is largely empty. org.eclipsercp.hyperbola/ApplicationActionBarAdvisor public class ApplicationActionBarAdvisor extends ActionBarAdvisor { public ApplicationActionBarAdvisor(IActionBarConfigurer configurer) { super(configurer); } protected void makeActions(IWorkbenchWindow window) { } protected void fillMenuBar(IMenuManager menuBar) { } } Note The name ActionBarAdvisor does not do justice to this class. It actually controls what appears in the menu bar, the cool bar, also known as the toolbar, and the status line. As such, it is a focal point of customization in RCP applications. 4.2.6. Summary That's it. You have seen all the code involved in creating the simple Hyperbola RCP application. Just to be sure you got all the steps right, use the Samples Manager detailed in Chapter 3, "Tutorial Introduction," to compare your workspace to the sample code for this chapterthey should be identical (except for possible formatting differences). Of course the application does not do much; it doesn't even have any actionsnor does it have any branding or splash screens. Nonetheless, the example shows how the major parts of the Eclipse RCP fit together.