Versione 3.2
Questo documento descrive la struttura del file del contenuto della pagina di aiuto come una serie di frammenti DTD (Schema XML leggibile dalla macchina).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
L'elemento <cheatsheet> definisce il corpo del file del contenuto della pagina di aiuto. Gli attributi <cheatsheet> sono:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
L'elemento <intro> viene utilizzato per descrivere l'introduzione della pagina di aiuto da visualizzare. L'elemento secondario <description> contiene il corpo dell'introduzione. Gli attributi <intro> sono:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
L'elemento <description> contiene la descrizione di una pagina di aiuto o di un elemento di una pagina di aiuto. La descrizione è composta dal testo intervallato da tag di formattazione semplici. La pagina di aiuto formatta automaticamente e dispone il testo in modo che venga visualizzato in modo chiaro nell'UI. All'interno del testo, i tag bilanciati <b>...</b> fanno in modo che il testo racchiuso vengono visualizzato in neretto e l'elemento <br/> può essere utilizzato per forzare un'interruzione di riga. Si tratta degli unici tag di formattazione supportati (altri tag possono essere aggiunti in futuro). Alcuni caratteri del testo hanno un significato speciale per i parser XML; in particolare, per scrivere "<", ">", "&", "'" e """ (punto interrogativo) anziché scrivere rispettivamente "<", ">", "&", "'" e """. Spazi e interruzioni di riga vengono considerati come separatori di parole, spazi adiacenti e interruzioni di riga vengono considerati come una singola unità e visualizzati come un unico spazio o un'interruzione di riga. Gli spazi subito dopo i tag <description> e <br/> vengono ignorati, come lo spazio subito prima del tag </description>.
item
<!ELEMENT item (description ([action|command|perform-when] | (subitem|repeated-subitem|conditional-subitem)*) [onCompletion])> <!ATTLIST item title CDATA #REQUIRED dialog ("true" | "false") "false" skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
Ciascun elemento <item> descrive una fase di livello elevato di una pagina di aiuto. Un elemento <item> può contenere elementi <subitem>. Gli attributi <item> sono:
L'attributo org.eclipse.ui.cheatsheets.cheatSheetItemExtension consente altri controlli personalizzati per l'elemento da visualizzare nell'UI. I contributi a questo punto di estensione indicano i nomi di altri attributi della stringa che possono essere visualizzati negli elementi <item>.
Gli elementi semplici presentano una descrizione e un'azione o un comando facoltativo. In una presentazione tipica, i titoli degli elementi delle pagine di aiuto vengono visualizzati all'utente la maggior parte delle volte. La descrizione di un elemento viene visualizzata solo quando la fase è in corso di esecuzione. La presenza di un elemento <action>, <command> o <perform-when>) è associata a un pulsante che può essere selezionato dall'utente per eseguire l'azione o il comando dell'operazione. Se non è presente alcuna azione o comando, l'operazione deve essere eseguita manualmente dall'utente che deve quindi chiaramente indicare che l'operazione è stata completata correttamente.
Le fasi composite sono divise in fasi secondarie, come specificato dagli elementi secondari <subitem>. A differenza degli elementi, che un utente deve seguire in una determinata sequenza, gli elementi secondari di un determinato elemento possono essere eseguiti in qualsiasi ordine. Tutti gli elementi secondari all'interno di un elemento devono essere tentati (o ignorati) prima di procedere con l'elemento successivo. Ciò significa che le azioni che devono essere eseguite in una determinata sequenza non possono essere rappresentate come elementi secondari.
Un elemento secondario <conditional-subitem> consente di adattare la presentazione di una fase secondaria in base alle variabili di una pagina di aiuto, i cui valori sono stati acquisiti nelle fasi precedenti. Un elemento secondario <repeated-subitem> consente di includere in una fase un insieme di fasi secondarie simili. L'insieme di fasi secondarie può essere basato sulle variabili delle pagine di aiuto i cui valori sono stati acquisiti nei passi precedenti.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Ciascun elemento <subitem> descrive una fase secondaria di una pagina di aiuto. Un elemento <subitem> presenta una semplice etichetta di testo, ma non presenta alcuna descrizione o altri elementi secondari. Gli attributi <subitem> sono:
Gli elementi secondari presentano un'azione o un comando facoltativo. La presenza di un elemento <action>, <command> o <perform-when> è di solito associata a un pulsante che può essere selezionato dall'utente per eseguire l'azione o il comando dell'operazione secondaria. Se non è presente alcuna azione o comando, l'operazione secondaria deve essere eseguita manualmente dall'utente che deve quindi chiaramente indicare che l'operazione è stata completata correttamente.
A differenza degli elementi, che un utente deve seguire in una determinata sequenza, gli elementi secondari di un determinato elemento possono essere eseguiti in qualsiasi ordine. Tutti gli elementi secondari all'interno di un elemento devono essere completati (o ignorati) prima di procedere con l'elemento successivo. Ciò significa che le azioni che devono essere eseguite in una determinata sequenza non devono essere rappresentate come elementi secondari.
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Ciascun elemento <conditional-subitem> descrive una singola fase secondaria il cui formato può essere diverso in base a una condizione conosciuta al momento dell'espansione dell'elemento. Gli attributi <conditional-subitem> sono:
L'attributo condition dell'elemento <conditional-subitem> fornisce il valore di una stringa (questo valore deriva da una variabile della pagina di aiuto). Ciascun elemento secondario <subitem> deve presentare un attributo when con un valore di stringa diverso. Quando l'elemento viene esteso, l'elemento <conditional-subitem> viene sostituito dall'elemento <subitem> con il valore corrispondente. Se non esiste alcun elemento <subitem> con un valore corrispondente, ciò viene considerato un errore.
Ad esempio, se la variabile della pagina di aiuto denominata "v1" presenta il valore "b" quando viene esteso l'elemento
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>viene selezionato il secondo elemento secondario e l'elemento viene esteso a qualcosa di equivalente a
<item ...> <subitem label="Step for B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Ciascun elemento <repeated-subitem> descrive un elemento secondario che si estende in 0, 1 o più fasi secondarie. Gli attributi <repeated-subitem> sono:
L'attributo values fornisce un elenco di stringhe separate da virgole, l'elemento secondario <subitem> fornisce il modello. Quando l'elemento viene esteso, l'elemento <repeated-subitem> viene sostituito dalle copie dall'elemento <subitem> con ricorrenze della variabile "this" sostituite dal valore della stringa corrispondente.
Ad esempio, se la variabile della pagina di aiuto denominata "v1" presenta il valore "1,b,three" quando viene esteso l'elemento
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>l'elemento si estende in qualcosa di simile a:
<item ...> <subitem label="Step 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Step b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Step three."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/> </subitem> </item>
action
<!ELEMENT action EMPTY> <!ATTLIST action class CDATA #REQUIRED pluginId CDATA #REQUIRED param1 CDATA #IMPLIED ... param9 CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Ciascun elemento <action> descrive un'azione di una pagina di aiuto. Gli attributi <action> sono:
org.eclipse.jface.action.IAction
.
Se questa azione implementa anche org.eclipse.ui.cheatsheets.ICheatSheetAction
, viene richiamata mediante il metodo run(String[],ICheatSheetManager) e trasferita al gestore delle pagine di aiuto e ai parametri delle azioni. L'attributo pluginId deve essere presente ogni volta che è presente questo attributo. Le azioni richiamate dalle pagine di aiuto devono riportare un risultato di successo/fallimento, se l'esecuzione dell'azione non dovesse riuscire (perché l'utente annulla l'azione dalla finestra di dialogo). Per i dettagli, fare riferimento a
org.eclipse.jface.action.Action.notifyResult(boolean).org.eclipse.ui.cheatsheets.ICheatSheetAction
,
i valori di stringa di questi attributi vengono trasferiti all'azione quando richiamati. È possibile trasferire 9 parametri in un'azione di una pagina di aiuto (param1,
param2, ecc.). I parametri forniti devono iniziare con il parametri 1 ed essere contigui, ciò significa che non è possibile specificare param2 senza param1. Se la stringa dell'attributo presenta il formato "${var}",
viene considerato un riferimento a una variabile della pagina di aiuto var ed il valore della condizione sarà il valore della variabile relativo alla pagina di aiuto all'inizio dell'esecuzione dell'elemento <item> (o la stringa vuota, se la variabile non è collegata).command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Ogni elemento <command> descrive un comando in una pagina di aiuto. Gli attributi dell'elemento <command> sono:
Di seguito è riportato un esempio di elemento con un comando che apre una finestra di dialogo e che memorizza il risultato nella variabile della pagina di aiuto "result".
<item title="View Selection"> <description>Select a view which will be opened in the next step.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
L'elemento <onCompletion> contiene il testo che verrà visualizzato una volta completato un elemento. Ciò è particolarmente utile nell'operazione finale della pagina di aiuto per sapere che l'intera attività è stata completata. La descrizione è composta dal testo intervallato da tag di formattazione semplici che seguono le stesse regole valide per l'elemento <description>. Gli elementi <onCompletion> possono contenere riferimenti a variabili di pagine di aiuto con formato "${var}", che verranno espansi utilizzando il valore corrente della variabile var nel momento in cui è stata completata l'operazione.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Ciascun elemento <perform-when> descrive un'azione di una pagina di aiuto. Gli attributi <perform-when> sono:
L'attributo condition dell'elemento <conditional-subitem> fornisce il valore di una stringa (questo valore deriva da una variabile della pagina di aiuto). Ciascun elemento secondario <subitem> deve presentare un attributo when con un valore di stringa diverso. Quando l'elemento viene esteso, l'elemento <conditional-subitem> viene sostituito dall'elemento <subitem> con il valore corrispondente. Se non esiste alcun elemento <subitem> con un valore corrispondente, ciò viene considerato un errore.
Ad esempio, se la variabile della pagina di aiuto denominata "v1" presenta il valore "b" quando viene esteso l'elemento
<item ...> <subitem label="Main step"> <perform-when condition="${v1}"> <action when="a" class="com.xyz.action1" pluginId="com.xyz" /> <action when="b" class="com.xyz.action2" pluginId="com.xyz" /> <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/> </conditional-subitem> </subitem> </item>viene selezionata la seconda azione e l'elemento viene esteso a qualcosa di equivalente a
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Di seguito è riportato un esempio di file di contenuto di una pagina di aiuto semplice che dimostra l'uso degli elementi commands, perform-when e conditional.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Sample Cheat Sheet"> <intro> <description>A cheat sheet which demonstrates the use of perform-when and conditional subitems</description> </intro> <item title="View Selection"> <description>Select a view which will be opened in the following steps.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when item" skip = "true"> <description>Uses perform when to open the view seleted previously.</description> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "Search View" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when subitem"> <description>Uses perform when to open the view seleted previously.</description> <subitem label="Perform when subitem" skip = "true"> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Search View" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a conditional subitem"> <description>Uses perform when to open the view seleted previously.</description> <conditional-subitem condition="${result}"> <subitem when="Package Explorer" label="Open package explorer."> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Search View" label="Open Search View"> <command serialization = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Copyright (c) 2004, 2006 IBM Corporation e altri.
Tutti i diritti riservati. Questo programma e il materiale di accompagnamento sono disponibili secondo i termini della Eclipse Public
License v1.0 che sono distribuiti con il prodotto, e disponibili all'indirizzo
http://www.eclipse.org/legal/epl-v10.html