Programar funciones de WinHelp

Artículo
04/11/2008

Puede programar su aplicación para que los usuarios tengan acceso a su sistema de ayuda en la ayuda de Microsoft. Aunque un sistema de ayuda puede consistir en uno o varios archivos separados, la ayuda aparece ante los usuarios como parte integrante de su aplicación.

Puede programar su aplicación Visual FoxPro para utilizar ayuda gráfica y ayuda de tipo .dbf con los comandos SET HELP TO y SET TOPIC TO o con la función WinHelp, descrita más adelante en este tema. SET HELP TO especifica el nombre de un archivo de ayuda personalizado para su aplicación. SET TOPIC TO establece la palabra clave identificadora de un tema del archivo de ayuda personalizado.

Usar la función WinHelp

Otra forma de programar su aplicación para utilizar ayuda es la utilización de la función WinHelp. La función WinHelp forma parte de la interfaz de programación de aplicaciones (API) de Windows. La función WinHelp sólo está disponible en las plataformas Windows.

Puede utilizar la función WinHelp junto con la propiedad HelpContextID, especialmente para invocar un segundo archivo de ayuda.

Sugerencia Si utiliza SET HELP TO, HELP ID y SET TOPIC TO, no necesita utilizar la función WinHelp.

Para utilizar la función WinHelp

Defina los parámetros de comando que va a pasar en la aplicación.

Para obtener la descripción de dichos parámetros, vea "El parámetro wCmd", más adelante en esta misma sección.
Establezca la biblioteca con SET LIBRARY TO y defina las variables que vaya a utilizar, normalmente en el código de inicialización del archivo principal de la aplicación.
```
SET LIBRARY TO SYS(2004) + "FOXTOOLS.FLL" ADDITIVE
Help = RegFn("Help", "LCIC", "I")
```
El valor de la biblioteca tiene debe ser Foxtools.fll. SYS(2004) devuelve el directorio raíz de Visual FoxPro, donde está instalado Foxtools.fll.

