Конфигурация стандартной программы просмотра

org.eclipse.ui.navigator.viewer

3.2

Элемент viewer определяет конфигурацию стандартной программы просмотра. Расширение может предоставлять ИД пользовательского всплывающего меню, определять, предоставляет ли программа просмотра ссылку на поддержку редактора, диалоговое окно фильтра и/или диалоговое окно "Доступные настройки". Кроме этого, вложенные элементы конфигурации обеспечивают управление структурой и поведением всплывающего контекстного меню.

viewerContentBinding связывает определенные расширения содержимого (посредством точки расширения navigatorContent) с программами просмотра (определенными с помощью точки расширения org.eclipse.ui.views). Любое расширение содержимого, связанное с программой просмотра, описывается как видимое. Служба информационного наполнения (org.eclipse.ui.navigator.INavigatorContentService) не будет возвращать расширения, которые не видны для ИД программы просмотра.

<!ELEMENT extension (viewer* , viewerContentBinding* , viewerActionBinding* , dragAssistant)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT viewer (popupMenu? , options?)>

<!ATTLIST viewer

viewerId    CDATA #REQUIRED

popupMenuId CDATA #IMPLIED>

Предоставляет основную конфигурацию для установления параметров программы просмотра. Для создания компонента панели клиенты также должны определить расширение org.eclipse.ui.views.



<!ELEMENT viewerContentBinding (includes? , excludes?)>

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

Клиенты должны определить один или несколько элементов viwerContentBinding для описания того, какие расширения содержимого и стандартные фильтры visible (видны) для программы просмотра. Расширение содержимого или стандартный фильтр visible (видны), если их ИД соответствует оператору includes в viewerContentBinding и не исключен оператором excludes. Если расширение содержимого или стандартный фильтр не visible (видны) для программы просмотра, то служба информационного наполнения для данной программы просмотра никогда не будет запрашивать содержимое у данного расширения и данное расширение не будет представлено для пользователя в диалоговом окне доступных фильтров.

Клиенты могут определить элемент includes для выбора того, какие расширения visible (видны) для программы просмотра, и элемент excludes для расширений, которые не должны быть visible (видны) для программы просмотра. Клиенты могут далее определить расширения, которые следует запрашивать явным образом для корневых элементов (посредством ITreeContentProvider.getElements()) с помощью атрибута "isRoot". Если для одного или нескольких элементов contentExtension атрибут "isRoot"=true в операторе includes, то для корневых элементов будут запрашиваться только эти расширения. Атрибут "isRoot" не воздействует на исключения.

Программа просмотра может иметь несколько определенных viewerContentBindings, и из операторы includes/excludes будут объединены для определения окончательного поведения.



<!ELEMENT viewerActionBinding (includes? , excludes?)>

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

Клиенты должны определить, какие модули действий видны для их программы просмотра. Клиенты могут определить элемент includes для выбора того, какие расширения видны для программы просмотра, и элемент excludes для расширений, которые не должны быть видны для программы просмотра.

Программа просмотра может иметь несколько определенных привязок viewerActionBinding, и их операторы includes/excludes будут объединены для определения окончательного поведения.

Для определений actionProvider, не вложенных в определение navigatorContent клиенты могут указать пользовательский ИД. Если клиенты не указывают ИД, то по умолчанию используется ИД = "org.eclipse.ui.navigator.actionProvider.X". Если необходимо использовать actionProvider без определенного ИД, то в качестве ИД по умолчанию клиенты должны определить viewerActionBinding. Пример приведен в разделе примеров.



<!ELEMENT includes ((contentExtension+) | (actionExtension+))>

Определите набор шаблонов, которые следует включить при поиске расширений содержимого для программы просмотра, соответствующей атрибуту "viewerId". Если операторы includes и excludes statements пересекаются, преимущество имеет оператор includes.



<!ELEMENT excludes ((contentExtension+) | (actionExtension+))>

Определите набор шаблонов, которые следует исключить при поиске расширений содержимого для программы просмотра, соответствующей атрибуту "viewerId". Если операторы includes и excludes statements пересекаются, преимущество имеет оператор includes.



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

Указывает ИД (или соответствующий шаблон) расширения содержимого, который следует запросить с помощью ITreeContentProvider.getElements() или ITreeContentProvider.getChildren() для корневого субъекта программы просмотра или стандартного фильтра, который должен быть доступен для пользователя в диалоговом окне "Доступные фильтры".

