TN028: Context-Sensitive Help-ondersteuning

In deze opmerking worden de regels beschreven voor het toewijzen van Help-context-id's en andere help-problemen in MFC. Contextgevoelige Help-ondersteuning vereist de Help-compiler die beschikbaar is in Visual C++.

Ondersteunde typen van hulp

Er zijn twee typen contextgevoelige help geïmplementeerd in Windows-toepassingen. De eerste, aangeduid als 'F1 Help', omvat het starten van WinHelp met de juiste context op basis van het momenteel actieve object. De tweede is de modus Shift+ F1. In deze modus verandert de muiscursor in de Help-cursor en klikt de gebruiker op een object. Op dat moment wordt WinHelp gestart om hulp te geven voor het object waarop de gebruiker heeft geklikt.

De Microsoft Foundation-klassen implementeren beide vormen van hulp. Daarnaast ondersteunt het framework twee eenvoudige Help-opdrachten, Help Index en Help gebruiken.

Help-bestanden

Bij de Microsoft Foundation-klassen wordt uitgegaan van één Help-bestand. Dat Help-bestand moet dezelfde naam en hetzelfde pad hebben als de toepassing. Als het uitvoerbare bestand bijvoorbeeld is C:\MyApplication\MyHelp.exe moet het Help-bestand C:\MyApplication\MyHelp.hlp zijn. U stelt het pad in via de m_pszHelpFilePath lidvariabele van de CWinApp-klasse.

Help-contextbereiken

Voor de standaard implementatie van MFC is een programma vereist om enkele regels te volgen over de toewijzing van Help-context-id's. Deze regels zijn een reeks id's die zijn toegewezen aan specifieke besturingselementen. U kunt deze regels overschrijven door verschillende implementaties van de verschillende Help-gerelateerde lidfuncties op te geven.

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_

Eenvoudige Help-opdrachten

Er zijn twee eenvoudige Help-opdrachten die worden geïmplementeerd door de Microsoft Foundation-klassen:

• ID_HELP_INDEX die is geïmplementeerd door CWinApp::OnHelpIndex

• ID_HELP_USING die is geïmplementeerd door CWinApp::OnHelpUsing

De eerste opdracht toont de Help-index voor de toepassing. De tweede toont de gebruikershulp bij het gebruik van het WinHelp-programma.

Context-Sensitive Hulp (F1 Hulp)

De F1-toets wordt meestal omgezet in een opdracht met een id van ID_HELP door een accelerator die in de acceleratortabel van het hoofdvenster geplaatst is. De opdracht ID_HELP kan ook worden gegenereerd door een knop met een id van ID_HELP in het hoofdvenster of dialoogvenster.

Ongeacht hoe de ID_HELP opdracht wordt gegenereerd, wordt deze gerouteerd als een normale opdracht totdat deze een opdrachthandler bereikt. Raadpleeg Technical Note 21 voor meer informatie over de MFC-architectuur voor opdrachtroutering. Als help is ingeschakeld voor de toepassing, wordt de opdracht ID_HELP verwerkt door CWinApp::OnHelp. Het toepassingsobject ontvangt het Help-bericht en stuurt vervolgens de opdracht op de juiste manier. Dit is nodig omdat de standaardopdrachtroutering niet voldoende is om de meest specifieke context te bepalen.

CWinApp::OnHelp probeert WinHelp in de volgende volgorde te starten:

1. Hiermee wordt gecontroleerd of er een actieve AfxMessageBox oproep is met een help-ID. Als er momenteel een berichtvak actief is, wordt WinHelp gestart met de context die geschikt is voor dat berichtvak.

2. Hiermee wordt een WM_COMMANDHELP bericht naar het actieve venster verzonden. Als dat venster niet reageert door WinHelp te starten, wordt hetzelfde bericht verzonden naar de voorouders van dat venster totdat het bericht is verwerkt of het huidige venster een bovenste venster is.

3. Hiermee wordt een ID_DEFAULT_HELP opdracht naar het hoofdvenster verzonden. Hiermee wordt de standaard-Help aangeroepen. Deze opdracht is over het algemeen toegewezen aan CWinApp::OnHelpIndex.

Als u de standaard-id-basiswaarden globaal wilt overschrijven (bijvoorbeeld 0x10000 voor opdrachten en 0x20000 voor resources zoals dialoogvensters), moet de toepassing CWinApp::WinHelp overschrijven.

