TN028: Suporte de ajuda sensível ao contexto
Esta nota descreve as regras para atribuir identificações de contextos de ajuda e outras questões ajuda no MFC.contexto-suporte de ajuda sensível ao requer o compilador de ajuda está disponível no Visual C++.
.gif "Observação") Observação: |
|---|
Juntamente com a implementação contexto - ajuda relacionada ao uso WinHelp MFC também oferece suporte ao uso de Ajuda em HTML.Para obter mais informações sobre esse suporte e a programação com HTML he LP, consulte Ajuda em HTML: Ajuda sensível ao contexto para seus programas. |
Tipos de ajuda com suporte
Há dois tipos de ajuda contextual implementado em aplicativos do Windows.A primeira, conhecido sistema autônomo "Ajuda F1" envolve iniciar WinHelp com o contexto apropriado com base no objeto ativo no momento.O segundo é o modo "deslocar + F1".Nesse modo, o cursor do mouse muda para o cursor de ajuda e o usuário continua a clicar um objeto.Neste ponto, WinHelp é iniciado para fornecer ajuda para o objeto que o usuário clicou em.
O Microsoft Foundation Classes implementar ambas essas formas de Ajuda.Além disso, a estrutura oferece suporte a dois comandos simples ajuda, usando Ajuda e o índice da Ajuda.
Arquivos de ajuda
As Microsoft Foundation classes assumem um único arquivo de Ajuda.Esse arquivo de ajuda deve ter o mesmo nome e caminho sistema autônomo o aplicativo.Por exemplo, se o executável é C:\MyApplication\MyHelp.exe o arquivo de ajuda deve ser C:\MyApplication\MyHelp.hlp.conjunto o caminho por meio de m_pszHelpFilePath variável de membro da Classes CWinApp.
Intervalos de contexto da Ajuda
A implementação padrão da MFC requer um programa a seguir algumas regras sobre a atribuição de identificações de contexto de Ajuda.Essas regras são um intervalo de identificações alocadas para controles específicos.Você pode substituir essas regras, fornecendo implementações diferentes de várias funções de membros relacionados ao Help.
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_
Simples de comandos "Ajuda"
Há dois comandos simples de ajuda que são implementados pela Microsoft Foundation Classes:
ID_HELP_INDEX que é implementada por CWinApp::OnHelpIndex
ID_HELP_USING que é implementada por CWinApp::OnHelpUsing
O primeiro comando mostra o índice do aplicativo.O segundo mostra a Ajuda do usuário usando o programa do WinHelp.
Ajuda sensível ao contexto (Ajuda F1)
O F1 chave geralmente é traduzido como um comando com uma ID de ID_HELP por um acelerador colocados na tabela de aceleração da janela principal. The ID_HELP comando também pode ser gerado por um botão com uma ID de ID_HELP Na caixa diálogo ou janela principal.
Independentemente de sistema autônomo a ID_HELP comando é gerado, ele será encaminhado sistema autônomo um comando normal até alcançar um manipulador de comandos. Para obter mais informações sobre a arquitetura de roteamento de comando do MFC, consulte Observação técnica 21.Se o aplicativo tem ajuda ativada, a ID_HELP comando será manipulado por CWinApp::OnHelp. O objeto do aplicativo recebe a mensagem de ajuda e encaminha 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 inicialização o WinHelp na seguinte ordem:
Verifica se há um ativo AfxMessageBox telefonar com um ID de Ajuda. Se uma caixa de mensagem estiver ativo no momento, WinHelp é aberto com o contexto apropriado para essa caixa de mensagem.
Envia uma mensagem WM_COMMANDHELP à janela ativo.Se essa janela não responder iniciando WinHelp, a mesma mensagem é, em seguida, enviada para os predecessores do que a janela até que a mensagem é processada ou janela corrente é uma janela de nível superior.
Envia um comando ID_DEFAULT_HELP à janela principal.Isso invoca a Ajuda padrão.Este comando geralmente é mapeado para CWinApp::OnHelpIndex.
Para substituir globalmente os valores de base ID padrão (por exemplo0x10000 para comandos e 0 x 20000 para recursos sistema autônomo caixas de diálogo), o aplicativo deve substituir CWinApp::WinHelp.
Para substituir essa funcionalidade e a maneira que um contexto de ajuda é determinado, você deve tratar a mensagem WM_COMMANDHELP.Você poderá fornecer mais específicas ajuda roteamento que fornece a estrutura, sistema autônomo ele só vai profundidade da janela filho MDI corrente.Você também poderá fornecer ajuda mais específica para uma determinada janela ou caixa de diálogo, talvez com base no estado interno corrente do objeto ou do controle ativo dentro da caixa de diálogo.
WM_COMMANDHELP
afx_msgLRESULTCWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)
WM_COMMANDHELP é uma mensagem de MFC do Windows particular recebida da janela ativo quando é solicitada ajuda.Quando a janela recebe essa mensagem, ele pode chamar CWinApp::WinHelp com o contexto que corresponde ao estado interno da janela.
lParam
Contém o contexto de ajuda disponível no momento.lParam será zero se não há contexto de Ajuda foi determinado. Uma implementação de OnCommandHelp pode usar a 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 o OnCommandHelp chamadas de função CWinApp::WinHelp, ele deverá retornar TRUE. Retornando TRUE pára o roteamento deste comando para outras classes e outras janelas.
Ajuda (deslocar+F1 Ajuda) do modo
Isso é o segundo de ajuda contextual.Em geral, esse modo é inserido, pressione deslocar+F1 ou por meio do menu/barra de ferramentas.Ele é implementado sistema autônomo um comando (ID_CONTEXT_HELP).O gancho do filtro de mensagem não é usado para traduzir esse comando ao mesmo tempo em uma caixa de diálogo modal ou menu estiver ativo, portanto este comando só está disponível para o usuário quando o aplicativo está em execução a bomba de mensagem principal (CWinApp::Run).
Depois de inserir nesse modo, o cursor do mouse de ajuda será exibido em todas sistema autônomo áreas do aplicativo, mesmo se o aplicativo exibirá normalmente seu próprio cursor para a área (por exemplo, a borda de dimensionamento ao redor da janela).O usuário é capaz de usar o mouse ou teclado para selecionar um comando.Em vez de executar o comando, ajuda sobre esse comando é exibida.Além disso, o usuário pode clicar em um objeto visível na tela, sistema autônomo um botão na barra de ferramentas, e ajuda será exibida para esse objeto.Esse modo de ajuda é fornecido por CWinApp::OnContextHelp.
Durante a execução desse loop, todos os entrada de teclado está inativo, exceto para as chaves que acessar o menu.Além disso, conversão de comando ainda é executada por meio de PreTranslateMessage para permitir que o usuário pressionar uma tecla de aceleração e obter ajuda sobre esse comando.
Se existem em determinado traduções ou tomar ações coloque no PreTranslateMessage função que não deveria ocorrer durante o modo de ajuda deslocar+F1, você deve verificar o m_bHelpMode membro de CWinApp antes de executar essas operações. The CDialog implementação do PreTranslateMessage verifica isso antes de ligar IsDialogMessage, por exemplo. Isso desativa as teclas de "caixa de diálogo navegação" em caixas de diálogo sem janela restrita durante o modo deslocar+F1.Além disso, CWinApp::OnIdle ainda é chamado durante este loop.
Se o usuário escolhe um comando no menu, ela é tratada sistema autônomo obter ajuda sobre esse comando (por meio de WM_COMMANDHELP, veja abaixo).Se o usuário clica em uma área visível da janela de aplicativos, uma determinação é feita se ele é um clicar que não é destinada aos clientes ou um clicar do cliente.OnContextHelp mapeamento de alças de que não é destinada aos clientes cliques para cliques de cliente automaticamente. Se for um clicar do cliente, em seguida, ele envia um WM_HELPHITTEST à janela que foi clicada.Se essa janela retorna um valor diferente de zero, esse valor é usado sistema autônomo o contexto para obter ajuda.Se ela retorna zero, OnContextHelp tenta a janela pai (e com falhas que seu pai e assim por diante). Se um contexto de Ajuda não pode ser determinado, o padrão é enviar um ID_DEFAULT_HELP comando janela principal, em seguida, (normalmente) é mapeado para CWinApp::OnHelpIndex.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest(WPARAM, LPARAM lParam)
WM_HELPHITTEST é uma mensagem de windows particular MFC recebida da janela ativo clicada durante o modo de ajuda deslocar+F1.Quando a janela recebe essa mensagem, ele retorna uma ID de ajuda de DWORD para uso pelo WinHelp.
LOWORD(lParam)
contém a coordenada de dispositivo do eixo x onde o mouse foi clicado em relação à área de cliente da janela.HIWORD(lParam)
contém as coordenada do eixo Y.wParam
não é usado e será zero.Se o valor retornado é diferente de zero, WinHelp é chamado com esse contexto.Se o valor retornado é zero, a janela pai será consultada para obter ajuda.
Em muitos casos, você pode aproveitar o código de teste de hit que talvez você já tenha.Consulte a implementação de CToolBar::OnHelpHitTest para obter um exemplo de manipular o WM_HELPHITTEST mensagem (o código utiliza o código de teste de hit usado nos botões e dicas de ferramentas na CControlBar).
Suporte a MFC aplicativo assistente e MAKEHM
O Assistente de aplicativo MFC cria os arquivos necessários para criar um arquivo de Ajuda (arquivos .cnt e .hpj).Ele também inclui um número de arquivos .rtf pré-construídos que são aceitos pelo Microsoft Help Compiler.Muitos dos tópicos são completos, mas algumas talvez precise ser modificado para seu aplicativo específico.
Há suporte para a criação automático de um arquivo de "Ajuda mapeamento" por um utilitário chamado MAKEHM.O utilitário MAKEHM pode traduzir um arquivo do aplicativo recurso.H para um arquivo de mapeamento de Ajuda.Por exemplo:
#define IDD_MY_DIALOG 2000
#define ID_MY_COMMAND 150
será convertido em:
HIDD_MY_DIALOG 0x207d0
HID_MY_COMMAND 0x10096
Esse formato é compatível com recurso do compilador da Ajuda, que mapeia as identificações do contexto (os números à direita) com nomes de tópico (símbolos no lado esquerdo).
O código-fonte para MAKEHM está disponível no MFC Programming utilitários amostra MAKEHM.
Adicionando suporte a Ajuda após executar o Assistente de aplicativo do MFC
A melhor maneira de adicionar ajuda a seu aplicativo é marcar a opção "contexto-sensitive ajuda" na página recursos avançados do Assistente do aplicativo MFC antes de criar seu aplicativo.Dessa forma, o Assistente de aplicativos MFC adiciona automaticamente as entradas de MAP de mensagem necessários ao seu CWinApp-derivado da classe para dar suporte a Ajuda.
Ajuda sobre caixas de mensagem
Obter ajuda sobre caixas de mensagens (às vezes chamado de alertas) é suportada através de AfxMessageBox função, um wrapper para o MessageBox API do Windows.
Há duas versões de AfxMessageBoxoutra para uso com um ID de string e outra para uso com um ponteiro para string ()LPCSTR):
int AFXAPI AfxMessageBox(LPCSTR lpszText, UINT nType, UINT nIDHelp);
int AFXAPI AfxMessageBox(UINT nIDPrompt, UINT nType, UINT nIDHelp);
Em ambos os casos, existe código um opcional ajuda.
No primeiro caso, o padrão para nIDHelp é 0, que não indica nenhuma ajuda para esta caixa de mensagem.Se o usuário pressiona F1 enquanto sistema autônomo mensagem de caixa estiver ativo, o usuário não receberá ajuda (mesmo que o aplicativo oferece suporte a Ajuda).Se não for desejável, uma ID de ajuda deve ser fornecida para nIDHelp.
No segundo caso, o valor padrão para nIDHelp é -1, que indica que a ID da Ajuda é a mesma nIDPrompt.Ajuda funcionará somente se o aplicativo ajuda ativada, é claro).Você deve fornecer 0 nIDHelp se desejar que a caixa de mensagem que não há suporte de Ajuda.Deve que a mensagem seja ajuda ativada, mas desejam uma ID de ajuda que nIDPrompt, simplesmente fornecer um valor positivo para nIDHelp diferente das nIDPrompt.