TN028: Ayuda y Soporte Técnico de Context-Sensitive

En esta nota se describen las reglas para asignar identificadores de contexto de ayuda y otras cuestiones relacionadas con la ayuda en MFC. La compatibilidad con ayuda contextual requiere el compilador de ayuda que está disponible en Visual C++.

Tipos de ayuda admitidos

Hay dos tipos de ayuda contextual implementada en las aplicaciones de Windows. La primera, denominada "Ayuda F1" implica iniciar WinHelp con el contexto adecuado basado en el objeto activo actualmente. La segunda es el modo "Mayús+ F1". En este modo, el cursor del mouse cambia al cursor de ayuda y el usuario continúa haciendo clic en un objeto. En ese momento, se inicia WinHelp para ofrecer ayuda para el objeto en el que el usuario ha hecho clic.

Microsoft Foundation Classes implementa ambas formas de ayuda. Además, el marco admite dos comandos de ayuda simples, Índice de ayuda y Uso de ayuda.

Archivos de ayuda

Las clases de Microsoft Foundation asumen un único archivo de Ayuda. Ese archivo de Ayuda debe tener el mismo nombre y ruta de acceso que la aplicación. Por ejemplo, si el archivo ejecutable es C:\MyApplication\MyHelp.exe el archivo de ayuda debe ser C:\MyApplication\MyHelp.hlp. La ruta de acceso se establece mediante la variable miembro m_pszHelpFilePath de la clase CWinApp.

Intervalos de contexto de ayuda

La implementación predeterminada de MFC requiere que un programa siga algunas reglas sobre la asignación de identificadores de contexto de ayuda. Estas reglas son una serie de identificadores asignados a controles específicos. Puede invalidar estas reglas proporcionando diferentes implementaciones de las distintas funciones miembro relacionadas con la ayuda.

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 sencillos de "Ayuda"

Hay dos comandos de Ayuda simples implementados por Microsoft Foundation Classes:

• ID_HELP_INDEX, implementado por CWinApp::OnHelpIndex

• ID_HELP_USING es implementado por CWinApp::OnHelpUsing

El primer comando muestra el índice de Ayuda de la aplicación. En el segundo se muestra la ayuda del usuario sobre el uso del programa WinHelp.

Ayuda contextual (Ayuda F1)

Normalmente, la tecla F1 se traduce a un comando con un identificador de ID_HELP mediante un acelerador colocado en la tabla de aceleradores de la ventana principal. El comando ID_HELP también se puede generar mediante un botón con un identificador de ID_HELP en la ventana principal o cuadro de diálogo.

Independientemente de cómo se genere el comando ID_HELP, se enruta como un comando normal hasta que llega a un controlador de comandos. Para obtener más información sobre la arquitectura de enrutamiento de comandos de MFC, consulte Nota técnica 21. Si la aplicación tiene habilitada la Ayuda, CWinApp::OnHelp controlará el comando ID_HELP. El objeto de aplicación recibe el mensaje de ayuda y, a continuación, enruta el comando correctamente. Esto es necesario, ya que el enrutamiento de comandos predeterminado no es adecuado para determinar el contexto más específico.

CWinApp::OnHelp intenta iniciar WinHelp en el orden siguiente:

1. Comprueba si hay una llamada activa AfxMessageBox con un identificador de ayuda. Si un cuadro de mensaje está activo actualmente, WinHelp se inicia con el contexto adecuado para ese cuadro de mensaje.

2. Envía un mensaje WM_COMMANDHELP a la ventana activa. Si esa ventana no responde iniciando WinHelp, se envía el mismo mensaje a los antecesores de esa ventana hasta que se procesa el mensaje o la ventana actual es una ventana de nivel superior.

3. Envía un comando ID_DEFAULT_HELP a la ventana principal. Esto invoca la Ayuda predeterminada. Este comando se asigna generalmente a CWinApp::OnHelpIndex.

Para invalidar globalmente los valores base de identificador predeterminados (por ejemplo, 0x10000 para comandos y 0x20000 para recursos como diálogos), la aplicación debe invalidar CWinApp::WinHelp.

