Introducción

HTMLHelp es el nuevo estándar para sistemas de ayuda basados en Windows. Se está convirtiendo rápidamente en un sistema popular y está disponible para cualquier usuario con Internet Explorer 4.01, Windows 98 o superiores. Sin embargo existe muy poca información útil incluso en el CD de MSDN para usarlo con Visual Basic. Hay alguna información en Microsoft, y si un desarrollador es persistente y experimenta bastante, puede que encuentre algunos métodos que funcionen.. Hay varios bugs conocidos al intentar llamadas desde C++ en donde el código simplemente no es reconocido como váliso

Qué es HTML Help?

La diferencia principal entre HTML Help y WinHelp es que HTML Help muestra los tópicos y contenidos al mismo tiempo. HTML Help también ofrece la funcionalidad de búsqueda, los archivos se basan en hojas HTML, por lo que resultan más pequeños que los de formato RTF y el archivo compilado es también más pequeño. Para mayor información puede visitar HTML Workshop en Mcrosoft.

BUG 1
En algunas versiones de HTML Help Workshop, al hacer click en Help en el menú principal se cuelga el sistema!

Proyectos en HTML Help

Hay seis secciones en un archivo de proyecto HTML Help:

Options	Información básica sobre el archivo de ayuda
Windows	Information acerca de las ventanas que se están usando
Files	Una lista de todos los archivos que usa el proyecto
Alias	Cada archivo tópico tiene un alias topic ID. Estos van istados aquí
Map	En esta sección se asignan valores a cada alias, que pueden usarse cuando llamenos la ayuda desde VB
Text Popup	Contiene todos los tópicos de las ventanas ¿Que es esto?

Como ejemplo aqui va un pequeño archivo de proyecto HTML Help:

[OPTIONS]
Auto Index=Yes
Compatibility=1.1
Compiled file=DevPadHelp.chm
Contents file=Contents.hhc
Default Window=Main
Default topic=html\welcome.htm
Display compile progress=Yes
Full-text search=Yes
Index file=Index.hhk
Language=0x809 English (United Kingdom)
Title=Developers Pad Help

[WINDOWS]
Main="Developers Pad 1 BETA 1 Help","Contents.hhc","Index.hhk","html\
welcome.htm","html\welcome.htm",,,,,0x520,,0x206e,[512,5,1153,496],,,,0,,,


[FILES]
html\welcome.htm
html\comments_suggestions.htm
html\copyright.htm
html\credits.htm
html\features.htm
html\report_bug.htm

[ALIAS]
IDH_DLG_FIND=html\find_dialog.htm
IDH_DLG_INSERT_SYMBOLS=html\insert_symbols.htm
IDH_WELCOME=html\welcome.htm

[MAP]
#define IDH_DLG_FIND 1010
#define IDH_DLG_INSERT 1020
#define IDH_WELCOME 1000

[TEXT POPUP]
popups.txt

BUG 2
Si tiene la versión 1.1, al presionar el botón Remove en la subsección Windows éste no funciona. Para solucionar esto hay que grabar, cerrar, luego abrir el archivo con el notepad y borrar la línea que corresponda en la sección [Windows].

La sección Windows es para colocar el tipo y las características de la ventana que ha creado.

Buttons sirve para elegir que botones serán mostrados en la barra de navegación que aparece en la ayuda:

.

Luego la sección Position sirve para especificar el tamaño y localización de la pantalla. Puede usar el autosizer para ajustar manualmente donde se coloca la pantalla. Valores recomendados son width 640, y height 440, un poquito menor que pantalla completa. Con Left y Top en 0 la ventana aparece en el centro de la pantalla

Files permite especificar que archivos tendrá el proyecto

El archivo TOC - contiene las entradas de los contenidos (extension HHC).

El archivo Index - contiene las entradas del índice (extension HHK).

Default - Es la hoja HTML que se muestra al abrirse la ayuda

Home - Es la hoja HTML donde llega al pulsar la tecla Home de la barra de navegación.

Jump 1 y Jump 2 - Son dos botones libres para que el usuario defina hojas HTML adonde saltar incondicionalmente

Navegation Pane permite especificar el aspecto y botones de la barra de navegación

Archivos de Contenidos

Los archivos de contenidole permiten crear una estructura para que el usuario pueda navegar por la ayuda.

Para crear una carpeta nueva haga click en el icono de carpeta o libro (según haya seteado)

Entre un título para la carpeta. Ahora se agregan los ítems o topics a la lista especificando cual archivo html se mostrará para cada uno de los tópicos

.

