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

Entrega número Cuatro

Publicado el 29/Dic/98
Actualizado el 17/Jul/2003
Autor: Guillermo 'guille' Som

En esta cuarta entrega vamos a ver una clase para manejar las funciones más habituales del control hhctrl.ocx, de esta forma "encapsularemos" la funcionalidad de ese control para que sea más fácil de usar. Simplemente se creará una referencia a la clase/objeto y usaremos las funciones/métodos que ésta tiene. También sería fácil crear un control basado en esta clase, el cual se añadiría al formulario y usarlo como cualquier otro control, pero esto último te lo dejo a ti, aunque lo mismo lo hago y lo pongo disponible... todo se andará.

Además de la clase para manejar las ayudas HTML, (cHtmlHelp.cls), veremos cómo mostrar mensajes emergentes al pulsar F1 en un campo de nuestro formulario, incluso pondremos en marcha la "famosa" interrogación What's This?, aunque esto sólo será posible en el Visual Basic 6, ya que el VB5 no lo permite con este tipo de ayudas...

El proyecto será parecido al visto en la tercera entrega, pero con algunos cambios, tanto en el fichero de ayuda como en el programa que muestra esa ayuda.

Tengo que indicar que el HHW que he usado es la versión 1.2 (4.72.8145), - la versión del HHCTRL es la 1.2 (4.72.8164) -, que aún sigue siendo beta y tiene algunos fallillos, pero que pone a nuestro alcance algunas nuevas características... ya las iremos viendo, aunque tendrás que deducirlas tu mismo, ya que no tengo la versión anterior y no se exactamente cuales pueden ser... lo siento.

Empecemos viendo el formulario para las pruebas en VB5 y cómo usar la clase, después veremos las modificaciones para VB6 y el código de la clase, también veremos cómo construir el fichero de ayuda, aunque, como ya te he dicho, es muy parecido al hhw_vb que vimos en la entrega anterior.

 

El código del programa de ejemplo para VB5:

Este es el aspecto y el código del formulario (frmHhw5.frm)

'------------------------------------------------------------------
'Form de prueba para HTML Help Workshop                 (28/Jun/98)
'
'Nueva revisión usando cHtmlHelp                        (25/Dic/98)
'Revisado para que se pueda usar con VB5                (26/Dic/98)
'
'©Guillermo 'guille' Som, 1998
'------------------------------------------------------------------
Option Explicit

Private m_HtmlHelp As cHtmlHelp 'Clase para mostrar la ayuda HTML

Const MAX_CAMPOS = 2


Private Sub Form_KeyUp(KeyCode As Integer, Shift As Integer)
    If KeyCode = vbKeyF1 Then
        'Mostrar la ayuda del control activo
        'El control debe tener hWnd y tener asignada la propiedad HelpContextID
        'Call m_HtmlHelp.HelpContext(Me.ActiveControl, "Message")
        'También funciona así:
        'ya que la función comprueba el control activo
        Call m_HtmlHelp.HelpContext(laVentana:="Message")
    ElseIf KeyCode = vbKeyF2 Then
        'Muestra el mensaje de ayuda en una ventana emergente
        m_HtmlHelp.HelpContextPop
    End If
End Sub

Private Sub Form_Load()
    Dim sHelpFile As String
    
    'asignar el nombre del fichero de ayuda
    sHelpFile = "hhw_vb.chm"
    sHelpFile = sHelpFile & "::/hhw_vb.txt"
    
    'Para VB5, no especificar el fichero de ayuda,
    'de esta forma se podrá usar F1 sin problemas...
    App.HelpFile = ""
    
    'Crear una referencia al objeto para mostrar la ayuda
    Set m_HtmlHelp = New cHtmlHelp
    
    'Asignar las propiedades del objeto
    With m_HtmlHelp
        .hWnd = Me.hWnd
        .HelpFile = sHelpFile
    End With
    
    'Limpiar las cajas de texto
    mnuLimpiar_Click

    'Para probar:
    Tag = "Prueba de POP-UP en HTML Work Shop, " & _
          "este texto está en el TAG del formulario."

End Sub

