Версия 3.2
Данный документ описывает структуру файла содержания памятки как ряд фрагментов 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|command|perform-when] | (subitem|repeated-subitem|conditional-subitem)*) [onCompletion])>
<!ATTLIST item
title CDATA #REQUIRED
dialog ("true" | "false") "false"
skip ("true" | "false") "false"
contextId CDATA #IMPLIED
href CDATA #IMPLIED
>
Каждый элемент <item> описывает один шаг верхнего уровня в памятке. Элемент <item> может содержать элементы <subitem>. Ниже перечислены атрибуты <item>:
org.eclipse.ui.cheatsheets.cheatSheetItemExtension предоставляет дополнительные управляющие элементы для показа в интерфейсе программы. Вклады в эту точку расширения объявляют имена дополнительных строковых атрибутов, которые могут входить в элементы <item>.
Простые элементы могут иметь описание и необязательное действие или команду. В типичном варианте заголовки элементов памятки большую часть времени показываются пользователю. Описание элемента показывается только в процессе выполнения данного шага. Наличие элемента <action>, <command> (или <perform-when>) обычно связывается с кнопкой, которую пользователь нажимает для выполнения действия или команды шага. Если действие или команда не заданы, то этот шаг пользователь должен выполнить вручную и явно указать, что шаг выполнен успешно.
Шаги могут разбиваться на ряд вложенных шагов, на которые указывают вложенные элементы <subitem>. Если шаги задают жестко последовательность своего выполнения, то действия вложенных шагов можно выполнять в произвольном порядке. Все вложенные шаги должны быть завершены (или пропущены) перед переходом к следующему шагу. Это означает, что жесткую последовательность шагов нельзя представить в виде вложенных элементов.
Вложенный элемент <conditional-subitem> позволяет изменить презентацию этапа внутри шага в зависимости от переменных памятки, заданных на предыдущих шагах. Подэлемент <repeated-subitem> позволяет включить в шаг набор похожих вложенных шагов. Сам набор вложенных шагов также может зависеть от переменных памятки, заданных на предыдущих шагах.
subitem<!ELEMENT subitem ( [action|command|perform-when] )>
<!ATTLIST subitem
label CDATA #REQUIRED
skip ("true" | "false") "false"
when CDATA #IMPLIED
>
Каждый вложенный элемент <subitem> описывает один вложенный шаг в памятке. <subitem> содержит простую метку текста, но не длинное описание или свои вложенные подэлементы. Ниже перечислены атрибуты <subitem>:
Вложенные элементы могут иметь необязательное действие или команду. Наличие элемента <action>, <command> или <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> (если переменная не будет существовать, строка будет пустой). command<!ELEMENT command EMPTY>
<!ATTLIST command
serialization CDATA #REQUIRED
returns CDATA #IMPLIED
confirm ("true" | "false") "false"
when CDATA #IMPLIED
>
Каждый элемент <command> описывает команду в памятке. Ниже перечислены атрибуты элемента <command>:
Ниже приведен пример элемента с командой, которая открывает окно диалога и сохраняет результат в переменной "result" памятки.
<item title="Выбор панели">
<description>Выберите панель, которая будет открыта на следующем шаге.</description>
<command returns = "result"
serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Выбор панели,buttonLabel0=Package Explorer,message=Выберите панель ,buttonLabel1=Search View)"/>
<onCompletion> Выбрано ${result}. </onCompletion>
</item>
onCompletion<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
Элемент <onCompletion> содержит текст, который будет показан при завершении элемента. Это особенно полезно на завершающем шаге памятки для подтверждения завершения задачи в целом. Описание состоит из текста, в который вставлены простые теги форматирования с соблюдением тех же правил, что и для элемента <description>. Элементы <onCompletion> также могут содержать ссылки на переменные памятки в форме "${var}", которая будет развернута с использованием фактического значения переменной var памятки при завершении этого шага.
perform-when<!ELEMENT perform-when ((action|command)+)> <!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" />
<command when="c" serialization="org.eclipse.search.ui.views.SearchView"/>
</conditional-subitem>
</subitem>
</item>
то будет выбрано второе действие и участок приобретет следующий вид:
<item ...>
<subitem label="Главный шаг">
<action class="com.xyz.action2" pluginId="com.xyz" />
</subitem>
</item>
Ниже приведен пример простого файла содержимого памятки, в котором показано использование команд, подэлементов perform-when и условных подэлементов.
<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Пример памятки">
<intro>
<description>Памятка, в которой демонстрируется применение подэлементов perform-when и условных подэлементов</description>
</intro>
<item title="Выбор панели">
<description>Выберите панель, которая будет открыта на следующих шагах.</description>
<command returns = "result"
serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Выбор панели,buttonLabel0=Package Explorer,message=Выберите панель ,buttonLabel1=Search View)"/>
<onCompletion> Выбрано ${result}. </onCompletion>
</item>
<item title="Закрытие панелей">
<description>Закрыть панель поиска и панель структуры пакетов (если открыта)</description>
</item>
<item title="Открыть панель, если элемент" skip = "true">
<description>Используется элемент perform when для открытия панели, выбранной ранее.</description>
<perform-when condition = "${result}">
<command when = "Структура пакетов"
serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/>
<command when = "Панель Поиск"
serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/>
</perform-when>
</item>
<item title="Закрытие панелей">
<description>Закрыть панель поиска и панель структуры пакетов (если открыта)</description>
</item>
<item title="Открытие панели из подэлемента perform when">
<description>Используется элемент perform when для открытия панели, выбранной ранее.</description>
<subitem label="Подэлемент Perform when" skip = "true">
<perform-when condition = "${result}">
<command when = "Структура пакетов"
serialization="org.eclipse.jdt.ui.PackageExplorer"/>
<command when = "Панель Поиск"
serialization="org.eclipse.search.ui.views.SearchView"/>
</perform-when>
</subitem>
</item>
<item title="Закрытие панелей">
<description>Закрыть панель поиска и панель структуры пакетов (если открыта)</description>
</item>
<item title="Открытие панели из подэлемента условия">
<description>Используется элемент perform when для открытия панели, выбранной ранее.</description>
<conditional-subitem condition="${result}">
<subitem when="Структура пакетов" label="Открыть структуру пакетов.">
<command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
</subitem>
<subitem when="Панель Поиск" label="Открыть панель Поиск">
<command serialization = "org.eclipse.search.ui.views.SearchView"/>
</subitem>
</conditional-subitem>
</item>
</cheatsheet>
Copyright (c) 2004, 2006 IBM Corporation и других фирм.
Все права защищены.
Эта программа и сопутствующие материалы распространяются на условиях Eclipse Public License v1.0, поставляемой вместе с продуктом и доступной на Web-сайте
http://www.eclipse.org/legal/epl-v10.html