Archivos de Indice

Los archivos de índice permiten crear una lista de palabras clave, de manera que cuando el usuario haga click en la clave se muestre el tópico correspomdiente

Mapeando Topics a ID's

Para especificar que tópicos se mostrarán en el programa VB se necesitan mapear Topics a ID's, y luego colocar valores a esos ID's.

Lo primero es ponerle 'alias' a los topic ID's.. Haga Click en el botón API button , y vaya a la pestaña Alias :

Haga click en add para especificar un topic ID para cada archivo de tópico específico:

Trate de hacer el Topic ID lo más claro posible de manera que pueda recordar a que tópico debe linkearse, luego seleccione el archivo que le corresponda

A continuación, necesitamos asignar un valor a la constante de Topic ID (la que pasaremos desde VB). HTML Help workshop no permite hacer esto directamente, así es que hay que grabar y cerrar el proyecto, ir al notepad, a la sección Alias y verá algunas ID´s y los archivos que se le han asignado

[ALIAS]
IDH_FIND_DIALOG=html\find_dialog.htm
IDH_DLG_INSERT_SYMBOLS=html\insert_symbols.htm
IDH_WELCOME=html\welcome.htm

Ahora, vaya a la sección Map (que probablemente no exista aún, en cuyo caso hay que crearla debajo de la sección Alias). Aquí necesitamos agregar algunas instrucciones que asignarán un valor a cada Topic ID. Se usa la siguiente Sintaxis:

:

#define TOPIC_ID CONTEXT_INTEGER

A continuación va un ejemplo:

[MAP]
#define IDH_FIND_DIALOG 1010
#define IDH_DLG_INSERT 1020
#define IDH_WELCOME 1000

Por convención los Context Integers parten de 1000 y se incrementan de 10 en 10. Grabe el archivo y recarguelo desde HTML Workshop.

Usando Style Sheets

Si desea uniformar el estilo de todos los documentos (por ejemplo todos los encabezados del mismo tamaño y color, etc.), pueden usarse las stylesheets. Para crear una stylesheet:

1) Abrir Notepad, y escribir

h1 {color:blue;font-size: 12pt;}
p {font-family: 'Tahoma';font-size: 10pt;}

2) Grabar el archivo como default.css .

Luego incluir el código siguiente en las páginas:

<link rel="STYLESHEET" HREF="default.css" TYPE="text/css">

Eso es todo, con las stylesheet, puede especificar estilos para:

Tag	Description
h1	Encabezado 1
h2	Encabezado 2
h3......h6	Encabezados 3 al 6
p	Texto del párrafo
a	Hyperlinks

Y, entre paréntesis pueden usarse los siguientes estilos:

'Descriptores' de estilo	Description
Color	Color de la fuente
font-face	Nombre de la fuente (entre comillas simples)
font-size	Tamaño de la fuente, ej. font-size: 10pt;
text-decoration	text-decoration: underline; para texto subrayado
font-weight	font-weight: bold; para negrita

Mostrando Ayuda desde un Msgbox

Es bastante simple, usando la siguiente sintaxis

Msgbox Message, Options + vbMsgBoxHelpButton, DialogTitle, HTMLHelpFilePath & ">" & WindowName, ContextInteger

Así el siguiente código de ejemplo

MsgBox "Test Error Message Text.", _
vbOKOnly + vbExclamation + vbMsgBoxHelpButton, _
"Test Error Message", _
"C:\TestHTMLHelp.chm" & ">Main", 1010

Donde se presume que el archivo de ayuda compilado se llama C:\TestHTMLHelp.chm, y se tienen los siguientes ítems en el archivo de proyecto

[ALIAS]
IDH_TESTTOPIC=2html\test_topic_2.htm

[MAP]
#define IDH_FIND_DIALOG 1010

Mostrando Ayuda desde su aplicación

Para usar HTML help en una aplicación VB hay que agregar el siguiente código en un módulo

' Visual Basic code for implementing HTML Help 1.1

'*****
' Declare the following two constants
' as PUBLIC
Public Const HH_HELP_CONTEXT = &HF ' display mapped numeric
Public Const HH_TP_HELP_WM_HELP = &H11 ' text popup help, same as
' WinHelp HELP_WM_HELP

