Версия 3.0
Данный документ описывает структуру файла содержания памятки как ряд фрагментов DTD (машинное представление схемы XML).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
Элемент <cheatsheet> задает тело файла содержимого памятки. Ниже перечислены атрибуты <cheatsheet>:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
Элемент <intro> служит для описания показываемого введения памятки. Вложенный элемент <description> содержит тело введения. Ниже перечислены атрибуты <intro>:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
Элемент <description> содержит описание памятки или элемента памятки. Описание - это текст с простыми тегами форматирования. Памятка автоматически форматирует и макетирует текст, чтобы он был показан более или менее правильно в пользовательском интерфейсе. Парные теги <b>...</b> выделят текст жирным шрифтом, <br/> приведет к переносу строки. В настоящее время поддерживаются только эти теги (возможно, в будущем будут поддерживаться и другие). Некоторые символы обрабатываются особым образом анализатором XML. Например, для того чтобы написать "<", ">", "&", "'" и """ (кавычка) пишите "<", ">", "&", "'" и """ соответственно. Пробелы (обычные и символы переноса строк) обрабатываются как разделитель слов; несколько пробелов подряд (равно как и переносы строк) считаются одним пробелом. Пробел сразу после тегов <description> и <br/> игнорируется, как и пробел непосредственно перед тегом </description>.
item
<!ELEMENT item (description ([action|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> <!ATTLIST item title CDATA #REQUIRED skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
Каждый элемент <item> описывает один шаг верхнего уровня в памятке. <item> бывает простым и составным. Ниже перечислены атрибуты <item>:
org.eclipse.ui.cheatsheets.cheatSheetItemExtension предоставляет дополнительные управляющие элементы для показа в интерфейсе программы. Вклады в эту точку расширения объявляют имена дополнительных строковых атрибутов, которые могут входить в элементы <item>.
Простые элементы могут иметь описание и необязательное действие. В типичном варианте заголовки элементов памятки большую часть времени показываются пользователю. Описание элемента показывается только в процессе выполнения данного шага. Наличие элемента <action> (или <perform-when>) обычно связывается с кнопкой, которую пользователь нажимает для выполнения действия шага. Если действие не задано, то этот шаг пользователь должен выполнить вручную и явно указать, что шаг выполнен успешно.
Составные шаги могут разбиваться на ряд вложенных шагов, на которые указывают вложенные элементы <subitem>. Если шаги задают жестко последовательность своего выполнения, то действия вложенных шагов можно выполнять в произвольном порядке. Все вложенные шаги должны быть завершены (или пропущены) перед переходом к следующему шагу. Это означает, что жесткую последовательность шагов нельзя представить в виде вложенных элементов.
Вложенный элемент <conditional-subitem> позволяет изменить презентацию этапа внутри шага в зависимости от переменных памятки, заданных на предыдущих шагах. Субэлемент <repeated-subitem> позволяет включить в шаг набор похожих вложенных шагов. Сам набор вложенных шагов также может зависеть от переменных памятки, заданных на предыдущих шагах.
subitem
<!ELEMENT subitem ( [action|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Каждый вложенный элемент <subitem> описывает один вложенный шаг в памятке. <subitem> содержит простую метку текста, но не длинное описание или свои вложенные субэлементы. Ниже перечислены атрибуты <subitem>:
Вложенные элементы могут иметь необязательное действие. Наличие элемента <action> (или <perform-when>) обычно связывается с кнопкой, которую пользователь нажимает для выполнения действия вложенного шага. Если действие не задано, то этот вложенный шаг пользователь должен выполнить вручную и явно указать, что шаг выполнен успешно.
Если шаги задают жестко последовательность своего выполнения, то действия вложенных шагов внутри шага можно выполнять в произвольном порядке. Все вложенные шаги должны быть завершены (или пропущены) перед переходом к следующему шагу. Это означает, что жесткую последовательность шагов не следует представлять в виде вложенных элементов.
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Каждый элемент <conditional-subitem> описывает вложенный шаг, форма которого может зависеть от условия, известного в момент обработки элемента. Ниже перечислены атрибуты <conditional-subitem>:
Атрибут condition элемента <conditional-subitem> задает строку, которая определяется по значению переменной памятки. Каждый вложенный элемент <subitem> должен содержать атрибут when с уникальной строкой. При обработке элемент <conditional-subitem> заменяется на <subitem> с соответствующим значением. Если такой элемент не будет найден, это приведёт к ошибке.
Например, если переменная памятки "v1" будет иметь значение "b" на момент обработки следующего участка
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Шаг для A." /> <subitem when="b" label="Шаг для B." /> </conditional-subitem> </item>то будет выбран второй вложенный элемент и участок приобретет следующий вид:
<item ...> <subitem label="Шаг для B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Каждый элемент <repeated-subitem> описывает вложенный элемент, который выполняется 0, 1 или более раз. Ниже перечислены атрибуты <repeated-subitem>:
Атрибут values задает список строк, разделенных запятыми; <subitem> - шаблон. При обработке элемент <repeated-subitem> заменяется на копии <subitem>, где переменная "this" принимает соответствующие значения строк.
Например, если переменная памятки "v1" равна "1,b,три", то следующий элемент обрабатывается так:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Шаг ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>и элемент приобретает вид:
<item ...> <subitem label="Шаг 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Шаг b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Шаг три."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="три"/> </subitem> </item>
action
<!ELEMENT action EMPTY> <!ATTLIST action class CDATA #REQUIRED pluginId CDATA #REQUIRED param1 CDATA #IMPLIED ... param9 CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Каждый элемент <action> описывает действие в памятке. Ниже перечислены атрибуты <action>:
org.eclipse.jface.action.IAction
.
Если это действие также реализует org.eclipse.ui.cheatsheets.ICheatSheetAction
,
то оно будет вызвано посредством метода run(String[],ICheatSheetManager), передано диспетчеру памятки с параметрами действия.
Вместе с этим атрибутом должен быть указан атрибут pluginId.
Настоятельно рекомендуется, чтобы действия, вызываемые из памятки, сообщали об успехе или сбое, если действие может выполниться неуспешно (например, если пользователь отменяет действие в окне диалога).
(Подробные сведения об этом приведены в описании
org.eclipse.jface.action.Action.notifyResult(boolean).)org.eclipse.ui.cheatsheets.ICheatSheetAction
,
строковые значения этих атрибутов будут переданы действию при вызове.
Действию памятки можно передать до 9 параметров (param1,
param2 и т.д.). Список параметров должен начинаться с параметра 1 и быть сплошным,
то есть param2 можно указать только при наличии param1.
Её значение может задаваться переменной памятки, - в этом случае строка должна быть в форме "${var}". Значение переменной определяется на момент начала выполнения элемента, содержащего <item> (если переменная не будет существовать, строка будет пустой). perform-when
<!ELEMENT perform-when (action+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Каждый элемент <perform-when> описывает действие в памятке. Ниже перечислены атрибуты <perform-when>:
Атрибут condition элемента <conditional-subitem> задает строку, которая определяется по значению переменной памятки. Каждый вложенный элемент <subitem> должен содержать атрибут when с уникальной строкой. При обработке элемент <conditional-subitem> заменяется на <subitem> с соответствующим значением. Если такой элемент не будет найден, это приведёт к ошибке.
Например, если переменная памятки "v1" будет иметь значение "b" на момент обработки следующего участка
<item ...> <subitem label="Главный шаг"> <perform-when condition="${v1}"> <action when="a" class="com.xyz.action1" pluginId="com.xyz" /> <action when="b" class="com.xyz.action2" pluginId="com.xyz" /> </conditional-subitem> </subitem> </item>то будет выбрано второе действие и участок приобретет следующий вид:
<item ...> <subitem label="Главный шаг"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Ниже приведен пример очень простого файла содержимого памятки:
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Пример"> <intro> <description>Простая памятка для двух шагов.</description> </intro> <item title="Шаг 1"> <description>На этом шаге выполняется действие.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Шаг 2"> <description>Этот шаг выполняется вручную.</description> </item> </cheatsheet>
Copyright (c) 2004 IBM Corporation и другие.
Все права защищены.
Эта программа и сопутствующие материалы распространяются на условиях Eclipse Public License v1.0, поставляемой вместе с продуктом и доступной на Web-сайте http://www.eclipse.org/legal/epl-v10.html.