Insiemi di azioni

Identificativo: org.eclipse.ui.actionSets

Descrizione: questo punto di estensione viene utilizzato per aggiungere menu, voci di menu e pulsanti della barra degli strumenti alle aree comuni presenti nella finestra del workbench. Questi contributi sono conosciuti collettivamente come insiemi di azioni e vengono visualizzati nella finestra del workbench dall'utente che personalizza una prospettiva.

L'abilitazione e/o la visibilità di una azione possono essere definite utilizzando rispettivamente gli elementi enablement e visibility. Questi due elementi contengono un'espressione booleana valutata per stabilire l'abilitazione e/o la visibilità.

La sintassi per gli elementi enablement e visibility è uguale. Entrambi contengono un elemento secondario con espressione booleana. Nel caso più semplice, sarà un elemento objectClass, objectState, pluginState o systemProperty. Nei casi più complessi, gli elementi and, or e not saranno combinati per creare espressioni booleane. Sia l'elemento and che l'elemento or devono contenere 2 elementi secondari. L'elemento not deve contenere un solo elemento secondario.

Tag di configurazione:

   <!ELEMENT extension (actionSet+)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

   <!ELEMENT actionSet (menu* , action*)>

   Questo elemento è utilizzato per definire un gruppo di azioni e/o menu.

   <!ATTLIST actionSet
      id          CDATA #REQUIRED
      label       CDATA #REQUIRED
     visible     (true | false)
     description CDATA #IMPLIED
   >

   <!ELEMENT action (selection* | enablement?)>

   Questo elemento definisce un'azione che l'utente può richiamare dall'interfaccia utente.

   <!ATTLIST action
      id               CDATA #REQUIRED
      label            CDATA #REQUIRED
     accelerator      CDATA #IMPLIED
     definitionId     CDATA #IMPLIED
     menubarPath      CDATA #IMPLIED
     toolbarPath      CDATA #IMPLIED
      icon             CDATA #IMPLIED
     disabledIcon     CDATA #IMPLIED
     hoverIcon        CDATA #IMPLIED
      tooltip          CDATA #IMPLIED
     helpContextId    CDATA #IMPLIED
     style            (push|radio|toggle|pulldown) "push"
     state            (true | false)
     pulldown         (true | false)
     class            CDATA #IMPLIED
     retarget         (true | false)
     allowLabelUpdate (true | false)
     enablesFor       CDATA #IMPLIED
   >

   <!ELEMENT menu (separator+ , groupMarker*)>

   Questo elemento è utilizzato per definire un nuovo menu.

   <!ATTLIST menu
      id    CDATA #REQUIRED
      label CDATA #REQUIRED
     path  CDATA #IMPLIED
   >

   <!ELEMENT separator EMPTY>

   Questo elemento è utilizzato per creare un separatore di menu nel nuovo menu.

   <!ATTLIST separator
     name CDATA #REQUIRED
   >

   <!ELEMENT groupMarker EMPTY>

   Questo elemento è utilizzato per creare un gruppo denominato nel nuovo menu. A differenza dell'elemento separator, questo non dispone di una rappresentazione visiva.

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

  Questo elemento è utilizzato nella determinazione dell'abilitazione dell'azione in base alla selezione corrente. Viene ignorato se è specificato l'elemento enablement.

   <!ATTLIST selection
     class CDATA #REQUIRED
     name  CDATA #IMPLIED
   >

   <!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Questo elemento è utilizzato per definire l'abilitazione dell'azione.

   <!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Questo elemento è utilizzato per definire la visibilità dell'azione.

   <!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Questo elemento rappresenta un'operazione booleana AND sul risultato della valutazione delle due espressioni secondarie.

   <!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Questo elemento rappresenta un'operazione booleana OR sul risultato della valutazione delle due espressioni secondarie.

   <!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Questo elemento rappresenta un'operazione booleana NOT sul risultato della valutazione delle due espressioni secondarie.

   <!ELEMENT objectClass EMPTY>

   Questo elemento è utilizzato per valutare la classe o l'interfaccia di ciascun oggetto nella selezione corrente. Se ciascun oggetto nella selezione implementa la classe o interfaccia specificata, l'espressione è considerata verificata.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   Questo elemento è utilizzato per valutare lo stato dell'attributo di ciascun oggetto nella selezione corrente. Se ciascun oggetto nella selezione presenta lo stato dell'attributo specificato, l'espressione è considerata verificata. Per valutare questo tipo di espressione, tutti gli oggetti della selezione devono implementare o adattarsi all'interfaccia org.eclipse.ui.IActionFilter.

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

   Questo elemento è utilizzato per valutare lo stato di un plug-in. Lo stato di un plug-in può assumere i valori installed o activated.

   <!ATTLIST pluginState
      id    CDATA #REQUIRED
     value (installed|activated) "installed"
   >

   <!ELEMENT systemProperty EMPTY>

   Questo elemento è utilizzato per valutare lo stato delle proprietà di un sistema. Il valore della proprietà è richiamato da java.lang.System.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Esempi: di seguito è riportato un esempio di insieme di azioni (si notino gli elementi secondari e il modo in cui vengono utilizzati gli attributi):

    <extension point = "org.eclipse.ui.actionSets"> 
        <actionSet
            id="com.xyz.actionSet" 
            label="My Actions"> 
            <menu
               id="com.xyz.xyzMenu" 
               label="XYZ Menu"
               path="additions"> 
               <separator name="group1"/>
               <separator name="option1"/>
            </menu>
            
            <action
               id="com.xyz.runXYZ" 
               label="&amp;Run XYZ Tool"
               style="toggle"
               state="false"
               menubarPath="com.xyz.xyzMenu/group1" 
               icon="icons/runXYZ.gif" 
               tooltip="Run XYZ Tool" 
               helpContextId="com.xyz.run_action_context" 
               class="com.xyz.actions.RunXYZ" 
               enablesFor="1"> 
               <selection class="org.eclipse.core.resources.IFile" name="*.java"/> 
            </action>
            <action 
               id="com.xyz.runABC"
               label="&amp;Run ABC Tool"
               style="push"
               menubarPath="com.xyz.xyzMenu/group1"
               toolbarPath="Normal/XYZ"
               icon="icons/runABC.gif"
               tooltip="Run ABC Tool"
               helpContextId="com.xyz.run_abc_action_context"
               retarget="true"
               allowLabelUpdate="true">
               <enablement>
                  <and>
                     <objectClass name="org.eclipse.core.resources.IFile"/>
                     <not>
                        <objectState name="extension" value="java"/>
                     </not>
                  </and>
               </enablement>
            </action>             

            <action 
               id="com.xyz.runDEF"
               label="&amp;Run DEF Tool"
               style="radio"
               state="true"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runDEF.gif"
               tooltip="Run DEF Tool"
               class="com.xyz.actions.RunDEF" 
               helpContextId="com.xyz.run_def_action_context">
            </action>             
            <action 
               id="com.xyz.runGHI"
               label="&amp;Run GHI Tool"
               style="radio"
               state="false"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runGHI.gif"
               tooltip="Run GHI Tool"
               class="com.xyz.actions.RunGHI" 
               helpContextId="com.xyz.run_ghi_action_context">
            </action>             
            <action 
               id="com.xyz.runJKL"
               label="&amp;Run JKL Tool"
               style="radio"
               state="false"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runJKL.gif"
               tooltip="Run JKL Tool"
               class="com.xyz.actions.RunJKL" 
               helpContextId="com.xyz.run_jkl_action_context">
            </action>             
        </actionSet> 
    </extension> 