Private Const HH_DISPLAY_TOPIC = &H0
Private Const HH_HELP_FINDER = &H0 ' WinHelp equivalent
Private Const HH_DISPLAY_TOC = &H1 ' WinHelp equivalent
Private Const HH_DISPLAY_INDEX = &H2 ' WinHelp equivalent
Private Const HH_DISPLAY_SEARCH = &H3 ' not currently implemented
Private Const HH_SET_WIN_TYPE = &H4
Private Const HH_GET_WIN_TYPE = &H5
Private Const HH_GET_WIN_HANDLE = &H6
Private Const HH_ENUM_INFO_TYPE = &H7 ' Get Info type name, call
' repeatedly to enumerate,
' -1 at end
Private Const HH_SET_INFO_TYPE = &H8 ' Add Info type to filter.
Private Const HH_SYNC = &H9
Private Const HH_ADD_NAV_UI = &HA ' not currently implemented
Private Const HH_ADD_BUTTON = &HB ' not currently implemented
Private Const HH_GETBROWSER_APP = &HC ' not currently implemented
Private Const HH_KEYWORD_LOOKUP = &HD
Private Const HH_DISPLAY_TEXT_POPUP = &HE ' display string resource id
' or text in a popup window
' value in dwData
Private Const HH_TP_HELP_CONTEXTMENU = &H10 ' text popup help, same as
' WinHelp HELP_CONTEXTMENU
Private Const HH_CLOSE_ALL = &H12 ' close all windows opened
' directly or indirectly by
' the caller
Private Const HH_ALINK_LOOKUP = &H13 ' ALink version of
' HH_KEYWORD_LOOKUP
Private Const HH_GET_LAST_ERROR = &H14 ' not currently implemented
Private Const HH_ENUM_CATEGORY = &H15 ' Get category name, call
' repeatedly to enumerate,
' -1 at end
Private Const HH_ENUM_CATEGORY_IT = &H16 ' Get category info type
' members, call repeatedly to
' enumerate, -1 at end
Private Const HH_RESET_IT_FILTER = &H17 ' Clear the info type filter
' of all info types.
Private Const HH_SET_INCLUSIVE_FILTER = &H18 ' set inclusive filtering
' method for untyped topics
' to be included in display
Private Const HH_SET_EXCLUSIVE_FILTER = &H19 ' set method for untyped
' topics to be excluded from
' the display
Private Const HH_SET_GUID = &H1A ' For Microsoft Installer --
' dwData is a pointer to the
' GUID string
Private Const HH_INTERNAL = &HFF ' Used internally.

' Button IDs

Private Const IDTB_EXPAND = 200
Private Const IDTB_CONTRACT = 201
Private Const IDTB_STOP = 202
Private Const IDTB_REFRESH = 203
Private Const IDTB_BACK = 204
Private Const IDTB_HOME = 205
Private Const IDTB_SYNC = 206
Private Const IDTB_PRINT = 207
Private Const IDTB_OPTIONS = 208
Private Const IDTB_FORWARD = 209
Private Const IDTB_NOTES = 210 ' not implemented
Private Const IDTB_BROWSE_FWD = 211
Private Const IDTB_BROWSE_BACK = 212
Private Const IDTB_CONTENTS = 213 ' not implemented
Private Const IDTB_INDEX = 214 ' not implemented
Private Const IDTB_SEARCH = 215 ' not implemented
Private Const IDTB_HISTORY = 216 ' not implemented
Private Const IDTB_BOOKMARKS = 217 ' not implemented
Private Const IDTB_JUMP1 = 218
Private Const IDTB_JUMP2 = 219
Private Const IDTB_CUSTOMIZE = 221
Private Const IDTB_ZOOM = 222
Private Const IDTB_TOC_NEXT = 223
Private Const IDTB_TOC_PREV = 224

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

Private Type tagHHN_NOTIFY
hdr As Variant
pszUrl As String ' Multi-byte, null-terminated string
End Type

Private Type tagHH_POPUP
cbStruct As Integer ' sizeof this structure
hinst As Variant ' instance handle for string resource
idString As Variant ' string resource id, or text id if pszFile
' is specified in HtmlHelp call
pszText As String ' used if idString is zero
pt As Integer ' top center of popup window
clrForeground As ColorConstants ' use -1 for default
clrBackground As ColorConstants ' use -1 for default
rcMargins As RECT ' amount of space between edges of window and
' text, -1 for each member to ignore
pszFont As String ' facename, point size, char set, BOLD ITALIC
' UNDERLINE
End Type

Private Type tagHH_AKLINK
cbStruct As Integer ' sizeof this structure
fReserved As Boolean ' must be FALSE (really!)
pszKeywords As String ' semi-colon separated keywords
pszUrl As String ' URL to jump to if no keywords found (may be
' NULL)
pszMsgText As String ' Message text to display in MessageBox if
' pszUrl
' is NULL and no keyword match
pszMsgTitle As String ' Message text to display in MessageBox if
' pszUrl is NULL and no keyword match
pszWindow As String ' Window to display URL in
fIndexOnFail As Boolean ' Displays index if keyword lookup fails.
End Type