Als u deze functionaliteit wilt overschrijven en de manier waarop een Help-context wordt bepaald, moet u het WM_COMMANDHELP bericht afhandelen. Mogelijk wilt u meer specifieke Help-routering bieden dan het framework doet, omdat dit slechts zo diep gaat als het huidige MDI-kindvenster. U kunt ook specifiekere hulp bieden voor een bepaald venster of dialoogvenster, mogelijk op basis van de huidige interne status van dat object of het actieve besturingselement in het dialoogvenster.

WM_COMMANDHELP

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

WM_COMMANDHELP is een privé Windows MFC-bericht dat wordt ontvangen door het actieve venster wanneer Help wordt aangevraagd. Wanneer het venster dit bericht ontvangt, kan CWinApp::WinHelp worden aangeroepen met een context die overeenkomt met de interne status van het venster.

lParam-
Bevat de momenteel beschikbare Help-context. lParam is nul als er geen Help-context is vastgesteld. Een implementatie van OnCommandHelp kan de context-id in lParam gebruiken om een andere context te bepalen of deze gewoon door te geven aan CWinApp::WinHelp.

wParam-
Wordt niet gebruikt en is nul.

Als de OnCommandHelp functie CWinApp::WinHelp, moet deze TRUE retourneren. Het teruggeven van 'WAAR' stopt de routering van deze opdracht naar andere klassen en naar andere vensters.

Help-modus (Shift+F1 Help)

Dit is de tweede vorm van contextgevoelige Help. Over het algemeen wordt deze modus ingevoerd door op Shift+F1 of via het menu/de werkbalk te drukken. Het wordt geïmplementeerd als een opdracht (ID_CONTEXT_HELP). De berichtfilterhook wordt niet gebruikt om deze opdracht te vertalen terwijl een modaal dialoogvenster of menu actief is, daarom is deze opdracht alleen beschikbaar voor de gebruiker wanneer de toepassing de hoofdberichtpomp uitvoert (CWinApp::Run).

Nadat u deze modus hebt ingevoerd, wordt de Helpcursor weergegeven op alle gebieden van de toepassing, zelfs als de toepassing normaal gesproken een eigen cursor voor dat gebied zou weergeven (zoals de grootterand rondom het venster). De gebruiker kan de muis of het toetsenbord gebruiken om een opdracht te selecteren. In plaats van de opdracht uit te voeren, wordt hulpinformatie over die opdracht weergegeven. De gebruiker kan ook op een zichtbaar object op het scherm klikken, zoals een knop op de werkbalk, en Help wordt voor dat object weergegeven. Deze helpmodus wordt geleverd door CWinApp::OnContextHelp.

Tijdens de uitvoering van deze lus is alle toetsenbordinvoer inactief, met uitzondering van toetsen die toegang hebben tot het menu. Bovendien wordt opdrachtomzetting nog steeds uitgevoerd via PreTranslateMessage , zodat de gebruiker op een acceleratortoets kan drukken en hulp kan ontvangen bij die opdracht.

Als er bepaalde vertalingen of acties plaatsvinden in de PreTranslateMessage-functie die niet mogen plaatsvinden tijdens de Help-modus Shift+F1, moet u het lid m_bHelpMode controleren voordat u deze bewerkingen uitvoert. De CDialog-implementatie van PreTranslateMessage controleert dit voordat IsDialogMessage wordt aangeroepen, bijvoorbeeld. Hiermee schakelt u de "dialoogvensternavigatie"-toetsen uit voor modeless dialoogvensters tijdens de Shift+F1-modus. Daarnaast wordt CWinApp::OnIdle nog steeds aangeroepen tijdens deze lus.

Als de gebruiker een opdracht in het menu kiest, wordt deze verwerkt als help voor die opdracht (via WM_COMMANDHELP, zie hieronder). Als de gebruiker op een zichtbaar gebied van het toepassingsvenster klikt, wordt bepaald of het om een niet-clientklik of een clientklik gaat. OnContextHelp vertaalt niet-clientklikken automatisch naar clientklikken. Als het een clientklik is, wordt er een WM_HELPHITTEST verzonden naar het venster waarop is geklikt. Als dat venster een niet-nulwaarde retourneert, wordt die waarde gebruikt als context voor help. Als het nul retourneert, probeert OnContextHelp het bovenliggende venster te gebruiken (en als dat niet lukt, het venster daarboven, enzovoort). Als een Help-context niet kan worden bepaald, wordt standaard een ID_DEFAULT_HELP opdracht verzonden naar het hoofdvenster, dat vervolgens (meestal) is toegewezen aan CWinApp::OnHelpIndex.