Клиенты могут указать "isRoot" для выбора определенных корневых расширений с целью переопределения расширений, которые в ином случае будут включены для элемента ввода программы просмотра (на основании соответствующего выражения triggerPoints для элемента ввода программы просмотра).

Дополнительная информация приведена в документации по viewerContentBinding.



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

Указывает, что расширение действий должно иметь возможность участия в контекстном меню и панелях действий.

Дополнительная информация приведена в документации по viewerActionBinding.



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

Элемент popupMenu можно определить только в том случае, если не задан атрибут "popupMenuId" элемента viewer.

Элемент popupMenu допускает дополнительную настройку контекстного меню, связанного с программой просмотра. Для правильного применения опций экземпляр программы просмотра должен делегировать org.eclipse.ui.navigator.NavigatorActionService, поведение которого аналогично поведению org.eclipse.ui.ActionGroup. Дополнительная информация об использовании данной функциональной возможности приведена в документации по данному классу API. Для клиентов, использующих экземпляр org.eclipse.ui.navigator.CommonNavigator, никаких дополнительных действий не требуется.

popupMenu объявляет одну или несколько insertionPoints, которые будут применяться участниками для организации дополнений в осмысленный, более доступный для пользователей, согласованный список.
Если клиентом задан только атрибут "popupMenuId" элемента viewer, то набор insertionPoints, используемый контекстным меню, будет являться набором по умолчанию для следующего списка в указанном порядке:

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


Клиенты, для которых необходимо обращаться к этим значением программным образом, могут использовать соответствующие константы в org.eclipse.ui.navigator.ICommonMenuConstants.

Клиенты, в которых требуется настроить меню, могут при необходимости добавлять или удалять точки вставки из этого списка. Клиенты также могут использовать шаблон, в котором каждое имя группы начинается с "group.".

Если элемент popupMenu задан и не содержит дочерних элементов insertionPoint, то в контекстном меню не будет опубликованных точек вставки. Конечно, для программируемых клиентов можно при необходимости добавлять собственные точки вставки. Определенные клиентами программы просмотра могут публиковать свои точки вставки для документирования и информирования программ просмотра/навигаторов находящихся по течению расширений, либо явным образом документировать, какие точки вставки считаются API, а какие считаются внутренними.



<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name      CDATA #REQUIRED

separator (true | false) >

Определяет точку вставки для контекстного меню. Включает имя точки для ссылок со стороны клиентов, а также определяет, следует ли выводить точку вставки как разделитель или как маркер группы.



<!ELEMENT options (property+)>

Предоставляет опции программы просмотра для настройки ее представления пользователю. Доступные свойства см. в org.eclipse.ui.navigator.INavigatorViewerDescriptor.



<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Предоставляет пару имя=значение. Значение будет предоставлено программе просмотра "как есть" (например, пустые строки будут распространяться как пустые строки). Доступные свойства и их описание см. в org.eclipse.ui.navigator.INavigatorViewerDescriptor.



<!ELEMENT dragAssistant EMPTY>

<!ATTLIST dragAssistant

class    CDATA #REQUIRED

viewerId CDATA #REQUIRED>

Помощник Drag and Drop предоставляет облегченный перехватчик для поддержки дополнительных типов передачи и логику для установки перенесенных данных. Этот элемент не является обязательным, поскольку базовый org.eclipse.ui.navigator.CommonViewer предоставляет тип org.eclipse.jface.util.LocalSelectionTransfer.

Клиентам следует определять это расширение только в облегченных модулях с неразветвленными деревьями зависимостей. Помощники по переносу должны быть загружены при создании программы просмотра, что вызовет загрузку затронутых модулей.



В следующем примере показана настройка ИД всплывающего меню для программы просмотра.


   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer id=

"org.eclipse.testViewer"

popupMenuId=

"org.eclipse.testViewer#PopupMenu"

/>

</extension>

Поскольку дочерний элемент popupMenu программы просмотра не используется в приведенном выше примере, то будет использован набор insertionPoints по умолчанию. Этот набор определяется следующим образом. Дополнительная информация приведена в документации по элементу popupMenu.

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

В следующем примере приведена конфигурация программы просмотра, которая объявляет пользовательские popupMenu/insertionPoints, однако ограничивает дополнения объектов и программы просмотра с помощью атрибута "allowsPlatformContributions". Клиенты могут вносить дополнения только в определенное меню с помощью модулей org.eclipse.ui.navigator.CommonActionProvider, объявленных для программы просмотра (либо верхнего уровня, либо связанных с расширениями содержимого).

