TN028: Suporte a Ajuda contextual
Esta anotação descreve as regras de atribuição de IDs de contextos de ajuda e outras questões ajuda no MFC.Suporte de ajuda contextual requer o compilador de ajuda está disponível no Visual C++.
.gif "Observação") Observação |
|---|
Além para implementar a Ajuda contextual usando o WinHelp, MFC também oferece suporte usando a Ajuda em HTML.Para obter mais informações sobre esse suporte e programação com a Ajuda de HTML, consulte Ajuda em HTML: ajuda sensível ao contexto para seus programas. |
Tipos de suporte de ajuda
Existem dois tipos de ajuda contextual implementada em aplicativos do Windows.O primeiro, conhecido como "Ajuda F1" envolve iniciar 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 continua o usuário clicar em um objeto.Nesse ponto, WinHelp é iniciado para fornecer ajuda para o objeto que o usuário clicou.
Microsoft Foundation Classes implementar ambas essas formas de Ajuda.Além disso, o framework oferece suporte a dois comandos simples ajuda, ajuda índice e usando a Ajuda.
Arquivos de ajuda
As Microsoft Foundation classes assumem um único arquivo de Ajuda.Arquivo de ajuda deve ter o mesmo nome e caminho do aplicativo.Por exemplo, se o executável é C:\MyApplication\MyHelp.exe o arquivo de ajuda deve ser C:\MyApplication\MyHelp.hlp.Definir o caminho através do m_pszHelpFilePath variável de membro de Classe de CWinApp.
Intervalos de contexto de ajuda
A implementação padrão do MFC requer um programa a seguir algumas regras sobre a atribuição de IDs 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 membro relacionadas a 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 "Ajuda"
Há dois comandos simples de ajuda que são implementados pela Microsoft Foundation Classes:
ID_HELP_INDEX que é implementada porCWinApp::OnHelpIndex
ID_HELP_USING que é implementada porCWinApp::OnHelpUsing
O primeiro comando mostra o índice da Ajuda do aplicativo.O segundo mostra a Ajuda do usuário usando o programa WinHelp.
Ajuda contextual (Ajuda F1)
A tecla F1 é geralmente traduzida para um comando com uma identificação de ID_HELP por um acelerador colocado na tabela do acelerador da janela principal.O ID_HELP comando também pode ser gerado por um botão com uma identificação de ID_HELP na caixa de diálogo ou janela principal.
Independentemente de como o ID_HELP comando é gerado, é roteado como um comando normal até alcançar um manipulador de comando.Para obter mais informações sobre a arquitetura de roteamento de comando do MFC, consulte técnico nota 21.Se o aplicativo tiver ajuda ativada, o ID_HELP comando será manipulado por CWinApp::OnHelp.O objeto de aplicativo recebe a mensagem de ajuda e roteia o comando adequadamente.Isso é necessário pois o roteamento de comando padrão não é adequado para determinar o contexto mais específico.
CWinApp::OnHelptenta iniciar WinHelp na seguinte ordem:
Verifica a existência de um ativo AfxMessageBox chamada com um ID de ajudaSe uma caixa de mensagem estiver atualmente ativa, WinHelp é iniciado com o contexto apropriado para essa caixa de mensagem.
Envia uma mensagem WM_COMMANDHELP para a janela ativa.Se essa janela não responder iniciando WinHelp, a mesma mensagem, em seguida, é enviada ancestrais da janela até que a mensagem é processada ou a janela atual é uma janela de nível superior.
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 de base de identificação do padrão (por exemplo0x10000 para comandos e 0x20000 para recursos como caixas de diálogo), o aplicativo deve substituir CWinApp::WinHelp.
Para substituir essa funcionalidade e a forma de um contexto de ajuda é determinado, você deve tratar a mensagem WM_COMMANDHELP.Você poderá fornecer mais específico ajuda roteamento que fornece a estrutura, como ele vai apenas como a janela de filho MDI atual.Você também poderá fornecer ajuda mais específica para uma janela ou caixa de diálogo, talvez com base no estado interno do objeto ou controle ativo dentro da caixa de diálogo atual.
WM_COMMANDHELP
afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)
WM_COMMANDHELP é uma mensagem de Windows MFC particular recebida pelo janela ativa quando a Ajuda é solicitada.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.lParamserá zero se nenhum contexto de ajuda foi determinado.Uma implementação de OnCommandHelp pode usar a identificação de contexto no lParam para determinar um contexto diferente ou 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.Retornar TRUE pára o roteamento deste comando para outras classes e outras janelas.
Modo de Ajuda (Shift + F1 Ajuda)
Esta é a segunda forma de ajuda contextual.Geralmente, esse modo é inserido pressionando SHIFT + F1 ou via menu/barra.Ele é implementado como um comando (ID_CONTEXT_HELP).O driver de filtro de mensagem não é usado para converter este comando enquanto uma caixa de diálogo restrita 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 esse modo, o cursor do mouse de ajuda é exibido em todas as áreas do aplicativo, mesmo se o aplicativo normalmente exibe seu próprio cursor para a área (como 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, ajudam no comando é exibido.Além disso, o usuário pode clicar em um objeto visível na tela, como um botão na barra de ferramentas e ajuda será exibida para o objeto.Esse modo de ajuda é fornecido por CWinApp::OnContextHelp.
Durante a execução deste loop, todos os entrada do teclado está inativo, exceto para as chaves que acessar o menu.Também, tradução de comando ainda é realizada por meio de PreTranslateMessage para permitir que o usuário pressione uma tecla aceleradora e receber ajuda sobre esse comando.
Se houver determinado traduções ou ações colocar na PreTranslateMessage função que não deveria ocorrer durante o modo SHIFT + F1 Ajuda, você deve verificar o m_bHelpMode membro do CWinApp antes de executar essas operações.O CDialog implementação de PreTranslateMessage verifica isso antes de chamar 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 SHIFT + F1.Além disso, CWinApp::OnIdle ainda é chamado durante este loop.
Se o usuário escolhe um comando de menu, é tratado como Ajuda do comando (por meio de WM_COMMANDHELP, veja abaixo).Se o usuário clica em uma área visível da janela de aplicativos, é feita uma determinação se ele é um clique não clientes ou um clique do cliente.OnContextHelpmapeamento de identificadores de não clientes cliques para cliques do cliente automaticamente.Se for um cliente clique, em seguida, envia uma WM_HELPHITTEST para a janela que foi clicada.Se essa janela retorna um valor diferente de zero, esse valor é usado como o contexto de Ajuda.Se ela retorna zero, OnContextHelp tenta a janela pai (e falha 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 para a janela principal, então (normalmente) é mapeada para CWinApp::OnHelpIndex.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest(WPARAM, LPARAM lParam)
WM_HELPHITTEST é uma mensagem de windows particulares MFC recebida por janela ativa clicada durante o modo de ajuda SHIFT + F1.Quando a janela recebe essa mensagem, ele retorna um DWORD ajuda ID para uso por WinHelp.
LOWORD (lParam)
contém a coordenada de dispositivo do eixo x onde o mouse foi clicado relativo para a área cliente da janela.HIWORD(lParam)
contém a coordenada Y.wParam
não é usado e será zero.Se o valor de retorno é diferente de zero, WinHelp é chamado com esse contexto.Se o valor de retorno for zero, a janela pai é consultada para obter ajuda.
Em muitos casos, você pode aproveitar talvez você já tenha o código de teste de impacto.Consulte a implementação de CToolBar::OnHelpHitTest para obter um exemplo de tratamento de WM_HELPHITTEST mensagem (o código utiliza o código de teste de hit usado em botões e dicas de ferramentas na CControlBar).
MAKEHM e suporte do Assistente de aplicativo MFC
O Assistente de aplicativo do 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 predefinidos que são aceitos pelo compilador de Ajuda do Microsoft.Vários tópicos estão completos, mas alguns talvez precise ser modificado para seu aplicativo específico.
Criação automática de um arquivo de "Ajuda mapeamento" é suportada por um utilitário chamado MAKEHM.O utilitário MAKEHM pode traduzir os recursos do aplicativo.Arquivo 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 o recurso de Ajuda do compilador, 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 exemplo MFC Programming utilitários MAKEHM.
Adicionando suporte a ajuda após executar o Assistente de aplicativo do MFC
A melhor maneira de adicionar ajuda para seu aplicativo é marcar a opção "Ajuda sensível ao contexto" na página recursos avançados do Assistente de aplicativo MFC antes de criar seu aplicativo.Dessa forma, o Assistente de aplicativo do MFC adiciona automaticamente as entradas de mapa de mensagem necessário para seu CWinApp-derivado classe para oferecer suporte a Ajuda.
Ajuda sobre caixas de mensagem
Ajuda em caixas de mensagens (às vezes chamado de alertas) é suportada através do AfxMessageBox função, um wrapper para o MessageBox API do Windows.
Há duas versões de AfxMessageBox, um 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, há uma identificação ajuda opcional
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 como mensagem caixa está ativa, o usuário não receberá ajuda (mesmo se o aplicativo oferece suporte a Ajuda).Se não for desejável, um ID de ajuda deve ser fornecido para nIDHelp.
No segundo caso, o valor padrão para nIDHelp é -1, que indica que o ID de ajuda é o mesmo que nIDPrompt.Ajuda funcionará somente se o aplicativo for ativado ajuda, é claro).Você deve fornecer 0 nIDHelp se você quiser que a caixa de mensagem não tem nenhum suporte de Ajuda.Você deve mensagem ajuda ativada, mas desejam uma ID de ajuda que nIDPrompt, simplesmente fornecer um valor positivo para nIDHelp diferente do nIDPrompt.