Private Sub Form_MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)
    If Button = 2 Then
        'Para mostrar una ventana PopUp con el mensaje indicado en el parámetro
        'Call m_HtmlHelp.PopUp("Prueba de POP-UP en HTML Work Shop")
        '
        'Esto mismo se podría hacer para mostrar la ayuda al pulsar F2,
        'si el texto a mostrar que se pasa como parámetro es el que queremos
        'que se muestre para cada control.
        'Por ejemplo se podría usar la propiedad Tag de un control para hacerlo:
        m_HtmlHelp.PopUp Me.Tag
    End If
End Sub

Private Sub Form_Unload(Cancel As Integer)
    Set m_HtmlHelp = Nothing
End Sub

Private Sub mnuAcerca_Click()
    frmAbout.Show vbModal
End Sub

Private Sub mnuAyuda_Click()
    'De esta forma se muestra en el tópico por defecto
    Call m_HtmlHelp.DisplayTopic
End Sub

Private Sub mnuDisplayTopic_Click()
    'Llamar a la página o el marcador que se quiera mostrar
    Call m_HtmlHelp.DisplayTopic("hhw_vb.htm#Nombre_de_usuario")
End Sub

Private Sub mnuIndex_Click()
    'Muestra la solapa índice con el texto indicado
    Call m_HtmlHelp.DisplayIndex("Acerca de...")
End Sub

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

Private Sub mnuSalir_Click()
    Unload Me
    End
End Sub

Private Sub mnuSearch_Click()
    'Mostrar la solapa de Búsqueda (Search)
    Call m_HtmlHelp.DisplaySearch
End Sub

Private Sub mnuToc_Click()
    'Mostrar la solapa de Contenidos (Contents)
    m_HtmlHelp.DisplayTOC
End Sub

Private Sub mnuDisplayContext_Click()
    'Así se llamaría para mostrar un tópico de la ayuda
    'Para poder usar esta llamada, en el proyecto HHP debe existir una sección
    '[ALIAS] con los valores nombres de las constantes definidas en el fichero
    'indicado en la sección [MAP] y el link a la página HTML
    '   Ver el fichero: hhw_lee.txt para el ejemplo
    '
    'En este caso se llamará a: Nombre_de_usuario (1000&)
    Call m_HtmlHelp.DisplayContext(1000&)
End Sub

Private Sub picIcon_Click()
    picIcon.BorderStyle = 1
    mnuAcerca_Click
    picIcon.BorderStyle = 0
End Sub

Como podrás observar, es fácil de usar esta clase, además como todo el código está "encapsulado" en la propia clase, no tendrás ningún problema en cambiar el código de dicha clase, siempre que se mantenga el mismo formato de las funciones actuales, pero que puedes cambiar internamente, según sea necesario... esto que te cuento es la "base" de cualquier clase que se cree con Visual Basic, pero para que lo sepas...

Para que este ejemplo funcione, hay que asignar a True la propiedad KeyPreview del formulario, de esta forma, al pulsar F1 se mostrará la ayuda de contexto, indicada en la propiedad HelpContextID, a esta propiedad hay que asignarle un valor numérico que estará también asignado (o mapeado) dentro del fichero de ayuda, (esto ya lo vimos en la entrega anterior y seguramente lo volveremos a ver en esta). Esta funcionalidad de F1, está hecha por código, no porque el VB lo haga, ya que en el caso de la versión 5 (y anteriores), el sistema de ayuda "reconocido" es en formato HLP y no en el nuevo HTML, por eso en el evento Form_Load sea ha "borrado" la propiedad HelpFile del objeto App, que es donde "normalmente" se indica que fichero de ayuda usará nuestra aplicación, (ver los comentarios del listado).
Bueno, a lo que iba, la funcionalidad de mostrar la ayuda contextual está implementada en el evento KeyUp del form, si te fijas en el código, no sólo se detecta la pulsación de F1, sino también la de F2; ésta última es para mostrar la ayuda emergente, al estilo de What's This? (¿Qué es esto?)
Al pulsar F1, se llama a la función HelpContext de la clase cHtmlHelp.cls, que es la que muestra la ayuda contextual, o relacionada con el control que tiene actualmente el foco. En esta función se detecta el control activo y se saca de él el valor de la propiedad HelpContextID, por tanto esa propiedad debería estar asignada, como es lógico, si nuestra intención es hacer que se muestre la ayuda... Además de detectar el control activo se le puede indicar que control queremos que tenga en cuenta, para ello habría que pasar una referencia a dicho control. También se puede indicar el nombre de la ventana en la que queremos que se muestre, (esta ventana estará creada en el propio fichero de ayuda).
En el caso de pulsar F2, se mostrará un mensaje emergente con el texto "predefinido" dentro del fichero de ayuda; ese texto se indicará, como veremos, en un fichero de texto especial... Para mostrar el mensaje se usará la función HelpContextPop, esta función espera (opcionalmente) el control al que se hace referencia, si no se indica, se usará el que esté activo en el momento de pulsar F2.

