Eclipse.PlatformPluginDeveloperGuide.navigatorContent

Вольный перевод раздела руководства разаботчика plug-in'ов для Eclipse.
Выполнен - Флоров Евгений.
Будет пополняться постепенно.


...



suppressedExtensionId CDATA #REQUIRED
policy (InvokeOnlyIfSuppressedExtAlsoVisibleAndActive|InvokeAlwaysRegardlessOfSuppressedExt) "InvokeAlwaysRegardlessOfSuppressedExt">

В случае, если для данного элемента срабатывает как выражение triggerPoints у подавляемого расширения, так и у объявляемого расширения, то данное расширение будет вызвано, а подавленное им расширение - нет. Клиенты, которые указывают перекрываемый элемент должны также предоставлять поставщика содержания (content provider) реализующего org.eclipse.ui.navigator.IPipelinedTreeContentProvider, который предоставляет методы для перехвата (intercept) запросов на дочерние узлы (children), родительские узлы (parents), и непосредственые обновления представления (viewer).

• suppressedExtensionId - Идентификатор подавляемого (если расширение в котором пределяется override видимо и активно) расширения.
• policy - Политика - объявляет, как расширение должно вызываться со стороны движка/каркаса (framework). Если политика не указана, то используется значение по-умолчанию InvokeAlwaysRegardlessOfSuppressedExt. Доступны следующие политики:
• InvokeOnlyIfSuppressedExtAlsoVisibleAndActive: Данный компонент является безусловно перекрывающим компонентом. За исключением того, когда подавленное им расширение видимо и доступно представлению, определяемому расширению не должна предоставляться возможность участвовать в процессе предоставления содержания. Если используется эта политика, данный компонент будет вызван только тогда, когда выражение triggerPoints для подавляемого расширения и выражение triggerPoints данного расширения доступны (срабатывают) для текущего элемента содержания. Поэтому, выражения triggerPoints и possibleChildren для данного расширения должны быть подмножеством соотвественно выражений triggerPoints и possibleChildren подавляемого им расширения. Другими словами, данная политика позволяет подавить (переопределить) предоставление провайдером suppressedExtensionId содержания для некоторого подмножества обрабатываемых им элементов.
• InvokeAlwaysRegardlessOfSuppressedExt (default): Показывает, что данное расширение является первоклассным (first class) расширением; ему должна быть предоставлена возможность предоставлять содержание независимо от того активно-ли или видимо-ли для представления подавляемое расширение suppressedExtensionId. Таким образом, расширение является первоклассным и перекрывающим. Оно будет вызываться всегда, когда его выражение triggerPoints срабатывает. Когда подавляемое расширение и его выражение triggerPoints срабатывает, наше расширение будет вызвано вместо подавляемого расширения для данных элементов; подавленное расширение не получит возможность непосредственного участия в процессе.

...

Создание представлений на основе Common Navigator. Часть IV: Сборка объектов

Обзор

В предыдущем разделе, мы обсуждали как конфигурировать всплывающие меню для экземпляра Common Navigator. Как вы видели, Common Navigator может декларировать все его точки включения меню через точку расширения org.eclipse.ui.navigator.viewer и показывать все-ли привязки к точке расширения org.eclipse.ui.popupMenus должны быть учтены. Декларативная конфигурация меню предназначена для исключения программирования струткуры меню, и документирования структуры меню для потенциальных расширителей.

Мы также кратко говорили о двух способах, с помощью которых конфигураторы могут встроиться в меню:

1. через org.eclipse.ui.popupMenus, который позволяет вам добавить меню через workbench;
2. через org.eclipse.ui.navigator.navigatorContent, который специфичен для каркаса Common Navigator.
   

Мы рассмотрим ...popupMenus в данном разделе, и ...navigatorContent в следующем.

Как всегда, вы можете найти полные исходные тексты для этого примера в org.eclipse.ui.navigator.examples модуле из Eclipse CVS репозитория.

Добавление операции "Delete Property" с помощью org.eclipse.ui.popupMenus