Si quiere abrir un tema de ayuda enviando su palabra clave K, defina una variable con RegFn( ), de igual modo que la variable Help del ejemplo anterior. Si desea abrir un tema de ayuda asociado a un número, defina una variable con RegFn de igual modo que la variable HelpI del ejemplo anterior y utilice un número en lugar de una cadena en dwData. Si pasa números, tiene que asociarlos en la sección [MAP] del archivo .hpj con cadenas de contexto únicas definidas con la nota al pie (#).
Utilice CallFn( ) para invocar la función.

Por ejemplo, si su archivo de ayuda es Myhelpfile.hlp, utilice CallFn( ) para abrir un tema en Myhelpfile.hlp incluyendo la palabra clave K del tema:
```
#define HELP_KEY 0x0101
wCmd = HELP_KEY
cFilename = Myhelpfile.hlp"
dwData = "Add Menu Items at Run Time"
CallFn(Help, MainHWND(), cFileName, wCmd, dwData)
```

Para obtener más información acerca de las funciones FoxTools, vea el archivo Foxtools.chm en el directorio Vfp98\Tools.

Especificar los parámetros de WinHelp

Los siguientes parámetros especifican las opciones de la función WinHelp.

El parámetro hWnd

El parámetro hWnd identifica la ventana que solicita la ayuda. La ayuda utiliza este identificador para controlar qué aplicaciones han solicitado ayuda. En Visual FoxPro, utilice la función MainHWND( ), incluida en la biblioteca Foxtools.fll, para obtener el parámetro hWnd.

El argumento lpzFileName

El argumento lpzFileName representa una cadena de texto que especifica la ruta de acceso y el nombre válidos del archivo de ayuda que contiene el tema deseado. Se pasa por valor.

El parámetro wCmd

El parámetro wCmd especifica el tipo de búsqueda que la ayuda utiliza para buscar el tema especificado o que la aplicación ya no requiere ayuda. Puede establecerse uno de los siguientes valores.

Constante	Valor	Significado
HELP_FINDER	0x000B	Muestra la ventana Buscador de ayuda.
HELP_CONTEXT	0x0001	Muestra ayuda sobre un tema específico identificado por un número de contexto.
HELP_HELPONHELP	0x0004	Carga Help.hlp y muestra el tema Usar el índice de ayuda.
HELP_INDEX	0x0003	Muestra el tema de índice de ayuda principal definido en la sección [OPTIONS] del archivo de proyecto de ayuda (.hpj).
HELP_KEY	0x0101	Muestra el primer tema encontrado en la lista de palabras clave que corresponde a la palabra clave del parámetro dwData.
HELP_QUIT	0x0002	Informa a la aplicación de ayuda que la ayuda ya no es necesaria. Si ninguna otra aplicación ha solicitado ayuda, Windows cierra la aplicación de ayuda.
HELP_SETINDEX	0x0005	Establece un tema específico como tema de índice.

El parámetro dwData

El parámetro dwData representa el tema para el que la aplicación solicita ayuda. Su contenido y su formato dependen del valor de wCmd pasado cuando la aplicación invoca la función WinHelp.

En la mayor parte de las llamadas a ayuda, el argumento dwData se pasa por valor. Es la forma predeterminada de Visual FoxPro.

En función de las circunstancias, el argumento dwData de la línea anterior puede representar una cadena de texto, que indica la palabra clave que se busca, o un valor numérico, que indica el número de contexto que identifica un tema concreto.

La siguiente lista describe el formato de dwData para cada valor de wCmd.

Valor de wCmd	Formato de dwData
HELP_CONTEXT	Valor numérico que contiene el número de contexto del tema. En lugar de HELP_INDEX, HELP_CONTEXT puede utilizar el valor –1.
HELP_HELPONHELP	Omitido.
HELP_INDEX	Omitido.
HELP_KEY	Puntero largo a una cadena que contiene la palabra clave del tema deseado.
HELP_QUIT	Omitido.
HELP_SETINDEX	Valor numérico que contiene el número de contexto del tema que se va a establecer como índice.

Como la función WinHelp puede especificar un número de contexto o una palabra clave, es compatible con la ayuda interactiva y con la búsqueda de temas en el archivo de ayuda.

Nota Si un archivo de ayuda contiene dos o más índices, la aplicación tiene que asignar uno como índice predeterminado. Para garantizar que el índice correcto esté establecido, la aplicación tiene que invocar la ayuda con wCmd establecido en HELP_SETINDEX (y que dwData especifique el identificador de contexto adecuado). Todas las llamadas a ayuda tienen que ir seguidas de un comando establecido en HELP_CONTEXT. Nunca se debe utilizar HELP_INDEX con HELP_SETINDEX.

Reservar F1 para la ayuda

Cuando un usuario presiona F1 dentro de una aplicación, Visual FoxPro muestra un tema de ayuda interactiva. Para ello, asigne un Id. de contexto de ayuda a un tema de su tabla de ayuda y asigne el mismo valor a la propiedad HelpContextID del formulario o control. Cuando el formulario o el control estén resaltados y el usuario presione F1, Visual FoxPro mostrará el tema asociado.

Nota De forma predeterminada, F1 está activada para la ayuda interactiva. Como es un estándar admitido para la ayuda, no se recomienda la modificación de la definición de esta tecla.

Incluir botones de ayuda en los formularios

Si agrega botones de ayuda a los formularios, los usuarios podrán tener acceso a la ayuda con más facilidad. Especialmente, debe considerar la inclusión de un botón de ayuda si sus usuarios no son muy experimentados.

Para establecer ayuda interactiva y agregar un botón de ayuda

En el evento Init de su formulario, establezca en la propiedad HelpContextID de todos los objetos del formulario al mismo valor que el asignado al tema de ayuda. Por ejemplo, si dicho valor es 7, utilice el siguiente comando:
```
THIS.SetAll("HelpContextID", 7)
```
Agregue un botón de comando al formulario.
Establezca el valor Ayuda en la propiedad Caption del botón de comando.
En el evento Click del botón de comando, agregue el siguiente comando:
```
HELP ID THIS.HelpContextID
```
Sugerencia Guarde el botón de ayuda como una clase para poder incluirlo fácilmente en cualquier otro formulario. Para obtener más información acerca de cómo guardar objetos como clases, vea Crear formularios.

Salir de la ayuda

La aplicación de ayuda es un recurso compartido disponible en todas las aplicaciones Windows. Como también es una aplicación independiente, el usuario puede ejecutarla como cualquier otra aplicación. Como resultado, su aplicación tiene un control limitado sobre la aplicación de ayuda.

Aunque su aplicación no puede cerrar directamente la ventana de la aplicación de ayuda, puede informar a la aplicación de ayuda que ya no la va a necesitar. Antes de cerrar la ventana principal, la aplicación tiene que llamar a la ayuda con el parámetro wCmd establecido en HELP_QUIT, a fin de informar a la ayuda de que la aplicación ya no va a necesitarla.

Las aplicaciones que hayan llamado a la ayuda en algún punto de su ejecución tienen que llamar a la ayuda con el parámetro wCmd establecido en HELP_QUIT antes de terminar.

Si una aplicación abre más de un archivo de ayuda, tiene que invocar la función WinHelp para salir de la aplicación de ayuda para cada archivo.

Si una aplicación o una biblioteca de vínculos dinámicos (DLL) ha abierto un archivo de ayuda pero no quiere que la instancia asociada de la aplicación de ayuda siga activa, la aplicación o la DLL debe llamar a la ayuda con el parámetro wCmd establecido en HELP_QUIT para salir de dicha instancia de la aplicación de ayuda.

Nota Antes de terminar, las aplicaciones o las DLL tienen que llamar siempre a la ayuda para cada uno de los archivos de ayuda abiertos. Un archivo de ayuda se abre si se ha realizado una llamada a la ayuda con el nombre del archivo de ayuda.

La aplicación de ayuda no termina hasta que todas las ventanas que hayan solicitado la ayuda la hayan invocado con wCmd establecido en HELP_QUIT. Si alguna aplicación no lo hiciera, la aplicación de ayuda seguirá ejecutándose, aunque todas las aplicaciones que solicitaron ayuda hayan terminado.

Vea también

Compartir a través de