Komendy

org.eclipse.ui.commands

2.1

Punkt rozszerzenia org.eclipse.ui.commands służy do deklarowania komend i kategorii komend przy użyciu elementów command i category. Komenda jest abstrakcyjną reprezentacją semantycznego zachowania, ale nie jest rzeczywistą implementacją. Umożliwia to różnym programistom wnoszenie określonego zachowania w należących do nich częściach kodu. Na przykład komenda "wklej" może posiadać jedną implementację w edytorze, a inną w widgecie eksploratora. Takie implementacje są nazywane procedurami obsługi. Komendy można również traktować jako deklaracyjne wskaźniki funkcji lub procedury obsługi sygnału.

<!ELEMENT extension (category* , command* , commandParameterType* , keyBinding* , keyConfiguration* , context* , scope* , activeKeyConfiguration?)>

<!ATTLIST extension

id    CDATA #IMPLIED

name  CDATA #IMPLIED

point CDATA #REQUIRED>


<!ELEMENT command (defaultHandler? , state* , commandParameter*)>

<!ATTLIST command

category       CDATA #IMPLIED

description    CDATA #IMPLIED

id             CDATA #REQUIRED

name           CDATA #REQUIRED

categoryId     CDATA #IMPLIED

defaultHandler CDATA #IMPLIED

returnTypeId   CDATA #IMPLIED

helpContextId  CDATA #IMPLIED>

Ten element służy do definiowania komend. Komenda reprezentuje zgłoszone przez użytkownika żądanie wykonania określonej akcji. Powinna być semantycznie unikalna wśród innych komend. Nie należy definiować nowej komendy, jeśli istnieje już zdefiniowana komenda o takim samym znaczeniu. Jeśli istnieje więcej niż jeden element z tym samym atrybutem id, tylko ostatni zadeklarowany element (w kolejności wynikającej z odczytu rejestru wtyczek) jest uznawany za poprawny. Aby zrozumieć powiązanie między akcjami i komendami, należy zapoznać się z punktami rozszerzeń org.eclipse.ui.actionSets oraz org.eclipse.ui.editorActions.



<!ELEMENT category EMPTY>

<!ATTLIST category

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED>

W interfejsie użytkownika komendy są często organizowane z podziałem na kategorie, aby można było nimi łatwiej zarządzać. Ten element służy do definiowania tych kategorii. Komendy dodaje się co najwyżej do jednej kategorii. Jeśli istnieje więcej niż jeden element z tym samym atrybutem id, tylko ostatni zadeklarowany element (w kolejności wynikającej z odczytu rejestru wtyczek) jest uznawany za poprawny.



<!ELEMENT commandParameter (values?)>

<!ATTLIST commandParameter

id       CDATA #REQUIRED

name     CDATA #REQUIRED

values   CDATA #IMPLIED

typeId   CDATA #IMPLIED

optional (true | false) "true">

Definiuje parametr zrozumiały dla komendy. Parametr umożliwia przekazanie dodatkowych informacji do procedury obsługi w czasie wykonywania. Na przykład parametrem komendy wyświetlenia widoku może być nazwa widoku. Te parametry powinny być zrozumiałe dla procedur obsługi i dlatego procedury te powinny być traktowane jak funkcje API.

Od wersji 3.1



<!ELEMENT commandParameterType EMPTY>

<!ATTLIST commandParameterType

id        CDATA #REQUIRED

type      CDATA #IMPLIED

converter CDATA #IMPLIED>

Element ten służy do definiowania typu obiektu parametru commandParameter. Oprócz tego można za jego pomocą określić podklasę org.eclipse.core.commands.AbstractParameterValueConverter służącą do przekształcania wartości parametrów w postaci łańcuchów w obiekty i odwrotnie.

Od wersji 3.2



<!ELEMENT values (parameter*)>

<!ATTLIST values

class CDATA #REQUIRED>

Bardziej szczegółowa wersja atrybutu values elementu commandParameter.

Od wersji 3.1



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dozwolona wartość parametru.

Od wersji 3.1



<!ELEMENT defaultHandler (parameter)>

<!ATTLIST defaultHandler

class CDATA #REQUIRED>

Domyślna procedura obsługi dla tej komendy. Ta procedura obsługi będzie aktywna, jeśli nie zostanie aktywowana żadna inna procedura obsługi. Ta procedura obsługi będzie wchodzić w konflikty z innymi definicjami procedur obsługi, które nie określają warunków activeWhen. W zastępstwie podczas tworzenia interfejsu IExecutableExtension można używać atrybutu defaultHandler.

Od wersji 3.1



<!ELEMENT state (class?)>

<!ATTLIST state

class CDATA #IMPLIED

id    CDATA #REQUIRED>

