Konfiguracja wspólnej przeglądarki

org.eclipse.ui.navigator.viewer

3.2

Element viewer definiuje konfigurację wspólnej przeglądarki. Rozszerzenie może udostępniać identyfikator niestandardowego menu podręcznego, a także nadpisywać ustawienia określające, czy przeglądarka udostępnia odsyłacz z obsługą edytora, okno dialogowe filtrowania lub okno dialogowe "Dostępne dostosowania". Dodatkowe zagnieżdżone elementy konfiguracji zapewniają pełną kontrolę nad strukturą i zachowaniem podręcznego menu kontekstowego.

Element viewerContentBinding wiąże zdefiniowane rozszerzenia treści (przez punkt rozszerzenia navigatorContent) z przeglądarkami (zdefiniowanymi przez punkt rozszerzenia org.eclipse.ui.views). Każde rozszerzenie treści powiązane z przeglądarką jest opisane jako widoczne. Usługa treści (org.eclipse.ui.navigator.INavigatorContentService) nie zwraca rozszerzeń, które nie są widoczne dla jej identyfikatora przeglądarki.

<!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>

Udostępnia podstawową konfigurację umożliwiającą ustanowienie parametrów przeglądarki. Klienty muszą też zdefiniować rozszerzenie org.eclipse.ui.views aby utworzyć część widoku.



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

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

Klienty muszą zdefiniować jeden lub więcej elementów viewerContentBinding, aby opisać, które rozszerzenia treści oraz wspólne filtry są widoczne dla przeglądarki. Rozszerzenie treści lub filtr wspólny są widoczne, jeśli identyfikator rozszerzenia treści lub wspólnego filtru jest zgodny z dyrektywą includes w elemencie viewerContentBinding i nie jest wyłączony za pomocą dyrektywy excludes. Jeśli rozszerzenie treści lub filtr wspólny nie są widoczne dla przeglądarki, prośba o treść nie będzie nigdy przekazywana do rozszerzenia przez usługę treści dla tej przeglądarki, a rozszerzenie nie będzie prezentowane użytkownikowi w oknie dialogowym dostępnych filtrów.

Klienty mogą definiować element includes aby wybrać, które rozszerzenia są widoczne dla przeglądarki, a także element excludes określający rozszerzenia, które nie powinny być widoczne dla przeglądarki. Klienty mogą też definiować rozszerzenia, do których powinny być przesyłane jawne zapytania o elementy główne (przez mechanizm ITreeContentProvider.getElements()) wysyłane przez atrybut "isRoot". Jeśli jeden lub więcej elementów contentExtension ma atrybut "isRoot" o wartości true w dyrektywie includes, tylko do tych rozszerzeń będą przesyłane zapytania o elementy główne. Atrybut "isRoot" nie ma wpływu na wyłączenia.

Przeglądarka może mieć wiele zdefiniowanych elementów viewerContentBindings, a ich dyrektywy includes i excludes będą agregowane w celu określenia ostatecznego zachowania.



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

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

Klienty muszą zdefiniować, którzy dostawcy akcji są widoczne dla swoich przeglądarek. Klienty mogą definiować element includes, aby wybrać rozszerzenia widoczne dla przeglądarki, a także element excludes określający rozszerzenia, które nie powinny być widoczne dla przeglądarki.

Przeglądarka może mieć wiele zdefiniowanych elementów viewerActionBinding, a ich dyrektywy includes i excludes będą agregowane w celu określenia ostatecznego zachowania.

Dla definicji actionProvider, które nie są zagnieżdżone w definicji navigatorContent, klienty mogą określić niestandardowy identyfikator. Jeśli klienty nie określą identyfikatora, jego wartością domyślną będzie "org.eclipse.ui.navigator.actionProvider.X". Klienty, dla których ma być dostępna definicja actionProvider bez konkretnego identyfikatora, muszą zdefiniować viewerActionBinding dla identyfikatora domyślnego. Sposób realizacji tego zadania przedstawiono w sekcji zawierającej przykłady.



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

Definiuje zbiór wzorców, które powinny być wzięte pod uwagę podczas szukania rozszerzeń treści dla przeglądarki odpowiadającej atrybutowi "viewerId". Jeśli dyrektywy includes i excludes mają część wspólną, priorytetowa jest dyrektywa includes.



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

Definiuje zbiór wzorców, które nie powinny być brane pod uwagę podczas szukania rozszerzeń treści dla przeglądarki odpowiadającej atrybutowi "viewerId". Jeśli dyrektywy includes i excludes mają część wspólną, priorytetowa jest dyrektywa includes.



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

Określa identyfikator (lub pasujący wzorzec) rozszerzenia treści, do którego powinno być wysyłane zapytanie z ITreeContentProvider.getElements() lub ITreeContentProvider.getChildren(), w celu uzyskania elementu głównego przeglądarki lub wspólnego filtru, który powinien być dostępny dla użytkownika w oknie dialogowym "Dostępne filtry".

Klienty mogą określać element "isRoot", aby wybrać konkretne rozszerzenia główne do nadpisania rozszerzeń, które byłyby aktywne dla elementu wejściowego przeglądarki (w oparciu o pasujące wyrażenie triggerPoints dla elementu wejściowego przeglądarki).

Więcej informacji na ten temat zawiera dokumentacja viewerContentBinding.



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

Wskazuje rozszerzenie akcji, które powinno mieć możliwość udziału w menu kontekstowym i paskach działań.

Więcej informacji na ten temat zawiera dokumentacja viewerActionBinding.



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

Element popupMenu może być zdefiniowany tylko wówczas, gdy atrybut "popupMenuId w elemencie viewer nie jest określony.

Element popupMenu umożliwia dalsze dostosowanie menu kontekstowego powiązanego z przeglądarką. Aby opcje były prawidłowo zastosowane, instancja przeglądarki musi delegować do elementu org.eclipse.ui.navigator.NavigatorActionService, który zachowuje się jak normalny element org.eclipse.ui.ActionGroup. Więcej informacji na temat korzystania z tej funkcjonalności znajduje się w dokumentacji tej klasy API. Dla klientów, którzy używają instancji org.eclipse.ui.navigator.CommonNavigator, nie trzeba wykonywać żadnych dodatkowych działań.

Element popupMenu deklaruje jeden lub więcej punktów insertionPoint, które będą używane przez kontrybutory w celu organizowania wnoszonych obiektów w bardziej przyjazną dla użytkownika, czytelną i spójną listę.
Jeśli klienty określają tylko atrybut "popupMenuId" elementu viewer, zestaw punktów insertionPoint używanych przez menu kontekstowe będzie miał wartość domyślną w postaci następującej listy, w przedstawionej kolejności:

"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"


Klienty, którym potrzebne jest programistyczne odwołanie do tych wartości, mogą użyć odpowiadających im stałych w elemencie org.eclipse.ui.navigator.ICommonMenuConstants.

Klienty, którym potrzebne jest menu niestandardowe, mogą rozpocząć od tej listy i dodawać lub usuwać punkty wstawiania w miarę potrzeb. Zaleca się też, aby stosować wzorzec rozpoczynania każdej nazwy grupy od słowa "group".

Jeśli element popupMenu jest określony i nie zawiera żadnych elementów potomnych insertionPoint, menu kontekstowe nie będzie miało żadnych opublikowanych punktów wstawiania. Oczywiście klienty programowe nie mają ograniczeń w zakresie dodawania własnych punktów wstawiania, w miarę potrzeb. Klienty definiujące przeglądarki powinni publikować punkty wstawiania dla celów dokumentacji oraz wyjaśnienia działania rozszerzeń zgodnych z przeglądarkami/nawigatorami, lub też jawnie dokumentować, które punkty wstawiania są uznawane za elementy API, a które są wewnętrzne.



<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name      CDATA #REQUIRED

separator (true | false) >

Definiuje punkt wstawiania dla menu kontekstowego. Zawiera nazwę punktu, do której mogą odnosić się klienty, a także określa, czy punkt wstawiania powinien być renderowany jako separator, czy znacznik grupy.



<!ELEMENT options (property+)>

Udostępnia przeglądarce opcje dopasowania sposobu prezentacji dla użytkownika. Więcej informacji o dostępnych właściwościach zawiera dokumentacja interfejsu org.eclipse.ui.navigator.INavigatorViewerDescriptor.



<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Udostępnia parę nazwa=wartość. Wartość będzie udostępniona przeglądarce w niezmienionej formie (a więc łańcuchy puste będą propagowane jako łańcuchy puste). Więcej informacji o dostępnych właściwościach, wraz z ich opisami, zawiera dokumentacja interfejsu org.eclipse.ui.navigator.INavigatorViewerDescriptor.



<!ELEMENT dragAssistant EMPTY>

<!ATTLIST dragAssistant

class    CDATA #REQUIRED

viewerId CDATA #REQUIRED>

Asystent przeciągania i upuszczania udostępnia prosty hak do udostępniania dodatkowych typów przesyłania oraz logikę konfiguracji danych przeciągania. Ten element nie jest wymagany, ponieważ podstawowy element org.eclipse.ui.navigator.CommonViewer udostępnia typ org.eclipse.jface.util.LocalSelectionTransfer.

To rozszerzenie powinno być definiowane w klientach tylko w lekkich wtyczkach z płytkimi drzewami zależności. Asystentów przeciągania należy załadować na początku, przy tworzeniu przeglądarki, co wymusi załadowanie odpowiednich wtyczek.



W poniższym przykładzie konfigurowane jest menu podręczne dla przeglądarki.


   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer id=

"org.eclipse.testViewer"

popupMenuId=

"org.eclipse.testViewer#PopupMenu"

/>

</extension>

Ponieważ w powyższym przykładnie nie jest używany element potomny przeglądarki popupMenu, wykorzystany będzie domyślny zestaw punktów insertionPoint. Ten zestaw jest zdefiniowany tak, jak przedstawiono poniżej. Więcej informacji na ten temat zawiera dokumentacja elementu 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"

W poniższym przykładzie przedstawiono konfigurację przeglądarki, która deklaruje niestandardowe elementy popupMenu/insertionPoint, ale ogranicza możliwość wnoszenia obiektów i przeglądarek przy użyciu atrybutu "allowsPlatformContributions". Klienty mogą uzupełniać zdefiniowane menu przy użyciu elementów org.eclipse.ui.navigator.CommonActionProvider zadeklarowanych dla przeglądarki (najwyższego poziomu lub powiązanych z rozszerzeniami treści).

Należy zauważyć, że atrybut "popupMenuId" nie jest określony wspólnie z elementem popupMenu. Prawidłowa konfiguracja zawiera tylko jeden z nich, nie oba jednocześnie.

   

<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>

W poniższym przykładzie zadeklarowano, że jedno rozszerzenie treści (id: "org.eclipse.ui.navigator.resourceContent") jest powiązane z przeglądarką pasującą do identyfikatora "org.eclipse.ui.navigator.resourceContent" (w tym przykładzie identyfikatory rozszerzenia treści i przeglądarki są takie same, ale nie jest to wymagane). Występujące dalej rozszerzenia treści z identyfikatorem rozpoczynającym się od "org.eclipse.ui.navigator.tests." będą ignorowane.

   

<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>

W poniższym przykładzie zadeklarowano viewerActionBinding dla wszystkich elementów actionProvider (niezagnieżdżonych w rozszerzeniu navigatorContent), które są zgodne z wyrażeniem regularnym "org.acme.actions.*", ale nie są zgodne z wyrażeniem "org.acme.actions.tests.*". To wyrażenie spowoduje, że wszystkie elementy actionProvider, których identyfikator zaczyna się od "org.acme.actions.", ale nie zaczyna się od "org.acme.actions.tests.", będą widoczne dla przeglądarki z identyfikatorem "org.acme.viewer". Oczywiście viewerActionBindings odnosi się do elementów actionProvider, które nie są zagnieżdżone w elemencie navigatorContent. Widoczność zagnieżdżonych elementów actionProvider jest kontrolowana przez viewerContentBindings dla odpowiedniego elementu 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>

W poniższym przykładzie wszystkie elementy actionProvider bez atrybutu "id" będą widoczne dla przeglądarki "org.acme.viewer". Elementy actionProvider bez atrybutu "id" mają domyślny identyfikator "org.eclipse.ui.navigator.actionProvider.X". Oczywiście viewerActionBindings odnosi się do elementów actionProvider, które nie są zagnieżdżone w elemencie navigatorContent. Widoczność zagnieżdżonych elementów actionProvider jest kontrolowana przez viewerContentBinding dla odpowiedniego elementu navigatorContent.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

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

/>

</includes>

</viewerActionBinding>

</extension>

W poniższym przykładzie przedstawiono standardowe właściwości dostępne dla przeglądarki.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer popupMenuId=

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

viewerId=

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

>

<options>

<!-- Ukryj zakładkę

"Dostępne rozszerzenia"

w oknie dialogowym

"Dostępne dostosowania"

(dostępnym z działania

"Filtry"

-->

<property name=

"org.eclipse.ui.navigator.hideAvailableExtensionsTab"

value=

"true"

/>

<!-- Całkowicie ukryj okno dialogowe

"Dostępne dostosowania"

. Obejmuje to ukrycie filtrów i dostępnych rozszerzeń treści. -->

<property name=

"org.eclipse.ui.navigator.hideAvailableCustomizationsDialog"

value=

"true"

/>

<!-- Ukryj działanie

"Połącz z edytorem"

z paska narzędzi przeglądarki -->

<property name=

"org.eclipse.ui.navigator.hideLinkWithEditorAction"

value=

"true"

/>

<!-- Ukryj działanie

"Zwiń wszystko"

z paska narzędzi przeglądarki -->

<property name=

"org.eclipse.ui.navigator.hideCollapseAllAction"

value=

"true"

/>

</options>

</viewer>

</extension>