Para invalidar esta funcionalidad y la forma en la que se determina un contexto de ayuda, debe controlar el mensaje WM_COMMANDHELP. Es posible que desee proporcionar un enrutamiento de Ayuda más detallado que el proporcionado por el marco de trabajo, ya que solo llega hasta el nivel de la ventana secundaria MDI actual. También puede proporcionar ayuda más específica para una ventana o un cuadro de diálogo concretos, quizás en función del estado interno actual de ese objeto o del control activo dentro del cuadro de diálogo.

WM_COMMANDHELP

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

WM_COMMANDHELP es un mensaje MFC privado de Windows que recibe la ventana activa cuando se solicita ayuda. Cuando la ventana recibe este mensaje, puede llamar a CWinApp::WinHelp con contexto que coincida con el estado interno de la ventana.

lParam
Contiene el contexto de ayuda disponible actualmente. lParam es cero si no se ha determinado ningún contexto de Ayuda. Una implementación de OnCommandHelp puede usar el identificador de contexto en lParam para determinar un contexto diferente o simplemente pasarlo a CWinApp::WinHelp.

wParam
No se usa y será cero.

Si la OnCommandHelp función llama a CWinApp::WinHelp, debe devolver TRUE. Devolver TRUE interrumpe el enrutamiento de este comando a otras clases y ventanas.

Modo de ayuda (Mayús+F1 Ayuda)

Esta es la segunda forma de ayuda contextual. Por lo general, este modo se introduce presionando MAYÚS+F1 o a través del menú o la barra de herramientas. Se implementa como un comando (ID_CONTEXT_HELP). El enlace de filtro de mensajes no se usa para traducir este comando mientras un cuadro de diálogo o menú modal está activo, por lo que este comando solo está disponible para el usuario cuando la aplicación ejecuta la bomba de mensajes principal (CWinApp::Run).

Después de entrar en este modo, el cursor de ayuda del ratón se muestra en todas las áreas de la aplicación, incluso si la aplicación normalmente mostraría su propio cursor para esa área (como el borde de ajuste de tamaño alrededor de la ventana). El usuario puede usar el mouse o el teclado para seleccionar un comando. En lugar de ejecutar el comando, se muestra la Ayuda en ese comando. Además, el usuario puede hacer clic en un objeto visible en la pantalla, como un botón de la barra de herramientas, y se mostrará ayuda para ese objeto. Este modo de ayuda lo proporciona CWinApp::OnContextHelp.

Durante la ejecución de este bucle, toda la entrada del teclado está inactiva, excepto las teclas que acceden al menú. Además, la traducción de comandos se sigue realizando a través PreTranslateMessage de para permitir al usuario presionar una tecla de aceleración y recibir ayuda en ese comando.

Si hay traducciones o acciones específicas que se realizan en la función PreTranslateMessage que no se deben realizar durante el modo de ayuda MAYÚS+F1, debe comprobar el miembro m_bHelpMode de CWinApp antes de realizar esas operaciones. La CDialog implementación de PreTranslateMessage comprueba esto antes de llamar a IsDialogMessage, por ejemplo. Esto deshabilita las teclas de "navegación de cuadro de diálogo" en los cuadros de diálogo sin modo durante el modo MAYÚS+F1. Además, se sigue llamando a CWinApp::OnIdle durante este bucle.

Si el usuario elige un comando en el menú, se maneja como ayuda relacionada con ese comando (a través de WM_COMMANDHELP, consulte a continuación). Si el usuario hace clic en un área visible de la ventana de aplicaciones, se determina si es un clic no cliente o un clic de cliente. OnContextHelp controla automáticamente la conversión de clics que no son de cliente en clics de cliente. Si es un clic de cliente, envía un WM_HELPHITTEST a la ventana en la que se hizo clic. Si esa ventana devuelve un valor distinto de cero, ese valor se usa como contexto de ayuda. Si devuelve cero, OnContextHelp lo intenta con la ventana primaria (y se produce un error, su elemento primario, etc.). Si no se puede determinar un contexto de ayuda, el valor predeterminado es enviar un comando ID_DEFAULT_HELP a la ventana principal, que se asigna a continuación (normalmente) a CWinApp::OnHelpIndex.

