Overview
WebWorks Help provides full featured, cross-platform, cross-browser HTML based help without compromises. Many companies have chosen to deploy WebWorks Help systems for their applications. WebWorks Help enables technical writers to make major changes to documentation without requiring development to modify context-sensitive help calls in their code. This affords technical writers the freedom they require without placing development schedules at risk.
Despite the advantages given by WebWorks Help to technical writers and developers, a significant problem remains. How do developers easily display context-sensitive help links in a user's default browser?
The answer is WebWorks Help 4.0 API.
The WebWorks Help 4.0 API is written in ANSI compliant C for portability. It compiles cleanly and runs on a variety of Windows, Macintosh, and UNIX operating systems. Full source code is provided.
Description
WebWorks Help 4.0 API supports detecting the user's current default browser and sending help topics to the browser for display. Additionally, the API will attempt to update a help topic without reloading the entire frameset. This avoids re-initialization of the Java or JavaScript navigation systems.
WebWorks Help 4.0 API supports connections to Internet Explorer 4.0 and above, Netscape 4.x, Netscape 6.x, and Mozilla browsers running on the Windows, Macintosh, and UNIX platforms. Internet Explorer and Netscape compatible browsers may also work with the API but are not guaranteed to support reuse of help system frame sets.
API Functions
WebWorks Help 4.0 API consists of the following functions:
int WWHelp_Startup(const char* pParamBaseURL); int WWHelp_Shutdown(); int WWHelp_DisplayHelp(const char* pParamContext, const char* pParamTopic); int WWHelp_DisplayHelpWithNavigation(const char* pParamContext, const char* pParamTopic); int WWHelp_DisplayHelpWithContents(const char* pParamContext, const char* pParamTopic); int WWHelp_DisplayHelpWithIndex(const char* pParamContext, const char* pParamTopic); int WWHelp_DisplayHelpWithSearch(const char* pParamContext, const char* pParamTopic); int WWHelp_DisplayHelpWithFavorites(const char* pParamContext, const char* pParamTopic); int WWHelp_DisplayHelpNavigation(); int WWHelp_DisplayHelpContents(); int WWHelp_DisplayHelpIndex(); int WWHelp_DisplayHelpSearch(); int WWHelp_DisplayHelpFavorites();All functions return 0 if successful and non-zero if an error occurs.
API Usage
Developers need to insert a call to
WWHelp_Startup
during program initialization and a call toWWHelp_Shutdown
just before the program exits. The call toWWHelp_Startup
takes a single parameter, a C style, NULL terminated string that specifies the location of the help set. This string should point to the directory containing the help set and should not include a filename such as "index.htm".To display context-sensitive help topics, developers should call either
WWHelp_DisplayHelp
orWWHelp_DisplayHelpWithNavigation
. The first function,WWHelp_DisplayHelp
, displays the help topic without navigation aides such as a table of contents, index, or search options. The second function,WWHelp_DisplayHelpWithNavigation
, will display the help topic with navigation aides. The callsWWHelp_DisplayHelpWithContents
,WWHelp_DisplayHelpWithIndex
,WWHelp_DisplayHelpWithSearch
, andWWHelp_DisplayHelpWithFavorites
allow developers to display context-sensitive help with a particular tab selected.To display the help set with navigation, developers should call
WWHelp_DisplayHelpNavigation
. This will display the help set in the default browser with navigation aides. The callsWWHelp_DisplayHelpContents
,WWHelp_DisplayHelpIndex
,WWHelp_DisplayHelpSearch
, andWWHelp_DisplayHelpFavorites
allow developers to display the help set with a particular tab selected.Note
Since the WebWorks API functions always attempt to reuse the existing frameset, callingWWHelp_DisplayHelpWithNavigation
will not reload the frameset in order to display navigation aides. Similarly, callingWWHelp_DisplayHelp
will not reload the frameset to eliminate navigation aides.Platform Notes
Each platform may require platform-specific initializations before using the WebWorks Help 4.0 API.
Windows
Under Windows, developers must include<objbase.h>
and callCoInitialize
during program initialization andCoUninitialize
before the program exits. These calls are required since the WebWorks Help 4.0 API uses COM to communicate with running instances of Internet Explorer. These calls cannot be made inside ofWWHelp_Startup
andWWHelp_Shutdown
since they must be called once and only once for your program.
Required libraries:kernel32.lib
,user32.lib
,advapi32.lib
,oleaut32.lib
,ole32.lib
,uuid.lib
The Windows platform also supports calling the API via Visual Basic from a DLL and Windows platform languages (C#, VB .Net, VBScript, etc.) via COM. The following interfaces are used to support these runtimes:
int WWHelp_VB_Startup(const char* pParamBaseURL); int WWHelp_VB_Shutdown(); int WWHelp_VB_DisplayHelp(const char* pParamContext, const char* pParamTopic); int WWHelp_VB_DisplayHelpWithNavigation(const char* pParamContext, const char* pParamTopic); int WWHelp_VB_DisplayHelpWithContents(const char* pParamContext, const char* pParamTopic); int WWHelp_VB_DisplayHelpWithIndex(const char* pParamContext, const char* pParamTopic); int WWHelp_VB_DisplayHelpWithSearch(const char* pParamContext, const char* pParamTopic); int WWHelp_VB_DisplayHelpWithFavorites(const char* pParamContext, const char* pParamTopic); int WWHelp_VB_DisplayHelpNavigation(); int WWHelp_VB_DisplayHelpContents(); int WWHelp_VB_DisplayHelpIndex(); int WWHelp_VB_DisplayHelpSearch(); int WWHelp_VB_DisplayHelpFavorites();The BSTR API is used to implement the "WWHelp4.API" COM interface.
int WWHelp_BSTR_Startup(const BSTR ParamBaseURL); int WWHelp_BSTR_Shutdown(); int WWHelp_BSTR_DisplayHelp(const BSTR ParamContext, const BSTR ParamTopic); int WWHelp_BSTR_DisplayHelpWithNavigation(const BSTR ParamContext, const BSTR ParamTopic); int WWHelp_BSTR_DisplayHelpWithContents(const BSTR ParamContext, const BSTR ParamTopic); int WWHelp_BSTR_DisplayHelpWithIndex(const BSTR ParamContext, const BSTR ParamTopic); int WWHelp_BSTR_DisplayHelpWithSearch(const BSTR ParamContext, const BSTR ParamTopic); int WWHelp_BSTR_DisplayHelpWithFavorites(const BSTR ParamContext, const BSTR ParamTopic); int WWHelp_BSTR_DisplayHelpNavigation(); int WWHelp_BSTR_DisplayHelpContents(); int WWHelp_BSTR_DisplayHelpIndex(); int WWHelp_BSTR_DisplayHelpSearch(); int WWHelp_BSTR_DisplayHelpFavorites();Macintosh
No Macintosh specific initialization is required for the WebWorks Help 4.0 API. However, it is recommended that developers callLSInit
during program initialization andLSTerm
before the program exits. This will minimize the performance overhead associated with using Launch Services under Mac OS X.
Additionally, developers should be aware that WebWorks Help 4.0 API creates temporary instances of InternetConfig to access browser information during calls toWWHelp_Comm_SetDefaultBrowserInfo
. No known side-effects occur if your application maintains it's own InternetConfig instance. However, if problems do arise, you will need to modify theWWHelp_Comm_SetDefaultBrowserInfo
function to use your application's InternetConfig instance.
Projects created under Metrowerks Codewarrior should enable the "Interpret DOS and Unix paths" option under "Target", "Access Paths". Additionally, developers should specify "Prefix File:" under "Language", "C/C++ Language" to point to a header file that definesTARGET_API_MAC_OS8
,TARGET_API_MAC_CARBON
,TARGET_API_MAC_OSX
, andCALL_NOT_IN_CARBON
as required before including Apple's<ConditionalMacros.h>
header file.
Carbon builds require the latest available Carbon SDK, currently Carbon 1.4 SDK.
Required libraries for Classic applications:InterfaceLib
,InternetConfigLib
,MathLib
Required libraries for Carbon applications:CarbonLib
CarbonFrameworkLib
Unix
No Unix specific initialization is required for the WebWorks Help 4.0 API.API Example
Below is an example program that uses the WebWorks Help 4.0 API to display a context-sensitive topic defined in the example help set.
#include "wwhelp/wwhapi.h" #include <stdio.h> #include <string.h> #if defined(_WIN32) #include <objbase.h> #elif TARGET_OS_MAC #if (TARGET_API_MAC_CARBON) #include <CodeFragments.h> #include <LaunchServices.h> #endif #else #endif int main(int argc, char* argv[]) { char* pBaseHelpURL = "file:///P:/work/wwhapi/example/helpset"; int ReturnCode; /* Platform specific initializations */ /* */ #if defined(_WIN32) CoInitialize(NULL); #elif TARGET_OS_MAC #if (TARGET_API_MAC_CARBON) if (((UInt32)LSInit) != ((UInt32)kUnresolvedCFragSymbolAddress)) { LSInit(kLSInitializeDefaults); } #endif #else #endif /* Initialize WWHelp API */ /* */ ReturnCode = WWHelp_Startup(pBaseHelpURL); if (ReturnCode == 0) { /* Display help URL */ /* */ ReturnCode = WWHelp_DisplayHelp("beta", "section2"); /* Shutdown WWHelp API */ /* */ WWHelp_Shutdown(); } /* Platform specific cleanup */ /* */ #if defined(_WIN32) CoUninitialize(); #elif TARGET_OS_MAC #if (TARGET_API_MAC_CARBON) if (((UInt32)LSTerm) != ((UInt32)kUnresolvedCFragSymbolAddress)) { LSTerm(); } #endif #else #endif return ReturnCode; }