TN028: supporto della guida sensibile al contesto

Questa nota descrive le regole per l'assegnazione degli ID dei contesti della Guida e altri problemi della Guida in MFC. Il supporto della Guida sensibile al contesto richiede il compilatore della Guida disponibile in Visual C++.

Tipi di guida supportati

Esistono due tipi di supporto sensibile al contesto implementati nelle applicazioni Windows. Il primo, definito "Guida F1" prevede l'avvio di WinHelp con il contesto appropriato in base all'oggetto attualmente attivo. Il secondo è la modalità "Maiusc+ F1". In questa modalità il cursore del mouse passa al cursore della Guida e l'utente continua a fare clic su un oggetto. A questo punto, WinHelp viene avviato per fornire assistenza per l'oggetto su cui l'utente ha fatto clic.

Le classi Microsoft Foundation implementano entrambe queste forme di aiuto. Inoltre, il framework supporta due semplici comandi della Guida, l'indice della Guida e l'uso della Guida.

File della Guida

Le classi Microsoft Foundation presuppongono un singolo file della Guida. Il file della Guida deve avere lo stesso nome e percorso dell'applicazione. Ad esempio, se il file eseguibile è C:\MyApplication\MyHelp.exe, il file della Guida deve essere C:\MyApplication\MyHelp.hlp. Il percorso viene impostato tramite la variabile membro m_pszHelpFilePath della classe CWinApp.

Intervalli di contesto della Guida

L'implementazione predefinita di MFC richiede che un programma segua alcune regole sull'assegnazione degli ID contesto della Guida. Queste regole sono un intervallo di ID allocati a controlli specifici. È possibile eseguire l'override di queste regole fornendo implementazioni diverse delle varie funzioni membro correlate alla Guida.

0x00000000 - 0x0000FFFF : user defined
0x00010000 - 0x0001FFFF : commands (menus/command buttons)
0x00010000 + ID_
(note: 0x18000-> 0x1FFFF is the practical range since command IDs are>=0x8000)
0x00020000 - 0x0002FFFF : windows and dialogs
0x00020000 + IDR_
(note: 0x20000-> 0x27FFF is the practical range since IDRs are <= 0x7FFF)
0x00030000 - 0x0003FFFF : error messages (based on error string ID)
0x00030000 + IDP_
0x00040000 - 0x0004FFFF : special purpose (non-client areas)
0x00040000 + HitTest area
0x00050000 - 0x0005FFFF : controls (those that are not commands)
0x00040000 + IDW_

Semplici comandi "Guida"

Esistono due semplici comandi della Guida implementati dalle classi Microsoft Foundation:

• ID_HELP_INDEX implementato da CWinApp::OnHelpIndex

• ID_HELP_USING implementato da CWinApp::OnHelpUsing

Il primo comando mostra l'indice della Guida per l'applicazione. La seconda mostra la Guida dell'utente sull'uso del programma WinHelp.

Guida sensibile al contesto (Guida sensibile al contesto)

Il tasto F1 viene in genere convertito in un comando con un ID di ID_HELP da un acceleratore posizionato nella tabella degli acceleratori della finestra principale. Il comando ID_HELP può essere generato anche da un pulsante con ID di ID_HELP nella finestra principale o nella finestra di dialogo.

Indipendentemente dalla modalità di generazione del comando ID_HELP, viene instradata come comando normale fino a raggiungere un gestore comandi. Per altre informazioni sull'architettura di routing dei comandi MFC, vedere la nota tecnica 21. Se l'applicazione ha abilitato la Guida, il comando ID_HELP verrà gestito da CWinApp::OnHelp. L'oggetto applicazione riceve il messaggio della Guida e quindi indirizza il comando in modo appropriato. Questa operazione è necessaria perché il routing dei comandi predefinito non è adeguato per determinare il contesto più specifico.

CWinApp::OnHelp tenta di avviare WinHelp nell'ordine seguente:

1. Verifica la presenza di una chiamata attiva AfxMessageBox con un ID guida. Se una finestra di messaggio è attualmente attiva, WinHelp viene avviato con il contesto appropriato per tale finestra di messaggio.

2. Invia un messaggio di WM_COMMANDHELP alla finestra attiva. Se tale finestra non risponde avviando WinHelp, lo stesso messaggio viene quindi inviato ai predecessori di tale finestra fino a quando il messaggio non viene elaborato o la finestra corrente è una finestra di primo livello.

