Newsgroup: it.comp.lang.visual-basic
Titolo: crere file *.hlp

ciao a tutti, qualcuno saprebbe indicarmi un SW molto semplice per poter
creare da un file pippo.hlp da un file ad es pippo.doc da poter richiamare
attraverso il CommonDialog ??
grazie
--------------------------------
Inviato via 
http://usenet.libero.it

 attraverso il CommonDialog ??
Con l'help compiler di Microsoft (c'è una versione
gratuita all'interno del pacchetto di visual basic
e credo che si trovi facilmente anche in rete;
prova su 
volftp.mondadori.it
)
--
Er Roscio.

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

Toner,
hai fatto un ottimo lavoro :-)
ti FAQizzo :-P
-- 
ciao, un hal sempre in ritardo con le faq