HTML Help Workshop Utilidad para crear un sistema de ayuda basado en páginas HTML

Entrega número Tres

Publicado el 30/Jun/98
Autor: Guillermo 'guille' Som

El tema de esta entrega consiste en preparar un archivo de ayuda para usar desde Visual Basic.

Para ello vamos a crear un nuevo proyecto con la información necesaria para llamarlo desde VB, veremos cómo hacerlo paso a paso, así que preparados, listos... ¡YA!

Un ejemplo de ayuda para usar con Visual Basic

Crea un nuevo proyecto que se llame: hhw_vb Añade la página hhw_vb.htm al proyecto, se supone que ya sabrás cómo hacerlo, porque lo hemos hecho anteriormente, pero si tienes dudas, repasate de nuevo la primera entrega. Para este ejemplo no es necesario usar libros ni hojas, pero si quieres puedes añadir lo que quieras. La página htm tiene los siguientes marcadores: Acerca_de Nombre_de_usuario Cuenta_de_email Arriba Asunto Enviar Limpiar_campos Salir Los que tendremos que asociar con un Alias para poder usarlo desde VB, ya que en VB no se puede especificar otra cosa que números. Pulsa en el cuarto botón de la barra de herramientas el que muestra el ToolTip: HmlHelp API information Pulsa en la solapa Alias. Pulsa en el botón Add..., te mostrará un cuadro de diálogo indicándote que cuando se encuentre una constante o un número que es lo que debe hacer. En la primera casilla escribe 1000, (después te explicaré de dónde saco estos números) En la siguiente casilla, escribe: hhw_vb.htm#Nombre_de_usuario Pulsa en OK Sigue añadiendo para indicarle todos los alias que la aplicación de ejemplo usará. Ya sabes, usando el formato: hhw_vb.htm#Acerca_de, los nombres de los marcadores están un poco más arriba, aquí te indico los valores que tiene asociado cada uno de ellos: 1120 1000 1010 1110 1020 1030 1100 1140 Para crear la asociación de los valores a usar con el ContextID, en el fichero de ayuda hay que usar un fichero "include" al estilo C, es decir una definición de las constantes que se van a usar. Por ejemplo: #define Nombre_de_usuario 1000 #define Cuenta_de_email 1010 #define Asunto 1020 #define Enviar 1030 #define Limpiar_campos 1100 #define Arriba 1110 #define Acerca_de 1120 #define Salir 1140 Por tanto crea un fichero llamado hhw_vb.h Pulsa en el botón "HmlHelp API information" y en la primera solapa MAP, pulsa en el botón Header file... Selecciona el fichero con las definiciones y pulsa OK Ahora compila la ayuda y pasaremos a crear la aplicación de ejemplo.

La aplicación de ejemplo

 

El truco consiste en asociar un valor a la propiedad HelpContextID y WhatThisHelpID de cada control con el valor que hemos escrito en los ALIAS del fichero de ayuda. Por ejemplo: pulsa en la primera caja de texto y escribe 1000 en esa propiedad, haz lo mismo con el resto de las cajas de texto, botón enviar y la imagen con el icono (estos valores ya están puestos en el form que puedes bajar con el código necesario) Para que la aplicación pueda usar la ayuda, además de asignar el valor TRUE a la propiedad WhatThisHelp del form, puedes hacer que aparezca la interrogación en la ventana, si asignas el valor True a la propiedad WhatThisButton del formulario de ejemplo, aunque esto último es opcional.   Después de un montón de pruebas, esto no funciona como yo esperaba... así que lo dejaremos "reposar" y a ver si consigo más información sobre el tema este. Bueno, funcionar, funciona, pero no como esperaba... Para que la ayuda se pueda mostrar, tendrás crear una tabla de contenidos, ya que al llamar a la ayuda, me da un error de que no puede abrir la página de ayuda... Pero si tiene la tabla de contenidos, al menos te permite navegar usando los links que hayas creados en las hojas y libros...   Ya empieza a funcionar. El problema era la declaración que tenía para llamar a la ayuda. O mejor dicho la forma en que usaba la función para mostrar la ayuda. En el ejemplo que adjunto ya está solucionado, además he dejado la otra declaración y la explicación de cómo usarla, por si te ocurre en otra ocasión. Lo único que no he podido poner en práctica es que funcione con la ayuda "sensible al contexto", es decir pulsando F1 en uno de los campos. Y tampoco he logrado que la interrogación funcione como se espera (y de hecho funciona con ficheros HLP normales) En mi caso, ¡me ha mostrado la ayuda de otra aplicación!

El código del formulario

Vamos a ver el código usado en el formulario

'------------------------------------------------------------------
'Form de prueba para HTML Help Workshop                 (28/Jun/98)
'
'©Guillermo 'guille' Som, 1998
'------------------------------------------------------------------
Option Explicit

Const MAX_CAMPOS = 2

'En Microsoft TechNet puedes encontrar este artículo:
'HOWTO: Use HTML Help API in a Visual Basic 5.0 Application
'PSS ID Number: Q183434
'
'Aunque la definición de la Enumeración y la primera declaración
'es de las news
'
'Htmlhelp consts
Private Enum HH_COMMAND
    HH_DISPLAY_TOPIC = &H0
    HH_HELP_FINDER = &H0        ' WinHelp equivalent
    HH_DISPLAY_TOC = &H1        ' not currently implemented
    HH_DISPLAY_INDEX = &H2      ' not currently implemented
    HH_DISPLAY_SEARCH = &H3     ' not currently implemented
    HH_SET_WIN_TYPE = &H4
    HH_GET_WIN_TYPE = &H5
    HH_GET_WIN_HANDLE = &H6
    HH_GET_INFO_TYPES = &H7     ' not currently implemented
    HH_SET_INFO_TYPES = &H8     ' not currently implemented
    HH_SYNC = &H9
    HH_ADD_NAV_UI = &HA         ' not currently implemented
    HH_ADD_BUTTON = &HB         ' not currently implemented
    HH_GETBROWSER_APP = &HC     ' not currently implemented
    HH_KEYWORD_LOOKUP = &HD
    HH_DISPLAY_TEXT_POPUP = &HE ' display string resource id
                                ' or text in a popup window
    HH_HELP_CONTEXT = &HF       ' display mapped numeric value
                                ' in dwData
    HH_TP_HELP_CONTEXTMENU      ' Text pop-up help, similar to
                                ' WinHelp's HELP_CONTEXTMENU.
    HH_TP_HELP_WM_HELP = &H11   ' text pop-up help, similar to
                                ' WinHelp's HELP_WM_HELP.
    HH_CLOSE_ALL = &H12         ' close all windows opened directly
                                ' or indirectly by the caller
    HH_ALINK_LOOKUP = &H13      ' ALink version of HH_KEYWORD_LOOKUP
End Enum

'HtmlHelp api call
'NOTA: Si se usa esta forma, hay que indicar el último parámetro
'      con la palabra ByVal delante...
'Private Declare Function HtmlHelp Lib "hhctrl.ocx" Alias "HtmlHelpA" _
    (ByVal hwndCaller As Long, ByVal pszFile As String, _
    ByVal uCommand As HH_COMMAND, dwData As Any) As Long
'Con esta funciona perfectamente
Private Declare Function HtmlHelp Lib "hhctrl.ocx" Alias "HtmlHelpA" _
    (ByVal hwndCaller As Long, ByVal pszFile As String, _
    ByVal uCommand As HH_COMMAND, ByVal dwData As Long) As Long


Private Sub Form_Load()
    'Limpiar las cajas de texto
    mnuLimpiar_Click
End Sub

Private Sub mnuAcerca_Click()
    'Así se llamaría para mostrar un tópico de la ayuda
    Dim h As Long
    h = HtmlHelp(Me.hWnd, "hhw_vb.chm", HH_HELP_CONTEXT, 1120&)
    frmAbout.Show vbModal
End Sub

Private Sub mnuAyuda_Click()
    'De esta forma se muestra en el tópico por defecto
    Dim h As Long
    h = HtmlHelp(Me.hWnd, "hhw_vb.chm", HH_DISPLAY_TOPIC, 0&)
End Sub

Private Sub mnuLimpiar_Click()
    Dim i As Integer
    
    For i = 0 To MAX_CAMPOS
        Text1(i) = ""
    Next
End Sub

Private Sub picIcon_DblClick()
    mnuAcerca_Click
End Sub

Ejecuta el programa, necesitarás también el form de Acerca de (frmAbout).
En el zip que acompaña a este artículo, incluyo el proyecto completo, además de los ficheros para crear la ayuda.

Espero que todo esto te haya servido de algo...
En cuanto tenga más información la pondré.

Nos vemos.
Guillermo

Los ficheros de la entrega 3, (incluye el proyecto VB y la ayuda para probar con VB) (hhw3.zip 15.1 KB)