Private Enum NavigationTypes
HHWIN_NAVTYPE_TOC
HHWIN_NAVTYPE_INDEX
HHWIN_NAVTYPE_SEARCH
HHWIN_NAVTYPE_BOOKMARKS
HHWIN_NAVTYPE_HISTORY ' not implemented
End Enum

Private Enum IT
IT_INCLUSIVE
IT_EXCLUSIVE
IT_HIDDEN
End Enum

Private Type tagHH_ENUM_IT
cbStruct As Integer ' size of this structure
iType As Integer ' the type of the information type i.e.
' Inclusive, Exclusive, or Hidden
pszCatName As String ' Set to the name of the Category to
' enumerate the info types in a category;
' else NULL
pszITName As String ' volitile pointer to the name of the
' infotype. Allocated by call. Caller
' responsible for freeing
pszITDescription As String ' volitile pointer to the description of the
' infotype.
End Type

Private Type tagHH_ENUM_CAT
cbStruct As Integer ' size of this structure
pszCatName As String ' volitile pointer to the category name
pszCatDescription As String ' volitile pointer to the category
' description
End Type

Private Type tagHH_SET_INFOTYPE
cbStruct As Integer ' the size of this structure
pszCatName As String ' the name of the category, if any, the
' InfoType is a member of.
pszInfoTypeName As String ' the name of the info type to add to the
' filter
End Type

Private Enum NavTabs
HHWIN_NAVTAB_TOP
HHWIN_NAVTAB_LEFT
HHWIN_NAVTAB_BOTTOM
End Enum

Private Const HH_MAX_TABS = 19 ' maximum number of tabs
Private Enum Tabs
HH_TAB_CONTENTS
HH_TAB_INDEX
HH_TAB_SEARCH
HH_TAB_BOOKMARKS
HH_TAB_HISTORY
End Enum

' HH_DISPLAY_SEARCH Command Related Structures and Constants

Private Const HH_FTS_DEFAULT_PROXIMITY = (-1)

Private Type tagHH_FTS_QUERY
cbStruct As Integer ' Sizeof structure in bytes.
fUniCodeStrings As Boolean ' TRUE if all strings are unicode.
pszSearchQuery As String ' String containing the search query.
iProximity As Long ' Word proximity.
fStemmedSearch As Boolean ' TRUE for StemmedSearch only.
fTitleOnly As Boolean ' TRUE for Title search only.
fExecute As Boolean ' TRUE to initiate the search.
pszWindow As String ' Window to display in
End Type

' HH_WINTYPE Structure

Private Const SW_MAXIMIZE = 3
Private Const SW_MINIMIZE = 6
Private Const SW_NORMAL = 1
Private Const SW_SHOW = 5

Private Type HH_WINTYPE
cbStruct As Integer ' IN: size of this structure including all
' Information Types
fUniCodeStrings As Boolean ' IN/OUT: TRUE if all strings are in UNICODE
pszType As String ' IN/OUT: Name of a type of window
fsValidMembers As Variant ' IN: Bit flag of valid members
' (HHWIN_PARAM_)
fsWinProperties As Variant ' IN/OUT: Properties/attributes of the window
' (HHWIN_)
pszCaption As String ' IN/OUT: Window title
dwStyles As Variant ' IN/OUT: Window styles
dwExStyles As Variant ' IN/OUT: Extended Window styles
rcWindowPos As RECT ' IN: Starting position, OUT: current
' position
nShowState As Integer ' IN: show state (e.g., SW_SHOW)
hwndHelp As Variant ' OUT: window handle
hwndCaller As Variant ' OUT: who called this window
' The following members are only valid if
' HHWIN_PROP_TRI_PANE is set
hwndToolBar As Variant ' OUT: toolbar window in tri-pane window
hwndNavigation As Variant ' OUT: navigation window in tri-pane window
hwndHTML As Variant ' OUT: window displaying HTML in tri-pane
' window
iNavWidth As Integer ' IN/OUT: width of navigation window
rcHTML As RECT ' OUT: HTML window coordinates
pszToc As String ' IN: Location of the table of contents file
pszIndex As String ' IN: Location of the index file
pszFile As String ' IN: Default location of the html file
pszHome As String ' IN/OUT: html file to display when Home
' button is clicked
fsToolBarFlags As Variant ' IN: flags controling the appearance of the
' toolbar
fNotExpanded As Boolean ' IN: TRUE/FALSE to contract or expand, OUT:
' current state
curNavType As Integer ' IN/OUT: UI to display in the navigational
' pane
tabpos As Integer ' IN/OUT: HHWIN_NAVTAB_TOP, HHWIN_NAVTAB_LEFT,
' or HHWIN_NAVTAB_BOTTOM
idNotify As Integer ' IN: ID to use for WM_NOTIFY messages
tabOrder(HH_MAX_TABS + 1) As Byte ' IN/OUT: tab order: Contents, Index,
' Search, History, Favorites, Reserved 1-5,
' Custom tabs
cHistory As Integer ' IN/OUT: number of history items to keep
' (default is 30)
pszJump1 As String ' Text for HHWIN_BUTTON_JUMP1
pszJump2 As String ' Text for HHWIN_BUTTON_JUMP2
pszUrlJump1 As String ' URL for HHWIN_BUTTON_JUMP1
pszUrlJump2 As String ' URL for HHWIN_BUTTON_JUMP2
rcMinSize As RECT ' Minimum size for window (ignored in version
' 1 of the Workshop)
cbInfoTypes As Integer ' size of paInfoTypes;
End Type

