Versione 3.0
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|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> <!ATTLIST item title CDATA #REQUIRED skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
Ciascun elemento <item> descrive una fase di livello elevato di una pagina di aiuto. L'elemento <item> può essere semplice o composto. 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>.
Elementi semplici presentano una descrizione e un'azione facoltativa. 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> (o <perform-when>) è in genere associata ad un pulsante che l'utente può premere per eseguire un'azione. Se non è presente alcuna azione, ciò indica che questa fase deve essere eseguita dall'utente manualmente o che la fase è stata completata.
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|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:
Elementi secondari presentano un'azione facoltativa. La presenza di un elemento <action> (o <perform-when>) è in genere associata ad un pulsante che l'utente può premere per eseguire l'azione della fase secondaria. Se non è presente alcuna azione, ciò indica che questa fase secondaria deve essere eseguita dall'utente manualmente o che la fase è stata completata.
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 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).perform-when
<!ELEMENT perform-when (action+)> <!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" /> </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 un file del contenuto di una pagina di aiuto molto semplice:
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Example"> <intro> <description>Example cheat sheet with two steps.</description> </intro> <item title="Step 1"> <description>This is a step with an action.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Step 2"> <description>This is a fully manual step.</description> </item> </cheatsheet>
Copyright (c) 2004 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