Implementare un sistema di Help

A cura di Daniele Simone

Basi per la pianificazione e la creazione di un Help e la sua integrazione con il programma Visual Basic.

Un file HLP e' costituito da una serie di pagine, ossia di Topics. Ognuna di esse e' identificata in modo univoco all'interno del file da un nome, inoltre presenta un titolo visibile all'utente (qualcosa di analogo alle proprieta' Name e Caption). Opzionalmente una pagina puo' avere una serie di parole chiave associate; implementando questa caratteristica, ricercando nell'help una parola verra' mostrata la pagina relativa.

Un file di help generalmente si compone di un solo documento RTF, anche se teoricamente se ne potrebbero usare di piu' per dividere una grande quantita' di dati. Le istruzioni seguenti ammettono che si utilizzi un solo documento RTF (che sarebbe la traccia da cui viene compilato l'HLP) e che lo si scriva con Microsoft Word, ma con poche modifiche esse possono essere applicate a qualunque editor RTF.

Il compilatore che trasforma il documento RTF in HLP accetta certe convenzioni da parte del documento Rich Text Format. Ogni Topic e' separata dalle altre mediante un Page Break, ma vengono considerati solo i break inseriti manualmente: quelli automatici (in chiaro) vengono ignorati.

Per assegnare nome, titolo e keywords ad una pagina bisogna inserire prima del primo carattere della pagina tre Footnotes, ma invece dei numeri bisogna impostare tre codici convenzionati: # per il nome della pagina, $ per il titolo e K per le parole chiave. Se ad esempio, si vuole chiamare una pagina SOMMARIO, bisogna inserire la nota con il carattere #, quindi digitare la parola SOMMARIO come corpo della Footnote. Per indicare piu' parole chiave occorre separarle mediante un punto e virgola

Questa operazione, indispensabile per tutte le pagine dell'Help, puo' essere automatizzata con una macro simile alla seguente (potete copiarla e incollarla in Word come macro, poi magari assegnarla ad un pulsante custom delle toolbar):

Sub MAIN
Begin Dialog UserDialog 190, 190, "Parametri"
TextBox 14, 29, 160, 18, .tname
TextBox 13, 67, 160, 18, .cname
Text 14, 52, 79, 13, "Page Title", .Text2
TextBox 14, 105, 160, 18, .kname
Text 14, 91, 73, 13, "Keywords", .Text3
Text 16, 14, 92, 13, "Topic Name", .Text1
OKButton 52, 148, 88, 21
End Dialog
Dim dlg As UserDialog
Dialog(dlg)
StartOfLine
InsertFootnote .Reference = "#", .NoteType = 0
Insert UCase$(dlg.tname)
OtherPane
CharLeft 1
InsertFootnote .Reference = "$", .NoteType = 0
Insert dlg.cname
OtherPane
CharLeft 1
InsertFootnote .Reference = "K", .NoteType = 0
Insert dlg.kname
OtherPane
End Sub

Una convenzione molto utile e' di mantenere semre i nomi delle Topic in maiuscolo.

Una volta definite le proprieta' di ogni pagina, come impostare i collegamenti?
I "salti" tra le pagine sono di due tipi: popup e links. Quando si fa click su di una parola sottolineata a puntini compare una finestra di popup con un'altra pagina, ma dopo si ritorna subito alla precedente. Quando la sottolineatura e' piena, il link porta direttamente alla nuova pagina. I codici per queste due operazioni sono la sottolineatura semplice (per i popup links) e quella doppia (per i links "veri"). Siccome questa ultima formattazione e' la piu' usata ma non compare in Word, e' consigliabile di creare un apposito pulsante associato a questo comando. Per indicare la pagina di destinazione del link, comunque esso sia, occorre far seguire alla parola sottolineata il nome della Topic, IN CARATTERI NASCOSTI. Sono quei caratteri che Word non vi fa vedere a meno che non attiviate quel pulsante con la P rovesciata. Esso mostra i caratteri di ritorno a capo, i Tab, gli spazi, e tutto il testo NASCOSTO del documento. Per creare gli Help si lavora quasi sempre con i caratteri nascosti attivi.

Ad esempio, per creare un link "vero" ad una pagina chiamata SOMMARIO (quindi con una Footnote # con scritto SOMMARIO) contrassegnato dalla frase Vai al Sommario, occorre formattare questa frase con doppia sottolineatura, e SUBITO DOPO scrivere SOMMARIO, quindi impostare questa parola in Hidden (nascosto).
Siccome il pulsante di formattazione Nascosto non e' disponibile in Word, e' utile aggiungerlo alla Toolbar perche' creando gli Help se ne fa largo uso.
Un'altra macro molto utile e' lo SmartLink: selezionando una parola e premendo il pulsante associato viene richiesto il nome della pagina destinazione: il resto e' automatico. In questo modo non c'e' neanche bisogno di vedere i fastidiosi caratteri nascosti. Ecco il codice della macro:

Sub MAIN
Begin Dialog UserDialog 330, 76, "Microsoft Word"
TextBox 13, 25, 300, 18, .tname
Text 102, 6, 111, 13, "Target del link", .Text1
OKButton 112, 46, 88, 21
End Dialog
Dim dlg As UserDialog
Dialog dlg
DoubleUnderline
CharRight 1
Hidden
Insert UCase$(dlg.tname)
Hidden
DoubleUnderline
End Sub

A questo punto, la struttura dell'Help e' completa: un documento RTF (a proposito, bisogna salvare in questo formato e non come DOC !) con tante Topic, una per pagina, ognuna identificata da Nome, Titolo e Keywords, e con numerosi link, popup e non. I link sono seguiti dal nome della destinazione in caratteri nascosti.

Per includere bitmaps nell'help, si puo' procedere per riferimento o per incorporamento. Il secondo metodo, seppure occupi un po' piu' spazio, e' il piu' semplice e veloce. Si inserisce l'immagine come si farebbe per un documento normale ed essa viene inclusa nel file Help.

Nota importante: gli apici e i doppi apici vengono automaticamente sostituiti da Word con quelli speciali, di apertura e chiusura. Questi ultimi non fanno parte del set di caratteri riconosciuti da HC, quindi vengono ignorati nella creazione dell'HLP. E' necessario disattivare la sostituzione automatica degli apici e delle virgolette durante la creazione del file RTF.

Una volta stilato il documento RTF, occorre includerlo in un file HPJ - che sarebbe un file Ascii che definisce le caratteristiche dell'Help e contiene riefrimenti ai files RTF inclusi in esso - di norma uno solo.
Per creare un file HPJ si puo' usare un qualunque editor di testo, come Notepad.

Il file HPJ e' diviso in sezioni, cho come per i files INI sono indicate tra parentesi quadre. Ogni sezione contiene le informazioni da passare al compilatore di Help, /hc/hc.exe. Alcune di queste sezioni sono secondarie; qui vengono descritte le piu' importanti e quelle obbligatorie.

[OPTIONS]: contiene le voci ROOT, CONTENTS, TITLE e WARNING. Root indica la directory in cui si trovano i files RTF contenenti le pagine, e gli eventuali files aggiuntivi (bitmaps inseriti per riferimento, ...). Contents specifica il Topic Name (quello che aveva la Footnote segnata con #) della pagina introduttiva, quella che viene visualizzata all'apertura dell'help. Title indica il titolo della finestra di Help, mentre Warning specifica la gravita' di errori da segnalare durante la compilazione. E' sempre bene impostarlo a 3, il valore massimo.

[FILES]: indica i files RTF da compilare nel file HLP risultante. In questa sezione occorre scrivere i nomi (senza percorso) di tutti i files RTF che si vuole includere. Essi devono trvarsi nella directory specificata in ROOT.

[MAP]: e' una sezione molto importante in quanto permette di indicare un ContextID per ogni pagina, in modo da richiamare dalla propria applicazione VB una specifica pagina dell'help conoscendone tale ID. In questa sezione ogni riga e' costituita da un nome di Topic - come indicato con la Footnote #, seguita da un numero univoco. E' consigliato posizionare tutti i numeri alla stessa colonna e scriverli tutti con lo stesso cumero di cifre, se necessario facendoli precedere da zeri.

[WINDOWS]: servirebbe a definire finestre secondarie dell'Help, ma questa e' una opzione avanzata. Puo' essere invece utile per configurare la finestra principale dell'Help, cioe' Main. Inserire una riga come la seguente:
main = "Guida di XXXX", (300,200,600,500)
serve ad impostare titolo, posizione e dimensioni della finestra nello schermo.

Ecco un esempio completo di file HPJ:
[OPTIONS]
ROOT = c:\helpfiles\
CONTENTS = SOMMARIO
TITLE = Guida di XXXX
WARNING = 3
[FILES]
file_hlp.rtf
[MAP]
SOMMARIO 001
ABOUT 111
MENUS 112
COMANDI 113
INSTALLAZIONE 201
DISINSTALLAZIONE 202
[WINDOWS]
main = "Guida di XXXX", (300,200,600,500)

Compilazione: per creare il file HLP occorre apirire una finestra DOS, andare nella sottodirectory /Hc di vb e digitare:
HC c:\esempio\miohelp.hpj
dove ovviamente la directory e il nome del file hpj sono variabili. Se tutto va bene dopo un po' di puntini il file HLP verra' creato nella directory di HC. Di qui bisogna spostare il file nella directory del programma.

NOTA IMPORTANTE per Windows NT: Se il lavoro di compilazione viene effettuato sotto Windows NT (quindi su un NTFS), occorre andare nella directory di HC usando i filenames corti, ad esempio invece di cd "visual basic" digitare cd visual~1.
In caso contrario potrebbe verificarsi un malinteso con NT, che scambia HC.exe con un suo comando OS2 e ne mostra la schermata di help.

Ora bisogna collegare l'Help alla propria applicazione VB. Un modo consiste nello specificare a VB un ContextID per ogni elemento, indicare un file HLP per l'intero progetto e automaticamente la pressione di F1 aprira' l'help. Per avere un controllo maggiore su di esso pero' e' conveniente usare le API.

L'handle  (proprieta' hWnd) serve a stabilire un collegamento tra l'Help e la finestra chiamante, in modo da poterlo facilmente chiudere quando non serve piu' o quando l'applicazione finisce, anche dal codice. Questa chiusura viene effettuata mediante la funzione HelpQuit, che accetta un handle di finestra come parametro e chiude tutti gli help chiamati da essa.

Una tecnica vantaggiosa e' quella di: impostare per tutti i form la proprieta' KeyPreview su True, quindi scrivere:
Sub Form1_KeyUp(KeyCode As Integer, Shift As Integer)
If KeyCode = vbKeyF1 Then
HelpMe 18, Me.hWnd, "c:\helps\miohelp.hlp"
End If
End Sub
In questo modo ad un form e' associata una pagina. Per integrare ancora di piu' l'help nell'applicazione si potrebbe concatenare una serie di If ActiveControl Is nomecontrollo Then ... ElseIf ..., per differenziare la pagina richiamata in risposta al controllo attivo nel form.

Ovviamente rimarra' anche una voce di Help che mostrara' il sommario. Basta chiamare HelpMe con il context ID della pagina di sommario per ottenere questo risultato.

Informazioni prelevate dalla rete