Te recuerdo que estas funciones son propias de la clase y no del control OCX que maneja la ayuda HTML.

Si te fijas en el código del evento MouseDown del formulario, verás que se pueden mostrar cualquier tipo de mensaje emergente, en este caso definido dentro del propio programa, por tanto si no quieres complicarte la vida creando ficheros especiales para tu sistema de ayuda, podrías indicar "manualmente" el mensaje emergente a mostrar si ese texto lo incluyes, por ejemplo, en la propiedad Tag del control y lo muestras de esta forma:

Call m_HtmlHelp.PopUp(ActiveControl.Tag)

Con la función PopUp de la clase, se muestra el texto indicado en el parámetro de la función. Pero esto te lo dejo a tu elección. Aunque en ocasiones puede resultar más "práctico" hacerlo de esta forma que tener que crear esa información en el fichero de ayuda.

Nota: Las funciones en VB se pueden usar igual que los SUBs, sólo que sin usar los paréntesis. Por ejemplo estas tres formas son equivalentes: Call m_HtmlHelp.PopUp(ActiveControl.Tag) m_HtmlHelp.PopUp ActiveControl.Tag ret = m_HtmlHelp.PopUp(ActiveControl.Tag) En el caso de las funciones de las que no necesitamos usar el valor devuelto, es preferible usar CALL, de esta forma, se sabe que es una función de la que no queremos ese valor devuelto, aunque esto último es sólo una convención, la cual puedes seguir si te place... como casi todas las recomendaciones...

 

 

El código del programa de ejemplo para Visual Basic 6:

Del programa para VB6, sólo vamos a ver parte del listado, ya que el resto es casi como el de VB5, con la salvedad de que no es necesario usar la detección de las teclas de ayuda en el evento KeyUp del formulario, ya que esta versión del VB si sabe lo que hacer con los ficheros nuevos de ayuda...
Por tanto, se puede usar la "?" de la parte superior del formulario. El único inconveniente es que no se puede usar la ayuda contextual, es decir que al pulsar F1 en un control se muestre la ayuda normal, en las pruebas que he hecho, sólo se muestra la ayuda emergente... si queremos usar ayuda contextual, hay que quitar la "?" del formulario.
Hablando de formulario, este es el aspecto de la versión para VB6, como verás es "casi" igual que el de su hermano pequeño:

Como verás, la diferencia es que este formulario tiene la "?", para conseguirlo tienes que asignar el valor True a las propiedades WhatsThisButton y WhatsThisHelp.
Si quieres mostrar la ayuda emergente, pero sin que se muestre la interrogación, asigna False a la propiedad WhatsThisButton.
Si lo que quieres es que se muestre la ayuda contextual, sin la interrogación ni mensajes "flotantes", asigna el valor False a las dos propiedades.

En el caso de que se quiera mostrar la ayuda emergente, hay que indicar en el nombre del fichero de ayuda que se asigna a App.HelpFile el nombre del fichero de texto que tiene las definiciones de los "tópicos", esto suele estar en un fichero de texto compilado en el propio fichero de ayuda y se indica de la siguiente forma:

'En este ejemplo se tiene en cuenta si están asignadas
'las propiedades que hacen que se muestren los mensajes emergentes

    'asignar el nombre del fichero de ayuda
    sHelpFile = "hhw_vb.chm"
    If WhatsThisButton Or WhatsThisHelp Then
        sHelpFile = sHelpFile & "::/hhw_vb.txt"
    'Else
        'Con esto siempre se mostraría en la ventana indicada
        'sHelpFile = sHelpFile & ">Message"
    End If
    App.HelpFile = sHelpFile

Si quieres tener un botón o, como en este caso, una opción de un menú que te muestre el cursor de What's This?, puedes indicárselo al Visual Basic de esta forma:

Private Sub mnuWhatsThisHelp_Click()
    Dim sHelpFileAnt As String
    
    'guardar el fichero anterior:
    sHelpFileAnt = App.HelpFile
    'asignar el nombre del fichero de ayuda
    App.HelpFile = cHelpFile & "::/hhw_vb.txt"
    
    WhatsThisMode
    
    'Restaurar el valor normal
    App.HelpFile = sHelpFileAnt
End Sub

Es decir, usando el método WhatsThisMode del formulario, en cuanto se entra en este modo se muestra un cursor con una flecha y una interrogación y al hacer click en un control, se muestra el mensaje emergente que esté asociado, si lo hay, en caso de que no haya, nos lo indicaría con un aviso de que no hay ayuda asociada a ese control.

 

El código de la clase cHtmlHelp.cls:

Para terminar el código, vamos a ver la clase que encapsula el funcionamiento del control hhctrl.ocx, no daré explicaciones extras, ya que está comentada y será de fácil entendimiento, aunque no es necesario que entiendas como funciona, sino cómo usarla, que es lo importante. Al principio del código están las funciones que tiene esta clase y en cada una de ellas, los parámetros que soporta. Espero que te parezca interesante y si quieres hacer algún comentario, ya sabes...

'
'----------------------------------------------------------------------------------
'cHtmlHelp.cls Clase para manejar ficheros de ayuda HTML                (25/Dic/98)
'Estos ficheros de ayuda (compilados) tienen extensión CHM
'
'©Guillermo 'guille' Som, 1998 <[email protected]>
'
'Para poder usar esta clase hay que tener el control hhc.ocx registrado,
'este control viene con el Html Help Workshop y con el Windows 98
'Además hay que tener el Internet Explorer 4 ya que usa la Shdocvw.dll
'
'Métodos y Propiedades de esta clase:
'   Nombre          Descripción
'   -----------     ---------------------------------------------------------------
'   hWnd            El hWnd del Form
'   HelpFile        Nombre del fichero de ayuda (extensión .chm)
'                       Si hay un fichero con tópicos, indicarlo así:
'                       HelpFile = "ayuda.chm::/topicos.ext"
'   DisplayContext  Muestra el HelpContextID especificado en el parámetro
'   DisplayIndex    Muestra la solapa del índice (Index)
'   DisplaySearch   Muestra la solapa de búsqueda (Search)
'   DisplayTOC      Muestra la solapa de contenidos (Contents)
'   DisplayTopic    Muestra el tópico indicado, pasado como cadena
'   HelpContext     Muestra el tópico del control indicado
'   HelpContextPop  Para usar con VB5,
'                       muestra la ayuda asociada con el control indicado
'   PopUp           Muestra el mensaje indicado en una ventana PopUp
'----------------------------------------------------------------------------------
Option Explicit

'Asignar el valor -1 a la constante ES_DEBUG
'para mostrar los valores devueltos por la función HtmlHelp
#Const ES_DEBUG = 0

'Para usar con VB5 los mensajes emergentes
'-----------------------------------------
'Tomado del tutorial de HTML Help de http://www.vbexplorer.com/
Private Type HH_IDPAIR
    dwControlId As Long
    dwTopicId As Long
End Type

'This array should contain the number of controls that have
'context-sensitive help, plus one more for a zero-terminating
'pair.
Private ids(0 To 1) As HH_IDPAIR

Private Declare Function GetDlgCtrlID Lib "user32" (ByVal hWnd As Long) As Long
'-----------------------------------------

'Propiedades públicas
Public hWnd As Long         'El hWnd del form que llama a la ayuda
Public HelpFile As String   'El fichero de ayuda con extensión chm

'----------------------------------------------------------------------------------
'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        ' Muestra la tabla de contenidos
    HH_DISPLAY_INDEX = &H2      ' Muestra la solapa Index
    HH_DISPLAY_SEARCH = &H3     ' Muestra la solapa de búsqueda (Search)
    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_CONTEXTMENU = &H10
    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

Private Type RECT
    Left    As Long
    Top     As Long
    Right   As Long
    Bottom  As Long
End Type

Private Type POINTAPI
    X   As Long
    Y   As Long
End Type
    
'
'Estructura para usar con el comando HH_DISPLAY_TEXT_POPUP
'Sacada de la página HTML Help API Reference del site de MS.
'
'typedef struct tagHH_POPUP         Member         Description
'{                                  ------            -----------
'    int       cbStruct;            cbStruct       Specifies the size of the structure. This value must always be filled in before passing the structure to the HtmlHelp API.
'    HINSTANCE hinst;               hinst          Instance handle of the program or .dll file to retrieve the string resource from. Ignored if idString is zero, or a filename was passed to the HtmlHelp API.
'    UINT      idString;            idString       Specifies either a resource ID or a topic number in a text file.
'    LPCTSTR   pszText;             pszText        Specifies the text to display if idString is zero.
'    POINT     pt;                  pt             Specifies where the top center of the pop-up should be located.
'    COLORREF  clrForeground;       clrForeground  Specifies the RGB value to use for the foreground color. If this value is -1, the system color for window text will be used.
'    COLORREF  clrBackground;       clrBackground  Specifies the RGB value to use for the background color. If this value is -1, the system color for window background will be used.
'    RECT      rcMargins;           rcMargins      Specifies the margins to use on the left, top, right, and bottom sides of the pop-up. The default for all rectangle members is -1.
'    LPCTSTR   pszFont;             pszFont        Specifies an optional text string containing: facename[,point size[,charset[,color[, BOLD ITALIC UNDERLINE]]]]. This string specifies a font, its point size, its character set, its color, and various attributes. Options can be omitted by simply specifying the next comma. For example, to create a bold, 10-pt MS Sans Serif font, the parameter value would be: MS Sans Serif, 10, , , BOLD
'} HH_POPUP;
'
Private Type tagHH_POPUP
    cbStruct        As Long     '=Len(HH_POPUP) Longitud de la estructura
    hinst           As Long     '
    idString        As Long     '
    pszText         As String   'Texto a mostrar
    pt              As POINTAPI 'Posición de la ventana popup, en pixels
    clrForeground   As Long     'Color de la letra, -1 es el valor por defecto
    clrBackground   As Long     'Color de fondo, -1 es el valor por defecto
    rcMargins       As RECT     'Tamaño de la ventana, -1 son los valores por defecto
    pszFont         As String   'Tipo de letra a usar: "Arial,9"
                                'facename[,point size[,charset[,color[, BOLD ITALIC UNDERLINE]]]].
End Type

'
'Estructura para mostrar la solapa Search y un texto a buscar
'sacada del fichero de ayuda api.chm de MS.
'
'typedef struct tagHH_FTS_QUERY     Member             Description
'{                                  ------              -----------
'     int      cbStruct;            cbStruct           Specifies the size of the structure.
'     BOOL     fUniCodeStrings;     fUniCodeStrings    TRUE if all strings are Unicode.
'     LPCTSTR  pszSearchQuery;      pszSearchQuery     String containing the search query.
'     LONG     iProximity;          iProximity         Word proximity.
'     BOOL     fStemmedSearch;      fStemmedSearch     TRUE for StemmedSearch only.
'     BOOL     fTitleOnly;          fTitleOnly         TRUE for Title search only.
'     BOOL     fExecute;            fExecute           TRUE to initiate the search.
'     LPCTSTR  pszWindow;           pszWindow          Window to display in.
'} HH_FTS_QUERY;
'
Private Type tagHH_FTS_QUERY
    cbStruct        As Long     '=Len(HH_FTS_QUERY) Longitud de la estructura.
    fUniCodeStrings As Long     'TRUE if all strings are Unicode.
    pszSearchQuery  As String   'String containing the search query.
    iProximity      As Long     'Word proximity.
    fStemmedSearch  As Long     'TRUE for StemmedSearch only.
    fTitleOnly      As Long     'TRUE for Title search only.
    fExecute        As Long     'TRUE to initiate the search.
    pszWindow       As String   'Window to display in.
End Type

'
'HtmlHelp api call
'Con esta funciona perfectamente, los LONGs
'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

'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


Public Function DisplayContext(Optional ByVal TopicNum As Long = 0&) As Long
    'Mostrar el tópico de ayuda,
    'si no se indica se mostrará el tópico por defecto
    '
    Dim sHelpFile As String
    
    sHelpFile = SoloCHM
    DisplayContext = HtmlHelp(hWnd, sHelpFile, HH_HELP_CONTEXT, ByVal TopicNum)
    
    #If ES_DEBUG Then
        Debug.Print "DisplayContext= " & DisplayContext
    #End If
End Function

Public Function DisplayTopic(Optional ByVal TopicName As String = "") As Long
    'Mostrar el tópico de ayuda,
    'si no se indica el valor de TopicName, se mostrará el tópico por defecto.
    'TopicName deberá usarse como suele hacerse con los links normales:
    '   nombrePágina.htm#NombreMarcador o nombrePagina.htm
    '
    Dim sHelpFile As String
        
    sHelpFile = SoloCHM
    If Len(TopicName) = 0 Then
        DisplayTopic = HtmlHelp(hWnd, sHelpFile, HH_DISPLAY_TOPIC, ByVal 0&)
    Else
        DisplayTopic = HtmlHelp(hWnd, sHelpFile, HH_DISPLAY_TOPIC, ByVal TopicName)
    End If
    
    #If ES_DEBUG Then
        Debug.Print "DisplayTopic= " & DisplayTopic
    #End If
End Function

Public Function PopUp(ByVal Text As String) As Long
    'Para mostrar una ventana PopUp con el texto indicado
    Dim HH_POPUP As tagHH_POPUP
    Dim elForm As Form
    
    On Local Error Resume Next
    
    'Asignar el form activo
    Set elForm = Screen.ActiveForm
    
    With HH_POPUP
        .cbStruct = Len(HH_POPUP)
        .clrBackground = -1
        .clrForeground = -1
        .pszFont = "Verdana,8"
        .pszText = Text
        'posicionar la ventana de PopUp
        .pt.X = (elForm.Left + 360) \ Screen.TwipsPerPixelX
        .pt.Y = (elForm.Top + (elForm.Height \ 2) + 240) \ Screen.TwipsPerPixelY
        .rcMargins.Bottom = -1
        .rcMargins.Left = -1
        .rcMargins.Right = -1
        .rcMargins.Top = -1
    End With
    PopUp = HtmlHelp(hWnd, HelpFile, HH_DISPLAY_TEXT_POPUP, HH_POPUP)
    
    #If ES_DEBUG Then
        Debug.Print "PopUp= " & PopUp
    #End If
    
    Err = 0
End Function

Public Function DisplaySearch() As Long
'                              Optional ByVal sBuscar As String = ""
'                              Optional ByVal laVentana As String = "") As Long
    'Muestra la solapa Search (Búsqueda)
    '
    Dim sHelpFile As String
    Dim HH_FTS_QUERY As tagHH_FTS_QUERY
    
    With HH_FTS_QUERY
        .cbStruct = Len(HH_FTS_QUERY)
        .fStemmedSearch = 0&
        .fTitleOnly = 0&
        .fUniCodeStrings = 0&
        .iProximity = 0&
        .pszSearchQuery = "" 'sBuscar   'sólo se mostrará si no se ha efectuado ninguna búsqueda
        .pszWindow = ""             'laVentana 'esto no tiene efecto
        .fExecute = 1&              'esto parece que no tiene efecto en VB
    End With
    
    sHelpFile = SoloCHM
    DisplaySearch = HtmlHelp(hWnd, sHelpFile, HH_DISPLAY_SEARCH, HH_FTS_QUERY)
    
    #If ES_DEBUG Then
        Debug.Print "DisplaySearch= " & DisplaySearch
    #End If
End Function

Public Function DisplayTOC() As Long
    'Muestra la tabla de contenidos (TOC)
    Dim sHelpFile As String
    
    sHelpFile = SoloCHM
    DisplayTOC = HtmlHelp(hWnd, sHelpFile, HH_DISPLAY_TOC, ByVal 0&)
    
    #If ES_DEBUG Then
        Debug.Print "DiplayToc= " & DisplayTOC
    #End If
End Function

Public Function DisplayIndex(Optional ByVal sKeyWord As String = "") As Long
    'Muestra la solapa Index,
    'si se especifica una palabra clave, se mostrará esa clave          (27/Dic/98)
    Dim sHelpFile As String
    
    sHelpFile = SoloCHM
    If Len(sKeyWord) = 0 Then
        DisplayIndex = HtmlHelp(hWnd, sHelpFile, HH_DISPLAY_INDEX, ByVal 0&)
    Else
        DisplayIndex = HtmlHelp(hWnd, sHelpFile, HH_DISPLAY_INDEX, ByVal sKeyWord)
    End If
    
    #If ES_DEBUG Then
        Debug.Print "DisplayIndex= " & DisplayIndex
    #End If
End Function

Private Function SoloCHM() As String
    'Devuelve sólo el fichero base de la ayuda
    
    'Hay que quitarle el ::/xxx que tenga
    Dim i As Long
    Dim sHelpFile As String
    
    sHelpFile = HelpFile
    i = InStr(sHelpFile, "::/")
    If i Then
        sHelpFile = Trim$(Left$(sHelpFile, i - 1))
    End If
    SoloCHM = sHelpFile
End Function

Public Function HelpContextPop(Optional ByVal elControl As Control) As Long
    'Se pasará el control en el que se ha pulsado F1
    'Deberá tener asignado el valor del HelpContextID
    'Esta función es para usar con VB5 o con un formulario en el que no se
    'ha especificado el WhatThisHelp...
    Dim vControl As Control
    
    On Local Error Resume Next
    
    If elControl Is Nothing Then
        Set vControl = Screen.ActiveControl
    Else
        Set vControl = elControl
    End If
    
    ids(0).dwTopicId = CLng(vControl.HelpContextID)
    ids(0).dwControlId = GetDlgCtrlID(vControl.hWnd)
    ' The last pair in the array must contain zeros (0)
    ids(1).dwControlId = 0
    ids(1).dwTopicId = 0
    
    If Err = 0 Then
        HelpContextPop = HtmlHelp(vControl.hWnd, HelpFile, HH_TP_HELP_WM_HELP, ids(0))
    End If
    
    Err = 0
End Function

Public Function HelpContext(Optional ByVal elControl As Control, _
                            Optional ByVal laVentana As String = "") As Long
    'elControl  será el control en el que se ha pulsado F1
    '           si no se especifica, se tomará el control activo.
    '           Ese control deberá tener asignado el valor del HelpContextID
    'laVentana  será la ventana que se usará para mostrar la ayuda
    '
    Dim vControl As Control
    Dim TopicNum As Long
    Dim sHelpFile As String
    
    On Local Error Resume Next
    
    If elControl Is Nothing Then
        Set vControl = Screen.ActiveControl
    Else
        Set vControl = elControl
    End If
    
    TopicNum = CLng(vControl.HelpContextID)
    
    If Err = 0 Then
        sHelpFile = SoloCHM
        If Len(laVentana) Then
            sHelpFile = sHelpFile & " >" & laVentana
        End If
        HelpContext = HtmlHelp(hWnd, sHelpFile, HH_HELP_CONTEXT, ByVal TopicNum)
    End If
    
    Err = 0
End Function

En vista de que se ha alargado un poco esta página, dejaremos para otra ocasión cómo crear el fichero de ayuda para usar estas nuevas cosillas...
Aunque puedes echarle un vistazo al código del proyecto HHP y averiguarlo por ti mismo.

Recuerda que si quieres usar la nueva versión 1.2 del HHW deberás bajartelo del sitio de Microsoft, el link está en el índice de este "tutorial"
Te recomiendo que te bajes la información que hay en ese "web" ya que, a pesar de estar en inglés, te puede ser de utilidad:
http://msdn.microsoft.com/workshop/author/htmlhelp
(link actualizado el 17/Jul/03, gracias a Carlos Vázquez)
 

Si quieres enviarme algún comentario sobre este artículo, usa este link y, por favor, no lo uses para hacer consultas, gracias.

Nos vemos.
Guillermo

Los ficheros de la entrega 4, (incluye los proyectos para VB5 y 6, además del proyecto para crear la ayuda) (hhw4.zip 68.7 KB)