Версия 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