WM_HELPHITTEST

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

WM_HELPHITTEST is een MFC-privévensterbericht dat wordt ontvangen door het actieve venster dat is geklikt tijdens de Help-modus Shift+F1. Wanneer het venster dit bericht ontvangt, wordt er een DWORD Help-id geretourneerd voor gebruik door WinHelp.

LOWORD(lParam) bevat de X-as coördinaat waar de muis is geklikt ten opzichte van het cliëntgebied van het venster.

HIWORD(lParam) bevat de coördinaat van de Y-as.

wParam-
wordt niet gebruikt en zal nul zijn. Als de retourwaarde niet-nul is, wordt WinHelp met die context aangeroepen. Als de retourwaarde nul is, wordt het oudervenster om hulp gevraagd.

In veel gevallen kunt u gebruikmaken van hit-testing-code die u mogelijk al hebt. Zie de implementatie van CToolBar::OnHelpHitTest voor een voorbeeld van het verwerken van het WM_HELPHITTEST-bericht (de code maakt gebruik van de hit-test-code die wordt gebruikt op knoppen en tooltips in CControlBar).

Ondersteuning van de MFC-toepassingswizard en MAKEHM

De MFC-toepassing Wizard maakt de benodigde bestanden om een help-bestand (.cnt- en .hpj-bestanden) te maken. Het bevat ook een aantal vooraf gedefinieerde .rtf bestanden die worden geaccepteerd door de Microsoft Help Compiler. Veel van de onderwerpen zijn voltooid, maar sommige moeten mogelijk worden gewijzigd voor uw specifieke toepassing.

Het automatisch maken van een help-toewijzingsbestand wordt ondersteund door een hulpprogramma met de naam MAKEHM. Het hulpprogramma MAKEHM kan het RESOURCE.H-bestand van een toepassing vertalen naar een Help-koppelingsbestand. Voorbeeld:

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

wordt vertaald naar:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Deze indeling is compatibel met de functie van de Help-compiler, die context-id's (de getallen aan de rechterkant) aan onderwerpnamen (de symbolen aan de linkerkant) toewijst.

De broncode voor MAKEHM is beschikbaar in het MFC Programming Utilities-voorbeeld MAKEHM.

Ondersteuning voor Help toevoegen na het uitvoeren van de MFC-toepassingswizard

De beste manier om Help aan uw toepassing toe te voegen, is door de optie Contextgevoelige Help te controleren op de pagina Geavanceerde functies van de wizard MFC-toepassing voordat u uw toepassing maakt. Op die manier voegt de MFC-toepassingswizard automatisch de benodigde berichttoewijzingen toe aan uw CWinApp-afgeleide klasse, ter ondersteuning van Help.

Help bij berichtvensters

Hulp bij berichtvakken (ook wel waarschuwingen genoemd) wordt ondersteund via de AfxMessageBox functie, een wrapper voor de MessageBox Windows-API.

Er zijn twee versies van AfxMessageBox, een voor gebruik met een tekenreeks-id en een andere voor gebruik met een aanwijzer naar tekenreeks (LPCSTR):

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

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

In beide gevallen is er een optionele Help-id.

In het eerste geval is de standaardwaarde voor nIDHelp 0, wat aangeeft dat er geen Help voor dit berichtvak is. Als de gebruiker op F1 drukt terwijl het berichtvak actief is, ontvangt de gebruiker geen Help (zelfs als de toepassing Help ondersteunt). Als dit niet wenselijk is, moet er een Help-id worden opgegeven voor nIDHelp.

In het tweede geval is de standaardwaarde voor nIDHelp -1, wat aangeeft dat de Help-id hetzelfde is als nIDPrompt. Help werkt alleen als de toepassing is ingeschakeld voor Help, natuurlijk). Geef 0 op voor nIDHelp als u wilt dat het berichtvak geen ondersteuning biedt. Als u wilt dat het bericht Help is ingeschakeld, maar een andere Help-id wenst dan nIDPrompt, geeft u gewoon een positieve waarde op voor nIDHelp anders dan die van nIDPrompt.

Zie ook

Technische notities per nummer
Technische Aantekeningen Per Categorie