Capitolo 025 - AIUTO!
Questo breve capitolo dice come aggiungere Help all'applicazione.
Sorgenti: Documentazione Apple e CocoaDevCentral.
Primo inserimento: 2 settembre 2002
Aiuto
La questione è stata a lungo sofferta, finché non ho affrontato il problema di petto e mi sono messo a leggere la documentazione, dietro suggerimento di un tutorial su Cocoa Dev Central.
Come dovreste aver notato, Mac OS X ha un meccanismo di Help per le applicazioni che si basa su una normale struttura di file HTML. Attraverso la comune voce di menu Aiuto si attiva l'applicazione Help Viewer: altri non è che un comune browser HTML (semplificato, e senza troppi fronzoli su Javascript e compagnia), che legge tranquillamente file HTML conformi alla versione 3.2 del linguaggio (adeguata alla maggior parte degli scopi di Help).
Ora, l'architettura Cocoa fornisce di serie tutto l'occorrente per attivare questo Help. Bisogna solo avere un po' di accortezza nella preparazione dei file HTML e poi inserire due/tre voci nella Info.plist.
HTML
Per scrivere lo Help di una applicazione, conviene fare riferimento alla documentazione Apple, che voi troverete facilmente seguendo questo indirizzo (sulla documentazione locale): /Developer/ Documentation/ Carbon/ HumanInterfaceToolbox/ AppleHelp/ ProvidingUserAssitAppleHelp/ index.html e che invece io, trovandosi nella parte relativa a Carbon, ho inizialmente colpevolmente trascurato. Di particolare interesse la sezione Designing a Help Book, dalla quale stralcio velocemente alcuni punti.
Lo Help è tipicamente formato da una pagina di titolo e da una pagina principale, dalla quale accedere poi a tutte le altre pagine che costituiscono l'indice. Io non mi sono preoccupato troppo di fornire un Help completo, ma, bastandomi per il momento i concetti alla base, mi sono limitato a produrre una pagina di titolo.
Ed è in questa pagina di titolo che entra il primo trucco per un Help funzionante: occorre aggiungere un meta tag del tipo
<HEAD>
<META NAME="AppleTitle" CONTENT="CDCat Help">
</HEAD>
In questo modo, la voce CDCat Help sarà mostrata all'interno della lista delle applicazioni con Help presentate dalla pagina principale di Help Viewer.
Questa è in effetti l'unica cosa da tenere presente per scrivere le pagine di Help. Le altre direttive (carattere, link, eccetera) sono opzionali, mentre le raccomandazioni per la strutturazione in capitoli sono sensate e ragionevoli, e di nessuna difficoltà.
Il risultato finale della scrittura dello Help comunque sarà bene sia sempre una struttura di questo tipo: tutto lo Help si trova all'interno di una directory, opportunamente chiamata (nel mio caso, MacocoaHelp, ma il nome può essere qualunque); all'interno di questa directory, un file, comunque chiamato, che rappresenta la pagina di titolo avente il meta tag sopra indicato; la pagina principale dello Help (che potrebbe essere anche la pagina del titolo); altre sotto directory con dentro le immagini e gli altri file HTML di help.
Se proprio si vuole essere professionali, occorre indicizzare lo Help, in modo che quando l'utente dall'interno dello Help Viewer esegue delle ricerche, queste possano produrre risultati anche guardando questi nuovi file di Help. L'operazione è oltre tutto molto semplice: basta droppare l'intera cartella sull'applicazione Help Indexer che si trova in /Developer/Application/Utilities. Questa operazione produce un file (nel mio caso, MacocoaHelp.helpindex) già nel posto corretto.
Tutto ciò funzionava quando scrivevo questa pagina. Tuttavia, nel corso del tempo, le cose si sono modificate, e sembra che la ricerca all'interno del visore aiuto non produca risultati; dovrò indagare più a fondo, ovvero, dovrò leggere la documentazione aggiornata...
Registrazione dello Help
Il passo successivo è informare l'applicazione dell'esistenza di questo Help. Questo si ottiene eseguendo due operazioni: si inserisce la cartella all'interno del progetto, e si aggiungono un paio di voci all'interno della property list. Entrambe le operazioni mi hanno fatto innervosire.
La prima, innocente operazione di aggiungere la cartella dei file al progetto richiede un'avvertenza: nel dialogo che compare ad un certo punto dell'operazione, bisogna selezionare il pulsante Create Folder References...; nel mio caso, era automaticamente selezionato l'altro pulsante (che aggiunge i file al progetto,ma non nel posto giusto), cosa che proibiva il corretto funzionamento del meccanismo.
Scopo ultimo di questa operazione è di fare in modo che la cartella e l'intero suo contenuto siano copiate all'interno della cartella Resources contenuta all'interno dell'applicazione CDCat finale.
La seconda operazione consiste nell'aggiungere due voci alla property list dell'applicazione. Questa property list contiene molte altre informazioni di servizio utili alla normale vita dell'applicazione stessa; ad esempio, il nome del file dove sono contenute le icone. Per impostare valori su questa property list si usa la finestra che riporta le informazioni sul Target. Tuttavia, i campi da aggiungere qui non sono previsti: occorre passare alla modalità Expert. Ciò che compare è una tabella che ricorda molto (ma va'?) la finestra dell'applicazione Property List Editor. In questa finestra bisogna aggiungere due voci: CFBundleHelpBookFolder, con il nome della directory in cui è contenuto l'intero sistema di Help (nel mio caso MacocoaHelp), e CFBundleHelpBookName, con il content del meta tag AppleTitle della pagina di titolo (CDCat Help, va da sé). Cocoa Dev Central raccomanda di impostare anche la voce CFBundleIdentifier, ma questo era già stato fatto quando ho lavorato con le Preferenze.
Nonostante tutto, le cose non funzionavano ancora, ed un irritante messaggio sul fatto che l'applicazione non aveva un Help associato continuava a saltare fuori. Colto da disperazione, ho spento tutto. Alla riaccensione, tutto funziona. Ho il sospetto che il meccanismo abbia bisogno di pensarci su prima di funzionare (forse basta aspettare un po', senza necessariamente spegnere).
- Download del progetto completo (Archivio Zip)