3. Invia un comando ID_DEFAULT_HELP alla finestra principale. Viene richiamata la Guida predefinita. Questo comando viene in genere mappato a CWinApp::OnHelpIndex.

Per eseguire l'override globale dei valori di base ID predefiniti ,ad esempio 0x10000 per i comandi e 0x20000 per le risorse come le finestre di dialogo, l'applicazione deve eseguire l'override di CWinApp::WinHelp.

Per eseguire l'override di questa funzionalità e del modo in cui viene determinato un contesto della Guida, è necessario gestire il messaggio di WM_COMMANDHELP. È possibile specificare un routing della Guida più specifico rispetto al framework fornito, perché viene eseguito solo in profondità rispetto alla finestra figlio MDI corrente. È anche possibile fornire informazioni più specifiche per una finestra o un dialogo specifico, ad esempio in base allo stato interno corrente di tale oggetto o al controllo attivo all'interno della finestra di dialogo.

WM_COMMANDHELP

afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)

WM_COMMANDHELP è un messaggio MFC di Windows privato ricevuto dalla finestra attiva quando viene richiesta la Guida. Quando la finestra riceve questo messaggio, può chiamare CWinApp::WinHelp con contesto corrispondente allo stato interno della finestra.

lParam
Contiene il contesto della Guida attualmente disponibile. lParam è zero se non è stato determinato alcun contesto della Guida. Un'implementazione di OnCommandHelp può usare l'ID contesto in lParam per determinare un contesto diverso o può semplicemente passarlo a CWinApp::WinHelp.

wParam
Non viene usato e sarà zero.

Se la OnCommandHelp funzione chiama CWinApp::WinHelp, deve restituire TRUE. La restituzione di TRUE arresta il routing di questo comando ad altre classi e ad altre finestre.

Modalità Guida (Guida maiusc+F1)

Questa è la seconda forma di Guida sensibile al contesto. In genere, questa modalità viene attivata premendo MAIUSC+F1 o tramite il menu/barra degli strumenti. Viene implementato come comando (ID_CONTEXT_HELP). L'hook del filtro messaggi non viene usato per tradurre questo comando mentre è attiva una finestra di dialogo modale o un menu, pertanto questo comando è disponibile solo per l'utente quando l'applicazione esegue il pump di messaggi principale (CWinApp::Run).

Dopo aver immesso questa modalità, il cursore del mouse della Guida viene visualizzato in tutte le aree dell'applicazione, anche se l'applicazione visualizza normalmente il proprio cursore per tale area, ad esempio il bordo di ridimensionamento intorno alla finestra. L'utente può usare il mouse o la tastiera per selezionare un comando. Anziché eseguire il comando, viene visualizzata la Guida su tale comando. Inoltre, l'utente può fare clic su un oggetto visibile sullo schermo, ad esempio un pulsante sulla barra degli strumenti e la Guida verrà visualizzata per tale oggetto. Questa modalità della Guida viene fornita da CWinApp::OnContextHelp.

Durante l'esecuzione di questo ciclo, tutti gli input della tastiera sono inattivi, ad eccezione dei tasti che accedono al menu. Inoltre, la conversione dei comandi viene ancora eseguita tramite PreTranslateMessage per consentire all'utente di premere un tasto di scelta rapida e ricevere assistenza su tale comando.

Se sono presenti particolari traduzioni o azioni eseguite nella funzione che non devono essere eseguite durante la PreTranslateMessage modalità Guida MAIUSC+F1, è necessario controllare il membro m_bHelpMode di prima di CWinApp eseguire tali operazioni. L'implementazione CDialog di controlla questa operazione prima di PreTranslateMessage chiamare IsDialogMessage, ad esempio. In questo modo i tasti di spostamento della finestra di dialogo vengono disabilitati nelle finestre di dialogo senza modalità MAIUSC+F1. Inoltre, CWinApp::OnIdle viene ancora chiamato durante questo ciclo.

Se l'utente sceglie un comando dal menu, viene gestito come guida su tale comando (tramite WM_COMMANDHELP, vedere di seguito). Se l'utente fa clic su un'area visibile della finestra delle applicazioni, viene determinata se si tratta di un clic non client o di un clic client. OnContextHelp gestisce automaticamente il mapping dei clic non client ai clic del client. Se si tratta di un clic client, invia un WM_HELPHITTEST alla finestra su cui è stato fatto clic. Se tale finestra restituisce un valore diverso da zero, tale valore viene usato come contesto per la Guida. Se restituisce zero, OnContextHelp prova la finestra padre e ha esito negativo, il relativo elemento padre e così via. Se non è possibile determinare un contesto della Guida, l'impostazione predefinita consiste nell'inviare un comando ID_DEFAULT_HELP alla finestra principale, che in genere viene mappato a CWinApp::OnHelpIndex.

WM_HELPHITTEST

afx_msg LRESULT CWnd::OnHelpHitTest(
WPARAM, LPARAM lParam)

WM_HELPHITTEST è un messaggio di windows privato MFC ricevuto dalla finestra attiva selezionata durante la modalità Guida MAIUSC+F1. Quando la finestra riceve questo messaggio, restituisce un ID guida DWORD da usare da WinHelp.

LOWORD(lParam) contiene la coordinata del dispositivo dell'asse X in cui è stato fatto clic sul mouse rispetto all'area client della finestra.

HIWORD(lParam) contiene la coordinata dell'asse Y.

wParam
non viene usato e sarà zero. Se il valore restituito è diverso da zero, WinHelp viene chiamato con tale contesto. Se il valore restituito è zero, viene eseguita una query della Guida nella finestra padre.

In molti casi, è possibile sfruttare il codice di hit testing già disponibile. Vedere l'implementazione di CToolBar::OnHelpHitTest per un esempio di gestione del messaggio WM_HELPHITTEST (il codice sfrutta il codice di hit test usato nei pulsanti e nelle descrizioni comando in CControlBar).

Supporto della Creazione guidata applicazioni MFC e MAKEHM

La Creazione guidata applicazione MFC crea i file necessari per compilare un file della Guida (file con estensione cnt e hpj). Include anche una serie di file RTF predefiniti accettati dal compilatore della Guida Microsoft. Molti degli argomenti sono completi, ma alcuni potrebbero dover essere modificati per l'applicazione specifica.

La creazione automatica di un file di "mapping della Guida" è supportata da un'utilità denominata MAKEHM. L'utilità MAKEHM può convertire la risorsa di un'applicazione. File H in un file di mapping della Guida. Ad esempio:

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

verrà convertito in:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Questo formato è compatibile con la funzionalità del compilatore della Guida, che esegue il mapping degli ID contesto (i numeri a destra) con nomi di argomento (i simboli a sinistra).

Il codice sorgente per MAKEHM è disponibile nell'esempio MAKEHM dell'esempio MFC Programming Utilities.

Aggiunta del supporto della Guida dopo l'esecuzione della Creazione guidata applicazione MFC

Il modo migliore per aggiungere la Guida all'applicazione consiste nel controllare l'opzione "Guida sensibile al contesto" nella pagina Funzionalità avanzate della Creazione guidata applicazione MFC prima di creare l'applicazione. In questo modo, la Creazione guidata applicazione MFC aggiunge automaticamente le voci della mappa messaggi necessarie alla CWinAppclasse derivata da per supportare la Guida.

Guida nelle finestre di messaggio

La Guida sulle finestre di messaggio (talvolta denominate avvisi) è supportata tramite la AfxMessageBox funzione , un wrapper per l'API MessageBox Windows.

Esistono due versioni di AfxMessageBox, una per l'uso con un ID stringa e un'altra da usare con un puntatore a stringa (LPCSTR):

int AFXAPI AfxMessageBox(LPCSTR lpszText,
    UINT nType,
    UINT nIDHelp);

int AFXAPI AfxMessageBox(UINT nIDPrompt,
    UINT nType,
    UINT nIDHelp);

In entrambi i casi è presente un ID guida facoltativo.

Nel primo caso, il valore predefinito per nIDHelp è 0, che indica che non è presente alcuna Guida per questa finestra di messaggio. Se l'utente preme F1 mentre la finestra di messaggio è attiva, l'utente non riceverà la Guida (anche se l'applicazione supporta la Guida). Se non è consigliabile, per nIDHelp deve essere fornito un ID guida.

Nel secondo caso, il valore predefinito per nIDHelp è -1, che indica che l'ID guida è uguale a nIDPrompt. La Guida funzionerà solo se l'applicazione è abilitata per la Guida, naturalmente. È consigliabile specificare 0 per nIDHelp se si desidera che la finestra di messaggio non disponga di supporto della Guida. Se si vuole che il messaggio sia abilitato per la Guida, ma si desidera un ID guida diverso da nIDPrompt, è sufficiente fornire un valore positivo per nIDHelp diverso da quello di nIDPrompt.

Vedi anche

Note tecniche per numero
Note tecniche per categoria