Element ten obejmuje informacje o stanie, które są współużytkowane przez wszystkie procedury obsługi i mogą trwać przez kilka sesji. Zazwyczaj jest to stan poza wyboru lub etykieta procedury obsługi. Informacje o stanie mają postać klasy, która jest ładowana w celu nadzorowania stanu. Więcej informacji na ten temat zawiera punkt Informacje o interfejsie API.

Od wersji 3.2



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Klasa, którą można załadować w celu zapisania informacji o stanie komendy. Element ten wykorzystuje się do przekazywania kilku parametrów do interfejsu org.eclipse.core.runtime.IExecutableExtension.

Od wersji 3.2



Element keyConfiguration jest nieaktualny.

<!ELEMENT keyConfiguration EMPTY>

<!ATTLIST keyConfiguration

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

parent      CDATA #IMPLIED

parentId    CDATA #IMPLIED>

Ten element służy do definiowania konfiguracji klawiszy. Jeśli istnieje więcej niż jeden element z tym samym atrybutem id, tylko ostatni zadeklarowany element (w kolejności wynikającej z odczytu rejestru wtyczek) jest uznawany za poprawny. W zamian należy użyć punktu rozszerzenia org.eclipse.ui.bindings.



Element context jest nieaktualny.

<!ELEMENT context EMPTY>

<!ATTLIST context

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

parent      CDATA #IMPLIED

parentId    CDATA #IMPLIED>

Ten element służy do definiowania kontekstów. Jeśli istnieje więcej niż jeden element z tym samym atrybutem id, tylko ostatni zadeklarowany element (w kolejności wynikającej z odczytu rejestru wtyczek) jest uznawany za poprawny. W zamian należy użyć punktu rozszerzenia org.eclipse.ui.contexts.



Element scope jest nieaktualny.

<!ELEMENT scope EMPTY>

<!ATTLIST scope

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

parent      CDATA #IMPLIED>

Ten element służy do definiowania zasięgów. Jeśli istnieje więcej niż jeden element z tym samym atrybutem id, tylko ostatni zadeklarowany element (w kolejności wynikającej z odczytu rejestru wtyczek) jest uznawany za poprawny. @Element nieaktualny - w zamian należy użyć punktu rozszerzenia "org.eclipse.ui.contexts".



Element activeKeyConfiguration jest nieaktualny.

<!ELEMENT activeKeyConfiguration EMPTY>

<!ATTLIST activeKeyConfiguration

value              CDATA #IMPLIED

keyConfigurationId CDATA #IMPLIED>

Ten element służy do definiowania początkowej konfiguracji aktywnych klawiszy dla środowiska Eclipse. Jeśli istnieje więcej niż jeden tego rodzaju element, tylko ostatni zadeklarowany element (w kolejności wynikającej z odczytu rejestru wtyczek) jest uznawany za poprawny.

Ten element został zastąpiony preferencją. Jeśli aplikacja musi zmienić domyślną konfigurację klawiszy, w pliku plugin_customization.ini należy podać następujące informacje: org.eclipse.ui/KEY_CONFIGURATION_ID=your.default.key.configuration.id.



Element keyBinding jest nieaktualny.

<!ELEMENT keyBinding EMPTY>

<!ATTLIST keyBinding

configuration      CDATA #IMPLIED

command            CDATA #IMPLIED

locale             CDATA #IMPLIED

platform           CDATA #IMPLIED

contextId          CDATA #IMPLIED

string             CDATA #IMPLIED

scope              CDATA #IMPLIED

keyConfigurationId CDATA #IMPLIED

commandId          CDATA #IMPLIED

keySequence        CDATA #IMPLIED>

Ten element służy do przypisywania sekwencji klawiszy do komend. W zamian należy użyć elementu key w punkcie rozszerzenia org.eclipse.ui.bindings.



Plik plugin.xml we wtyczce org.eclipse.ui korzysta w znacznym stopniu z punktu rozszerzenia org.eclipse.ui.commands.

Procedury obsługi można przypisywać do komend za pomocą interfejsu org.eclipse.ui.handlers.IHandlerService. Można go pobrać z różnych komponentów środowiska roboczego (np. samego środowiska roboczego, okna środowiska roboczego, serwisu części itd.), wywołując klasę getService(IHandlerService.class).

Zasadniczo zaleca się tworzenia deklaracji statycznych w odniesieniu do wszystkich komend (w pliku plugin.xml). Pozwala to użytkownikom przypisywać klawisze do komend. Można jednak także tworzyć deklaracje komend podczas pracy. W tym calu należy pobrać interfejs org.eclipse.ui.commands.ICommandService z komponentu środowiska roboczego, wywołać klasę getCommand(yourCommandID), a następnie wywołać metodę Command.define(...)..

Użytkownicy opisywanego punktu rozszerzenia mogą skorzystać z kilku domyślnych implementacji stanów procedur obsługi: