Manual del programador, Parte 7: Crear archivos de … · 2002-02-11 · Además de dicho comando,...

Manual del programador, Parte 7: Crear archivos de Ayuda Página 1 de 24

file://C:\temp\~hhCCF2.htm 30/05/2000

Manual del programador, Parte 7: Crear archivos de Ayuda

Los archivos de Ayuda son un origen de información valiosa para los usuarios de la aplicación. Con Visual FoxPro, puede elegir crear Winhelp, Ayuda HTML o Ayuda de tipo .DBF.

Capítulo 23 Crear Ayuda gráfica

La Ayuda gráfica puede ser Winhelp si desea una apariencia Windows, o una Ayuda HTML si desea una apariencia de Web.

Capítulo 24 Crear Ayuda de tipo .DBF

La Ayuda de tipo .DBF está basada en caracteres y le proporciona flexibilidad para migrar el archivo de Ayuda a otras plataformas. Este tipo de Ayuda es fácil de crear porque está basada en una tabla de Visual FoxPro.

Capítulo 23: Crear Ayuda gráficaPuede agregar un toque profesional a su aplicación al incluir un archivo de Ayuda gráfico en forma de Ayuda HTML o Ayuda WinHelp. La Ayuda gráfica puede incluir gráficos y texto con formato; la Ayuda de tipo dbf está limitada a una sola fuente sin gráficos. Para obtener información acerca de la creación de Ayuda de tipo .DBF, vea el capítulo 24, Crear Ayuda de tipo .DBF.

Nota Microsoft Visual Studio 6.0 incluye el Microsoft HTML Workshop (Hhw.exe) para crear archivos de Ayuda HTML. No incluye Microsoft Help Workshop 4.0 (Hcw.exe) para crear archivos Winhelp. Las versiones anteriores de Microsoft Visual FoxPro incluían Microsoft Help Workshop 4.0.

Los temas descritos en este capítulo son:

l Ayuda HTMLl WinHelp 4.0

Ayuda HTML

La Ayuda HTML proporciona muchas de las características de Winhelp y agrega las siguientes:



l Soporte para HTML.

l Soporte para ActiveX, Java y secuencias de comandos (Javascript y Microsoft Visual Basic Script).

l Soporte para los formatos de imagen de HTML (.jpg, .gif, .png).

l Capacidad para ir desde un tema de Ayuda a un sitio de Internet.

l Capacidad para ver el código HTML de un tema de Ayuda.

La Ayuda HTML se crea con Microsoft HTML Help Workshop, que se incluye en Visual Studio y en Visual FoxPro. HTML Help Workshop proporciona un completo sistema de creación de Ayuda HTML e incluye una compatibilidad con versiones anteriores que le permite crear fácilmente archivos de Ayuda HTML a partir de proyectos Winhelp existentes. Para crear archivos de Ayuda HTML en su aplicación, consulte la Ayuda en pantalla de HTML Help Workshop.

En …\Samples\Vfp98\Solution\Help se incluye un proyecto de Ayuda HTML de ejemplo, parte del ejemplo Solutions. Incluye los siguientes archivos:

Archivo Descripción

Solution.chm Archivo de Ayuda compilado.

Solution.hhp Archivo de proyecto (un archivo de texto que reúne todos los elementos de un proyecto de Ayuda y contiene información acerca de cómo va a aparecer un archivo de Ayuda compilado).

Solution.hhk Archivo de índice; contiene las entradas del índice (palabras clave).

Solution.hhc Archivo de Tabla de contenido.

Solution.ali Archivo de alias para el soporte de Ayuda interactiva. Asocia Id. de producto con temas de Ayuda.

Solution.hh Archivo de encabezados para el soporte de Ayuda interactiva. Incluye los Id. de producto.

Solution.chi Archivo de índice utilizado cuando se suministran archivos .chm que van a permanecer en un CD-ROM, como en el caso de la biblioteca MSDN. El archivo .chi permite la instalación local de cierta información de exploración en el disco duro que permite tener acceso de forma rápida, mientras que el contenido principal reside en el CD-ROM. Los archivos .chi no se usan en entornos sin CD-ROM. Cuando no se utilizan archivos .chi, toda la información que podría almacenar permanece en el propio archivo .chm.

MSDN_ie3.css Hoja con el estilo de cascada.

MSDN_ie4.css Hoja con el estilo de cascada.

Archivo.htm Archivos de contenido.



Archivo.gif Archivos gráficos.

Diseñar el acceso a la Ayuda HTML

Además de crear un archivo de Ayuda HTML que contenga información útil, tiene que proporcionar un medio para que los usuarios de su aplicación tengan acceso a dicha Ayuda. Hay tres maneras de proporcionar Ayuda:

l Un menú Ayuda (un menú que aparece en la barra del menú principal de su aplicación). l Ayuda interactiva (Ayuda que aparece cuando el usuario presiona F1, u otra tecla especificada,

mientras está seleccionado un objeto, control o opción de menú determinado). l Ayuda "¿Qué es esto?" (Ayuda que aparece cuando el usuario pide Ayuda sobre un objeto o

control determinado).

La implementación de la Ayuda HTML es similar a la de WinHelp. Las siguientes secciones describen cómo puede implementar la Ayuda HTML en sus aplicaciones.

Diseñar el menú Ayuda

El menú Ayuda suele contener comandos que proporcionan acceso a los temas de su sistema de Ayuda. Se recomienda que sólo un comando del menú Ayuda abra su sistema de Ayuda HTML. Además de dicho comando, puede incluir otros comandos en el menú Ayuda para proporcionar información del sistema o la información de derechos de autor y la versión de su aplicación.

Interactividad

La Ayuda interactiva permite que los usuarios tengan acceso a los temas de Ayuda relacionados con lo que estén haciendo o viendo en su aplicación en cualquier momento dado. Por ejemplo, si un usuario está viendo un formulario de introducción de datos, la Ayuda interactiva podría proporcionar un tema relacionado específicamente con dicho formulario.

Usted decide el nivel de detalle de la implementación de la Ayuda interactiva en su aplicación. Por ejemplo, puede asociar un tema de Ayuda interactiva con un formulario o puede asociar temas de Ayuda más detallados para cada uno de los controles y campos del formulario.

Se suele llegar a la Ayuda interactiva al presionar F1, pero puede especificar que se active mediante cualquier tecla con ON KEY LABEL.

Usar la Ayuda interactiva en un formulario

Para implementar Ayuda interactiva, tiene que especificar el archivo de Ayuda de su aplicación y después asociar temas de Ayuda determinados con objetos de su aplicación.

Para agregar Ayuda interactiva

1. Especifique el archivo de Ayuda de su aplicación.

2. Asigne un tema de Ayuda a cada objeto para el que vaya a proporcionar Ayuda interactiva.



Especificar el archivo de Ayuda

El archivo de Ayuda al que se tiene acceso en su aplicación se determina al incluir el comando SET HELP TO archivo en el código, donde archivo es el nombre del archivo de Ayuda. Por ejemplo, si el archivo de Ayuda es MiAyuda.chm, puede utilizar el siguiente comando:

SET HELP TO MIAYUDA.CHM

Este comando suele estar incluido en el código de configuración del programa principal de su aplicación.

Asignar temas de Ayuda

Puede asignar un tema de Ayuda a objetos específicos de su aplicación de Visual FoxPro.

Para asignar un tema de Ayuda a un objeto

1. En modo Diseño, abra el objeto (por ejemplo, un formulario, un control o una barra de herramientas) al que vaya a asignar Ayuda interactiva.

2. Vea las propiedades del objeto.

3. Establezca la propiedad HelpContextID al número correspondiente al tema asociado de su archivo de Ayuda HTML.

Para obtener más información acerca de la asociación de temas de Ayuda HTML con Id. de contexto, consulte la Ayuda de HTML Help Workshop.

Nota Para asignar temas de Ayuda a títulos de menú o a comandos de menú, tiene que incluir el comando SET TOPIC TO en el procedimiento asociado con el título de menú o el comando de menú.

Implementar la Ayuda "¿Qué es esto?"

La Ayuda "¿Qué es esto?" es similar a la Ayuda interactiva puesto que proporciona Ayuda relacionada con el objeto o control específico que actualmente tiene el enfoque.

En WinHelp, en lugar de invocar el archivo de Ayuda y mostrar el tema de Ayuda en la ventana de Ayuda con su tamaño predeterminado, la Ayuda "¿Qué es esto?" presenta el tema en una pequeña ventana emergente que desaparece en cuanto el usuario hace clic en cualquier parte de la pantalla. La Ayuda "¿Qué es esto?" es útil para proporcionar breves descripciones, definiciones o sugerencias sobre controles específicos.

Al contrario que en WinHelp, la Ayuda HTML "¿Qué es esto?" se presenta en la ventana de Ayuda con su tamaño predeterminado.

La Ayuda "¿Qué es esto?" se asocia con un formulario, control de formulario o barra de herramientas particular estableciendo su propiedad WhatsThisHelpID al número correspondiente al tema asociado de su archivo de Ayuda.



Para implementar la Ayuda "¿Qué es esto?", utilice las siguientes propiedades y métodos:

Propiedad Descripción

WhatsThisHelp Establezca esta propiedad a True (.T.) en un formulario para activar la Ayuda "¿Qué es esto?" en el formulario y en los controles del formulario.

WhatsThisButton Establezca esta propiedad a True (.T.) si quiere que aparezca un botón "¿Qué es esto?" en la barra de título del formulario.

WhatsThisHelpID En un formulario, control o barra de herramientas, establezca esta propiedad al ID correspondiente al tema asociado de su archivo de Ayuda HTML.

WhatsThisMode Utilice este método para mostrar el puntero con la interrogación para la Ayuda "¿Qué es esto?" y activar dicho modo de Ayuda. Al hacer clic en un objeto se muestra el tema de Ayuda "¿Qué es esto?" especificado por la propiedad WhatsThisHelpID del objeto.

Para implementar la Ayuda "¿Qué es esto?"

1. En modo Diseño, abra el formulario en el que vaya a activar la Ayuda "¿Qué es esto?".

2. Establezca la propiedad WhatsThisHelp del formulario a True (.T.).

3. Para mostrar un botón "¿Qué es esto?" en la barra de título del formulario, establezca la propiedad WhatsThisButton del formulario a True (.T.).

4. Para asociar un tema de Ayuda "¿Qué es esto?" al formulario, establezca la propiedad WhatsThisHelpID del formulario al Id. correspondiente al tema asociado de su archivo de Ayuda HTML.

5. Para asociar un tema de Ayuda "¿Qué es esto?" con un control concreto del formulario, seleccione el control y establezca su propiedad WhatsThisHelpID al Id. correspondiente al tema asociado de su archivo de Ayuda HTML.

Programar las funciones de Ayuda

Puede programar su aplicación para que los usuarios tengan acceso a su sistema de Ayuda HTML. Aunque un sistema de Ayuda HTML 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 de Visual FoxPro para utilizar Ayuda gráfica y Ayuda de tipo .dbf con los comandos SET HELP TO y SET TOPIC TO. SET HELP TO especifica el nombre de un archivo de Ayuda personalizado para su aplicación. SET TOPIC TO establece la palabra clave identificativa de un tema del archivo de Ayuda personalizado.



Reservar F1

Cuando un usuario presiona F1 dentro de su aplicación, Visual FoxPro puede mostrar un tema de Ayuda interactiva. Para hacerlo así, asigne un Id. de contexto con un tema de su tabla de Ayuda y asigne el mismo valor a la propiedad HelpContextID del formulario o el control. Cuando el formulario o el control tengan el enfoque y el usuario presione F1, Visual FoxPro muestra 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 esta tecla.

Incluir botones de Ayuda en los formularios

Si agrega botones de Ayuda a sus formularios, los usuarios pueden 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 la sensibilidad al contexto y agregar un botón de Ayuda

1. En el evento Init de su formulario, establezca la propiedad HelpContextID de todos los objetos del formulario al mismo valor, correspondiente a un tema de Ayuda. Por ejemplo, si dicho valor es 7, podría utilizar el siguiente comando:

THIS.SetAll("HelpContextID", 7)

2. Agregue un botón de comando al formulario.

3. Establezca la propiedad Caption del botón de comando a "Ayuda".

4. 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 de forma que pueda incluirlo fácilmente en cualquier otro formulario. Para obtener más información acerca de cómo guardar objetos como clases, vea el capítulo 9, Crear formularios.

Distribuir un sistema de Ayuda HTML compilado

Además del archivo .chm que se crea para el sistema de Ayuda HTML, puede utilizar un programa de instalación de uso y distribución gratuita, Hhupd.exe, que instala y registra los componentes de ejecución de la Ayuda HTML mostrados a continuación. El Explorador de Internet o el motor de ejecución del Explorador de Internet tienen que estar instalados en los equipos de los usuarios.



Componente Descripción

Hhctrl.ocx Control ActiveX de la Ayuda HTML

Itss.dll Biblioteca de vínculos dinámicos que controla el HTML compilado

Itircl.dll Biblioteca de vínculos dinámicos para búsquedas de texto

Hh.exe Visor de Ayuda HTML

Este programa de instalación se encuentra en la carpeta Redist de la carpeta de instalación del Taller de Ayuda HTML. Puede llamar a dicho programa de instalación desde otros programas de instalación y ejecutarlo en modo 'silencioso' para que no interfiera con el programa de instalación que haya creado. Para obtener la lista completa de las opciones de línea de comandos, ejecute Hhupd.exe/?.

WinHelp 4.0

Utilice Microsoft Help Workshop, proporcionado en las versiones anteriores de Visual FoxPro, para crear archivos Winhelp. Microsoft Help Workshop incluye una Guía de diseño de Ayudas. La Guía de diseño de Ayudas (Hcw.hlp) es un archivo de Ayuda gráfica que contiene gran parte de la información necesaria para diseñar sistemas de Ayuda robustos.

Elegir las funciones de Ayuda

Los sistemas WinHelp puede tener algunas o todas las funciones siguientes:

l Una página de contenido que proporciona una vista jerárquica de los temas del sistema de Ayuda.

l Un índice, basado en las palabras clave que usted proporcione, que guía al usuario hasta una información específica.

l Funciones de búsqueda de texto que permiten que los usuarios busquen palabras o frases en la Ayuda.

l Texto con varias fuentes, tamaños de fuente y colores. l Gráficos, incluyendo mapas de bits con varias resoluciones. l Macros que automatizan o amplían la operación del sistema de Ayuda. l Zonas activas (áreas sensibles al mouse que se crean para proporcionar a los usuarios saltos que

vinculan temas; ventanas emergentes que muestran texto adicional; y macros incluidas en el sistema de Ayuda).

l Hipergráficos segmentados: gráficos con una o varias zonas activas. l Ventanas secundarias. l Menús personalizables. l Gráficos en formato metarchivo de Windows. l .DLLs.

Diseñar el acceso a la Ayuda en pantalla

Además de crear un archivo WinHelp que contenga la información necesaria, tiene que proporcionar los medios a través de los cuales los usuarios de su aplicación van a tener acceso a la Ayuda. Hay tres



maneras de proporcionar Ayuda:

l Un menú Ayuda (un menú que aparece en la barra del menú principal de su aplicación). l Ayuda interactiva (Ayuda que aparece cuando el usuario presiona F1, u otra tecla especificada,

mientras está seleccionado un objeto, control u opción de un menú determinado). l Ayuda "¿Qué es esto?" (Ayuda que aparece como sugerencia emergente cuando el usuario pide

Ayuda sobre un objeto o control específico).

Diseñar el menú Ayuda

El menú Ayuda suele contener comandos que proporcionan acceso a los temas de su sistema de Ayuda. WinHelp 4.0 incorpora la ventana Buscador de Ayuda, que es un único cuadro de diálogo que proporciona acceso al contenido, al índice y a la búsqueda de texto.

La ventana Buscador de Ayuda

Se recomienda que sólo un comando del menú Ayuda abra la ventana Buscador de Ayuda. Además de dicho comando, puede incluir otros comandos en el menú Ayuda para proporcionar información del sistema o la información de derechos de autor y la versión de su aplicación.

Puede invocar la ventana Buscador de Ayuda desde los programas mediante la función WinHelp con el parámetro HELP FINDER. Para obtener más información, vea "Usar la función WinHelp" más adelante en este capítulo y el tema WinHelp de la Guía de diseño de Ayudas.

Interactividad de la Ayuda



La Ayuda interactiva permite que los usuarios tengan acceso a los temas de Ayuda relacionados con lo que estén haciendo o viendo en su aplicación en cualquier momento dado. Por ejemplo, si un usuario está viendo un formulario de introducción de datos, la Ayuda interactiva podría proporcionar un tema relacionado específicamente con dicho formulario

Usted decide el nivel de detalle de la implementación de la Ayuda interactiva en su aplicación. Por ejemplo, puede asociar un tema de Ayuda interactiva con un formulario, o puede asociar temas de Ayuda más detallados para cada uno de los controles y campos del formulario.

Se suele llegar a la Ayuda interactiva al presionar F1, pero puede especificar la activación de la Ayuda interactiva mediante cualquier tecla con ON KEY LABEL.

Usar WinHelp interactiva en un formulario

Para implementar Ayuda interactiva, tiene que especificar el archivo de Ayuda de su aplicación y, a continuación, asociar temas de Ayuda específicos a objetos de su aplicación.

Para agregar Ayuda interactiva

1. Especifique el archivo de Ayuda de su aplicación.

2. Asigne un tema de Ayuda a cada objeto para el que vaya a proporcionar Ayuda interactiva.

Especificar el archivo de Ayuda

El archivo de Ayuda al que se tiene acceso en su aplicación se determina al incluir el comando SET



HELP TO archivo en el código, donde archivo es el nombre del archivo de Ayuda. Por ejemplo, si el archivo de Ayuda es MiAyuda.hlp, puede utilizar el siguiente comando:

SET HELP TO MIAYUDA.HLP

Este comando suele estar incluido en el código de configuración del programa principal de su aplicación.

Asignar temas de Ayuda

Puede asignar un tema de Ayuda a objetos específicos de su aplicación de Visual FoxPro.

Para asignar un tema de Ayuda a un objeto

1. En modo Diseño, abra el objeto (por ejemplo, un formulario, un control o una barra de herramientas) al que vaya a asignar Ayuda interactiva.

2. Vea las propiedades del objeto.

3. Establezca la propiedad HelpContextID al número correspondiente al tema asociado de su archivo de Ayuda.

Para obtener más información acerca de la asociación de temas de Ayuda con Id. de contexto, consulte la Guía de diseño de Ayuda.

Nota Para asignar temas de Ayuda a títulos de menú o a comandos de menú, tiene que incluir el comando SET TOPIC TO en el procedimiento asociado con el título de menú o el comando de menú.

Implementar la Ayuda "¿Qué es esto?"

La Ayuda "¿Qué es esto?" es similar a la Ayuda interactiva puesto que proporciona Ayuda relacionada con el objeto o control determinado que tiene actualmente el enfoque. Sin embargo, en lugar de invocar el archivo de Ayuda y mostrar el tema de Ayuda en la ventana de Ayuda con su tamaño predeterminado, la Ayuda "¿Qué es esto?" muestra el tema en una pequeña ventana emergente que desaparece en cuanto el usuario haga clic en cualquier parte de la pantalla. La Ayuda "¿Qué es esto?" es útil para proporcionar breves descripciones, definiciones o sugerencias sobre controles concretos.

Sugerencia Los temas de Ayuda "¿Qué es esto?" deben ser breves y concisos para que la ventana no sea tan grande como para ocultar el componente que describe.

Ayuda "¿Qué es esto?"



La Ayuda "¿Qué es esto?" se asocia a un formulario, control de formulario o barra de herramientas particular al establecer su propiedad WhatsThisHelpID al número correspondiente al tema asociado de su archivo de Ayuda

Para implementar la Ayuda "¿Qué es esto?", utilice las siguientes propiedades y métodos:

Propiedad Descripción

WhatsThisHelp Establezca esta propiedad a True (.T.) en un formulario para activar la Ayuda "¿Qué es esto?" en el formulario y en los controles del formulario.

WhatsThisButton Establezca esta propiedad a True (.T.) si desea que aparezca un botón "¿Qué es esto?" en la barra de título del formulario.

WhatsThisHelpID En un formulario, control o barra de herramientas, establezca esta propiedad al Id. correspondiente al tema asociado de su archivo de Ayuda.

WhatsThisMode Utilice este método para mostrar el puntero con la interrogación para la Ayuda "¿Qué es esto?" y activar dicho modo de Ayuda. Al hacer clic en un objeto se presenta el tema de Ayuda "¿Qué es esto?" especificado por la propiedad WhatsThisHelpID del objeto.



Usar un botón "¿Qué es esto?"

Para implementar la Ayuda "¿Qué es esto?"

1. En modo Diseño, abra el formulario en el que vaya a activar la Ayuda "¿Qué es esto?".

2. Establezca la propiedad WhatsThisHelp del formulario a True (.T.).

3. Para mostrar un botón "¿Qué es esto?" en la barra de título del formulario, establezca la propiedad WhatsThisButton del formulario a True (.T.).

4. Para asociar un tema de Ayuda "¿Qué es esto?" al formulario, establezca la propiedad WhatsThisHelpID del formulario al Id. correspondiente al tema asociado de su archivo de



Ayuda.

5. Para asociar un tema de Ayuda "¿Qué es esto?" a un control específico del formulario, seleccione el control y establezca su propiedad WhatsThisHelpID al Id. correspondiente al tema asociado de su archivo de Ayuda.

Programar las funciones de Ayuda

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 capítulo. SET HELP TO especifica el nombre de un archivo de Ayuda personalizado para su aplicación. SET TOPIC TO establece la palabra clave identificativa 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, 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

1. Defina los parámetros que va a pasar desde su aplicación.

Para obtener la descripción de dichos parámetros, vea "El parámetro wCmd", más adelante en este mismo capítulo.

2. 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" ADDITIVEHelp = RegFn("Help", "LCIC", "I")

La biblioteca tiene que establecerse a Foxtools.fll. SYS(2004) devuelve el directorio raíz de Visual FoxPro, en donde está instalada 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, define una variable con RegFn de igual modo que la variable Help del



ejemplo anterior y utilice un número en lugar de una cadena de texto 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 (#).

3. Utilice CallFn( ) para invocar la función.

Por ejemplo, si su archivo de Ayuda es MiAyuda.hlp, utilice CallFn( ) para abrir un tema en MiAyuda.hlp incluyendo la palabra clave K del tema:

#define HELP_KEY 0x0101wCmd = HELP_KEYcNombreArchivo = MiAyuda.hlp"dwData = "Agregar elementos de menú en tiempo de ejecución"CallFn(Help, MainHWND(), cFileName, wCmd, dwData)

Para obtener más información sobre las funciones de FoxTools, consulte 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 saber 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 y el nombre 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 a 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 definido en la sección [OPTIONS] del archivo de proyecto de Ayuda (.hpj).

HELP_KEY 0x0101 Muestra el primer tema encontrado entre los que contienen la palabra clave especificada en el parámetrodwData.

HELP_QUIT 0x0002 Informa a la aplicación de Ayuda que 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.

Dependiendo de las circunstancias, dwData puede representar una cadena de texto, indicando la palabra clave que se busca, o un valor numérico, indicando el número de contexto que identifica al tema concreto.

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

Valor de wCmd Formato de dwData

HELP_CONTEXT Un 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 Ignorado.

HELP_INDEX Ignorado.

HELP_KEY Un puntero a una cadena que contiene la palabra clave del tema deseado.

HELP_QUIT Ignorado.

HELP_SETINDEX Un 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, acepta la



Ayuda interactiva y 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 asegurarse de que el índice correcto esté establecido, la aplicación tiene que invocar la Ayuda con wCmd establecido a help_setindex (y dwData especificando el identificador de contexto adecuado). Todas las llamadas a Ayuda tienen que ir seguidas de un comando establecido a help_context. Nunca se debe utilizar HELP_index con help_setindex.

Reservar F1 para la Ayuda

Cuando un usuario presiona F1 en su aplicación, Visual FoxPro puede mostrar un tema de Ayuda interactiva. Para hacerlo, 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 el control. Cuando el formulario o el control tiene el enfoque y el usuario presiona F1, Visual FoxPro muestra 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 esta tecla.

Incluir botones de Ayuda en los formularios

Si agrega botones de Ayuda a sus formularios, los usuarios pueden 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 la sensibilidad al contexto y agregar un botón de Ayuda

1. En el evento Init de su formulario, establezca la propiedad HelpContextID de todos los objetos del formulario al mismo valor, correspondiente a un tema de Ayuda. Por ejemplo, si dicho valor es 7, podría utilizar el siguiente comando:



3. Establezca la propiedad Caption del botón de comando a "Ayuda".

4. En el evento Click del botón de comando, agregue el siguiente comando:


Sugerencia Guarde el botón de Ayuda como una clase de forma que pueda incluirlo fácilmente en cualquier otro formulario. Para obtener más información acerca de cómo guardar objetos como clases, vea el capítulo 9, Crear formularios..

Salir de la Ayuda

La aplicación de Ayuda es un recurso compartido disponible por 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 aplicación de Ayuda, puede informar a la aplicación de Ayuda que ya no la va a necesitar. Antes de cerrar su ventana principal, su aplicación tiene que invocar a Ayuda con el parámetro wCmd establecido a help_quit, que informa a la Ayuda de que su 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 a 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 una vez por cada archivo abierto.

Si una aplicación o una biblioteca de vínculos dinámico (DLL) ha abierto un archivo de Ayuda pero no quiere seguir manteniendo la asociación con la instancia de la aplicación de Ayuda, la aplicación o la DLL tiene que invocar WinHelp con el parámetro wCmd establecido a 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 WinHelp por cada uno de los archivos de Ayuda abiertos. Un archivo de Ayuda se abre si hace cualquier 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 a help_quit. Si alguna aplicación no lo hiciera, la aplicación de Ayuda seguiría ejecutándose, incluso después de que todas las aplicaciones que solicitaron Ayuda hubieran terminado.

Capítulo 24: Crear Ayuda de tipo .DBFLa Ayuda de tipo .DBF es fácil de crear y utiliza tablas estándar de Visual FoxPro que se transfieren fácilmente a otras plataformas. Si quiere una solución sencilla para proporcionar ayuda, si programa aplicaciones para varias plataformas o si prefiere un archivo de ayuda compatible con versiones anteriores, puede proporcionar una ayuda de tipo .DBF a sus usuarios.

En este capítulo se tratan los temas siguientes:

l Diseñar Ayuda de tipo .DBFl Ver el archivo de ejemplo de Ayuda de tipo .DBFl Usar la Ayuda de tipo .DBFl Personalizar la Ayuda de tipo .DBF

Diseñar la Ayuda de tipo .DBF

Los archivos de Ayuda de tipo .DBF, o las tablas de Ayuda, son tablas libres que se muestran en la ventana de Ayuda de tipo .DBF. Con este tipo de Ayuda, los usuarios pueden:

l Obtener Ayuda interactiva sobre el cuadro de diálogo, el comando de menú o el objeto actual al presionar F1.



l Saltar a temas relacionados del archivo de Ayuda seleccionando un tema en la lista desplegable "Vea también".

l Seleccionar una palabra o frase clave en medio de un tema y saltar a dicha palabra o frase haciendo clic en el botón "Buscar".

l Copiar al Portapapeles el texto seleccionado en la ventana de Ayuda.

En Visual FoxPro se incluye un archivo de Ayuda de tipo .DBF, Ttrade.dbf, ubicado en el directorio ...\Samples\Vfp98\Tastrade\Help de Visual Studio. Las secciones siguientes usan el ejemplo Ttrade.dbf para describir el diseño y el desplazamiento por la ayuda de tipo .DBF.

Ver el archivo de Ayuda de tipo .DBF

Para ver el archivo de ayuda de ejemplo Ttrade.dbf

l En la ventana Comandos, con el directorio predeterminado establecido al que contiene Ttrade.dbf, escriba:

SET HELP TO TTRADE.DBFHELP

Visual FoxPro muestra la Ayuda de tipo .DBF Ttrade en su propia ventana.

La ventana de Ayuda .DBF tiene dos modos: Temas y Detalles. El modo Temas muestra una lista de todos los temas del archivo de Ayuda. Observe que la fuente de la ventana Ayuda .DBF es MS Sans Serif y no se puede cambiar.

Ventana de Ayuda .DBF en modo Temas

Al hacer doble clic en un tema, el contenido de ese tema aparece en el modo Detalles.

Ventana de Ayuda .DBF en modo Detalles



Requisitos de las tablas de Ayuda

Las tablas de Ayuda tienen capacidad para un máximo de 32.767 registros y deben contener al menos dos campos. La tabla puede tener un primer campo opcional para interactividad. El ejemplo siguiente muestra la configuración de una tabla de Ayuda típica:

Tabla TTRADE en modo Examinar

No hay requisitos para los nombres de campo. Los tipos de campo son, en orden:

Numéricos Este campo es opcional y contiene el identificador de contexto (HelpContextID) empleado con la Ayuda interactiva.

Carácter Es el nombre del tema que aparece en el modo Temas de la ventana de Ayuda.

Memo Este campo contiene la información que aparece en el modo Detalles de la ventana de Ayuda.

Aparte de estos requisitos, puede agregar tantos campos adicionales como desee.

Descripción de Ttrade.dbf

Ttrade.dbf es un buen ejemplo de un archivo de Ayuda de tipo .DBF. Puede diseñar su archivo de Ayuda basándose en Ttrade.dbf, o bien puede crear su propio diseño. Puesto que un archivo de Ayuda es una tabla, puede crear su propio archivo de Ayuda creando una tabla nueva o copiando y



modificando una tabla existente.

Para ver o modificar la tabla Ttrade.dbf, ábrala y examine su contenido como cualquier otra tabla. Si ha ejecutado anteriormente el comando SET HELP TO TTRADE.DBF, deberá utilizar primero el comando SET HELP OFF antes de abrir la tabla Ttrade.dbf.

Temas de TTRADE

Ttrade.dbf incluye varios tipos de temas. Son los siguientes:

l Instrucciones paso a paso. l Temas de interfaz para Ayuda interactiva, incluidos comandos de menú y cuadros de diálogo. l Temas de referencia del lenguaje.

En su archivo de Ayuda puede utilizar estas categorías y otras distintas.

Detalles de TTRADE

Cuando un usuario selecciona un tema en el modo Temas, la ventana de Ayuda muestra el contenido del campo memo llamado Details.

Referencias cruzadas de TTRADE

En la mayoría de los temas de Ayuda, las referencias cruzadas de tipo "Vea también" aparecen al final de la información de Detalles. Estas referencias se muestran automáticamente en el cuadro "Vea también" y actúan como vínculos directos a los temas relacionados.

Para crear una referencia cruzada tipo "Vea también"

1. Al final del campo memo, escriba Vea también seguido de un signo de dos puntos y espacios opcionales.

2. En la misma línea, escriba una lista delimitada por comas de los temas deseados.

3. Introduzca un retorno de carro para indicar el final de la lista.

La distinción entre mayúsculas y minúsculas no importa en la lista "Vea también"; Visual FoxPro elimina los espacios en blanco de cada tema al que se hace referencia. Por ejemplo, las referencias cruzadas para el tema Introducción aparecen a continuación.

Contenido del campo memo del tema Introducción



Sugerencia Agregue líneas por encima y por debajo de la sección "Vea también" al final del tema para separarla visualmente del contenido.

Al buscar un tema en el cuadro "Vea también", Visual FoxPro intenta hacer coincidir la selección del usuario con el primer tema de Ayuda que conste o comience por la misma cadena de texto. Si Visual FoxPro no encuentra ninguna coincidencia, mostrará "No hay Ayuda para tema" en la barra de estado.

Usar la Ayuda de tipo .DBF

Los usuarios podrán tener acceso fácilmente a la Ayuda si incluye un comando Contenido en el menú Ayuda que utilice el comando HELP. Cuando el usuario elija el comando Contenido, aparecerá la ventana de Ayuda en modo Temas. El usuario puede desplazarse por la lista para buscar el tema deseado o escribir una letra para seleccionar el primer tema que comience por esa letra. Una vez seleccionado un tema, hay tres formas de mostrar información sobre él:

l Hacer doble clic en el tema de la lista. l Hacer clic en el botón Ayuda. l Presionar la tecla ENTRAR.

Personalizar la Ayuda de tipo .DBF

En el código de la aplicación, especifique el archivo de Ayuda que utiliza, los temas que se muestran y cuándo se muestran, y otras configuraciones opcionales. Si incluye Ayuda interactiva, los usuarios podrán obtener Ayuda al solicitarla desde cuadros de diálogo y los comandos de menú de la aplicación.

Especificar una tabla de Ayuda

Especifique la tabla de Ayuda; para ello, ejecute el comando SET HELP TO nombrearchivo. De este modo se cerrará la tabla de Ayuda actual, si había alguna abierta, y se abrirá nombrearchivo como nueva tabla de Ayuda.



En una situación típica de programación, guarde en una variable el nombre del archivo de Ayuda actual y especifique el nombre del archivo de Ayuda en el código de inicialización, como en el ejemplo siguiente:

cAyudaUsuario = SET("HELP", 1)SET HELP TO MIAYUDA.DBF

Al salir de la aplicación, podrá restaurar el archivo de Ayuda original:

SET HELP TO (cAyudaUsuario)

Mostrar temas en la ventana de Ayuda

Después de especificar la tabla de Ayuda, puede especificar los temas que desea mostrar de esta forma:

l Para seleccionar temas por nombre, utilice los comandos HELP Tema o SET TOPIC TO cNombreTemaAyuda.

l Para temas de Ayuda interactiva, utilice la propiedad HelpContextID. l Para mostrar un subconjunto de temas, use el comando SET HELPFILTER.

Seleccionar temas por nombre

Para seleccionar temas por nombre, utilice el comando HELP Tema. Cuando utilice este comando, Visual FoxPro buscará en la tabla de Ayuda el registro cuyo campo de tema coincide con Tema. En la búsqueda no se distinguen mayúsculas de minúsculas.

Cuando Visual FoxPro encuentre una coincidencia, mostrará el contenido del campo memo Detalles en el modo Detalles de la ventana de Ayuda. Si Visual FoxPro no encuentra ninguna coincidencia, mostrará todos los temas de una lista en el cuadro de diálogo Temas de Ayuda con la coincidencia más cercana resaltada.

Activar la Ayuda interactiva

Puede diseñar la aplicación de modo que el usuario pueda obtener Ayuda interactiva de dos formas:

l Al presionar la tecla F1 en cualquier momento. l Al hacer clic en un botón "Ayuda" que se incluye en los formularios y los cuadros de diálogo.

Reserva de F1

Cuando un usuario presiona F1 en la aplicación, Visual FoxPro puede mostrar un tema de Ayuda interactiva. Para ello, asigne un HelpcontextID a un tema en la tabla de Ayuda y asigne el mismo valor a la propiedad HelpContextID del formulario o el control. Cuando el formulario o el control tenga el enfoque y el usuario presione F1, Visual FoxPro mostrará el tema correspondiente.

Nota F1 está activada para Ayuda interactiva de forma predeterminada. Puesto que se trata de un estándar reconocido para la Ayuda, no se recomienda redefinir esta tecla.



Agregar botones Ayuda a formularios

Si agrega botones Ayuda a los formularios, los usuarios podrán tener acceso a la Ayuda de forma más fácil. El botón Ayuda puede resultar especialmente útil si el usuario no tiene mucha experiencia.

Para crear un tema de Ayuda interactiva

1. En el primer campo de un registro de la tabla de Ayuda, escriba un valor numérico.

2. Rellene los campos Tema y Detalles del registro.

Ahora ya puede asignar el tema de Ayuda al formulario. Es conveniente asignar un botón Ayuda, el formulario y sus objetos al mismo tema de Ayuda.

Para establecer Ayuda interactiva y agregar un botón Ayuda

1. En el evento Init del formulario, establezca la propiedad HelpContextID de todos los objetos del formulario con el mismo valor que haya asignado al tema de Ayuda. Por ejemplo, si el valor es 7, podrá emplear el comando siguiente:



3. Establezca como Ayuda la propiedad Caption del botón de comando.

4. En el evento Click del botón de comando, agregue el comando siguiente:


Sugerencia Guarde el botón de Ayuda como una clase de manera que pueda agregarlo fácilmente a cualquier formulario. En el Diseñador de formularios, elija Guardar como en el menú Archivo. Para obtener más información sobre cómo guardar objetos como clases, consulte el capítulo 9, Crear formularios..

Controlar la ubicación de la ventana de Ayuda

Para especificar una ubicación para la Ayuda, debe crear su propia ventana mediante el comando DEFINE WINDOW. Utilice este comando en el código de inicialización para especificar el tamaño y la ubicación de la ventana. A continuación, muestre la ventana activándola o mostrándola.

Por ejemplo, los comandos siguientes definen una ventana llamada prueba y muestran la tabla de Ayuda actual dentro de esa ventana:

DEFINE WINDOW prueba FROM 1,1 TO 35,60 SYSTEM ACTIVATE WINDOW prueba HELP IN WINDOW prueba

Adaptar la Ayuda a su aplicación



Puesto que es posible agregar cualquier número de campos a una tabla de Ayuda, y que puede emplearse cualquier expresión lógica para seleccionar temas de Ayuda, la imaginación es el único límite para el sistema de Ayuda que puede crear.

Por ejemplo, puede:

l Definir una o muchas variables de programa que controlan el comportamiento del sistema de Ayuda y, a continuación, asignar valores a estas variables de acuerdo con el modo operativo del programa.

l Proporcionar más detalles en los archivos de Ayuda para los usuarios sin experiencia que para los usuarios experimentados.

l Permitir que los usuarios tengan acceso a la Ayuda sólo si introducen una contraseña determinada.

Manual del programador, Parte 7: Crear archivos de … · 2002-02-11 · Además de dicho comando,...

Documents

Transcript of Manual del programador, Parte 7: Crear archivos de … · 2002-02-11 · Además de dicho comando,...