Памятки - это специальные панели, которые проводят по этапам выполнения задачи, позволяя достичь положительного результата. Например, памятка может провести пользователя через все этапы создания, компиляции и выполнения программы Java. Памятки запускаются с помощью пункта меню Справка>Памятки.... Памятки можно также запустить из страницы введения.
Памятки задаются с помощью точки расширения org.eclipse.ui.cheatsheets.cheatSheetContent. Само содержимое памятки задается в отдельном файле, чтобы его можно было легче перевести на другие языки.
Добавление памятки является довольно простым процессом. Давайте рассмотрим памятку, добавленную JDT для создания простого приложения Java.
<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent"> <cheatsheet name="%cheatsheet.helloworld.name" contentFile="$nl$/cheatsheets/HelloWorld.xml" id="org.eclipse.jdt.helloworld"> <description>%cheatsheet.helloworld.desc</description> </cheatsheet> ...Для памятки, также как и для других дополнений рабочей среды, можно задать имя, описание и ИД. Имя и описание отображаются в списке, доступном с помощью меню Справка>Памятки.... Также для памятки можно задать категорию, если вы хотите поместить несколько памяток в одну логическую группу. Если категория не указана, памятка отобразится в категории Прочие.
Основная работа для памяток проделывается в файле содержимого. Файл содержимого - это файл в формате XML, имя и расположение которого заданы в атрибуте contentFile. Путь к файлу указывается относительно каталога модуля. (Обратите внимание на использование переменной $nl$ в имени каталога, что означает, что файл будет расположен в каталоге соответствующего языка целевой среды).
Файл содержит общую информацию о памятке с описанием каждого этапа (называемого элемент), которые будет выполнять пользователь. По сути элемент является подробным описанием действия, которое должен выполнить пользователь. Однако элемент также может задать действие, которое следует выполнить для осуществления определенного шага от имени пользователя. Рассмотрим первую часть файла содержимого (HelloWorld.xml) памятки Java.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Простое приложение на Java"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Вас приветствует учебник Java - Hello, World. Он поможет вам создать знаменитое приложение "hello world" и опробовать его. Вы создадите проект java и java-класс, который при выполнении будет печатать строку "hello world" в консоли. Начнем! </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Открыть проекцию Java"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> В строке меню, расположенной в верхней части рабочей среды, выберите Окно->Открыть проекцию->Java. На этом шаге в рабочей среде Eclipse открывается проекция, предназначенная для разработки Java. Кнопка "Щелкните для выполнения" позволяет автоматически открыть проекцию "Java". </description> </item> ...
Название и введение показаны вверху памятки. Затем описываются элементы. Первый элемент памятки описывает, как открыть проекцию Java. Атрибут action указывает класс, который можно использовать для выполнения действия от имени пользователя. Класс должен реализовывать IAction. Это довольно удобно, так как позволяет повторно использовать классы действий, созданные для дополнений меню и панелей инструментов.
Класс действия может реализовывать ICheatSheetAction если действие использует параметры или должно знать о памятке и ее состоянии. В этом случае действию будет передан массив параметров и ссылка на ICheatSheetManager, чтобы оно могло запросить дополнительную информацию о памятке. Любые необходимые параметры можно передать методу run действия с помощью атрибутов paramN.
Настоятельно рекомендуется, чтобы действия, вызываемые из памятки, сообщали об успехе или сбое, если действие может выполниться неуспешно. Например, пользователь может прервать выполнение действия. Дополнительные сведения содержатся в разделе IAction.notifyResult(булевский).
Элементы необязательно должны задавать действия. Если элемент должен быть выполнен пользователем вручную, указывать действие не нужно. Ниже приведен третий шаг из памятки Java, который сообщает пользователю, как создать код простого приложения. Когда действие на задано, описание элемента должно сообщить пользователю о необходимости нажать определенную кнопку после завершения выполнения задачи.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Добавление строки System.out.println в метод main"> <description> В классе HelloWorld в метод "public static void main" следует добавить выражение: System.out.println("Hello world!"); и сохранить изменения. Нажмите кнопку "Щелкните для выполнения". </description> </item>Дополнительные атрибуты задают, можно ли полностью пропустить элемент, и какой документ следует выполнить, если пользователь запросит справку на определенном этапе. Описание всех атрибутов, которые можно задать внутри памятки, содержится в документации по точке расширения org.eclipse.ui.cheatsheets.cheatSheetContent.
Подпункты можно использовать для лучшей организации элементов. В отличие от пунктов, подпункты можно проходить а произвольном порядке. Подпункты также могут задавать действия, которые будут автоматически выполнять подзадачи для пользователя. Действия подпунктов описываются также, как и действия элементов.
Условные выражения можно использовать для определения элементов памяток, содержимое или поведение которых зависит от определенных условий. Условия описываются в элементе condition подпункта, с помощью строковых значений, совпадающих с атрибутов when каждого элемента. Обычно условия ссылаются на переменные памятки в формате ${var}, где var - это имя переменной памятки. Несколько простых примеров помогут продемонстрировать, как работают условные выражения.
Условные подпункты можно использовать для выбора одного из возможных подпунктов. В памятку включается только первый подпункт, атрибут when которого совпадает с атрибутом условия. Например:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Шаг для A." /> <subitem when="b" label="Шаг для B." /> </conditional-subitem> </item>Этот элемент задает два возможных подпункта, которые зависят от значения переменной v1. Если переменная имеет значение a, то будет включен первый подпункт. Если переменная имеет значение b, то будет включен второй подпункт. Если у переменной будет другое значение, такая ситуация считается ошибкой.
Условные действия похожи на условные подпункты. Элемент perform-when определяет условие для выполнения одного из возможных действий. Условие описывается таким же образом, с помощью произвольной строки, зачастую ссылающейся на переменную. Действие, атрибут when которого совпадает с условием, будет выполнено. Например:
<item ...> <perform-when condition="${v1}"> <action when="a" class="com.example.actionA" pluginId-"com.example" /> <action when="b" class="com.example.actionB" pluginId-"com.example" /> </perform-when> </item>Действие для выполнения выбирается исходя из значения переменной v1. Если переменная имеет значение, отличное от a или b, такая ситуация считается ошибкой.
Повторяющиеся подпункты описывают подпункт, который выполняется 0, 1 или более раз в виде схожих под-этапов. Под-этапы задаются с помощью специальной переменной ${this}. Эта переменная будет заменена на значения, указанные в атрибуте values. Атрибут values - это строка значений, разделенных запятыми. В атрибуте values можно использовать переменную, содержащую список значений. Например:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Шаг ${this}" /> </repeated-subitem> </item>Если переменная имеет значение 1,b,три, то в памятке отобразятся три подпункта, каждый из них будет иметь свою уникальную метку ("Шаг 1," "Шаг b," "Шаг три"). Переменную можно использовать в метке или значении параметра действия. К ней также можно получить доступ посредством ICheatSheetManager во время выполнения действия.
В некоторых случаях требуется изменить другие компоненты пользовательского интерфейса, если активна памятка. Например, может потребоваться, чтобы редактор отображал особые комментарии, если пользователь работает с задачей редактирования с помощью памятки. В этом случае можно указать получатель запросов в качестве атрибута памятки. Атрибут получателя запросов должен быть полным именем класса Java с производным классом CheatSheetListener. Получатели запросов будут получать уведомления вместе с ICheatSheetEvent когда в жизненный цикл памятки вносятся изменения, например при открытии, закрытии или завершении работы.
Расширение org.eclipse.ui.cheatsheets.cheatSheetItemExtension можно использовать для добавления произвольных атрибутов к имеющимся памяткам. Эта точка расширения предоставляет возможность модулю добавлять дополнительные кнопки для помощи пользователю на определенной этапе. Эти дополнительные кнопки располагаются рядом со значком справки.
Для использования данного механизма можно определить любой атрибут внутри определения элемента в XML-файле памятки. Имя атрибута будет сопоставлено всеми атрибутами, добавленными в расширениях к org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Дополнительные сведения можно найти в описании точек расширения.