Nell'esempio sopra riportato, l'insieme di azioni specificato, denominato "My Actions", può inizialmente essere visualizzato in ciascuna prospettiva in quanto non è specificato l'attributo visible.

L'azione XYZ apparirà come una casella di controllo non selezionata. Sarà abilitata solo se il numero di selezione è 1 e la selezione contiene una risorsa file Java.

L'azione ABC apparirà sia nel menu che nella barra degli strumenti. Sarà abilitata solo se la selezione non contiene alcuna risorsa file Java. Si noti anche che questa è un'azione di etichetta retarget e pertanto non fornisce un attributo class.

Le azioni DEF, GHI e JKL appariranno come pulsanti di opzione. Questi saranno sempre abilitati, indipendentemente dallo stato di selezione corrente.

Informazione API: il valore dell'attributo class deve essere un nome completo di una classe che implementa org.eclipse.ui.IWorkbenchWindowActionDelegate o org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Quest'ultima sarà implementata nei casi in cui l'attributo style ha il valore pulldown. Questa classe è il gestore responsabile dell'esecuzione dell'azione. Questo attributo viene ignorato, e non deve essere fornito, se l'attributo retarget è true. Questa classe viene caricata per ultima, in modo da evitare il caricamento dell'intero plug-in prima del necessario.