WM_HELPHITTEST

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

WM_HELPHITTEST es un mensaje de ventana privada de MFC que recibe la ventana activa en la que se hace clic durante el modo de ayuda MAYÚS+F1. Cuando la ventana recibe este mensaje, devuelve un identificador de ayuda de DWORD para su uso por WinHelp.

LOWORD(lParam) contiene la coordenada del dispositivo del eje X en la que se hizo clic con el mouse en relación con el área cliente de la ventana.

HIWORD(lParam) contiene la coordenada del eje Y.

wParam
no se usa y será cero. Si el valor devuelto es distinto de cero, se llama a WinHelp con ese contexto. Si el valor devuelto es cero, se consulta la ventana primaria para obtener ayuda.

En muchos casos, puede aprovechar el código de prueba de posicionamiento que pueda tener. Consulte la implementación de CToolBar::OnHelpHitTest para obtener un ejemplo del control del mensaje WM_HELPHITTEST (el código aprovecha el código de prueba de posicionamiento usado en los botones y la información sobre herramientas de CControlBar).

Compatibilidad con el Asistente para aplicaciones MFC y MAKEHM

El Asistente para aplicaciones MFC crea los archivos necesarios para compilar un archivo de Ayuda (archivos .cnt y .hpj). También incluye una serie de archivos .rtf creados previamente que el compilador de Ayuda de Microsoft acepta. Muchos de los temas están completos, pero es posible que sea necesario modificar algunos para su aplicación específica.

Una utilidad llamada MAKEHM permite la creación automática de un archivo de "asignación de ayuda". La utilidad MAKEHM puede traducir el archivo RESOURCE.H de una aplicación a un archivo de asignación de Ayuda. Por ejemplo:

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

se traducirá en:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Este formato es compatible con la funcionalidad del compilador de Ayuda, que asigna identificadores de contexto (los números del lado derecho) a nombres de tema (los símbolos del lado izquierdo).

El código fuente de MAKEHM está disponible en el ejemplo MAKEHM de utilidades de programación de MFC.

Añadir soporte de ayuda después de ejecutar el Asistente de aplicaciones MFC

La mejor manera de agregar Ayuda a la aplicación es comprobar la opción "Ayuda contextual" en la página Características avanzadas del Asistente para aplicaciones MFC antes de crear la aplicación. De este modo, el Asistente para aplicaciones de MFC agrega automáticamente las entradas de asignación de mensajes necesarias a la clase derivada de CWinApp para admitir la ayuda.

Ayuda sobre cuadros de mensaje

La ayuda sobre cuadros de mensaje (a veces llamados alertas) se admite mediante la función AfxMessageBox, un contenedor para la API MessageBox de Windows.

Hay dos versiones de AfxMessageBox, una para su uso con un identificador de cadena y otra para su uso con un puntero a cadena (LPCSTR):

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

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

En ambos casos, hay un identificador de ayuda opcional.

En el primer caso, el valor predeterminado de nIDHelp es 0, que indica que no hay ayuda para este cuadro de mensaje. Si el usuario presiona F1 mientras el cuadro de mensaje está activo, el usuario no recibirá ayuda (aunque la aplicación admita ayuda). Si esto no es deseable, se debe proporcionar un identificador de ayuda para nIDHelp.

En el segundo caso, el valor predeterminado de nIDHelp es -1, lo que indica que el identificador de ayuda es el mismo que nIDPrompt. La ayuda solo funcionará si la aplicación está habilitada para ayuda, por supuesto). Debe proporcionar 0 para nIDHelp si desea que el cuadro de mensaje no tenga soporte técnico. Si desea que el mensaje esté habilitado para Ayuda y utilizar un identificador de ayuda diferente al de nIDPrompt, simplemente proporcione un valor positivo para nIDHelp diferente del de nIDPrompt.

Consulte también

Notas técnicas por número
Notas Técnicas por Categoría