Private Enum Actions
HHACT_TAB_CONTENTS
HHACT_TAB_INDEX
HHACT_TAB_SEARCH
HHACT_TAB_HISTORY
HHACT_TAB_FAVORITES
HHACT_EXPAND
HHACT_CONTRACT
HHACT_BACK
HHACT_FORWARD
HHACT_STOP
HHACT_REFRESH
HHACT_HOME
HHACT_SYNC
HHACT_OPTIONS
HHACT_PRINT
HHACT_HIGHLIGHT
HHACT_CUSTOMIZE
HHACT_JUMP1
HHACT_JUMP2
HHACT_ZOOM
HHACT_TOC_NEXT
HHACT_TOC_PREV
HHACT_NOTES
HHACT_LAST_ENUM
End Enum

Private Type tagHHNTRACK
hdr As Variant
pszCurUrl As String ' Multi-byte, null-terminated string
idAction As Integer ' HHACT_ value
phhWinType As HH_WINTYPE ' Current window type structure
End Type

Public Type HH_IDPAIR
dwControlId As Long
dwTopicId As Long
End Type
Public Declare Function htmlhelp Lib "hhctrl.ocx" _
Alias "HtmlHelpA" (ByVal hwnd As Long, _
ByVal lpHelpFile As String, _
ByVal wCommand As Long, _
ByVal dwData As Long) As Long

Then, you need to add a procedure that will set the HTML file path:

Public Function SetHTMLHelpStrings() As String
'// this presumes the help file is in the same directory as your app, and Main is the name of the window
SetHTMLHelpStrings = App.Path & "\TestHTMLHelp.chm" & ">Main"
End Function

To display the contents, use this code (from a form, otherwise you will need to change the hwnd value that is passed):

Public Sub HTMLHelpContents()
' Force the Help window to display
' the Contents file (*.hhc) in the left pane
htmlhelp hwnd, SetHTMLHelpStrings(), HH_DISPLAY_TOC, 0

End Sub

To display the index, use this code (from a form, otherwise you will need to change the hwnd value that is passed):

Public Sub HTMLHelpIndex()

' Force the Help window to display the Index file
' (*.hhk) in the left pane
htmlhelp hwnd, SetHTMLHelpStrings(), HH_DISPLAY_INDEX, 0

End Sub

To display a specific topic, using a filename this code (from a form, otherwise you will need to change the hwnd value that is passed):

Public Sub HTMLShowTopic(strTopic As String)

' Force the Help window to load a specific topic.
' The Help window will synchronize the
' Contents display automatically
htmlHelpTopic hwnd, SetHTMLHelpStrings(), HH_DISPLAY_TOPIC, strTopic

End Sub

To call it , use this code:

HTMLShowTopic "html\test_topic_1.htm"

To display a specific topic, using a context id (from a form, otherwise you will need to change the hwnd value that is passed):

Public Sub HTMLShowTopic(lngTopicID As Long)

' Force the Help window to load a specific topic.
' The Help window will synchronize the
' Contents display automatically
htmlHelpTopic hwnd, SetHTMLHelpStrings(), HH_HELP_CONTEXT, lngTopicID

End Sub

Para llamar a la ayuda, use este código

:

HTMLShowTopic 1000 '// 1000 = Context ID