指令

org.eclipse.ui.commands

2.1

org.eclipse.ui.commands 延伸點係用來利用 commandcategory 元素, 來宣告指令和指令種類。指令為某些語意行為的抽象表示法,但不是實際的實作方式。這可讓不同開發人員提出各自個別組件的專屬行為模式。例如,在某個編輯器中可能有一種實作方式的「貼上」指令,但在檔案總管小組件中有不同的實作方式。這些實作方式稱為處理常式。指令也可以視為宣告的函數指標或信號處理常式。

<!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>

這個元素用來定義指令。指令代表來自使用者的要求,這個要求可被動作處理,而且在其他指令之間應該具有專屬的語意。如果已定義一個具有相同意義的指令, 請不要定義它。如果這些元素有多個存在且具有相同 id 屬性, 僅最後宣告的元素(按讀取外掛程式登錄的次序)才視為有效。請參閱 org.eclipse.ui.actionSetsorg.eclipse.ui.editorActions 延伸點,以瞭解動作如何連接至指令。



<!ELEMENT category EMPTY>

<!ATTLIST category

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED>

在 UI 中,指令通常是按種類來組織,這使得它們更加容易管理。這個元素用來定義這些種類。指令可以將它們自己新增至最多一個種類中。如果這些元素有多個存在且具有相同 id 屬性, 僅最後宣告的元素(按讀取外掛程式登錄的次序)才視為有效。



<!ELEMENT commandParameter (values?)>

<!ATTLIST commandParameter

id       CDATA #REQUIRED

name     CDATA #REQUIRED

values   CDATA #IMPLIED

typeId   CDATA #IMPLIED

optional (true | false) "true">

定義指令應能瞭解的參數。參數是一個在執行時間能提供詳細資訊給處理常式的方式。例如,"Show view 指令可能會使用視圖作為參數。處理常式應該能夠瞭解這些參數,這樣他們能被視為 API。

自從:3.1



<!ELEMENT commandParameterType EMPTY>

<!ATTLIST commandParameterType

id        CDATA #REQUIRED

type      CDATA #IMPLIED

converter CDATA #IMPLIED>

定義 commandParameter 的物件類型,並指定 org.eclipse.core.commands.AbstractParameterValueConverter 子類別來轉換字串參數值和物件。

自從:3.2



<!ELEMENT values (parameter*)>

<!ATTLIST values

class CDATA #REQUIRED>

commandParametervalues 屬性的更詳細版本。

自從:3.1



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

參數的可能值。

自從:3.1



<!ELEMENT defaultHandler (parameter)>

<!ATTLIST defaultHandler

class CDATA #REQUIRED>

此指令的預設處理常式。如果沒有其他作用中的處理常式,這個處理常式將成為作用中。此處理常式將會與其他未指定 activeWhen 條件的處理常式定義衝突。如果您未建立 IExecutableExtension,您可以改用 defaultHandler 屬性。

自從:3.1



<!ELEMENT state (class?)>

<!ATTLIST state

class CDATA #IMPLIED

id    CDATA #REQUIRED>

所有處理常式共用的狀態資訊,且在不同階段作業之間可能持續保存。通常是關於勾選框狀態或處理常式的標籤。狀態只是載入來監督狀態的類別。如需詳細資訊,請參閱 API 資訊。

自從:3.2



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

載入來儲存這個指令的狀態的類別。如果要將多個參數傳遞至 org.eclipse.core.runtime.IExecutableExtension,可使用這個元素。

自從:3.2



keyConfiguration 元素已棄用

<!ELEMENT keyConfiguration EMPTY>

<!ATTLIST keyConfiguration

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

parent      CDATA #IMPLIED

parentId    CDATA #IMPLIED>

這個元素用來定義按鍵配置。如果這些元素有多個存在且具有相同 id 屬性, 僅最後宣告的元素(按讀取外掛程式登錄的次序)才視為有效。請改用 "org.eclipse.ui.bindings" 延伸點。



context 元素已棄用

<!ELEMENT context EMPTY>

<!ATTLIST context

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

parent      CDATA #IMPLIED

parentId    CDATA #IMPLIED>

這個元素用來定義環境定義。如果這些元素有多個存在且具有相同 id 屬性, 僅最後宣告的元素(按讀取外掛程式登錄的次序)才視為有效。請改用 org.eclipse.ui.contexts 延伸點。



scope 元素已棄用

<!ELEMENT scope EMPTY>

<!ATTLIST scope

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

parent      CDATA #IMPLIED>

這個元素用來定義範圍。如果這些元素有多個存在且具有相同 id 屬性, 僅最後宣告的元素(按讀取外掛程式登錄的次序)才視為有效。@deprecated 請改用 "org.eclipse.ui.contexts" 延伸點。



activeKeyConfiguration 元素已棄用

<!ELEMENT activeKeyConfiguration EMPTY>

<!ATTLIST activeKeyConfiguration

value              CDATA #IMPLIED

keyConfigurationId CDATA #IMPLIED>

這個元素用來定義 Eclipse 的起始作用中按鍵配置。如果這些元素有多個存在,僅最後宣告的元素(按讀取外掛程式登錄的次序)才視為有效。

此元素已被喜好設定所取代。如果您的應用程式需要變更預設按鍵配置,請在您的 plugin_customization.ini 檔:org.eclipse.ui/KEY_CONFIGURATION_ID=your.default.key.configuration.id 中指定以下各項。



keyBinding 元素已棄用

<!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>

這個元素可讓使用者指派按鍵順序給指令。請改用 "org.eclipse.ui.bindings" 延伸點中的 key 元素。



org.eclipse.ui 外掛程式中的 plugin.xml 檔會充分利用 org.eclipse.ui.commands 延伸點。

利用 org.eclipse.ui.handlers.IHandlerService 可登錄指令的處理常式。這可從各種工作台元件中(例如,工作台、工作台視窗、組件網站等)呼叫 getService(IHandlerService.class) 來擷取。

通常最好靜態地宣告所有指令(在 plugin.xml 中)。以利於使用者將按鍵連結附加至指令。不過,也可以在執行時期宣告指令。作法是從工作台元件中擷取 org.eclipse.ui.commands.ICommandService,呼叫 getCommand(yourCommandID),再呼叫 Command.define(...)

處理常式狀態有幾個預設實作可能對這個延伸點的使用者有用: