Configurazione visualizzatore comune

org.eclipse.ui.navigator.viewer

3.2

L'elemento visualizzatore definisce la configurazione di un visualizzatore comune. L'estensione può fornire un ID di menu a comparsa personalizzato, sovrascrivere l'impostazione per cui vengono forniti collegamenti con supporto per editor, fornisce una finestra di filtraggio e/o fornisce una finestra "Personalizzazioni disponibili". Inoltre, gli elementi di configurazione nidificati danno pieno controllo alla struttura e al comportamento del menu di scelta rapida.

viewerContentBinding associa le estensioni di contenuto definite (attraverso il punto di estensione navigatorContent) ai visualizzatori (definiti attraverso il punto di estensione org.eclipse.ui.views). Qualsiasi estensione di contenuto associata a un visualizzatore è descritta come visibile. Il servizio di contenuto (org.eclipse.ui.navigator.INavigatorContentService) non restituirà alcuna estensione non visibile all'ID del visualizzatore.

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

Fornisce una configurazione di base per stabilire le caratteristiche di un visualizzatore. I client devono anche definire un'estensione org.eclipse.ui.views per creare la parte di visualizzazione.



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

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

I client devono definire uno o più elementi viwerContentBinding per descrivere quali estensioni del contenuto e quali filtri comuni sono visibili al visualizzatore. Un'estensione di contenuto o un filtro comune è visibile se l'ID dell'estensione di contenuto o il filtro comune corrisponde a un'istruzione includes in un viewerContentBinding e non è esclusa da un'istruzione excludes. Se un'estensione del contenuto o un filtro comune non è visibile a un visualizzatore, nessun servizio di contenuto richiederà mai all'estensione il contenuto e non verrà mai presentata all'utente nella finestra dei filtri disponibili.

I client possono definire un elemento includes per selezionare le estensioni visibili al visualizzatore, e allo stesso modo un'elemento excludes per le estensioni che non devono essere visibili al visualizzatore. I client possono ulteriormente definire le estensioni che devono essere esplicitamente sottoposte a query per gli elementi principali (mediante ITreeContentProvider.getElements()) con l'attributo "isRoot". Se uno i più elementi contentExtension hanno "isRoot" impostato su true nell'istruzione includes, gli elementi principali verranno ricercati solo in quelle estensioni. L'attributo "isRoot" non ha effetto per le esclusioni.

È possibile definire più viewerContentBindings per un visualizzatore e le rispettive istruzioni verranno aggregate per produrre il comportamento finale.



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

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

I client devono definire i fornitori di azioni visibili per il visualizzatore. I client possono definire un elemento includes per selezionare le estensioni visibili al visualizzatore, e allo stesso modo un'elemento excludes per le estensioni che non devono essere visibili al visualizzatore.

È possibile definire più viewerActionBinding per un visualizzatore e le rispettive istruzioni includes/excludes verranno aggregate per produrre il comportamento finale.

Per le definizioni actionProvider non nidificate in una definizione navigatorContent, i client possono specificare un ID personalizzato. Se i client non specificano alcun ID, per impostazione predefinita viene utilizzato "org.eclipse.ui.navigator.actionProvider.X". Per i client che preferiscono utilizzare actionProvider senza un ID specifico, sarà necessario definire un viewerActionBinding per l'ID predefinito. Fare riferimento alla sezione degli esempi.



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

Definisce un insieme di modelli da includere quando si ricercano le estensioni del contenuto per il visualizzatore che corrisponde all'attributo "viewerId". Quando le istruzioni includes ed excludes si accavallano, verrà data la precedenza all'istruzione includes.



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

Definisce un insieme di modelli da escludere quando si ricercano le estensioni del contenuto per il visualizzatore che corrisponde all'attributo "viewerId". Quando le istruzioni includes ed excludes si accavallano, verrà data la precedenza all'istruzione includes.



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

Indica l'ID (o modello di corrispondenza) di un'estensione di contenuto che deve essere interrogata da ITreeContentProvider.getElements() o ITreeContentProvider.getChildren() per l'elemento principale del visualizzatore e che deve essere disponibile per l'utente nella finestra "Filtri disponibili".

I client possono specificare "isRoot" per selezionare estensioni principali specifiche per sovrascrivere le estensioni che altrimenti verrebbero abilitate dall'elemento di input del visualizzatore (in base all'espressione triggerPoints corrispondente per l'elemento di input del visualizzatore).

Per ulteriori informazioni, fare riferimento alla documentazione relativa a viewerContentBinding.



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

Indica che l'estensione di azioni può contribuire al menu di scelta rapida e alle barre di azioni.

Per ulteriori informazioni, fare riferimento alla documentazione relativa a viewerActionBinding.



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

È possibile definire un elemento popupMenu solo se l'attributo "popupMenuId" dell'elemento viewer non è specificato.

L'elemento popupMenu consente di personalizzare ulteriormente il menu di scelta rapida con il visualizzatore. Affinché le opzioni vengano applicate correttamente, è necessario delegare un'istanza del visualizzatore a org.eclipse.ui.navigator.NavigatorActionService, che si comporterà come un org.eclipse.ui.ActionGroup normale. Per ulteriori informazioni sull'uso di questa funzione, fare riferimento alla documentazione relativa a questa classe API. Per i client che utilizzano un'istanza di org.eclipse.ui.navigator.CommonNavigator non è necessario effettuare alcuna operazione.

Un popupMenu dichiara uno o più insertionPoints che verranno utilizzati dai contributor per organizzare i rispettivi contributi in un elenco coerente, logico e semplice da utilizzare.
Se i client specificano solo l'attributo "popupMenuId" dell'elemento viewer, l'insieme di insertionPoints utilizzato dal menu di scelta rapida, si servirà del seguente elenco.

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


I client che desiderano utilizzare questi valori programmaticamente, possono utilizzare le costanti corrispondenti in org.eclipse.ui.navigator.ICommonMenuConstants.

I client che desiderano personalizzare i propri menu, dovrebbero iniziare da questo elenco e aggiungervi o rimuovere i punti di inserimento in base alle proprie necessità. Si consiglia inoltre ai client, di attenersi alla regola secondo la quale ciascun nome di gruppo inizia per "group.".

Se viene specificato l'elemento popupMenu e non contiene nessun elemento secondario insertionPoint, il menu di scelta rapida non avrà punti di inserimento pubblicati. Naturalmente, non si impedisce ai client programmatici di aggiungere i propri punti di inserimento. I client che definiscono i i visualizzatori dovrebbero pubblicare i propri punti di inserimento per facilitare la documentazione per i propri visualizzatori/navigatori, o per indicare esplicitamente i punti di inserimento che sono considerati API e quelli che sono considerati interni.



<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name      CDATA #REQUIRED

separator (true | false) >

Definisce un punto di inserimento per il menu di scelta rapida. Include il nome del punto a cui i client possono fare riferimento e indica se il punto di inserimento deve essere reso come un separatore o un indicatore di gruppo.



<!ELEMENT options (property+)>

Fornisce opzioni per personalizzare l'aspetto del visualizzatore. Per le proprietà disponibili, vedere org.eclipse.ui.navigator.INavigatorViewerDescriptor.



<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Fornisce una coppia nome=valore. Il valore verrà fornito nello stato in cui si trova al visualizzatore (in modo che le stringhe vuote vengano propagate come stringhe vuote). Per le proprietà disponibili e le relative descrizioni, vedere org.eclipse.ui.navigator.INavigatorViewerDescriptor.



<!ELEMENT dragAssistant EMPTY>

<!ATTLIST dragAssistant

class    CDATA #REQUIRED

viewerId CDATA #REQUIRED>

L'assistente al trascinamento fornisce altri tipi di trasferimento e logica per impostare il trascinamento dei dati. Questo elemento non è obbligatorio, in quanto org.eclipse.ui.navigator.CommonViewer di base fornisce un tipo org.eclipse.jface.util.LocalSelectionTransfer.

I client dovrebbero definire questa estensione solo nei plugin di tipo lightweight con strutture di dipendenza superficiali. L'assistente al trascinamento deve essere caricato durante la creazione del visualizzatore, in modo che vengano caricati anche i plugin interessati.



Mediante il seguente esempio, è possibile configurare l'ID del menu a comparsa di un visualizzatore.


   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer id=

"org.eclipse.testViewer"

popupMenuId=

"org.eclipse.testViewer#PopupMenu"

/>

</extension>

Poiché l'elemento secondario popupMenu del visualizzatore non è utilizzato nell'esempio precedente, verrà utilizzato l'insieme predefinito di insertionPoints. Di seguito è riportata la definizione dell'insieme. Per ulteriori informazioni, fare riferimento all'elemento 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"

Il seguente esempio mostra una configurazione del visualizzatore che dichiara un popupMenu/insertionPoints personalizzato, ma limita i contributi agli oggetti e al visualizzatore con l'attributo "allowsPlatformContributions". I client possono applicare contributi al menu definito solo con i org.eclipse.ui.navigator.CommonActionProvider dichiarati per il visualizzatore (a livello superiore o associati alle estensioni del contenuto).

Tenere presente che l'attributo "popupMenuId" non viene specificato contemporaneamente all'elemento popupMenu. Una configurazione valida può contenere o l'uno o l'altro, ma non entrambi.

   

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

Il seguente esempio dichiara che un'estensione di contenuto (ID: "org.eclipse.ui.navigator.resourceContent") è associata ad un visualizzatore che corrisponde all'ID "org.eclipse.ui.navigator.resourceContent". In questo esempio gli id dell'estensione e del visualizzatore corrispondono, ma non è una condizione obbligatoria. Inoltre, qualsiasi estensione di contenuto con ID che inizia con "org.eclipse.ui.navigator.tests." verrà ignorata.

   

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

Il seguente esempio dichiara un viewerActionBinding per tutti i actionProvider (non nidificati nell'estensione navigatorContent) che corrisponde all'espressione regolare "org.acme.actions.*" ma non a "org.acme.actions.tests.*". Questa espressione renderà ogni actionProvider il cui ID comincia con "org.acme.actions." ma non con "org.acme.actions.tests." visibile al visualizzatore con ID "org.acme.viewer". viewerActionBindings è valido solo per gli elementi actionProvider non nidificati nell'elemento navigatorContent. La visibilità degli elementi actionProvider nidificati è controllata da viewerContentBindings per gli elementi navigatorContent di chiusura.

   

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

Il seguente esempio rende qualsiasi actionProvider senza attributo "id" visibile al visualizzatore "org.acme.viewer". Gli actionProvider senza attributo "id" hanno l'ID predefinito "org.eclipse.ui.navigator.actionProvider.X". viewerActionBindings è valido solo per gli elementi actionProvider non nidificati nell'elemento navigatorContent. La visibilità degli elementi actionProvider nidificati è controllata dai viewerContentBinding per gli elementi navigatorContent di chiusura.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

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

/>

</includes>

</viewerActionBinding>

</extension>

Il seguente esempio mostra le proprietà standard disponibili per il visualizzatore.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer popupMenuId=

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

viewerId=

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

>

<options>

<!-- Hide the

"Available Extensions"

tab in the

"Available Customizations"

dialog (available from the

"Filters"

action -->

<property name=

"org.eclipse.ui.navigator.hideAvailableExtensionsTab"

value=

"true"

/>

<!-- Hide the

"Available Customizations"

dialog completely. This includes hiding the filters and the available content extensions. -->

<property name=

"org.eclipse.ui.navigator.hideAvailableCustomizationsDialog"

value=

"true"

/>

<!-- Hide the

"Link with Editor"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideLinkWithEditorAction"

value=

"true"

/>

<!-- Hide the

"Collapse All"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideCollapseAllAction"

value=

"true"

/>

</options>

</viewer>

</extension>