Commands I

Motivation

Seit Eclipse 3.3 besteht mit dem Command-Framework ein einheitlicher, auf Extension-Points basierender Mechanismus, mit dem Plugins Kommandos deklarieren und diese in Menüs oder Toolbars der Anwendung einfügen können.

Dabei wird durch die deklarative Herangehensweise eine hohe Flexibilität und Erweiterbarkeit erreicht. So können Plugins beispielsweise bestehende Menüstrukturen erweitern oder zu einem vorhandenen Command ein neues Verhalten in einem bestimmten Kontext hinzufügen.

Ein weiterer Vorteil der Commands besteht darin, dass Menüs und Toolbars von der Workbench angezeigt werden können, ohne Klassen aus dem jeweiligen Plug-in zu laden, da alle zur Anzeige benötigten Informationen im plugin.xml enthalten sind. Dies macht sich insbesondere bei großen Anwendungen mit sehr vielen Commands hinsichtlich Startzeit und Performance bemerkbar.

Standard-Commands

Ein Command definiert eine ausführbare Aktion wie “Speichern”, “Schließen” oder “Aktualisieren”, nicht jedoch das Verhalten dieser Aktion. Gängige Standard-Commands werden von dem Plug-in org.eclipse.ui bereitgestellt, z.B.:

• org.eclipse.ui.file... save, saveAll, close, closeAll, refresh, exit
• org.eclipse.ui.edit... undo, redo, cut, copy, paste, delete

Eigene Commands

Eigene Commands können über den Extension Point org.eclipse.ui.commands registriert werden:

<extension point="org.eclipse.ui.commands">
    <command id="com.example.somecommand" name="SomeCommand"/>
</extension>

Commands in Menüs einfügen

Über den Extension Point org.eclipse.ui.menus können Sie Menüs erzeugen und Commands in Menüs einfügen:

Über eine menuContribution wird einer bestehenden Menüstruktur etwas hinzugefügt. Das Attribut locationURI gibt dabei die Stelle an, an der die neuen Einträge eingefügt werden sollen. Die entsprechenden Orte sind in der Klasse org.eclipse.ui.menus.MenuUtil spezifiziert:

• menu:<menu-id> Menü der Anwendung
• toolbar:<toolbar-id> Tool-Bar der Anwendung
• popup:<popupmenu-id> Popup-Menüs der Anwendung
• menu:org.eclipse.ui.main.menu Oberste Ebene des Hauptmenüs
• toolbar:org.eclipse.ui.main.toolbar Oberste Ebene der Toolbar
• popup:org.eclipse.ui.popup.any Alle Popup-Menüs der Anwendung

Optional können Sie mit ?after=menuId oder ?before=menuId auf die Reihenfolge der Menüpunkte Einfluss nehmen. In eine solche menuContribution können Sie direkt Untermenüs oder Commands einfügen:

<extension point="org.eclipse.ui.menus">
    <menuContribution
        locationURI="menu:org.eclipse.ui.main.menu?after=file">

        <menu id="com.example.somemenu" label="SomeMenu">

            <command
                commandId="com.example.somecommand"
                id="somemenuitem"
                mnemonic="somecommand"
                style="push">
            </command>

        </menu>
    </menuContribution>
</extension>

Handler

Das Verhalten von Commands wird separat durch Handler definiert. Über den Extension Point org.eclipse.ui.handlers kann zu einem Command eine Handler-Klasse registriert werden, die für die Ausführung des Commands zuständig ist:

<extension point="org.eclipse.ui.handlers">
    <handler
        commandId="com.example.somecommand"
        class="com.example.example.SomeCommandHandler"/>
</extension>

Handler sollten von org.eclipse.core.commands.AbstractHandler erben und die execute-Methode implementieren. Über statische Methoden auf der HandlerUtil-Klasse können Sie in einer Handler-Implementierung auf die Workbench zugreifen:

public class SomeCommandHandler extends AbstractHandler {

    public Object execute(ExecutionEvent event) throws ExecutionException {
        
        // Handle command here, Workbench can be accessed using HandlerUtil
        
        // Return value is reserved for future changes
        return null;
    }

}

Häufig benötigte HandlerUtil-Methoden sind:

• getActiveShell
• getActiveWorkbenchWindow
• getActiveEditor, getActiveEditorId
• getActivePart, getActivePartId
• getActiveSite
• getCurrentSelection

Actions und Commands, Probleme mit den Standard-Commands

Die Commands lösen das alte Action-Konzept der Eclipse Workbench ab. Sie werden in vielen Dokumenten und Webseiten noch Verweise auf dieses Konzept finden. Da die Commands seit Eclipse 3.4 ein vollwertiger Ersatz für die alten Konzepte, APIs und Extension Points sind und die Actions weithin als veraltetet betrachtet werden, werden hier nur noch die neuen Commands behandelt.

Leider ist für einige Commands ein kleiner Workaround notwendig, damit sie korrekt funktionieren. Dies betrifft insbesondere den Speichern-Command. Die alte Action muss noch bei der Workbench registriert werden, damit der neue Command korrekt funktioniert (siehe Eclipse Bug 270007). Sollten Sie auf das Problem stoßen, dass ein Command ausgegraut ist, obwohl er aktiv sein müsste, registrieren Sie die alte Action in der ActionBarAdvisor-Klasse der Anwendung:

public class ApplicationActionBarAdvisor extends ActionBarAdvisor {

    /* ... */

    protected void makeActions(IWorkbenchWindow window) {
        // Some commands need to be registered for the respective commands to
        // work. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=270007
        register(ActionFactory.SAVE.create(window));
        register(ActionFactory.HELP_CONTENTS.create(window));
        register(ActionFactory.HELP_SEARCH.create(window));
        register(ActionFactory.DYNAMIC_HELP.create(window));
        register(ActionFactory.RESET_PERSPECTIVE.create(window));
    }

}

Weitere Informationen

• Platform Command Framework (Eclipse Wiki)
• Eclipse Commands with Eclipse 3.5 (Galileo), Tutorial von Lars Vogel
• Eclipse Tips: Commands, sehr ausführlicher Blog-Post von Prakash G.R.
• Working with the menus extension point, Blogpost von Tonny Madsen