TN028: Suporte de ajuda Context-Sensitive

Esta nota descreve as regras para atribuir IDs de contextos de Ajuda e outras questões de ajuda no MFC. O suporte de ajuda sensível ao contexto requer o compilador de ajuda que está disponível no Visual C++.

Tipos de Ajuda Suportados

Há dois tipos de ajuda contextual implementada em aplicativos do Windows. A primeira, referida como "Ajuda F1", envolve iniciar o WinHelp com o contexto apropriado com base no objeto ativo no momento. O segundo é o modo "Shift + F1". Nesse modo, o cursor do mouse muda para o cursor de ajuda e o usuário continua a clicar em um objeto. Nesse ponto, WinHelp é iniciado para dar ajuda para o objeto que o usuário clicou.

As Microsoft Foundation Classes implementam ambas as formas de ajuda. Além disso, a estrutura suporta dois comandos de ajuda simples, Índice de Ajuda e Usando a Ajuda.

Ficheiros de Ajuda

As classes do Microsoft Foundation assumem um único arquivo de Ajuda. Esse arquivo de Ajuda deve ter o mesmo nome e caminho que o aplicativo. Por exemplo, se o executável estiver C:\MyApplication\MyHelp.exe o arquivo de ajuda deverá ser C:\MyApplication\MyHelp.hlp. Você define o caminho através da variável membro m_pszHelpFilePath da classe CWinApp.

Intervalos de Contexto de Ajuda

A implementação padrão do MFC requer que um programa siga algumas regras sobre a atribuição de IDs de contexto da Ajuda. Estas regras constituem um conjunto de IDs atribuídos a controlos específicos. Você pode substituir essas regras fornecendo diferentes implementações das várias funções de membro relacionadas à Ajuda.

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_

Comandos simples de "Ajuda"

Há dois comandos de Ajuda simples que são implementados pelo Microsoft Foundation Classes:

• ID_HELP_INDEX que é implementado por CWinApp::OnHelpIndex

• ID_HELP_USING que é implementado por CWinApp::OnHelpUsing

O primeiro comando mostra o índice da Ajuda para o aplicativo. O segundo mostra a ajuda do usuário sobre como usar o programa WinHelp.

Ajuda do Context-Sensitive (Ajuda F1)

A tecla F1 é geralmente traduzida para um comando com um ID de ID_HELP por um acelerador colocado na tabela de aceleração da janela principal. O comando ID_HELP também pode ser gerado por um botão com um ID de ID_HELP na janela principal ou caixa de diálogo.

Independentemente de como o comando ID_HELP é gerado, ele é roteado como um comando normal até chegar a um manipulador de comandos. Para obter mais informações sobre a arquitetura de roteamento de comandos MFC, consulte a Nota Técnica 21. Se o aplicativo tiver a Ajuda habilitada, o comando ID_HELP será manipulado por CWinApp::OnHelp. O objeto de aplicativo recebe a mensagem de ajuda e, em seguida, roteia o comando apropriadamente. Isso é necessário, pois o roteamento de comando padrão não é adequado para determinar o contexto mais específico.

CWinApp::OnHelp tenta iniciar o WinHelp na seguinte ordem:

1. Verifica a existência de uma chamada ativa AfxMessageBox associada a um ID de Ajuda. Se uma caixa de mensagem estiver ativa no momento, o WinHelp será iniciado com o contexto apropriado para essa caixa de mensagem.

2. Envia uma mensagem WM_COMMANDHELP para a janela ativa. Se essa janela não responder iniciando o WinHelp, a mesma mensagem será enviada para os ancestrais dessa janela até que a mensagem seja processada ou a janela atual seja uma janela de nível superior.

3. Envia um comando ID_DEFAULT_HELP para a janela principal. Isso invoca a Ajuda padrão. Este comando é geralmente mapeado para CWinApp::OnHelpIndex.

Para substituir globalmente os valores básicos de ID padrão (por exemplo, 0x10000 para comandos e 0x20000 para recursos como caixas de diálogo), o aplicativo deve substituir CWinApp::WinHelp.