I criteri di abilitazione per l'estensione di un'azione sono inizialmente definiti da enablesFor e da uno tra selection e enablement. Tuttavia, dopo aver creato l'istanza di gestione dell'azione, è possibile controllare lo stato di abilitazione dell'azione utilizzando direttamente il relativo metodo selectionChanged.

Si osservi che il workbench non genera menu per conto del plug-in; i percorsi di menu devo fare riferimento a menu già esistenti.

L'utente può includere nelle etichette delle azioni e dei menu caratteri speciali, che codificano tasti di scelta utilizzando le seguenti regole:

  1. I tasti di scelta vengono specificati mediante il carattere e commerciale ('&') davanti al carattere selezionato nel testo. Dal momento che il carattere e commerciale non è supportato nelle stringhe XML, utilizzare il carattere &amp;.
Se due o più azioni sono fornite a un menu o una barra degli strumenti mediante una singola estensione, le azioni verranno visualizzate in ordine inverso rispetto a come sono elencate nel file plugin.xml. Questo comportamento non era intenzionale. È stato, tuttavia, scoperto dopo che le API della piattaforma Eclipse erano state completate. La modifica del comportamento adesso danneggerebbe tutti i plug-in basati sul comportamento esistente.

Gli elementi selection e enablement sono mutualmente esclusivi. L'elemento enablement può sostituire l'elemento selection se si utilizzano gli elementi secondari objectClass e objectState. Ad esempio:

 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
può essere espresso utilizzando:
 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Implementazione fornita: i plug-in possono utilizzare questo punto di estensione per aggiungere nuovi menu di livello superiore. I plug-in possono anche definire gruppi denominati mediante i quali altri plug-in possono fornire il proprio contributo.

I menu di livello superiore vengono creati utilizzando per l'attributo path i seguenti valori:

Se l'attributo path viene omesso, il nuovo menu viene aggiunto nel gruppo della barra dei menu additions.

I gruppi predefiniti di una finestra del workbench sono definiti nell'interfaccia IWorkbenchActionConstants. È possibile utilizzare queste costanti nel codice per il contributo dinamico. È anche possibile copiare i valori in un file XML per integrarli in maniera precisa con i menu e la barra degli strumenti presenti sul workbench.

Diversi elementi del menu e della barra degli strumenti presenti nella finestra del workbench sono definiti mediante algoritmi. In questi casi, è necessario utilizzare un meccanismo separato per estendere la finestra. Ad esempio, l'aggiunta di una nuova vista del workbench determina la visualizzazione di un nuovo elemento nel menu Prospettiva. Anche le estensioni relative a Importazione, Esportazione e procedure guidate Nuovo vengono aggiunte automaticamente alla finestra.

Copyright (c) 2000, 2003 IBM Corporation e altri. Tutti i diritti riservati. Questo programma e il materiale di accompagnamento sono disponibili secondo i termini della Common Public License v1.0 che sono distribuiti con il prodotto, e disponibili all'indirizzo http://www.eclipse.org/legal/cpl-v10.html