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.
categoryId
.Od wersji 3.0
activeWhen
. W
zastępstwie podczas tworzenia interfejsu IExecutableExtension
można używać elementu defaultHandler
.
Od wersji 3.1
commandParameterType
wskazujący typ wartości zwracany przez komendę. Określenie atrybutu returnTypeId
umożliwia klientom wykonującym daną komendę powiązanie zwracanej wartości z typem Java i przekształcenie tej wartości w łańcuch, który można przechowywać oraz przekazywać innej komendzie przyjmującej parametry tego samego typu.
Od wersji 3.2
Od wersji 3.2
<!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
org.eclipse.core.commands.IParameterValues
. Jeśli
klasa ta nie zostanie określona, należy zdefiniować bardziej szczegółowo element values
. Więcej informacji zawiera dokumentacja interfejsu org.eclipse.core.runtime.IExecutableExtension
.commandParameterType
dotyczącego parametru commandParameter
. Określenie atrybutu typeId
umożliwia procedurom obsługi komendy spójne przekształcanie wartości parametrów w postaci łańcuchów w obiekty, a także pozwala potencjalnym programom wywołującym wyszukiwać komendy przyjmujące obiekty różnych typów jako parametry.<!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
commandParameterType
.java.lang.Object
jako typu parametru.org.eclipse.core.commands.AbstractParameterValueConverter
. Konwerter powinien tworzyć i wykorzystywać obiekty typu wskazanego atrybutem type
. Jeśli klasa ta nie zostanie określona, funkcja przekształcania wartości parametru z łańcuchów w obiekty i odwrotnie nie będzie dostępna (wykonanie metody getValueConverter()
w odniesieniu do klasy ParameterType
spowoduje zwrócenie wartości null
).<!ELEMENT values (parameter*)>
<!ATTLIST values
class CDATA #REQUIRED>
Bardziej szczegółowa wersja atrybutu values
elementu commandParameter
.
Od wersji 3.1
org.eclipse.core.commands.IParameterValues
. Jeśli
klasa ta nie zostanie określona, należy zdefiniować bardziej szczegółowo element values
. Więcej informacji zawiera dokumentacja interfejsu org.eclipse.core.runtime.IExecutableExtension
.<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
Dozwolona wartość parametru.
Od wersji 3.1
IExecutableExtension
.IExecutableExtension
.<!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
org.eclipse.core.commands.IHandler
.<!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
org.eclipse.core.commands.State
. Patrz temat Informacje o interfejsie API.org.eclipse.jface.commands.PersistentState
). Podczas wyświetlania komendy w menu lub na paskach narzędzi rozpoznawanych jest kilka wspólnych identyfikatorów (patrz interfejs org.eclipse.jface.menus.IMenuStateIds
). Identyfikator musi być unikalny wyłącznie w ramach komendy definiującej stan.
<!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
org.eclipse.core.commands.State
. Patrz temat Informacje o interfejsie API.<!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 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 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 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
.
id
) elementu keyConfiguration
, który ma być początkowo aktywny.id
) elementu keyConfiguration
, który ma być początkowo aktywny.<!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.
java.util.Locale
.platform
to zestaw wartości zwracanych przez metodę
org.eclipse.swt.SWT.getPlatform()
.schemeId
w elemencie key
w nowym punkcie rozszerzenia org.eclipse.ui.bindings.Klawisze modyfikujące można również określić w sposób niezależny od platformy. Na przykład w systemie operacyjnym MacOS X łańcuch Command jest prawie zawsze używany zamiast łańcucha Ctrl. Udostępniono więc łańcuch M1, który będzie stanowił odwzorowanie łańcuchów Ctrl lub Command. Analogicznie łańcuch M2 odpowiada klawiszowi Shift, M3 odpowiada klawiszowi Alt, a M4 to odpowiednik klawisza Ctrl (w systemie operacyjnym MacOS X). Jeśli dodano więcej platform, można oczekiwać, że te aliasy zostaną odwzorowane na właściwe wartości domyślne platformy.
Składnia tego łańcucha została zdefiniowana w interfejsie org.eclipse.ui.internal.keys
. Mówiąc w skrócie, wielkość liter w łańcuchu nie jest rozróżniana, ale ze względów stylistycznych preferowane jest używanie wielkich liter. Jeśli klawisz jest literą, należy po prostu dodać literę. Jeśli
klawisz jest klawiszem specjalnym (tzn. nie jest to klawisz ASCII), należy użyć jednego z następujących łańcuchów: ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, BREAK, CAPS_LOCK, END, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, HOME, INSERT, NUM_LOCK, NUMPAD_0, NUMPAD_1, NUMPAD_2, NUMPAD_3, NUMPAD_4, NUMPAD_5, NUMPAD_6, NUMPAD_7, NUMPAD_8, NUMPAD_9, NUMPAD_ADD, NUMPAD_DECIMAL, NUMPAD_DIVIDE, NUMPAD_ENTER, NUMPAD_EQUAL, NUMPAD_MULTIPLY, NUMPAD_SUBTRACT, PAGE_UP, PAGE_DOWN, PAUSE, PRINT_SCREEN lub SCROLL_LOCK. Jeśli
klawisz jest niedrukowanym klawiszem ASCII, należy użyć jednego z następujących łańcuchów: BS, CR, DEL, ESC, FF, LF, NUL, SPACE, TAB lub VT. Należy pamiętać, że główny klawisz Enter/Return na klawiaturze to CR.
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:
Copyright (c) 2000, 2005 IBM Corporation i inne podmioty.
Wszelkie prawa zastrzeżone. Program ten oraz towarzyszące mu materiały są udostępniane na warunkach
licencji EPL (Eclipse Public License), wersja 1.0, dołączonej do nich i
dostępnej pod adresem http://www.eclipse.org/legal/epl-v10.html.