Eclipse RCP (Rich Client Platform) - 13.Menu와 toolbar application 객체

 

13. Menu and toolbar application objects

: Menu와 toolbar application 객체

 

13.1. Adding menu and toolbar entries

You can add menus and toolbars to your Eclipse application via the application model. These entries can be positioned at various places. You can, for example, add a menu to a window or a part. Each element define, directly or indirectly, one or several links to a class which is responsible for the execution. These classes are responsible for the behavior once the menu or toolbar entry is selected. Such a class is called handler class.

 

13.2. The usage of commands and handlers

The Eclipse application model allows you to specify commands and handlers.

 

The usage of the commands and handlers model element is optional. You can use the Direct MenuItem or a Direct ToolItem model elements. These entries define a reference to a class (handler class). An instance of this handler class is created by the framework and its annotated methods are called by the framework if necessary. Menus and toolbars support separators.

 

A command is a declarative description of an abstract action which can be performed, for example, save, edit or copy.

 

A command is independent from its implementation details. The Eclipse framework does not provide standard commands, e.g., you have to create all required commands in your application model.

 

The behavior of a command is defined via a handler. A handler model element points to a class (handler class) via the contributionURI property of the handler. This attribute is displayed as Class URI in the model editor.

 

Commands are used by the Handled MenuItem and Handled ToolItem model elements.

 

Prefer the usage of commands over the usage of direct (menu or tool) items. Using commands together with handlers allows you to define different handlers for different scopes (applications or part) and you can define key bindings for the handler’s associated commands.

 

13.3. Behavior annotations and dependency injection for handler classes

In a handler class exactly one method must be annotated with the @Execute annotation. In additional, you can also annotate one method with the @CanExecute annotation. If you annotate more than one method with the same annotation, the framework calls only one of them. The Eclipse runtime uses dependency injection to provide the parameters of the method. The purpose of these annotations are described in the following table.

 

Table 10. Behavior annotations for handler classes

Annotation	Description
@Execute	Marks the method which is responsible for the action of the handler class. The framework executes this method once the related user interface element, e.g., the menu entry, is selected.
@CanExecute	Marks a method to be visited by the Eclipse framework to check if the handler class can be executed. If a handler class returns false in this method, Eclipse disables the corresponding user interface element. For example, the save button is active if the handler class returns true in the @CanExecute method. The default for this method is true, which means, if the handler class can always be executed, it does not need to implement a @CanExecute method.

The following example demonstrates the implementation of a handler class.

 

package com.vogella.tasks.ui.handlers;

// import statements cut out
// ..

public class ExitHandler {
    @Execute
    public void execute(IWorkbench workbench) {
        workbench.close();
    }

    // NOT REQUIRED IN THIS EXAMPLE
    // just to demonstrates the usage of
    // the annotation
    @CanExecute
    public boolean canExecute() {
        return true;
    }

}

 

 

A handler instance does not have its own Eclipse context ( IEclipseContext). It is executed with the Eclipse context of the active model element which has a Eclipse context. In most common cases this is the context of the active part.

All required parameters should be injected into the method annotated with @Execute, as you want the handler class to retrieve its runtime information during execution.

 

주의 : To ensure that you get the expected values from the active context ALWAYS get the required values injected as parameters into your methods annotated with @Execute or @CanExecute.

 

13.4. Determining the relevant handler for a command

If a command is selected, the runtime determines the relevant handler for the command. The application model allows you to create a handler for the application, a window and a part.

 

Each command can have only one valid handler for a given scope. The Eclipse framework selects the handler most specific to the model element.

 

For example, if you have two handlers for the "Copy" command, one for the window and another one for the part then the runtime selects the handlers closest to model element which is currently selected by the user.

 

13.5. Evaluation of @CanExecute

A method annotated with @CanExecute is called by the framework, if a change in the Eclipse context happens. For example, if you select a new part. If the method returns false, the framework disables any menu and tool items that point to that command.

 

You can request the re-evaluation of the @CanExecute methods by sending out an event via the event broker.

 

// evaluate all @CanExecute methods
eventBroker.post(UIEvents.REQUEST_ENABLEMENT_UPDATE_TOPIC, UIEvents.ALL_ELEMENT_ID);

// evaluate a context via a selector
Selector s = (a selector that an MApplicationElement or an ID);
eventBroker.post(UIEvents.REQUEST_ENABLEMENT_UPDATE_TOPIC, s);


//See  https://bugs.eclipse.org/bugs/show_bug.cgi?id=427465 for details

 

 

13.6. Mnemonics

The application model allows you to define mnemonics. A mnemonic appears as an underlined letter in the menu when the user presses and holds the ALT key and allows the user to quickly access menu entries by keyboard.

You specify mnemonics by prefixing the letter intended to be the mnemonic with an ampersand (&) in the label definition. For example, if you use the the label &Save, the S will be underlined if the Alt key is pressed.

13.7. Naming schema for command and handler IDs

A good convention is to start IDs with the top level package name of your project and to use only lower case letters.

The IDs of commands and handlers should reflect their relationship. For example, if you implement a command with the com.example.contacts.commands.show ID, you should use com.example.contacts.handler.show as the ID for the handler. If you have more than one handler for one command, add another suffix to it, describing its purpose, e.g., com.example.contacts.handler.show.details.

In case you implement commonly used functions in your RCP application, e.g., save, copy, you should use the existing platform IDs, as some Eclipse contributions expect these IDs to better integrate with the OS (e.g., on Mac OS, preferences are normally placed under the first menu). A more complete list of command IDs is available in org.eclipse.ui.IWorkbenchCommandConstants.

 

Table 11. Default IDs for commonly used commands

Command	ID
Save	org.eclipse.ui.file.save
Save All	org.eclipse.ui.file.saveAll
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
Import	org.eclipse.ui.file.import
Export	org.eclipse.ui.file.export
Select All	org.eclipse.ui.edit.selectAll
About	org.eclipse.ui.help.aboutAction
Preferences	org.eclipse.ui.window.preferences
Exit	org.eclipse.ui.file.exit