Напоминаю, что для данной серии статей мы отображаем простую модель файла свойств.



Теперь мы добавим действие "Delete Property", которое позволяет пользователю выделить свойство из списка и удалить его.



Откройте редактор Plug-in Manifest двойным щелчком на файле plugin.xml в вашем проекте модуля. Если вы не не уверены в точ, что это означает, прочитайте еще раз раздел I данной серии.

На закладке Extensions, выберите Add... и затем org.eclipse.ui.popupMenus. Если вы не видете эту опции в списке, снимите метку с "Show only extension points from the required plugins". Если у вас org.eclipse.ui не добавлен в проект как модуль от которого зависит наш модуль, то сделайте это.

Теперь выберите элемент созданные в списке ("org.eclipse.ui.popupMenus"), нажмите правую кнопку и выберете "objectContribution". Затем, нажмите правую кнопку еще раз и выберите "action".



Любой objectContribution может объявить меню (поднемю расширения для всплывающего меню) и действия. Расширение довольно многословно для облегчения оптимизации загрузки модуля. Это означает, что расширение объявляет достаточно информации, для того, чтобы реальный класс (и следовательно модулю) не потребуется загружаться для отрисовки меню. Если пользователь не выбрал действие, то это означает, что модуль не был загружен.

На практике, расширение объявляет ярлыки меню, иконку меню, и контекстное окно для остальных типов. Расширение также объявляет путь панели меню (напоминаю, что мы описали значения для точек вставки в разделе III).

Используйте значения из следующей диаграммы для конфигурирования элементов действия. Вы можете ввести значения на странице Extensions, или перейти на закладку plugin.xml и заполнить его вручную.



Есть несколько вещей, которые мы должны обсудить здесь.

Первое - это objectClass, который объявляет, что именно нам интересно в ...PropertiesTreeData. Напоминаю, что мы уже определили простую модель объектов для представления name=value пар в файле свойств. Для удаления этих элементов, мы хотим, чтобы наши операции были доступны на экземпляре нашей модели.

Атрибут class указывает подкласс org.eclipse.ui.actions.ActionDelegate. Реализация DeletePropertyAction.run(IAction) имеет некоторый шаблон для robustness, но важная часть такова:



ActionDelegate объявляет метод selectionChanged(IAction, ISelection), который обновляется, когда меняется выбор в представлении. Мы перекрываем этот метод для запоминания выбора так, что когда приходит сообщение, что пользователь выбрал опцию меню мы знаем на каком элементе он кликнул.

Итого

Теперь вы должны чуствовать себя комфортно в экспериментах с добавлением большего числа действий во всплывающее меню, а так же при добавлении подменю. Убедитесь, что проверили элемент меню (accessible in the same way you found action earlier). Если вы используете закладку Extensions, все доступные атрибуты будут доступны вам и помните, что вы можете использовать правый щелчёк для создания подменю.

Создание представлений на основе Common Navigator. Часть III: Конфигурирование меню

Автор оригинальной статьи : Michael D. Elder
Перевод: Евгений Флоров

В предыдущих разделах мы узнали как конструироватьCommon Navigator Framework (CNF) представление и базовое расшиерние для отображения файлов свойств. Теперь мы разберёмся с тем как конфигурировать меню для CNF представления и как добавить действия в наше представление для манипулирования его содержанием.

Обзор

Существует две основные возможности для добавления действий в Common Navigator Framework (CNF) представление:

• Собрать действия используея org.eclipse.ui.popupMenus как objectContributions или viewerContributions. Точка расширения ...popupMenus позволит вам собрать индивидуальные делегаты действий через Eclipse Workbench. CNF представление может быть сконфигурировано с учётом условий (contributions) (это вариант по-умолчанию) или игнорируя их. В случае, когда Project Explorer contributed by Platform/UI, object and viewer contributions are honored. (Будет затронуто в разделе IV.)
• Сборка действий используя org.eclipse.ui.navigator.navigatorContent как actionProvider'ы. Иногда, клиенты требуют больше программного управления тем, какие действия собраны в данное меню в конкретном контексте, а также какие retargetable действия сконфгурированы на основе текущего выбора (элемента).
  

