VERSION 1.0 CLASS BEGIN MultiUse = -1 'True Persistable = 0 'NotPersistable DataBindingBehavior = 0 'vbNone DataSourceBehavior = 0 'vbNone MTSTransactionMode = 0 'NotAnMTSObject END Attribute VB_Name = "cHTMLHelp" Attribute VB_GlobalNameSpace = False Attribute VB_Creatable = True Attribute VB_PredeclaredId = False Attribute VB_Exposed = False Option Explicit '============================================================================================================= ' ' cHTMLHelp Class Module ' ---------------------- ' ' Created By : Kevin Wilson ' http://www.TheVBZone.com ( The VB Zone ) ' http://www.TheVBZone.net ( The VB Zone .net ) ' ' Last Update : April 01, 2003 ' Created On : April 01, 2000 ' ' VB Versions : 5.0 / 6.0 ' ' Requires : HHCTRL.OCX (Microsoft HTML ActiveX Control) ' Microsoft Internet Explorer 4.0 (or better) ' ' Description : This class module was created to easily access HTML Help systems from within Visual Basic. ' ' IMPORTANT : The MSDN documentation says that you should open the HTML Help API once and leave it open ' throughout the life of the application and shut it down as the application is being unloaded. ' I'm assuming this is for performance reasons because the HTML Help system takes FOREVER to ' start up and takes up quite a bit of memory to do so. Therefore, do not create and destroy ' this class multiple times if you can... instead keep one instance open. ' ' NOTE : This class module was re-designed on 04/01/03 because the HTML help system is a lot more ' stable now and is much more established within the popular operating systems. I've changed ' the entire interface to make it easier to use and more efficient. ' ' See Also : http://msdn.microsoft.com/library/en-us/htmlhelp/html/vsconOvabouthtmlhelpcommands.asp ' http://msdn.microsoft.com/library/en-us/htmlhelp/html/vsconOvhtmlhelpapioverview.asp ' http://msdn.microsoft.com/library/en-us/htmlhelp/html/vsconHowcallingthehtmlhelpapi.asp ' http://support.microsoft.com/default.aspx?scid=kb;en-us;297768 ' http://www.helpware.net/FAR/far_faq.htm ' http://www.helpware.net/htmlhelp/hh_info.htm ' http://www.workwrite.com/helpthink/vb_liske.htm ' http://www.mvps.org/htmlhelpcenter/htmlhelp/ ' http://helpware.net/htmlhelp/how_to_context.htm ' http://www.smountain.com/resource/VBHTMLHelp.pdf ' http://www.smountain.com/m_ProgrammingHelp.htm ' http://www.scit.wlv.ac.uk/~cm1810/CP3013/Lectures/html%20help.ppt ' ' Example Use : ' ' Option Explicit ' Private objHELP As cHTMLHelp ' Private Sub Form_Load() ' Dim lngErrNum As Long ' Dim strErrDesc As String ' Set objHELP = New cHTMLHelp ' If objHELP.Help_Open("C:\1.chm", Me.hWnd, lngErrNum, strErrDesc) = True Then ' If objHELP.Help_DisplayTOC(, , True) = True Then ' MsgBox "HTML Help displayed successfully", vbOKOnly + vbInformation, " " ' Else ' MsgBox "The following error occured:" & Chr(13) & Chr(13) & _ ' "Error Number = " & CStr(lngErrNum) & Chr(13) & _ ' "Error Description = " & strErrDesc, _ ' vbOKOnly + vbExclamation, " ERROR" ' End If ' Else ' MsgBox "The following error occured:" & Chr(13) & Chr(13) & _ ' "Error Number = " & CStr(lngErrNum) & Chr(13) & _ ' "Error Description = " & strErrDesc, _ ' vbOKOnly + vbExclamation, " ERROR" ' End If ' End Sub ' Private Sub Form_QueryUnload(Cancel As Integer, UnloadMode As Integer) ' Set objHELP = Nothing ' End Sub ' '============================================================================================================= ' ' LEGAL: ' ' You are free to use this code as long as you keep the above heading information intact and unchanged. Credit ' given where credit is due. Also, it is not required, but it would be appreciated if you would mention ' somewhere in your compiled program that that your program makes use of code written and distributed by ' Kevin Wilson (www.TheVBZone.com). Feel free to link to this code via your web site or articles. ' ' You may NOT take this code and pass it off as your own. You may NOT distribute this code on your own server ' or web site. You may NOT take code created by Kevin Wilson (www.TheVBZone.com) and use it to create products, ' utilities, or applications that directly compete with products, utilities, and applications created by Kevin ' Wilson, TheVBZone.com, or Wilson Media. You may NOT take this code and sell it for profit without first ' obtaining the written consent of the author Kevin Wilson. ' ' These conditions are subject to change at the discretion of the owner Kevin Wilson at any time without ' warning or notice. Copyrightİ by Kevin Wilson. All rights reserved. ' '============================================================================================================= Private Enum BOOL FALSE_ = 0 TRUE_ = 1 End Enum Private Type POINT X As Long Y As Long End Type Private Type RECT Left As Long Top As Long Right As Long Bottom As Long End Type '------------------------------------------------------------------------------------------------------------- ' HH_WINTYPE Structure '------------------------------------------------------------------------------------------------------------- Private Type HH_WINTYPE cbStruct As Long ' int // Specifies the size of the structure. This value must always be filled in before passing the structure to HtmlHelp(). fUniCodeStrings As BOOL ' BOOL // Specifies whether the strings used in this structure are UNICODE. pszType As String ' LPCTSTR // A null-terminated string that specifies the name of the window type. fsValidMembers As Long ' DWORD // Specifies which members in the structure are valid (HHWIN_PARAM_*) fsWinProperties As Long ' DWORD // Specifies the properties of the window, such as whether it is the standard HTML Help Viewer or whether it includes a Search tab (HHWIN_PROP_*). pszCaption As String ' LPCTSTR // A null-terminated string that specifies the caption to display in the title bar of the window. dwStyles As Long ' DWORD // Specifies the styles used to create the window. These styles can be ignored, combined with extended styles, or used exclusively depending on the value of the fsValidMembers and fsWinProperties parameters. dwExStyles As Long ' DWORD // Specifies the extended styles used to create the window. These styles can be ignored, combined with default styles, or used exclusively depending on the value of the fsValidMembers and fsWinProperties parameters. rcWindowPos As RECT ' RECT // Specifies the coordinates of the window in pixels. The values are read in the following order: rcWindowPos = {left, top, right, bottom}; nShowState As Long ' int // Specifies the initial display state of the window. Valid values are the same as those for the Win32 API ShowWindow function. hwndHelp As Long ' HWND // Specifies the handle of the window if the window has been created. hwndCaller As Long ' HWND // Specifies the window that will receive HTML Help notification messages. Notification messages are sent via Windows WM_NOTIFY messages. idNotify As Long ' int // Specifies a non-zero ID for enabling HTML Help notification messages. This ID is passed as the wParam value of Windows WM_NOTIFY messages. ' Members specific to the Help Viewer hwndToolBar As Long ' HWND // Specifies the handle of the toolbar. hwndNavigation As Long ' HWND // Specifies the handle of the Navigation pane. hwndHTML As Long ' HWND // Specifies the handle of the Topic pane, which hosts Shdocvw.dll. iNavWidth As Long ' int // Specifies the width of the Navigation pane when the Help Viewer is expanded. rcHTML As RECT ' RECT // Specifies the coordinates of the Topic pane. pszToc As String ' LPCTSTR // Specifies the contents (.hhc) file to display in the Navigation pane. pszIndex As String ' LPCTSTR // Specifies the index (.hhk) file to display in the Navigation pane. pszFile As String ' LPCTSTR // Specifies the default HTML file to display in the Topic pane. pszHome As String ' LPCTSTR // Specifies the file or URL to display in the Topic pane when the Home button is clicked. Specifies which buttons to include on the toolbar. fsToolBarFlags As Long ' DWORD // fNotExpanded As BOOL ' BOOL // Specifies that the Help Viewer open with the Navigation pane closed. curNavType As Long ' int // Specifies the default tab to display on the Navigation pane (HHWIN_NAVTYPE_*). pszJump1 As String ' LPCTSTR // Specifies the text to display underneath the Jump1 button. pszJump2 As String ' LPCTSTR // Specifies the text to display underneath the Jump2 button. pszUrlJump1 As String ' LPCTSTR // Specifies the URL to jump to when the Jump1 button is clicked. pszUrlJump2 As String ' LPCTSTR // Specifies the URL to jump to when the Jump2 button is clicked. End Type '------------------------------------------------------------------------------------------------------------- ' Use this structure to specify one or more ALink names or KLink keywords that you want to search for. If the lookup yields no matching topics, HtmlHelp() checks the values of the following HH_AKLINK members to determine what alternative action to take: ' fIndexOnFail - If fIndexOnFail is TRUE, the Index tab is selected in the help window specified in pszWindow, and the keyword specified in pszKeyword is selected in the entry field. ' pszURL - If fIndexOnFail is FALSE, the topic file specified in pszURL appears in the help window specified in pszWindow. ' pszMsgText - If fIndexOnFail is FALSE and pszURL is NULL, a message box appears using the text and caption specified in pszMsgText and pszMsgTitle. ' pszMsgTitle - (see pszMsgText) ' ' SAMPLE: ' ' With HH_AKLINK ' .cbStruct = Len(HH_AKLINK) ' .fReserved = FALSE_ ' .pszKeywords = "open" ' .pszUrl = vbNullString ' .pszMsgText = vbNullString ' .pszMsgTitle = vbNullString ' .pszWindow = vbNullString ' .fIndexOnFail = TRUE_ ' End With '------------------------------------------------------------------------------------------------------------- Private Type HH_AKLINK cbStruct As Long ' int // Specifies the size of the structure. This value must always be filled in before passing the structure to the HTML Help API. fReserved As BOOL ' BOOL // This parameter must be set to FALSE (0) pszKeywords As String ' LPCTSTR // Specifies one or more ALink names or KLink keywords to look up. Multiple entries are delimited by a semicolon. pszUrl As String ' LPCTSTR // (May be NULL) Specifies the topic file to navigate to if the lookup fails. pszURL refers to a valid topic within the specified compiled help (.chm) file and does not support Internet protocols that point to an HTML file. pszMsgText As String ' LPCTSTR // Specifies the text to display in a MessageBox if the lookup fails and fIndexOnFail is FALSE and pszURL is NULL. pszMsgTitle As String ' LPCTSTR // Specifies the caption of the MessageBox in which the pszMsgText parameter appears. pszWindow As String ' LPCTSTR // Specifies the name of the window type in which to display one of the following: ' - The selected topic, if the lookup yields one or more matching topics. ' - The topic specified in pszURL, if the lookup fails and a topic is specified in pszURL. ' - The Index tab, if the lookup fails and fIndexOnFail is specified as TRUE. fIndexOnFail As BOOL ' BOOL // Specifies whether to display the keyword in the Index tab of the HTML Help Viewer if the lookup fails. The value of pszWindow specifies the Help Viewer. End Type '------------------------------------------------------------------------------------------------------------- ' Use this structure for full-text search. '------------------------------------------------------------------------------------------------------------- Private Type HH_POPUP cbStruct As Long ' int // Specifies the size of the structure. This value must always be filled in before passing the structure to HtmlHelp(). hInst As Long ' HINSTANCE // Instance handle of the program or DLL to retrieve the string resource from. Ignored if idString is zero, or if idString specifies a file name. idString As Long ' UINT // Specifies zero, a resource ID, or a topic number in a text file. pszText As String ' LPCTSTR // Specifies the text to display if idString is zero. PT As POINT ' POINT // Specifies (in pixels) where the top center of the pop-up window should be located. clrForeground As Long ' COLORREF // Specifies the RGB value to use for the foreground color of the pop-up window. To use the system color for the window text, specify -1. clrBackground As Long ' COLORREF // Specifies the RGB value to use for the background color of the pop-up window. To use the system color for the window background, specify -1. rcMargins As RECT ' RECT // Specifies (in pixels) the margins to use on the left, top, right, and bottom sides of the pop-up window. The default for all rectangle members is -1. pszFont As String ' LPCTSTR // Specifies the font attributes to use for the text in the pop-up window. ' Use the following format to specify font family, point size, character set, and font format: ' facename [, point size[, charset[ BOLD ITALIC UNDERLINE]]] ' To omit an attribute, enter a comma. For example, to specify bold, 10-pt, MS Sans Serif font, pszFont would be: MS Sans Serif, 10, , BOLD End Type '------------------------------------------------------------------------------------------------------------- ' Use this structure for full-text search. '------------------------------------------------------------------------------------------------------------- Private Type HH_FTS_QUERY cbStruct As Long ' int // Specifies the size of the structure. fUniCodeStrings As BOOL ' BOOL // TRUE if all strings are Unicode. pszSearchQuery As String ' LPCTSTR // String containing the search query. iProximity As Long ' LONG // Word proximity. fStemmedSearch As BOOL ' BOOL // TRUE for StemmedSearch only. fTitleOnly As BOOL ' BOOL // TRUE for Title search only. fExecute As BOOL ' BOOL // TRUE to initiate the search. pszWindow As String ' LPCTSTR // Window to display in. End Type '------------------------------------------------------------------------------------------------------------- ' This structure returns the last HtmlHelp() error code and description. '------------------------------------------------------------------------------------------------------------- Private Type HH_LAST_ERROR cbStruct As Long ' int // Specifies the size of the structure. This value must always be filled in before passing the structure to HtmlHelp(). hr As Long ' HRESULT // Specifies the last error code. Description As String ' BSTR // Specifies a Unicode string containing a description of the error. End Type '------------------------------------------------------------------------------------------------------------- ' This structure is used with the HH_PRETRANSLATEMESSAGE command '------------------------------------------------------------------------------------------------------------- Private Type MSG hWnd As Long ' HWND // Identifies the window whose window procedure receives the message. Message As Long ' UINT // Specifies the message number. wParam As Long ' WPARAM // Specifies additional information about the message. The exact meaning depends on the value of the message member. lParam As Long ' LPARAM // Specifies additional information about the message. The exact meaning depends on the value of the message member. Time As Long ' DWORD // Specifies the time at which the message was posted. PT As POINT ' POINT // Specifies the cursor position, in screen coordinates, when the message was posted. End Type ' Constants - General Private Const MAX_PATH = 260 ' Constants - FormatMessage.dwFlags Private Const FORMAT_MESSAGE_ALLOCATE_BUFFER = &H100 ' Specifies that the lpBuffer parameter is a pointer to a PVOID pointer, and that the nSize parameter specifies the minimum number of TCHARs to allocate for an output message buffer. The function allocates a buffer large enough to hold the formatted message, and places a pointer to the allocated buffer at the address specified by lpBuffer. The caller should use the LocalFree function to free the buffer when it is no longer needed. Private Const FORMAT_MESSAGE_IGNORE_INSERTS = &H200 ' Specifies that insert sequences in the message definition are to be ignored and passed through to the output buffer unchanged. This flag is useful for fetching a message for later formatting. If this flag is set, the Arguments parameter is ignored. Private Const FORMAT_MESSAGE_FROM_STRING = &H400 ' Specifies that lpSource is a pointer to a null-terminated message definition. The message definition may contain insert sequences, just as the message text in a message table resource may. Cannot be used with FORMAT_MESSAGE_FROM_HMODULE or FORMAT_MESSAGE_FROM_SYSTEM. Private Const FORMAT_MESSAGE_FROM_HMODULE = &H800 ' Specifies that lpSource is a module handle containing the message-table resource(s) to search. If this lpSource handle is NULL, the current process's application image file will be searched. Cannot be used with FORMAT_MESSAGE_FROM_STRING. Private Const FORMAT_MESSAGE_FROM_SYSTEM = &H1000 ' Specifies that the function should search the system message-table resource(s) for the requested message. If this flag is specified with FORMAT_MESSAGE_FROM_HMODULE, the function searches the system message table if the message is not found in the module specified by lpSource. Cannot be used with FORMAT_MESSAGE_FROM_STRING. If this flag is specified, an application can pass the result of the GetLastError function to retrieve the message text for a system-defined error. Private Const FORMAT_MESSAGE_ARGUMENT_ARRAY = &H2000 ' Specifies that the Arguments parameter is not a va_list structure, but instead is just a pointer to an array of values that represent the arguments. ' Constants - SetWindowPos.uFlags Private Const SWP_FRAMECHANGED = &H20 ' Sends a WM_NCCALCSIZE message to the window, even if the window’s size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window’s size is being changed. Private Const SWP_HIDEWINDOW = &H80 ' Hides the window. Private Const SWP_NOACTIVATE = &H10 ' Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or non-topmost group (depending on the setting of the hWndInsertAfter parameter). Private Const SWP_NOCOPYBITS = &H100 ' Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned. Private Const SWP_NOMOVE = &H2 ' Retains the current position (ignores the X and Y parameters). Private Const SWP_NOOWNERZORDER = &H200 ' Does not change the owner window’s position in the Z order. Private Const SWP_NOREDRAW = &H8 ' Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the window being moved. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing. Private Const SWP_NOSENDCHANGING = &H400 ' Prevents the window from receiving the WM_WINDOWPOSCHANGING message. Private Const SWP_NOSIZE = &H1 ' Retains the current size (ignores the cx and cy parameters). Private Const SWP_NOZORDER = &H4 ' Retains the current Z order (ignores the hWndInsertAfter parameter). Private Const SWP_SHOWWINDOW = &H40 ' Displays the window. Private Const SWP_NOREPOSITION = SWP_NOOWNERZORDER ' Same as the SWP_NOOWNERZORDER flag. Private Const SWP_DRAWFRAME = SWP_FRAMECHANGED ' Draws a frame (defined in the window’s class description) around the window. '_____________________________________________________________________________________________________________ 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ ' Window Types: Private Const HH_CLOSE_ALL = &H12 ' (0, 0, HH_CLOSE_ALL, 0) Close all windows opened directly or indirectly by the caller ' pszFile = NULL ' dwData = NULL ' Return = NULL Private Const HH_GET_WIN_HANDLE = &H6 ' (hWnd, "C:\Help.chm", HH_GET_WIN_HANDLE, WindowTypeName) Returns the handle (hwnd) of a specified window type ' pszFile = Specifies the name of the compiled help (.chm) file in which the window type is defined. ' dwData = Specifies the name of the window type whose handle you want to return. ' Return = The handle (hwnd) of the window type specified in the dwData parameter, or NULL if the help window has not yet been created. Private Const HH_GET_WIN_TYPE = &H5 ' (GetDesktopWindow, "Help.chm>mainwin", HH_GET_WIN_TYPE, HH_WINTYPE) Retrieves a pointer to the HH_WINTYPE structure associated with a specified window type. Always specify the name of the compiled help file in which the window type is defined when calling an API command. If the window type is not defined in a .chm file, then specify NULL. ' pszFile = Specifies the name of the window type whose information you want to get and the name of the compiled help (.chm) file in which the window type is defined. The window name must begin with a greater-than (>) character and must be preceded by the name of the compiled help file it is defined in. ' dwData = Specifies the address of a pointer to an HH_WINTYPE structure. Deep copy the structure to which dwData points before modifying the structure. ' Return = On success, returns the handle (hWnd) of the parent help window if the specified window type has been defined, or NULL if the help window has not yet been created. On failure, returns -1 if the specified window type has not been defined. Private Const HH_SET_WIN_TYPE = &H4 ' (GetDesktopWindow, "..\Help.chm>mainwin", HH_SET_WIN_TYPE, HH_WINTYPE) Creates a new help window or modifies an existing help window at run time. ' pszFile = Specifies the name of the window type that you want to create or modify and the name of the compiled help (.chm) file in which the window type is defined. The window type name must begin with a greater-than (>) character and must be preceded by the name of the compiled help file in which it is defined. ' dwData = Points to an HH_WINTYPE structure. ' Return = On success, returns the handle (hWnd) of the help window, or NULL if the help window has not yet been created. On failure, returns NULL if the specified window type has not been defined. ' Context-Sensitive Help: Private Const HH_DISPLAY_TEXT_POPUP = &HE ' (hWnd, 0, HH_DISPLAY_TEXT_POPUP, HH_POPUP) Opens a pop-up window that displays the contents of one of the following: An explicit text string, A text string based on a resource ID, or A text string ID based on a text file contained in a compiled help (.chm) file. ' pszFile = To use an explicit text string: Specify a NULL value. To use a text string from a resource: Specify a NULL value. To use text string from a text file contained in a compiled help file: Specify the .chm file and the text file within the .chm file. ' dwData = Specifies a pointer to an HH_POPUP structure. ' Return = The handle (hwnd) of the pop-up window. Private Const HH_DISPLAY_TOPIC = &H0 ' (GetDesktopWindow, "C:\Help.chm::/intro.htm>mainwin", HH_DISPLAY_TOPIC, 0) Opens a help topic in a specified help window. If a window type is not specified, a default window type is used. If the window type or default window type is open, the help topic replaces the current topic in the window. ' pszFile = Specifies a compiled help (.chm) file, or a specific topic within a compiled help file. To specify a defined window type, insert a greater-than (>) character followed by the name of the window type. ' dwData = Specifies NULL or a pointer to a topic within a compiled help file. ' Return = The handle (hwnd) of the help window. Private Const HH_HELP_CONTEXT = &HF ' (GetDesktopWindow, "Help.chm", HH_HELP_CONTEXT, 5000) Displays a help topic based on a mapped topic ID. If a window type is not specified, a default window type is used. If the window type or default window type is open, the help topic replaces the current topic in the window. ' pszFile = Specifies the compiled help (.chm) file that contains the mapping information. To specify a defined window type, insert a greater-than (>) character followed by the name of the window type. ' dwData = Specifies the numeric ID of the topic to display. You must map symbolic IDs of dialog boxes to numeric IDs in the [MAP] section of your project (.hhp) file. ' Return = ?? Private Const HH_TP_HELP_CONTEXTMENU = &H10 ' (hwndCTRL, "C:\Help.chm::/popups\cshelp.txt", HH_TP_HELP_CONTEXTMENU, ids) Opens a pop-up context menu. Generally used in response to the Windows WM_CONTEXTMENU message. For example, this message is sent when a user right-clicks a dialog box control. The text (.txt) file that contains the pop-up help topics must be included in the [TEXT POPUPS] section of your project (.hhp) file. ' hwndCaller = Specifies the window handle of the dialog box control for which you want pop-up help to appear. This is typically the control that has focus. ' pszFile = Specifies the compiled help (.chm) file, and the text file that contains the pop-up help topics. By default, the text file is named Cshelp.txt. If Cshelp.txt is located in the root of the compiled help file, then you only need to specify the help file name. If not, you must also specify the relative path. ' dwData = Specifies an array of DWORDs containing pairs of dialog box control IDs and help topic IDs. The array must be terminated by zero. If a control does not require pop-up help, specify -1 for the help topic ID. ' DWORD ids[5] ; ' ids[0] = ControlID1 ; ' ids[1] = HelpID1 ; ' ids[2] = ControlID2 ; ' ids[3] = -1 ; ' ids[4] = 0 ; ' Return = ?? Private Const HH_TP_HELP_WM_HELP = &H11 ' (hwndCTRL, "C:\myHelp.chm::/popups\cshelp.txt", HH_TP_HELP_WM_HELP, ids) Opens a pop-up help topic. Generally used in response to the Windows WM_HELP message. For example, this message is sent when a user presses F1. The text file that contains the pop-up help topics must be included in the [TEXT POPUPS] section of your project (.hhp) file. ' hwndCaller = Specifies the window handle of the dialog box control for which you want pop-up help to appear. This is typically the control that has focus. ' pszFile = Specifies the compiled help (.chm) file, and the text file that contains the pop-up help topics. By default, the text file is named Cshelp.txt. If Cshelp.txt is located in the root of the compiled help file, then you only need to specify the help file name. If not, you must also specify the relative path. ' dwData = Specifies an array of DWORDs containing pairs of dialog box control IDs and help topic IDs. The array must be terminated by zero. If a control does not require pop-up help, specify -1 for the help topic ID. ' DWORD ids[5] ; ' ids[0] = ControlID1 ; ' ids[1] = HelpID1 ; ' ids[2] = ControlID2 ; ' ids[3] = -1 ; ' ids[4] = 0 ; ' Return = ?? ' Keyword Lookups: Private Const HH_ALINK_LOOKUP = &H13 ' (GetDesktopWindow, "C:\Help.chm", HH_ALINK_LOOKUP, HH_AKLINK) Looks up one or more Associative link (ALink) names in a compiled help (.chm) file. The ALink names to search for, and the action to be taken if no matches are found, are specified in the HH_AKLINK structure. You must first call the HH_DISPLAY_TOPIC command before calling this command, to ensure that the help window is created. Help authors insert ALink names into target topic files using the HTML Help Compiler Information feature. ' pszFile = Specifies the compiled help (.chm) file that contains ALink names. ' dwData = Points to an HH_AKLINK structure. ' Return = The handle (hwnd) of the help window. Private Const HH_KEYWORD_LOOKUP = &HD ' (GetDesktopWindow, "C:\Help.chm", HH_KEYWORD_LOOKUP, HH_AKLINK) Looks up one or more keywords in a compiled help (.chm) file. The keywords to search for and the action to be taken if no matches are found are specified in the HH_AKLINK structure. You must first call the HH_DISPLAY_TOPIC command before calling this command to ensure that the help window is created. Help authors insert keywords into topic files using the HTML Help Compiler Information feature. ' pszFile = Specifies the compiled help (.chm) file that contains keywords. ' dwData = Points to an HH_AKLINK structure. ' Return = The handle (hwnd) of the help window. ' Navigation Pane: Private Const HH_DISPLAY_INDEX = &H2 ' (hWnd, "Help.chm", HH_DISPLAY_INDEX, "Hello") Selects the Index tab in the Navigation pane of the HTML Help Viewer and searches for the keyword specified in the dwData parameter. ' pszFile = Specifies a compiled help (.chm) file, or a specific topic within a compiled help file. ' dwData = Specifies the keyword to select in the index (.hhk) file. ' Return = The handle (hwnd) of the help window. Private Const HH_DISPLAY_SEARCH = &H3 ' (hWnd, "Help.chm", HH_DISPLAY_SEARCH, HH_FTS_QUERY) Selects the Search tab in the Navigation pane of the HTML Help Viewer, but does not actually perform a search. ' pszFile = Specifies a compiled help (.chm) file, or a specific topic within a compiled help file. ' dwData = Specifies a pointer to an HH_FTS_QUERY structure. ' Return = The handle (hwnd) of the help window. Private Const HH_DISPLAY_TOC = &H1 ' (GetDesktopWindow, "C:\\Help.chm::/intro.htm", HH_DISPLAY_TOC, 0) Selects the Contents tab in the Navigation pane of the HTML Help Viewer. This command provides the same functionality as HH_DISPLAY_TOPIC. ' pszFile = Specifies a compiled help (.chm) file, or a specific topic within a compiled help file. ' dwData = Specifies NULL or a pointer to a topic within a compiled help file. ' Return = The handle (hwnd) of the help window. ' Error Messages: Private Const HH_GET_LAST_ERROR = &H14 ' (hWnd, 0, HH_GET_LAST_ERROR, HH_LAST_ERROR) Returns information about the last error that occurred in the HTML Help ActiveX control (HHCTRL.OCX). See also HHERROR.h ' pszFile = Must be NULL. ' dwData = A pointer to a HH_LAST_ERROR structure. ' Return = 0 = FAIL / 1 = SUCCESS ' Contents Synchronization Private Const HH_SYNC = &H9 ' (hWnd, "..\Help.chm>wintype", HH_SYNC, "Help.chm::/html/MyTopic.htm") Locates and selects the contents entry for the help topic that is open in the Topic pane of the HTML Help Viewer. Calling this command is equivalent to clicking the Locate button on the toolbar of the Help Viewer. ' pszFile = Specifies the name of the window type that you want to sync and the name of the compiled help (.chm) file in which the window type is defined. The window type name must begin with a greater-than (>) character and must be preceded by the name of the compiled help file in which it is defined. ' dwData = Specifies a pointer to a topic within a compiled help file. This value is the topic file to which the contents will synchronize. ' Return = ?? ' Single threading: Private Const HH_INITIALIZE = &H1C ' (0, 0, HH_INITIALIZE, lngCookie) This command initializes the help system for use and must be the first HTML Help command called. It returns a cookie which must be used in the HH_UNINITIALIZE call. HH_INITIALIZE configures HTML Help to run on the same thread as the calling application instead of a secondary thread by setting the global property HH_GPROPID_SINGLETHREAD to VARIANT_TRUE. Running HTML Help on the same thread as the calling application requires the calling application to send messages to HTML Help by calling the HH_PRETRANSLATEMESSAGE command. Call HH_INITIALIZE before calling any other command and call HH_UNINITIALIZE only when your application ends. You should call these commands once during the life of your application. ' pszFile = Must be NULL. ' dwData = Specifies a pointer to a DWORD. This call returns a cookie that you must pass as the value of dwData when you call HH_UNINITIALIZE. ' Return = ?? Private Const HH_PRETRANSLATEMESSAGE = &HFD ' (0, 0, HH_PRETRANSLATEMESSAGE, MSG) This command is called in the message loop of your Windows application to ensure proper handling of Windows messages, especially keyboard messages when running HTML Help single thread. The HTML Help API is not thread safe and must be called from one and only one thread in a process. Before calling this command, you must first set the global property HH_GPROPID_SINGLETHREAD to VARIANT_TRUE by calling the HH_INITIALIZE command. ' pszFile = Must be NULL. ' dwData = Points to a Win32 MSG structure. ' Return = Returns True (1), if message is translated. Returns False(0), if command fails. Private Const HH_UNINITIALIZE = &H1D ' (0, 0, HH_UNINITIALIZE, lngCookie) This command is called to properly shut down HTML Help. This function should be the last help command the application calls. HH_UNINITIALIZE should not be called during DLL process detach, but during the normal application shutdown process. ' pszFile = Must be NULL. ' dwData = Specifies a cookie. This is the cookie returned by HH_INITIALIZE. ' Return = ?? '------------------------------------------------------------------------------------------------------------- Private p_WindowHandle As Long Private p_OwnerHandle As Long Private p_FilePath As String Private blnOpened As Boolean Private blnInitialized As Boolean Private lngCookie As Long '------------------------------------------------------------------------------------------------------------- ' HWND HtmlHelp(HWND hwndCaller, ' Specifies the handle (hwnd) of the window calling HtmlHelp(). The help window is owned by this window. ' LPCSTR pszFile, ' Depending on the uCommand value, specifies the file path to either a compiled help (.chm) file, or a topic file within a specified help file. ' UINT uCommand, ' Specifies the command to complete. ' DWORD dwData ' Specifies any data that may be required, based on the value of the uCommand parameter. ' ); '------------------------------------------------------------------------------------------------------------- Private Declare Function HTMLHelp Lib "hhctrl.ocx" Alias "HtmlHelpA" (ByVal hwndCaller As Long, ByVal pszFile As String, ByVal uCommand As Long, ByRef dwData As Any) As Long Private Declare Sub Sleep Lib "kernel32.dll" (ByVal dwMilliseconds As Long) Private Declare Sub SetLastError Lib "kernel32.dll" (ByVal dwErrCode As Long) Private Declare Function GetLastError Lib "kernel32.dll" () As Long Private Declare Function FormatMessage Lib "kernel32.dll" Alias "FormatMessageA" (ByVal dwFlags As Long, ByRef lpSource As Any, ByVal dwMessageId As Long, ByVal dwLanguageId As Long, ByVal lpBuffer As String, ByVal nSize As Long, ByRef Arguments As Long) As Long Private Declare Function GetDesktopWindow Lib "USER32.DLL" () As Long Private Declare Function DestroyWindow Lib "USER32.DLL" (ByVal hWnd As Long) As BOOL Private Declare Function SetWindowPos Lib "USER32.DLL" (ByVal hWnd As Long, ByVal hWndInsertAfter As Long, ByVal lngX As Long, ByVal lngY As Long, ByVal lngWidth As Long, ByVal lngHeight As Long, ByVal uFlags As Long) As BOOL Private Declare Function GetWindowRect Lib "USER32.DLL" (ByVal hWnd As Long, ByRef lpRect As RECT) As BOOL 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'XXXXXXXXXX CLASS EVENTS XXXXXXXXXX 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ' This event properly cleans up the HTML Help system and any open windows Private Sub Class_Terminate() If blnInitialized = True Then If p_WindowHandle <> 0 Then Call Help_Close(p_WindowHandle) Call Help_CloseAll Call HTMLHelp(0, vbNullString, HH_UNINITIALIZE, ByVal lngCookie) End If End Sub 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'XXXXXXXXXX PUBLIC METHODS XXXXXXXXXX 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX '============================================================================================================= ' Help_Open ' ' This function checks if the specified HTML Help file exists, validates it, then initializes the HTML Help ' system in preperation for further action. ' ' Param Use ' ------------------------------------ ' strFilePath Specifies the full path to the HTML Help file (.chm) to use. If you will only use the ' "Help_DisplayPopUp" method, this file simply has to exist and have a ".chm" extention. ' It can be a blank ASCII TEXT file that was renamed to .CHM. ' hWnd_Owner Optional. Specifies the handle to the owner form. If not specified, the desktop's ' handle is used instead. ' Return_ErrNum Optional. If an error occurs during the execution of the function, this will return ' the error number. ' Return_ErrDesc Optional. If an error occurs during the execution of the function, this will return ' the error number. ' ' Return ' ------ ' Returns TRUE if it executed successfully. ' Returns FALSE if an error occured during execution (Return_ErrNum & Return_ErrDesc will have the error info) ' '============================================================================================================= Public Function Help_Open(ByVal strFilePath As String, Optional ByVal hWnd_Owner As Long, Optional ByRef Return_ErrNum As Long, Optional ByRef Return_ErrDesc As String) As Boolean ' Set initial values Return_ErrNum = 0 Return_ErrDesc = "" ' Make sure the file exists strFilePath = Trim(strFilePath) If Dir(strFilePath, vbArchive Or vbHidden Or vbNormal Or vbReadOnly Or vbSystem) = "" Then Return_ErrNum = 53 Return_ErrDesc = "File not found" Exit Function ElseIf UCase(Right(strFilePath, 4)) <> ".CHM" Then Return_ErrNum = -1 Return_ErrDesc = "The specified file is not a valid HTML Help file" Exit Function End If ' If the HTML Help system hasn't already been initialized, do so If blnInitialized = False Then If HTMLHelp(0, vbNullString, HH_INITIALIZE, lngCookie) = 0 Then Call Help_GetLastError(Return_ErrNum, Return_ErrDesc) If Return_ErrDesc = "" Then Return_ErrDesc = "Failed to successfully initialize the HTML Help system" Exit Function Else blnInitialized = True End If End If ' Close any existing HTML Help documents Call Help_CloseAll ' Remember the file's information If hWnd_Owner = 0 Or hWnd_Owner = -1 Then hWnd_Owner = GetDesktopWindow p_OwnerHandle = hWnd_Owner p_WindowHandle = 0 p_FilePath = strFilePath blnOpened = True Help_Open = True End Function '============================================================================================================= ' Help_Close ' ' This function takes the specified window handle and closes it by calling the "DestroyWindow" Win32 API. ' The window handle is passed back to you for every "Help_Display*" method so this function can be used ' to close just one window... but you can use this method to close any window within the calling thread. ' ' Param Use ' ------------------------------------ ' WindowHandle Specifies the handle of the window to close ' Return_ErrNum Optional. If an error occurs during the execution of the function, this will return ' the error number. ' Return_ErrDesc Optional. If an error occurs during the execution of the function, this will return ' the error number. ' ' Return ' ------ ' Returns TRUE if it executed successfully. ' Returns FALSE if an error occured during execution (Return_ErrNum & Return_ErrDesc will have the error info) ' '============================================================================================================= Public Function Help_Close(ByRef WindowHandle As Long, Optional ByRef Return_ErrNum As Long, Optional ByRef Return_ErrDesc As String) As Boolean ' Set initial values Return_ErrNum = 0 Return_ErrDesc = "" ' Make sure the window handle is valid If WindowHandle = 0 Then Return_ErrNum = -1 Return_ErrDesc = "No valid window handle specified to close" Exit Function End If ' Destroy the window handle If DestroyWindow(WindowHandle) = FALSE_ Then Return_ErrNum = Err.LastDllError Call Win32API_GetLastError(Return_ErrNum, Return_ErrDesc) Else If WindowHandle = p_WindowHandle Then p_FilePath = "" blnOpened = False End If WindowHandle = 0 Help_Close = True End If End Function '============================================================================================================= ' Help_CloseAll ' ' This function closes all HTML Help windows that were opened by the calling thread. ' ' Param Use ' ------------------------------------ ' (none) ' ' Return ' ------ ' (none) ' '============================================================================================================= Public Sub Help_CloseAll() ' Close all help windows Call HTMLHelp(0, vbNullString, HH_CLOSE_ALL, ByVal 0) Call Sleep(0) ' This is a workaround to prevent the HTML Help system from crashing blnOpened = False p_FilePath = "" p_WindowHandle = 0 End Sub '============================================================================================================= ' Help_DisplayTOC ' ' This function displays the HTML Help file's Table Of Contents (TOC) page, and optionalally takes the user ' to the specified HTML page and bookmark within the HTML Help file. ' ' Param Use ' ------------------------------------ ' strInitialPage Optional. Specifies the initial HTML page to go to within the HTML Help file. ' strInitialBookmark Optional. If the "strInitialPage" property is specified, this parameter specifies ' the bookmark to jump to within the specified HTML page. ' blnCenterWindow Optional. If set to TRUE and the HTML Help page is successfully brought up, the help ' window will be centered in the middle of the screen. ' lngResizeWidth Optional. If greater than 0 and the HTML Help page is successfully brought up, the ' help window will be resized to the specified width (in pixels) ' lngResizeHeight Optional. If greater than 0 and the HTML Help page is successfully brought up, the ' help window will be resized to the specified height (in pixels) ' Return_WindowHandle Optional. If the HTML Help page is successfully brought up, this parameter returns ' the window handle of the help system displaying the page. ' Return_ErrNum Optional. If an error occurs during the execution of the function, this will return ' the error number. ' Return_ErrDesc Optional. If an error occurs during the execution of the function, this will return ' the error number. ' ' Return ' ------ ' Returns TRUE if it executed successfully. ' Returns FALSE if an error occured during execution (Return_ErrNum & Return_ErrDesc will have the error info) ' '============================================================================================================= Public Function Help_DisplayTOC(Optional ByVal strInitialPage As String, Optional ByVal strInitialBookmark As String, Optional ByVal blnCenterWindow As Boolean, Optional ByVal lngResizeWidth As Long = -1, Optional ByVal lngResizeHeight As Long = -1, Optional ByRef Return_WindowHandle As Long, Optional ByRef Return_ErrNum As Long, Optional ByRef Return_ErrDesc As String) As Boolean Dim strOpenString As String ' Set initial values Return_WindowHandle = 0 Return_ErrNum = 0 Return_ErrDesc = "" ' Make sure the HTML Help system has been initialized If blnInitialized = False Then Return_ErrNum = -1 Return_ErrDesc = "HTML Help system not yet initialized. Call the 'Help_Open' method first." Exit Function ElseIf blnOpened = False Then Return_ErrNum = -1 Return_ErrDesc = "No HTML Help file specified to open." Exit Function End If ' Create the file path string based on what was passed strOpenString = p_FilePath strInitialPage = Trim(strInitialPage) strInitialBookmark = Trim(strInitialBookmark) If strInitialPage <> "" Then strOpenString = strOpenString & "::/" & strInitialPage If strInitialBookmark <> "" Then strOpenString = strOpenString & "#" & strInitialBookmark End If End If ' Open the Table Of Contents (TOC) p_WindowHandle = HTMLHelp(p_OwnerHandle, strOpenString, HH_DISPLAY_TOC, ByVal 0) ' Check for errors If p_WindowHandle = 0 Then Call Help_GetLastError(Return_ErrNum, Return_ErrDesc) If Return_ErrDesc = "" Then Return_ErrDesc = "Failed to successfully open the HTML Help file to the Table Of Contents (TOC) tab" Else Call CenterWindow(p_WindowHandle, blnCenterWindow, lngResizeWidth, lngResizeHeight) Return_WindowHandle = p_WindowHandle Help_DisplayTOC = True End If End Function '============================================================================================================= ' Help_DisplayIndex ' ' This function displays the HTML Help file's index page, and optionalally fills in the specified keyword text. ' ' Param Use ' ------------------------------------ ' strIndexKeyword Optional. Specifies the keyword to use to bring up the index tab of the help system ' blnCenterWindow Optional. If set to TRUE and the HTML Help page is successfully brought up, the help ' window will be centered in the middle of the screen. ' lngResizeWidth Optional. If greater than 0 and the HTML Help page is successfully brought up, the ' help window will be resized to the specified width (in pixels) ' lngResizeHeight Optional. If greater than 0 and the HTML Help page is successfully brought up, the ' help window will be resized to the specified height (in pixels) ' Return_WindowHandle Optional. If the HTML Help page is successfully brought up, this parameter returns ' the window handle of the help system displaying the page. ' Return_ErrNum Optional. If an error occurs during the execution of the function, this will return ' the error number. ' Return_ErrDesc Optional. If an error occurs during the execution of the function, this will return ' the error number. ' ' Return ' ------ ' Returns TRUE if it executed successfully. ' Returns FALSE if an error occured during execution (Return_ErrNum & Return_ErrDesc will have the error info) ' '============================================================================================================= Public Function Help_DisplayIndex(Optional ByVal strIndexKeyword As String, Optional ByVal blnCenterWindow As Boolean, Optional ByVal lngResizeWidth As Long = -1, Optional ByVal lngResizeHeight As Long = -1, Optional ByRef Return_WindowHandle As Long, Optional ByRef Return_ErrNum As Long, Optional ByRef Return_ErrDesc As String) As Boolean ' Set initial values Return_WindowHandle = 0 Return_ErrNum = 0 Return_ErrDesc = "" ' Make sure the HTML Help system has been initialized If blnInitialized = False Then Return_ErrNum = -1 Return_ErrDesc = "HTML Help system not yet initialized. Call the 'Help_Open' method first." Exit Function ElseIf blnOpened = False Then Return_ErrNum = -1 Return_ErrDesc = "No HTML Help file specified to open." Exit Function End If ' Open the help INDEX If strIndexKeyword = "" Then p_WindowHandle = HTMLHelp(p_OwnerHandle, p_FilePath, HH_DISPLAY_INDEX, ByVal 0) Else p_WindowHandle = HTMLHelp(p_OwnerHandle, p_FilePath, HH_DISPLAY_INDEX, ByVal strIndexKeyword) End If ' Check for errors If p_WindowHandle = 0 Then Call Help_GetLastError(Return_ErrNum, Return_ErrDesc) If Return_ErrDesc = "" Then Return_ErrDesc = "Failed to successfully open the HTML Help file to the Index tab" Else Call CenterWindow(p_WindowHandle, blnCenterWindow, lngResizeWidth, lngResizeHeight) Return_WindowHandle = p_WindowHandle Help_DisplayIndex = True End If End Function '============================================================================================================= ' Help_DisplaySearch ' ' This function displays the HTML Help file's search page. ' ' NOTE: The HTML Help system's documentation makes it seem as if you can specify the search text and even ' start the search automatically, but this functionality does not seem to be implemented. ' ' Param Use ' ------------------------------------ ' blnCenterWindow Optional. If set to TRUE and the HTML Help page is successfully brought up, the help ' window will be centered in the middle of the screen. ' lngResizeWidth Optional. If greater than 0 and the HTML Help page is successfully brought up, the ' help window will be resized to the specified width (in pixels) ' lngResizeHeight Optional. If greater than 0 and the HTML Help page is successfully brought up, the ' help window will be resized to the specified height (in pixels) ' Return_WindowHandle Optional. If the HTML Help page is successfully brought up, this parameter returns ' the window handle of the help system displaying the page. ' Return_ErrNum Optional. If an error occurs during the execution of the function, this will return ' the error number. ' Return_ErrDesc Optional. If an error occurs during the execution of the function, this will return ' the error number. ' ' Return ' ------ ' Returns TRUE if it executed successfully. ' Returns FALSE if an error occured during execution (Return_ErrNum & Return_ErrDesc will have the error info) ' '============================================================================================================= Public Function Help_DisplaySearch(Optional ByVal blnCenterWindow As Boolean, Optional ByVal lngResizeWidth As Long = -1, Optional ByVal lngResizeHeight As Long = -1, Optional ByRef Return_WindowHandle As Long, Optional ByRef Return_ErrNum As Long, Optional ByRef Return_ErrDesc As String) As Boolean Dim FtsQuery As HH_FTS_QUERY ' Set initial values Return_WindowHandle = 0 Return_ErrNum = 0 Return_ErrDesc = "" ' Make sure the HTML Help system has been initialized If blnInitialized = False Then Return_ErrNum = -1 Return_ErrDesc = "HTML Help system not yet initialized. Call the 'Help_Open' method first." Exit Function ElseIf blnOpened = False Then Return_ErrNum = -1 Return_ErrDesc = "No HTML Help file specified to open." Exit Function End If ' Setup the default information for the UDT With FtsQuery .cbStruct = Len(FtsQuery) .fUniCodeStrings = FALSE_ .pszSearchQuery = vbNullString .iProximity = 0 .fStemmedSearch = FALSE_ .fTitleOnly = FALSE_ .fExecute = FALSE_ .pszWindow = vbNullString End With ' Open the Search window p_WindowHandle = HTMLHelp(p_OwnerHandle, p_FilePath, HH_DISPLAY_SEARCH, FtsQuery) ' Check for errors If p_WindowHandle = 0 Then Call Help_GetLastError(Return_ErrNum, Return_ErrDesc) If Return_ErrDesc = "" Then Return_ErrDesc = "Failed to successfully open the HTML Help file to the Search tab" Else Call CenterWindow(p_WindowHandle, blnCenterWindow, lngResizeWidth, lngResizeHeight) Return_WindowHandle = p_WindowHandle Help_DisplaySearch = True End If End Function '============================================================================================================= ' Help_DisplayContext ' ' This function displays the HTML Help file and brings the user to the specified help topic ID. You must map ' symbolic IDs of dialog boxes to numeric IDs in the [MAP] section of your project (.hhp) file. ' ' Param Use ' ------------------------------------ ' lngTopicID Specifies the help topic ID to show the user. If the specified topic ID does not ' exist in the HTML Help file, an error is returned. ' blnCenterWindow Optional. If set to TRUE and the HTML Help page is successfully brought up, the help ' window will be centered in the middle of the screen. ' lngResizeWidth Optional. If greater than 0 and the HTML Help page is successfully brought up, the ' help window will be resized to the specified width (in pixels) ' lngResizeHeight Optional. If greater than 0 and the HTML Help page is successfully brought up, the ' help window will be resized to the specified height (in pixels) ' Return_WindowHandle Optional. If the HTML Help page is successfully brought up, this parameter returns ' the window handle of the help system displaying the page. ' Return_ErrNum Optional. If an error occurs during the execution of the function, this will return ' the error number. ' Return_ErrDesc Optional. If an error occurs during the execution of the function, this will return ' the error number. ' ' Return ' ------ ' Returns TRUE if it executed successfully. ' Returns FALSE if an error occured during execution (Return_ErrNum & Return_ErrDesc will have the error info) ' '============================================================================================================= Public Function Help_DisplayContext(ByVal lngTopicID As Long, Optional ByVal blnCenterWindow As Boolean = False, Optional ByVal lngResizeWidth As Long = -1, Optional ByVal lngResizeHeight As Long = -1, Optional ByRef Return_WindowHandle As Long, Optional ByRef Return_ErrNum As Long, Optional ByRef Return_ErrDesc As String) As Boolean ' Set initial values Return_WindowHandle = 0 Return_ErrNum = 0 Return_ErrDesc = "" ' Make sure the HTML Help system has been initialized If blnInitialized = False Then Return_ErrNum = -1 Return_ErrDesc = "HTML Help system not yet initialized. Call the 'Help_Open' method first." Exit Function ElseIf blnOpened = False Then Return_ErrNum = -1 Return_ErrDesc = "No HTML Help file specified to open." Exit Function End If ' Open the help context p_WindowHandle = HTMLHelp(p_OwnerHandle, p_FilePath, HH_HELP_CONTEXT, ByVal lngTopicID) ' Check for errors If p_WindowHandle = 0 Then Call Help_GetLastError(Return_ErrNum, Return_ErrDesc) If Return_ErrDesc = "" Then Return_ErrDesc = "Failed to successfully open the HTML Help context with the topic ID of " & CStr(lngTopicID) & "." Else Call CenterWindow(p_WindowHandle, blnCenterWindow, lngResizeWidth, lngResizeHeight) Return_WindowHandle = p_WindowHandle Help_DisplayContext = True End If End Function '============================================================================================================= ' Help_DisplayPopUp ' ' This function takes the specified text and displays it in a Pop-Up window at the specified location on the ' screen with the specified attributes. Suggested sources of help Pop-Up text are project or DLL string ' resource files, external string table, or hard-coded context sensative help strings. ' ' Param Use ' ------------------------------------ ' strPopupText The string of text to display in the Pop-Up window ' lngForeColor Optional. If set to a valid color value, the Pop-Up text ForeColor will be set to this ' color. If the defualt (-1) is left, the system's "ToolTipText" color will be used. ' lngBackColor Optional. If set to a valid color value, the Pop-Up text BackColor will be set to this ' color. If the defualt (-1) is left, the system's "ToolTipText" color will be used. ' strFontName Optional. Specifies the name of the font to use to display the Pop-Up text. If left ' blank, the default "ToolTipText" font will be used. ' intFontSize Optioanl. Specifies the point size of the font used to display the Pop-Up text. If ' left at the default (0), the default system "ToolTipText" font size will be used. ' blnFontBold Optioanl. Specifies if the font used to display the Pop-Up text will be BOLD. ' blnFontItalic Optioanl. Specifies if the font used to display the Pop-Up text will be ITALIC. ' blnFontUnderline Optioanl. Specifies if the font used to display the Pop-Up text will be UNDERLINED. ' lngLocationX Optioanl. Specifies the X coordinate (in pixels) of the location of the upper left ' corner of the Pop-Up window relative to the upper left corner of the screen. ' lngLocationY Optioanl. Specifies the Y coordinate (in pixels) of the location of the upper left ' corner of the Pop-Up window relative to the upper left corner of the screen. ' lngMarginLeft Optioanl. Specifies how many pixels of a margin should be used between the left side ' of the Pop-Up window and the text. If left to the defatul (-1), the system default ' for "ToolTipText" windows will be used. ' lngMarginTop Optioanl. Specifies how many pixels of a margin should be used between the top ' of the Pop-Up window and the text. If left to the defatul (-1), the system default ' for "ToolTipText" windows will be used. ' lngMarginRight Optioanl. Specifies how many pixels of a margin should be used between the right side ' of the Pop-Up window and the text. If left to the defatul (-1), the system default ' for "ToolTipText" windows will be used. ' lngMarginBottom Optioanl. Specifies how many pixels of a margin should be used between the bottom ' of the Pop-Up window and the text. If left to the defatul (-1), the system default ' for "ToolTipText" windows will be used. ' Return_WindowHandle Optional. If the Pop-Up window is successfully brought up, this parameter returns ' it's window handle. ' Return_ErrNum Optional. If an error occurs during the execution of the function, this will return ' the error number. ' Return_ErrDesc Optional. If an error occurs during the execution of the function, this will return ' the error number. ' ' Return ' ------ ' Returns TRUE if it executed successfully. ' Returns FALSE if an error occured during execution (Return_ErrNum & Return_ErrDesc will have the error info) ' '============================================================================================================= Public Function Help_DisplayPopUp(ByVal strPopupText As String, _ Optional ByVal lngForeColor As Long = -1, _ Optional ByVal lngBackColor As Long = -1, _ Optional ByVal strFontName As String = "", _ Optional ByVal intFontSize As Integer = 0, _ Optional ByVal blnFontBold As Boolean = False, _ Optional ByVal blnFontItalic As Boolean = False, _ Optional ByVal blnFontUnderline As Boolean = False, _ Optional ByVal lngLocationX As Long = 0, _ Optional ByVal lngLocationY As Long = 0, _ Optional ByVal lngMarginLeft As Long = -1, _ Optional ByVal lngMarginTop As Long = -1, _ Optional ByVal lngMarginRight As Long = -1, _ Optional ByVal lngMarginBottom As Long = -1, _ Optional ByRef Return_WindowHandle As Long, _ Optional ByRef Return_ErrNum As Long, _ Optional ByRef Return_ErrDesc As String) As Boolean Dim PopupInfo As HH_POPUP Dim strFontInfo As String ' Set initial values Return_WindowHandle = 0 Return_ErrNum = 0 Return_ErrDesc = "" ' Make sure the HTML Help system has been initialized If blnInitialized = False Then Return_ErrNum = -1 Return_ErrDesc = "HTML Help system not yet initialized. Call the 'Help_Open' method first." Exit Function ElseIf blnOpened = False Then Return_ErrNum = -1 Return_ErrDesc = "No HTML Help file specified to open." Exit Function End If ' Create the font information in the required format strFontInfo = strFontName & ", " If intFontSize > 0 Then strFontInfo = strFontInfo & CStr(intFontSize) strFontInfo = strFontInfo & ", , " If blnFontBold = True Then strFontInfo = strFontInfo & "BOLD " If blnFontItalic = True Then strFontInfo = strFontInfo & "ITALIC " If blnFontUnderline = True Then strFontInfo = strFontInfo & "UNDERLINE " strFontInfo = Trim(strFontInfo) With PopupInfo .cbStruct = Len(PopupInfo) .hInst = 0 .idString = 0 .pszText = strPopupText .PT.X = lngLocationX .PT.Y = lngLocationY .clrForeground = lngForeColor .clrBackground = lngBackColor .rcMargins.Left = lngMarginBottom .rcMargins.Top = lngMarginTop .rcMargins.Right = lngMarginRight .rcMargins.Bottom = lngMarginBottom .pszFont = strFontInfo End With ' Open the Pop-Up window p_WindowHandle = HTMLHelp(p_OwnerHandle, 0, HH_DISPLAY_TEXT_POPUP, PopupInfo) ' Check for errors If p_WindowHandle = 0 Then Call Help_GetLastError(Return_ErrNum, Return_ErrDesc) If Return_ErrDesc = "" Then Return_ErrDesc = "Failed to successfully open the Pop-Up HTML Help information." Else Return_WindowHandle = p_WindowHandle Help_DisplayPopUp = True End If End Function '============================================================================================================= ' Help_GetLastError ' ' This function returns the number and description of the last error to occur within the HTML Help system. ' The error number and description returned with each of the methods of this class should be used instead of ' calling this method after each function. The reason for this is the error information does not get properly ' cleared out of the HTML Help system after each call to it, so you might get the error information for ' another HTML Help call unrelated to yours. ' ' Param Use ' ------------------------------------ ' Return_ErrNum Returns the number of the last error that occured within the HTML Help system. ' Return_ErrDesc Returns the description of the last error that occured within the HTML Help system. ' ' Return ' ------ ' (none) ' '============================================================================================================= Public Sub Help_GetLastError(ByRef Return_ErrNum As Long, ByRef Return_ErrDesc As String) Dim LastError As HH_LAST_ERROR ' If the HTML Help system has not yet been initialized, exit If blnInitialized = False Then Return_ErrNum = 0 Return_ErrDesc = "" Exit Sub End If ' Get the last error information from the HTML Help system LastError.cbStruct = Len(LastError) If HTMLHelp(0, 0, HH_GET_LAST_ERROR, LastError) = 0 Then Return_ErrNum = -1 Return_ErrDesc = "An HTML Help error occured - failed to retrieve the error information" Else Return_ErrNum = LastError.hr Return_ErrDesc = LastError.Description Return_ErrDesc = StrConv(Return_ErrDesc, vbFromUnicode) 'Convert the error information from UNICODE to ASCII End If End Sub '============================================================================================================= ' Win32API_GetLastError ' ' This function returns the number and description of the last Win32 API error that occured. ' ' Param Use ' ------------------------------------ ' Return_ErrNum Returns the number of the last Win32 API error that occured. You can optionally pass ' an error number to this parameter to get it's description. If you pass the default ' ZERO (0) to this parameter, this function attempts to find the number of the last ' error to occur. ' Return_ErrDesc Returns the description of the last Win32 API error that occured. ' ' Return ' ------ ' (none) ' '============================================================================================================= Public Sub Win32API_GetLastError(ByRef Return_ErrNum As Long, ByRef Return_ErrDesc As String) ' Get the error number if none was passed If Return_ErrNum = 0 Then Return_ErrNum = Err.LastDllError If Return_ErrNum = 0 Then Return_ErrNum = GetLastError If Return_ErrNum = 0 Then Return_ErrDesc = "" Exit Sub End If End If End If ' Get the translated error description Return_ErrDesc = String(MAX_PATH, Chr(0)) If FormatMessage(FORMAT_MESSAGE_FROM_SYSTEM, ByVal 0&, Return_ErrNum, 0, Return_ErrDesc, MAX_PATH, 0) = 0 Then Return_ErrDesc = "A Win32 API error occured - failed to retrieve the error information" Else Return_ErrDesc = Left(Return_ErrDesc, InStr(Return_ErrDesc, Chr(0)) - 1) If Right(Return_ErrDesc, Len(vbCrLf)) = vbCrLf Then Return_ErrDesc = Left(Return_ErrDesc, Len(Return_ErrDesc) - Len(vbCrLf)) End If End Sub '============================================================================================================= ' Win32API_SetLastError ' ' This function sets the number of the last Win32 API error. This is most commonly used to reset the error ' number to ZERO (0). ' ' Param Use ' ------------------------------------ ' lngErrorNumber Specifies the error number to set. ' ' Return ' ------ ' (none) ' '============================================================================================================= Public Sub Win32API_SetLastError(Optional ByVal lngErrorNumber As Long = 0) ' Set the error number passed SetLastError lngErrorNumber End Sub 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'XXXXXXXXXX PRIVATE METHODS XXXXXXXXXX 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ' This function is used locally only to center and/or change the size of the help window Private Sub CenterWindow(ByVal hWnd As Long, ByVal blnCenter As Boolean, ByVal lngResizeWidth As Long, ByVal lngResizeHeight As Long) Dim rLocation As RECT Dim lngFlags As Long Dim lngWidth As Long Dim lngHeight As Long If blnCenter = False And lngResizeWidth < 1 And lngResizeHeight < 1 Then Exit Sub If GetWindowRect(hWnd, rLocation) = FALSE_ Then Exit Sub lngWidth = rLocation.Right - rLocation.Left lngHeight = rLocation.Bottom - rLocation.Top lngFlags = SWP_NOACTIVATE Or SWP_NOOWNERZORDER Or SWP_NOZORDER If lngResizeWidth < 1 Or lngResizeHeight < 1 Then lngFlags = lngFlags Or SWP_NOSIZE Else lngWidth = lngResizeWidth lngHeight = lngResizeHeight End If If blnCenter = True Then SetWindowPos hWnd, 0, ((Screen.Width / Screen.TwipsPerPixelX) - lngWidth) / 2, ((Screen.Height / Screen.TwipsPerPixelY) - lngHeight) / 2, lngResizeWidth, lngResizeHeight, lngFlags Else lngFlags = lngFlags Or SWP_NOMOVE SetWindowPos hWnd, 0, 0, 0, lngResizeWidth, lngResizeHeight, lngFlags End If End Sub