Обратите внимание, что атрибут "popupMenuId" не задается одновременно с элементом popupMenu. В конфигурации не допускается одновременное применение и данного атрибута, и данного элемента.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<popupMenu allowsPlatformContributions=

"false"

id=

"org.eclipse.ui.navigator.resourceContent#PopupMenu"

>

<insertionPoint name=

"group.new"

/>

<insertionPoint name=

"group.open"

separator=

"true"

/>

<insertionPoint name=

"group.openWith"

/>

<insertionPoint name=

"group.port"

separator=

"true"

/>

<insertionPoint name=

"additions"

separator=

"true"

/>

<insertionPoint name=

"group.properties"

separator=

"true"

/>

</popupMenu>

</viewer>

<viewerContentBinding viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<includes>

<contentExtension pattern=

"org.eclipse.ui.navigator.resourceContent"

/>

</includes>

</viewerContentBinding>

</extension>

В следующем примере объявляется, что одно расширение содержимого (ИД: "org.eclipse.ui.navigator.resourceContent") связано с программой просмотра, соответствующей ИД "org.eclipse.ui.navigator.resourceContent". (В этом примере идентификаторы расширения содержимого и программы просмотра совпадают, однако это необязательно.) Также все расширения содержимого, ИД которых начинается с "org.eclipse.ui.navigator.tests.", будут игнорироваться.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerContentBinding viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<includes>

<contentExtension pattern=

"org.eclipse.ui.navigator.resourceContent"

/>

</includes>

<excludes>

<contentExtension pattern=

"org.eclipse.ui.navigator.tests.*"

/>

</excludes>

</viewerContentBinding>

</extension>

В следующем примере объявляется viewerActionBinding для всех модулей actionProvider (не вложенных в расширение navigatorContent), которые соответствуют регулярному выражению "org.acme.actions.*", и не соответствуют выражению "org.acme.actions.tests.*". Это выражение сделает все actionProvider, ИД которых начинается с "org.acme.actions.", но не с "org.acme.actions.tests.", visible (видимыми) для программы просмотра с ИД "org.acme.viewer". Конечно, viewerActionBindings применяются только к элементам actionProvider, которые не вложены в элемент navigatorContent. visibility (область видимости) вложенных элементов actionProvider контролируется viewerContentBindings для включающего элемента navigatorContent.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

"org.acme.actions.*"

/>

</includes>

<excludes>

<actionExtension pattern=

"org.acme.actions.tests.*"

/>

</excludes>

</viewerActionBinding>

</extension>

В следующем примере любой actionProvider, в котором отсутствует атрибут "id", будет visible (виден) для программы просмотра "org.acme.viewer". Модули actionProvider, в которых отсутствует атрибут "id", имеют ИД по умолчанию "org.eclipse.ui.navigator.actionProvider.X". Конечно, viewerActionBindings применяются только к элементам actionProvider, которые не вложены в элемент navigatorContent. visibility (область видимости) вложенных элементов actionProvider контролируется viewerContentBinding для включающего элемента navigatorContent.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

"org.eclipse.ui.navigator.actionProvider.*"

/>

</includes>

</viewerActionBinding>

</extension>

В следующем примере показаны стандартные свойства, доступные для программы просмотра.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer popupMenuId=

"org.eclipse.ui.tests.navigator.TestView#PopupMenu"

viewerId=

"org.eclipse.ui.tests.navigator.TestView"

>

<options>

<!-- Скрыть вкладку

"Available Extensions"

в диалоговом окне

"Available Customizations"

(доступном в действии

"Filters"

-->

<property name=

"org.eclipse.ui.navigator.hideAvailableExtensionsTab"

value=

"true"

/>

<!-- Скрыть диалоговое окно

"Available Customizations"

Будут скрыты фильтры и доступные расширения содержимого. -->

<property name=

"org.eclipse.ui.navigator.hideAvailableCustomizationsDialog"

value=

"true"

/>

<!-- Скрыть действие

"Связь с редактором"

в панели инструментов программы просмотра -->

<property name=

"org.eclipse.ui.navigator.hideLinkWithEditorAction"

value=

"true"

/>

<!-- Скрыть действие

"Свернуть все"

в панели инструментов программы просмотра -->

<property name=

"org.eclipse.ui.navigator.hideCollapseAllAction"

value=

"true"

/>

</options>

</viewer>

</extension>