Конфигурирование структуры меню

В Разделе I, мы определили элемент viewer нашего примера, и всплывающее меню там было кратко упомянуто.
Напоминаю, что есть два способа конфигурирования всплывающего меню. Первая возможность - это простое указание значения для popupMenuId элемента viewer в org.eclipse.ui.navigator.viewer. Вторая возможность - это выполнить более активную роль в конфигурировании точек включения (insertion points) поддержки меню.

Подсказка: Случай, когда указывается (определяется) и popupMenuId и элемент popupMenu - является ошибкой.

Если мы установили popupMenuId, мы должны иметь что-то похожее на это:



Идентификатор может быть использован расширителями (extenders) org.eclipse.ui.popupMenus для добавления viewerContributions особенностей к представлению, однако не требуются идентификаторы для objectContributions.

Когда указан только атрибут popupMenuId, набор по-умолчанию точек вставки автоматически конфигурируется во всплывающем меню. Это документируется в schema
reference для org.eclipse.ui.navigator.viewer, но продублировано здесь для удобства:

"group.new" separator="true"
"group.goto"
"group.open" separator="true"
"group.openWith"
"group.edit" separator="true"
"group.show" separator="true"
"group.reorganize"
"group.port" separator="true"
"group.generate" separator="true"
"group.search" separator="true"
"group.build" separator="true"
"additions" separator="true"
"group.properties" separator="true"

Эти значения могут быть использованы атрибутом menubarPath элементов в org.eclipse.ui.popupMenus.

Эти значения могут быть также использованы тогда, когда программно используются или ищутся элементы меню (смотри org.eclipse.jface.action.IContributionManager, конкретно insertAfter(), insertBefore(), и appendToGroup().

Все строковые константы ("group.*") описаны в org.eclipse.ui.navigator.ICommonMenuConstants и доступны для программного использования.

С другой стороны, мы можем определить элемент popupMenu как дочку для viewer, где затем мы можем определить наш mix точек включения. Запомните, что вы можете использовать закладку Extensions редактора Plug-in Manifest для создания элементов расширения из меню.



Для нашего примера, мы можем использовать такую же конфигурацию меню, как и в Project Explorer:



Каждый элемент insertionPoint показывает GroupMarker'у, что является доступным через IContributionMenu API. Везде, где атрибут separator устанавливается в "истина", меню отобразит горизонтальную линию. Меню в Eclipse достаточно разумны, чтобы отображать лии по-необходимости, так две линии расположенные вплотную отображаются как одна горизонтальная линия.

Также, необходимо принять во внимание атрибут allowsPlatformContributions="true" для элемента popupMenu. По-умолчанию, CNF представления учитывают сборки ..popupMenus. Установка данного атрибута в "ложь" ограничит меню только учётом Action Provider'ов.

Пример выше не делает что-либо фанастического, но в вашем CNF представлении, мы можете определить ваши точки включения меню ("group.example") где сделать их чуствительными для ваших сценариев. Рекомендуемым соглашением именования является "group.*", как верхняя точка включения, с исключением для специальных дополнительных групп.

Несколько комментариев на счет расширения или управления набором точек включения в меню CNF. Невозможно декларативно управлять или расширять набор точек включения для уже сконфигурированных представлений. Возможно программно добавить новые GroupMarker'ы или Separators через Action Provider'ов, но эта правктика должна использоваться аккуратно. Мы получим подробности о том как это может быть в разделе V, но на данный момент просто примите во внимание предупреждение о том, что эта практика должна применяться с осторожностью и только используя в своих интересах атрибут dependsOn элемента actionProvider , где значение показывает идентификатор Action Provider, который добавляет к меню дополнительные точки включения. Точки включения не должны программно удаляться, так как другие расширения могут зависить от них. Если ваше представление не использует конкретную точку включения, то вы можете пропустить ее, когда определяете ваш элемент popupElement.