Ogni applicazione, anche la più
semplice, dispone di un file della guida di supporto, che ne documenta le funzioni
e l'utilizzo. Questi file della guida, in formato Help di Windows (.hlp), sono
veri e propri file compilati. Ogni file help è costituito da più
pagine al suo interno (denominate Topics -argomenti-). Ad ogni pagina viene
attribuito un nome univoco (paragonabile alla proprietà Name in Visual
Basic) e un titolo (paragonabile alla proprietà Caption in Visual Basic).
Addizionalmente, la pagina può contenere una serie di parole chiave (keywords,
paragonabile al meta tag in HTML) che ne descrivono il contenuto; queste parole
chiave verranno utilizzate per la funzione di 'Trova' della Guida. Il sorgente
di una guida si divide solitamente in due file: un file RTF standard (Rich Text
Format) e un file ASCII con estensione HPJ. Analizzeremo questi due file separatamente.
Il file RTF è un file Rich
Text Format normale: nel nostro caso lo stiamo realizzando con Word 97, ma qualsiasi
word processor compatibile potrà essere impiegato. Il file RTF deve rispettare
alcune convenzioni:
Ogni argomento (topic) deve essere
separato dall'altro tramite una interruzione di pagina (page break) manuale;
non sono valide le interruzioni generate automaticamente da Word;
I nomi, titoli e keywords dei vari argomenti vengono assegnati tramite commenti
a pie' di pagina (footnotes); questi vanno specificati all'inizio di ogni argomento,
prima del testo dell'argomento stesso:
Per impostare il nome della pagina inserire una footnote contentente al posto
di un numero il carattere #; come testo della footnote inserire il nome della
pagina (meglio se in maiuscolo);
Per impostare il titolo della pagina inserire una footnote contenente al posto
di un numero il carattere $; come testo della footnote inserire il titolo della
pagina;
Per impostare le keywords della pagina inserire una footnote contenente al posto
di un numero il carattere K; come testo della footnote inserire tutte le parole
chiave separate tra di loro da un punto e virgola;
I collegamenti verso altre pagine sono strutturati nel modo seguente:
Testo del linkTOPICDIDESTINAZIONE
Il TOPIC DI DESTINAZIONE deve essere scritto in caratteri nascosti e si deve
riferire al nome dell'argomento verso il quale link deve dirigersi.
Il testo del link deve essere sottolineato seguendo queste nozioni:
Per i link POPUP, la sottolineatura dev'essere 'a puntini';
Per i link normali, la sottolineatura dev'essere 'normale';
Le immagini vanno inserite normalmente
Il file HPJ, come specificato prima, è un file ASCII contenente tutte
le informazioni sul file della guida. Può essere paragonato al file .VBP
di un progetto in Visual Basic. Il file HPJ è strutturato in un modo
simile ai file INI. Si suddivide in più sezioni, racchiuse da parentesi
quadre. Ogni sezione riguarda una parte specifica dalla compilazione. Le sezioni
sono:
[OPTIONS]
ROOT=Directory contenente tutti i files della guida (.rtf, .bmp, ...)
CONTENTS=Nome (footnote #) del sommario della guida
WARNING=Il livello di visualizzazione errori durante la compilazione (max=3)
[FILES]
Elenco dei file RTF da includere nella guida; esempio:
file1.rtf
file2.rtf
[MAP]
Assegna ad ogni topic name un numero (ContextID) per poter richiamare l'argomento
da Visual Basic. Per esempio:
MIO_ARGOMENTO_UNO 001
[WINDOWS]
Funzione facoltativa avanzata: definisce la posizione della finestra dell'help,
utile per impostare la posizione iniziale della finestra (la finestra Main).
Si imposta così:
MAIN="Guida della mia applicazione",(100,100,600,300)
Per effettuare la compilazione
(il cui risultato sarà il nostro file .hlp!) è necessario aprire
una finestra MS-DOS e portarsi nella directory HC di Visual Basic. Da qui digitare:
HC c:percorsocompletofile.hpj
Se la compilazione ha esito positivo, nella directory HC verrà realizzato
il file .hlp. Per utilizzare il file .hlp appena creato con la nostra applicazione
VB, è sufficiente assegnare ad ogni componente dei nostri form un valore
ContextID (definito nella sezione MAP del file .HPJ) e assegnare il file .hlp
come help file per tutto il progetto. Così facendo ad ogni pressione
del tasto F1 verrà automaticamente aperta la guida sull'argomento specificato.
|