Para substituir essa funcionalidade e a maneira como um contexto de Ajuda é determinado, você deve manipular a mensagem WM_COMMANDHELP. Você pode querer fornecer roteamento de Ajuda mais específico do que o framework fornece, pois ele só vai tão fundo quanto a janela filho MDI atual. Você também pode fornecer ajuda mais específica para uma janela ou caixa de diálogo específica, talvez com base no estado interno atual desse objeto ou no controle ativo dentro da caixa de diálogo.

WM_COMMANDHELP

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

WM_COMMANDHELP é uma mensagem privada do Windows MFC que é recebida pela janela ativa quando a Ajuda é solicitada. Quando a janela recebe essa mensagem, ela pode chamar CWinApp::WinHelp com contexto que corresponde ao estado interno da janela.

lParam
Contém o contexto da Ajuda atualmente disponível. lParam é zero se nenhum contexto de Ajuda tiver sido determinado. A implementação de OnCommandHelp pode usar o ID de contexto em lParam para determinar um contexto diferente ou pode simplesmente passá-lo para CWinApp::WinHelp.

wParam
Não é usado e será zero.

Se a OnCommandHelp função chamar CWinApp::WinHelp, ela deve retornar TRUE. O retorno de TRUE interrompe o roteamento desse comando para outras classes e para outras janelas.

Modo de Ajuda (Shift+F1 Help)

Esta é a segunda forma de Ajuda sensível ao contexto. Geralmente, este modo é introduzido premindo SHIFT+F1 ou através do menu/barra de ferramentas. É implementado como um comando (ID_CONTEXT_HELP). O gancho do filtro de mensagens não é usado para traduzir esse comando enquanto uma caixa de diálogo modal ou menu estiver ativo, portanto, esse comando só estará disponível para o usuário quando o aplicativo estiver executando a bomba de mensagem principal (CWinApp::Run).

Depois de entrar neste modo, o cursor do rato Ajuda é exibido sobre todas as áreas da aplicação, mesmo que a aplicação normalmente exiba o seu próprio cursor para essa área (como a margem de redimensionamento à volta da janela). O usuário é capaz de usar o mouse ou teclado para selecionar um comando. Em vez de executar o comando, a Ajuda nesse comando é exibida. Além disso, o usuário pode clicar em um objeto visível na tela, como um botão na barra de ferramentas, e a Ajuda será exibida para esse objeto. Este modo de Ajuda é fornecido pela CWinApp::OnContextHelp.

Durante a execução deste loop, toda a entrada do teclado está inativa, exceto para as teclas que acessam o menu. Além disso, a tradução de comandos ainda é realizada através de PreTranslateMessage, de modo que o usuário possa pressionar uma tecla aceleradora e obtenha ajuda sobre o comando.

Se houver traduções ou ações específicas a ocorrer na PreTranslateMessage função que não devem ocorrer durante o modo de Ajuda SHIFT+F1, deve verificar o membro m_bHelpMode de CWinApp antes de realizar essas operações. A implementação de CDialog verifica isto antes de chamar PreTranslateMessage, por exemplo. Isso desativa as teclas de "navegação de diálogo" em caixas de diálogo sem modelo durante o modo SHIFT + F1. Além disso, CWinApp::OnIdle ainda é chamado durante este loop.

Se o usuário escolher um comando no menu, ele será tratado como ajuda nesse comando (através de WM_COMMANDHELP, veja abaixo). Se o usuário clicar em uma área visível da janela de aplicativos, uma determinação será feita para determinar se é um clique não cliente ou um clique cliente. OnContextHelp lida com o mapeamento de cliques que não são de clientes para cliques de clientes automaticamente. Se for um clique do cliente, ele enviará um WM_HELPHITTEST para a janela que foi clicada. Se essa janela retornar um valor diferente de zero, esse valor será usado como contexto para ajuda. Se retornar zero, OnContextHelp tentará usar a janela pai (e, se falhar, seu pai, e assim sucessivamente). Se um contexto de Ajuda não puder ser determinado, o padrão é enviar um comando ID_DEFAULT_HELP para a janela principal, que é então (geralmente) mapeada para CWinApp::OnHelpIndex.

WM_HELPHITTEST

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

WM_HELPHITTEST é uma mensagem privada do MFC do Windows que é recebida pela janela ativa clicada durante o modo de Ajuda SHIFT+F1. Quando a janela recebe essa mensagem, ela retorna uma ID de Ajuda DWORD para uso pelo WinHelp.

LOWORD(lParam) contém a coordenada do dispositivo do eixo X onde o rato foi clicado em relação à área cliente da janela.

HIWORD(lParam) contém a coordenada do eixo Y.

wParam
não é utilizado e ficará a zero. Se o valor de retorno for diferente de zero, WinHelp será chamado com esse contexto. Se o valor de retorno for zero, a janela pai será consultada para obter ajuda.

Em muitos casos, pode tirar partido do código de deteção de colisões que já possa ter. Consulte a implementação de CToolBar::OnHelpHitTest para um exemplo de manipulação da mensagem WM_HELPHITTEST (o código aproveita o teste de colisão usado em botões e dicas de ferramentas em CControlBar).

Suporte para o Assistente de Aplicação MFC e MAKEHM

O MFC Application Wizard cria os arquivos necessários para criar um arquivo de Ajuda (arquivos .cnt e .hpj). Ele também inclui vários arquivos de .rtf pré-criados que são aceitos pelo Microsoft Help Compiler. Muitos dos tópicos estão completos, mas alguns podem precisar ser modificados para sua aplicação específica.

A criação automática de um arquivo de "mapeamento de ajuda" é suportada por um utilitário chamado MAKEHM. O utilitário MAKEHM pode traduzir o ficheiro RESOURCE.H de um aplicativo para um ficheiro de mapeamento de ajuda. Por exemplo:

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

será traduzido para:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Esse formato é compatível com o recurso do compilador Help, que mapeia IDs de contexto (os números no lado direito) com nomes de tópicos (os símbolos no lado esquerdo).

O código-fonte para MAKEHM está disponível no exemplo de MFC Programming Utilities MAKEHM.

Adicionando suporte de ajuda após executar o Assistente de Aplicação MFC

A melhor maneira de adicionar Ajuda ao seu aplicativo é verificar a opção "Ajuda sensível ao contexto" na página Recursos Avançados do MFC Application Wizard antes de criar seu aplicativo. Dessa forma, o MFC Application Wizard adiciona automaticamente as entradas de mapa de mensagens necessárias à sua CWinAppclasse derivada para oferecer suporte à Ajuda.

Ajuda em caixas de mensagem

A ajuda em caixas de mensagens (às vezes chamadas de alertas) é suportada através da função AfxMessageBox, um wrapper para a API Windows MessageBox.

Há duas versões de AfxMessageBox, uma para uso com um ID de cadeia de caracteres e outra para uso com um ponteiro para cadeia de caracteres (LPCSTR).

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

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

Em ambos os casos, há um ID de Ajuda opcional.

No primeiro caso, o padrão para nIDHelp é 0, o que indica que não há Ajuda para esta caixa de mensagem. Se o usuário pressionar F1 enquanto a caixa de mensagem estiver ativa, o usuário não receberá Ajuda (mesmo que o aplicativo suporte Ajuda). Se isso não for desejável, um ID de Ajuda deve ser fornecido para nIDHelp.

No segundo caso, o valor padrão para nIDHelp é -1, o que indica que o ID da Ajuda é o mesmo que nIDPrompt. A Ajuda funcionará apenas se o aplicativo estiver habilitado para Ajuda, é claro). Você deve fornecer 0 para nIDHelp se desejar que a caixa de mensagem não tenha suporte de ajuda. Se você quiser que a mensagem seja habilitada para Ajuda, mas desejar um ID de ajuda diferente do nIDPrompt, basta fornecer um valor positivo para nIDHelp diferente do nIDPrompt.

Ver também

Notas técnicas por número
Notas técnicas por categoria