helpuser.cpp File Reference

(r1785/r1729)

#include "camtypes.h"
#include <stdlib.h>
#include "camelot.h"
#include "helpuser.h"
#include "helptabs.h"
#include "product.h"
#include "keypress.h"

Go to the source code of this file.

Defines
#define	SPLITPATH   (_tsplitpath)
#define	MAKEPATH   (_tmakepath)
#define	GETSHORTPATHNAME   ("GetShortPathNameA")
#define	TABBED_DIALOG_CLASS   (CC_RUNTIME_CLASS(DialogTabOp))
#define	BUTTON_CLASS   (TEXT("BUTTON"))
#define	NTLAUNCHER_TIMEOUT   (3)
Functions
	DECLARE_SOURCE ("$Revision: 1729 $")
static DWORD	LookupDialogTopic (LPCTSTR lpcszLookupClass, UINT32 nPageResID)
	Private helper function that finds the help topic associated with "named" dialogs, ie. those dialogs that are managed by a specialised C++ class, not error or warning dialogs.
static DWORD	LookupOperationTopic (LPCTSTR lpcszOpName)
	Private helper function that finds the help topic associated with Camelot operations, eg. those things exposed in menus!
static DWORD	LookupMessageTopic (UINT32 nMessageID)
	Private helper function that finds the help topic associated with the given message, generally diaplayed in an error or warning dialog.
static BOOL	FakeHelpButtonClick (HWND hwndDialog)
	Searches through the child windows of the given dialog, looking for a push button with the label "Help". If it finds one then the routine posts a "faked" click message for the button, so help is invoked.
static LRESULT CALLBACK EXPORT	F1HookProc (INT32 nCode, WPARAM wParam, LPARAM lParam)
static BOOL	RunOilHelp (LPCTSTR lpcszHelpPath, UINT32 nCommand, DWORD dwData)
	Private helper function that runs the system's help engine, whatever that might be, passing the given command. On Windows this is WINHELP.EXE or WINHLP32.EXE, on RISCOS it's get-the-manual-out time . . .
BOOL	MakeShortPath (LPTSTR lpszPath, size_t cchMaxLen)
	Special function to work around an ommission in Win32s, which does not include the GetShortPathName function, even though Win32s is supposed to export ALL Win32 functions. This version does nothing under Win32s, which shortens pathnames automatically (?), under other versions of Windows it dynamically links to the function in the kernel32 library, thus avoiding an explicit link to the function which would prevent the app loading.
static BOOL	ShowHelp (UINT32 nCommand, DWORD dwData)
	Called to display the given topic in the Xara Studio general help file. Makes a note if help is run successfully that we have to shut it down when we quit.
BOOL	HelpUser (const DialogOp &DlgOp)
	Public function that finds the help topic associated with the given dialog operation and runs the system help engine to display the topic.
BOOL	HelpUser (const wxDialog &dlg)
	Public function that finds the help topic associated with the given MFC dialog and runs the system help engine to display the topic.
BOOL	HelpUser (const OpDescriptor &opdesc)
	Public function that finds the help topic associated with the given OpDescriptor and runs the system help engine to display the topic.
BOOL	HelpUser (UINT32 nMessageID)
	Public function that finds the help topic associated with the given message and runs the system help engine to display the topic.
BOOL	HelpUserPropertyPage (UINT32 PageID)
	Public function that finds the help topic associated with the given property page. This is required due to the new way the tabbed dialogs work (via MFC).
BOOL	HelpUserTopic (DWORD dwHelpIndex)
	Public function that finds the help topic associated with the given message and runs the system help engine to display the topic.
BOOL	_HelpUser (LPCTSTR lpcszClassName, UINT32 nSubTopic)
	Public function that finds the help topic associated with the given object and runs the system help engine to display it. This is a "bodgey" direct-access function for invoking help in those tricky cases, such as the print-setup dialog, that do not have any Camelot object directly associated with them.
BOOL	HelpContents ()
	Runs the system help engine, displaying the "Contents" page.
BOOL	HelpUsingHelp ()
	Runs the system help engine, displaying the system's instructions for using it.
BOOL	HelpUsingTools ()
	Runs the system help engine, displaying the help on tools.
BOOL	HelpUsingGalleries ()
	Runs the system help engine, displaying the help on galleries.
BOOL	HelpOnlineDemos ()
	Runs the system help engine, displaying the on-line demos help page.
BOOL	HelpTechnicalSupport ()
	Runs the system help engine, displaying the tech support help page.
BOOL	CanHelpUser (UINT32 nMessageID)
	Public function to query whether a help topic exists for a given message. Depending on this the caller may display a help button in a message box, or may not etc.
void	SetNextMsgHelpContext (UINT32 nMessageID)
	Remembers the last format string passed to MakeMsg. If a call is made to InformWarning, InformError etc and no string resource ID is passed then we have a problem using the string resource as an index into the help file. This remembers that last one, which we use if the "error ID" is zero.
UINT32	GetNextMsgHelpContext ()
	Gets the last help context set by SetNextMsgHelpContext.
BOOL	InitHelpPath (BOOL bMainHelp)
	Initialises the help system. This should generally be called before just about everything else, so help is available for startup problems.
BOOL	HelpFileExists (LPTSTR FileName)
BOOL	InitUserHelp ()
BOOL	DeInitUserHelp ()
	Shuts down the help system. This should be called as late as possible, so help is available for app shut-down problems. Note that MFC will call WinHelp(HELP_QUIT) for us when the main frame window is destroyed.
Variables
static String_256	achzHelpPath
static TCHAR	achzMoviesHelpPath [_MAX_PATH]
static HHOOK	hF1Hook = NULL
static BOOL	fHaveUsedHelp = FALSE
static UINT32	nNextMessageHelpContext = 0

---

Define Documentation

#define BUTTON_CLASS   (TEXT("BUTTON"))

Definition at line 160 of file helpuser.cpp.

#define GETSHORTPATHNAME   ("GetShortPathNameA")

Definition at line 149 of file helpuser.cpp.

#define MAKEPATH   (_tmakepath)

Definition at line 148 of file helpuser.cpp.

#define NTLAUNCHER_TIMEOUT   (3)

Definition at line 165 of file helpuser.cpp.

#define SPLITPATH   (_tsplitpath)

Definition at line 147 of file helpuser.cpp.

#define TABBED_DIALOG_CLASS   (CC_RUNTIME_CLASS(DialogTabOp))

Definition at line 155 of file helpuser.cpp.

---

Function Documentation

BOOL _HelpUser (  LPCTSTR  lpcszClassName, UINT32  nSubTopic )

Public function that finds the help topic associated with the given object and runs the system help engine to display it. This is a "bodgey" direct-access function for invoking help in those tricky cases, such as the print-setup dialog, that do not have any Camelot object directly associated with them. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 23/5/95 Parameters: lpcszClassName  the class name of the object to run help for [INPUTS] nSubTopic which sub-topic for the object to display (by default, no sub-topic) Returns: TRUE if the help system is started successfully. See also: HelpUser; LookupDialogTopic; RunOilHelp Definition at line 799 of file helpuser.cpp. { DWORD dwHelpIndex = LookupDialogTopic(lpcszClassName, nSubTopic); if (dwHelpIndex == 0) { TRACEUSER( "Ollie", _T("Can't find raw help topic for %s (sub %lu)\n"), lpcszClassName, nSubTopic); return FALSE; } return ShowHelp(HELP_CONTEXT, dwHelpIndex); }

BOOL CanHelpUser (  UINT32  nMessageID  )

Public function to query whether a help topic exists for a given message. Depending on this the caller may display a help button in a message box, or may not etc. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Parameters: nMessageID  the resource identifier of the message that is being [INPUTS] enquired about Returns: TRUE if a help topic descrbing this message exists, FALSE otherwise. See also: LookupMessageTopic; InformGeneral Definition at line 962 of file helpuser.cpp. { // Just return TRUE if a help topic for the message exists. return LookupMessageTopic(nMessageID) != 0; }

DECLARE_SOURCE (  "$Revision: 1729 $"   )

BOOL DeInitUserHelp (   )

Shuts down the help system. This should be called as late as possible, so help is available for app shut-down problems. Note that MFC will call WinHelp(HELP_QUIT) for us when the main frame window is destroyed. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Returns: TRUE if successful. See also: InitUserHelp Definition at line 1108 of file helpuser.cpp. { PORTNOTETRACE("help", "Help function unimplemented!"); #if !defined(EXCLUDE_FROM_XARALX) // Tell the help engine we've finished using the help file(s). // NB. KNWON BUG: this doesn't do the job on Windows NT, leaving the helpfiles open. // As yet I have no idea why - it is as per the docs and works on Win32s & Chicago. if (fHaveUsedHelp) { TRACEUSER( "Ollie", _T("Closing general helpfile\n")); ShowHelp(HELP_QUIT, 0); } #ifdef STANDALONE // Same if we ran the special helpfile. if (fHaveUsedSpecHelp) { TRACEUSER( "Ollie", _T("Closing special helpfile\n")); RunOilHelp(achzSpecPath, HELP_QUIT, 0); } #endif // Remove our F1 message hook. return hF1Hook == NULL || ::UnhookWindowsHookEx(hF1Hook); #else return TRUE; #endif }

static LRESULT CALLBACK EXPORT F1HookProc (  INT32  nCode, WPARAM  wParam, LPARAM  lParam )  [static]

Definition at line 399 of file helpuser.cpp. { // Check if it's the F1 key going down within a dialog box . . . LPMSG lpmsg = (LPMSG) lParam; BOOL fHandleOK = ::IsWindow(lpmsg->hwnd); if (nCode == MSGF_DIALOGBOX && lpmsg->message == WM_KEYDOWN && lpmsg->wParam == CAMKEY(F1)) { // Simulate the help button within the dialog being clicked, if there is one. // Empirically I have discovered that the window handle contained within the // message is that of the first child window in the dialog. if (fHandleOK) FakeHelpButtonClick(::GetParent(lpmsg->hwnd)); } // Pass this event on to the next hook proc if it's valid. return (fHandleOK) ? ::CallNextHookEx(hF1Hook, nCode, wParam, lParam) : 0; }

static BOOL FakeHelpButtonClick (  HWND  hwndDialog  )  [static]

Searches through the child windows of the given dialog, looking for a push button with the label "Help". If it finds one then the routine posts a "faked" click message for the button, so help is invoked. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 31/5/95 Parameters: hwndDialog  the dialog box to fake a help button click within [INPUTS] Returns: TRUE if the fake click was possible, FALSE otherwise (maybe the dialog doesn't have a help button?) See also: F1HookProc Definition at line 341 of file helpuser.cpp. { // Make sure we've been passed a genuine window handle. if (!::IsWindow(hwndDialog)) return FALSE; // Get the text of a "help" button. String_256 strHelpLabel(_R(IDS_HELP)); // Search through all child windows of the given dialog, looking for a push-button // with the label "Help". for (HWND hwndChild = ::GetWindow(hwndDialog, GW_CHILD); hwndChild != NULL; hwndChild = ::GetWindow(hwndChild, GW_HWNDNEXT)) { // Find out the window class of the child window. TCHAR achzClassName[256]; ::GetClassName(hwndChild, achzClassName, 256); // If it is a button then examine the label. if (camStricmp(achzClassName, BUTTON_CLASS) == 0) { // It is a button. Get its label. TCHAR achzButtonLabel[256]; ::GetWindowText(hwndChild, achzButtonLabel, 256); // Does its label match the "help" label? if (camStricmp(achzButtonLabel, strHelpLabel) == 0) { // It does! Fake a click on it and return. return ::PostMessage(hwndDialog, WM_COMMAND, (WPARAM) MAKEWPARAM(::GetDlgCtrlID(hwndChild), BN_CLICKED), (LPARAM) hwndChild); } } } // No help button found, can't do it. return FALSE; }

UINT32 GetNextMsgHelpContext (   )

Gets the last help context set by SetNextMsgHelpContext. Author: Andy_Hills (Xara Group Ltd) <camelotdev@xara.com> Date: 22/11/00 Parameters: none  [INPUTS] Returns: help context See also: used by ScreenView::OnActivateView Definition at line 1002 of file helpuser.cpp. { return nNextMessageHelpContext; }

BOOL HelpContents (   )

Runs the system help engine, displaying the "Contents" page. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 12/5/95 Returns: TRUE if successful. Errors: - See also: HelpUser; HelpSearch; HelpUsingHelp Definition at line 825 of file helpuser.cpp. { #ifndef STANDALONE // If F1 was pressed, popup help in the context of the current tool. Use the tool's OpToken (of // the form "TOOL<ToolId>") to look-up its help page. Fixes #10489 if (KeyPress::IsKeyPressed(CAMKEY(F1))) { String OpToken; OpToken._MakeMsg( _T("TOOL%u"), Tool::GetCurrentID() ); DWORD dwHelpIndex = LookupOperationTopic(OpToken); return ShowHelp(HELP_CONTEXT, dwHelpIndex); } return ShowHelp(HELP_FINDER, 0); #else // STANDALONE // On the viewer go directly to the contents page on all OS's #ifdef WEBSTER return ShowHelp(HELP_CONTEXT, _R(IDH_Contents)); #else //WEBSTER return ShowHelp(HELP_CONTEXT, _R(IDH_Misc_Contents)); #endif // WEBSTER #endif // STANDALONE }

BOOL HelpFileExists (  LPTSTR  FileName  )

BOOL HelpOnlineDemos (   )

Runs the system help engine, displaying the on-line demos help page. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 12/5/95 Returns: TRUE if successful. See also: HelpUser; HelpContents; HelpSearch Definition at line 915 of file helpuser.cpp. { PORTNOTETRACE("help", "Help function unimplemented!"); #if !defined(EXCLUDE_FROM_XARALX) return RunOilHelp(achzMoviesHelpPath, 0, 0); #else return FALSE; #endif }

BOOL HelpTechnicalSupport (   )

Runs the system help engine, displaying the tech support help page. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 1/11/95 Returns: TRUE if successful. See also: HelpUser; HelpContents; HelpSearch Definition at line 937 of file helpuser.cpp. { #ifdef WEBSTER return FALSE; #else return ShowHelp(HELP_CONTEXT, _R(IDH_Misc_Tech_Support)); #endif }

BOOL HelpUser (  UINT32  nMessageID  )

Public function that finds the help topic associated with the given message and runs the system help engine to display the topic. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Parameters: nMessageID  the resource identifier of the message to display [INPUTS] help about Returns: TRUE if help was successfully provided, FALSE otherwise See also: RunOilHelp; LookupMessageTopic Definition at line 722 of file helpuser.cpp. { // Look-up the message ID in our list of help topics. If we can't find it // then return a failure code. DWORD dwHelpIndex = LookupMessageTopic(nMessageID); if (dwHelpIndex == 0) { TRACEUSER( "Ollie", _T("Can't find help topic for message 0x%lX\n"), (UINT32) nMessageID); return FALSE; } // Show this topic in the help system and return a success code. return ShowHelp(HELP_CONTEXT, dwHelpIndex); }

BOOL HelpUser (  const OpDescriptor &  opdesc  )

Public function that finds the help topic associated with the given OpDescriptor and runs the system help engine to display the topic. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Parameters: opdesc  the OpDescriptor of the Operation to provide help for [INPUTS] Returns: TRUE if help was successfully provided, FALSE if not. See also: RunOilHelp; LookupOperationTopic Definition at line 686 of file helpuser.cpp. { // Check if a help topic is already recorded within the OpDescriptor. If it isn't // then we will have to look it up instead. /* // NB. all the help topic ID's within the OpDescriptors are wrong, so ignore them! DWORD dwHelpIndex = ((OpDescriptor&) opdesc).GetHelpId(); if (dwHelpIndex == 0) dwHelpIndex = LookupOperationTopic(opdesc.Token); */ DWORD dwHelpIndex = LookupOperationTopic(opdesc.Token); if (dwHelpIndex == 0) { TRACEUSER( "Ollie", _T("Can't find help topic for the %s OpDescriptor\n"), (LPCTSTR) opdesc.Token); return FALSE; } // Show the topic we have found. return ShowHelp(HELP_CONTEXT, dwHelpIndex); }

BOOL HelpUser (  const wxDialog &  dlg  )

Public function that finds the help topic associated with the given MFC dialog and runs the system help engine to display the topic. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Parameters: dlg  the MFC dialog that requires help [INPUTS] Returns: TRUE if help was successfully provided, FALSE if not. See also: RunOilHelp; LookupDialogTopic Definition at line 656 of file helpuser.cpp. { // Look-up the class name/page ID in our list of help topics. If we can't find it // then we return a failure code. DWORD dwHelpIndex = LookupDialogTopic(dlg.GetClassInfo()->GetClassName(), 0); if (dwHelpIndex == 0) { TRACEUSER( "Ollie", _T("Can't find help topic for the %s MFC dialog\n"), (LPCTSTR) dlg.GetClassInfo()->GetClassName()); return FALSE; } // Show this topic in the help system and return a success code. return ShowHelp(HELP_CONTEXT, dwHelpIndex); }

BOOL HelpUser (  const DialogOp &  DlgOp  )

Public function that finds the help topic associated with the given dialog operation and runs the system help engine to display the topic. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Parameters: DlgOp  reference to a (constant) dialog operation to display [INPUTS] help about Returns: TRUE if help was successfully provided, FALSE if not. See also: RunOilHelp; LookupDialogTopic Definition at line 592 of file helpuser.cpp. { // Work out which page within the dialog is visible, if appropriate. We begin by // assuming this isn't relevant. UINT32 nPageResID = 0; if (DlgOp.IsKindOf(TABBED_DIALOG_CLASS)) { // Work out which is the active (top-most) page within the tabbed dialog. wxWindow* pWnd = (wxWindow*) DlgOp.WindowID; if (pWnd != NULL) { // We got the window handle, get its MFC CWnd analogue. wxBookCtrlBase* pSheet = DialogManager::GetBookControl( pWnd ); if (pSheet != NULL) { // Ask it for the resource ID of its currently active page. nPageResID = (UINT32) pSheet->GetCurrentPage()->GetId(); } #ifdef _DEBUG else { TRACEUSER( "Ollie", _T("Null OurPropSheet pointer in HelpUser\n")); } #endif } #ifdef _DEBUG else { TRACEUSER( "Ollie", _T("Null DialogOp window handle in HelpUser\n")); } #endif } // Get the run-time class name etc of the dialog. LPCTSTR lpcszDialogClass = DlgOp.GetRuntimeClass()->m_lpszClassName; // Look-up the class name/page ID in our list of help topics. If we can't find it // then we return a failure code. DWORD dwHelpIndex = LookupDialogTopic(lpcszDialogClass, nPageResID); if (dwHelpIndex == 0) { TRACEUSER( "Ollie", _T("Can't find help topic for %s dialog (page ID %lu)\n"), (LPTSTR) lpcszDialogClass, (UINT32) nPageResID); return FALSE; } // Show this topic in the help system and return a success code. return ShowHelp(HELP_CONTEXT, dwHelpIndex); }

BOOL HelpUserPropertyPage (  UINT32  PageID  )

Public function that finds the help topic associated with the given property page. This is required due to the new way the tabbed dialogs work (via MFC). Author: Richard_Millican (Xara Group Ltd) <camelotdev@xara.com> Date: 7/5/97 Parameters: PageID  ResourceID of the currently active page [INPUTS] Returns: TRUE if help was successfully provided, FALSE otherwise Definition at line 752 of file helpuser.cpp. { DWORD dwHelpIndex = LookupDialogTopic(NULL, PageID); return (HelpUserTopic(dwHelpIndex)); }

BOOL HelpUserTopic (  DWORD  dwHelpIndex  )

Public function that finds the help topic associated with the given message and runs the system help engine to display the topic. > BOOL HelpUserTopic(DWORD dwHelpIndex) Author: Will_Cowling (Xara Group Ltd) <camelotdev@xara.com> Date: 11/7/96 Parameters: nMessageID  the resource identifier of the message to display [INPUTS] help about Returns: TRUE if help was successfully provided, FALSE otherwise Definition at line 772 of file helpuser.cpp. { if (dwHelpIndex == 0) return FALSE; // Show this topic in the help system and return a success code. return ShowHelp(HELP_CONTEXT, dwHelpIndex); }

BOOL HelpUsingGalleries (   )

Runs the system help engine, displaying the help on galleries. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 12/5/95 Returns: TRUE if successful. See also: HelpUser; HelpContents; HelpSearch Definition at line 898 of file helpuser.cpp. { return ShowHelp(HELP_CONTEXT, _R(IDH_Overview_Galleries)); }

BOOL HelpUsingHelp (   )

Runs the system help engine, displaying the system's instructions for using it. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 12/5/95 Returns: TRUE if successful. See also: HelpUser; HelpContents; HelpSearch Definition at line 864 of file helpuser.cpp. { return RunOilHelp(NULL, HELP_HELPONHELP, 0); }

BOOL HelpUsingTools (   )

Runs the system help engine, displaying the help on tools. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 12/5/95 Returns: TRUE if successful. See also: HelpUser; HelpContents; HelpSearch Definition at line 881 of file helpuser.cpp. { return ShowHelp(HELP_CONTEXT, _R(IDH_Misc_Tools)); }

BOOL InitHelpPath (  BOOL  bMainHelp  )

Initialises the help system. This should generally be called before just about everything else, so help is available for startup problems. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Returns: TRUE if successful. See also: DeInitUserHelp Definition at line 1052 of file helpuser.cpp. { if( !bMainHelp ) { PORTNOTETRACE("help", "InitHelpPath does not support Movie path yet"); } // Get the locale id wxString strLocale( setlocale( LC_MESSAGES, NULL ), wxConvUTF8 ); INT32 ordSep = strLocale.Find( _T('_' ) ); if ( -1 != ordSep ) strLocale = strLocale.Left( ordSep ); TRACEUSER( "jlh92", _T("Locale = %s\n"), PCTSTR(strLocale) ); // Locale C is considered a synonym for en if( strLocale == _T("C") ) strLocale = _T("en"); // Check the help dir exists, if not bomb out wxString strHelpPath( (PCTSTR)CCamApp::GetResourceDirectory() ); strHelpPath += _T("/doc/"); TRACEUSER( "jlh92", _T("Using filter discovery directory \"%s\"\n"), PCTSTR(strHelpPath + strLocale) ); if( wxDir::Exists( strHelpPath + strLocale ) ) strHelpPath += strLocale + _T("/"); else { if( wxDir::Exists( strHelpPath + _T("en") ) ) strHelpPath += _T("en/"); #if defined(_DEBUG) else { // We'll try default location under debug to make life easier strHelpPath = _T("/usr/share/xaralx/doc/en/"); TRACEUSER( "jlh92", _T("Try = \"%s\"\n"), PCTSTR(strHelpPath) ); } #endif } achzHelpPath = strHelpPath; PORTNOTE( "help", "We should check and report non-existant help directory at some point" ) return TRUE; // wxDir::Exists( strHelpPath ); }

BOOL InitUserHelp (   )

Definition at line 1024 of file helpuser.cpp. { #if !defined(EXCLUDE_FROM_XARALX) // If we have any deferred file copies, deal with them now... HelpDownloadOp::DoDeferredFileCopy(); #endif // init main help file: BOOL bOK = InitHelpPath(TRUE); // init movies help file bOK = bOK && InitHelpPath(FALSE); #if !defined(EXCLUDE_FROM_XARALX) // Install a message filter hook to trap F1 being pressed in dialogs etc. We don't need // one for menus as our "custom menu code" (ha ha ha) does this already. hF1Hook = ::SetWindowsHookEx(WH_MSGFILTER, F1HookProc, NULL, ::GetCurrentThreadId()); ERROR3IF(hF1Hook == NULL, "Couldn't set F1 key hook in InitUserHelp"); // Success!?! return hF1Hook != NULL; #else return bOK; #endif }

static DWORD LookupDialogTopic (  LPCTSTR  lpcszLookupClass, UINT32  nPageResID )  [static]

Private helper function that finds the help topic associated with "named" dialogs, ie. those dialogs that are managed by a specialised C++ class, not error or warning dialogs. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Parameters: lpcszLookupClass  the run-time class name of the dialog to find [INPUTS] on-line help about. Can be null - in which case we just check the PageID nPageResID the resource ID of the current page, if we want help on a 'tabbed' dialog Returns: The index ID of the appropriate help topic, or zero if there isn't one. See also: HelpUser Definition at line 223 of file helpuser.cpp. { // Check we're not being passed junk. // ERROR3IF(lpcszLookupClass == NULL, "No dialog class in LookupDialogTopic"); // Scan through the whole table. for (DialogHelpTuple* ptpl = atplDialogTopics; ptpl->lpcszDialogClass != NULL; ptpl++) { // If the class-names & page ID's match then return the associated topic index. if ((lpcszLookupClass == NULL || ::camStricmp(ptpl->lpcszDialogClass, lpcszLookupClass) == 0) && ptpl->nPageResID == nPageResID) { return ptpl->dwTopicIndex; } } // Couldn't find such a dialog class. return 0; }

static DWORD LookupMessageTopic (  UINT32  nMessageID  )  [static]

Private helper function that finds the help topic associated with the given message, generally diaplayed in an error or warning dialog. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Parameters: nMessageID  the resource identifier of the message displayed in an [INPUTS] error or warning dialog Returns: The index ID of the appropriate help topic, or zero if there isn't one. See also: HelpUser Definition at line 296 of file helpuser.cpp. { #ifndef STANDALONE // If we have no message ID then use the last one passed to MakeMsg. if (nMessageID == 0) nMessageID = nNextMessageHelpContext; // Start at the beginning of the table, naturally . . . MsgHelpTuple* ptpl = atplMsgTopics; DWORD dwHelpTopic; // The table is terminated by a zero topic index. while ((dwHelpTopic = *ptpl++) != 0) { // Each sub-table is terminated by a zero message ID. while (*ptpl != 0) { // If one of the following matches the message then return the help topic. if (*ptpl++ == nMessageID) return dwHelpTopic; } // Skip over the terminating message ID. ptpl++; } #endif // No help topic for this message, so sorry. return 0; }

static DWORD LookupOperationTopic (  LPCTSTR  lpcszOpName  )  [static]

Private helper function that finds the help topic associated with Camelot operations, eg. those things exposed in menus! Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 23/5/95 Parameters: lpcszOpName  the OPTOKEN value of the Operation to look up help [INPUTS] for Returns: The index ID of the appropriate help topic, or zero if there isn't one. See also: HelpUser Definition at line 260 of file helpuser.cpp. { // Check for junk. ERROR3IF(lpcszOpName == NULL, "No valid OpToken in LookupOperationTopic"); // Scan through the whole table. for (OpHelpTuple* ptpl = atplOpTopics; ptpl->lpcszToken != NULL; ptpl++) { // If the token values match then we've found our help topic. if (::camStricmp(ptpl->lpcszToken, lpcszOpName) == 0) { return ptpl->dwTopicIndex; } } // No help topic, so sorry. return 0; }

BOOL MakeShortPath (  LPTSTR  lpszPath, size_t  cchMaxLen )

Special function to work around an ommission in Win32s, which does not include the GetShortPathName function, even though Win32s is supposed to export ALL Win32 functions. This version does nothing under Win32s, which shortens pathnames automatically (?), under other versions of Windows it dynamically links to the function in the kernel32 library, thus avoiding an explicit link to the function which would prevent the app loading. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 2/6/95 Parameters: lpszPath  the full path to shorten. The shortened version will be [INPUTS] "outputed" into this same buffer. cchMaxLen the size of the above buffer lpszPath  contains the shortened path [OUTPUTS] Returns: TRUE if successful, FALSE otherwise. Errors: - See also: - Definition at line 514 of file helpuser.cpp. { PORTNOTETRACE("help", "Help function unimplemented!"); #if !defined(EXCLUDE_FROM_XARALX) // Under Win32s we don't want to do this, because (i) Win32s does it anyway; // and (ii) the bloody GetShortPathName function isn't supported because they // forgot it (a serious bug, Mr Gates!) if (IsWin32s() && !IsWin32c()) return TRUE; // Now we have some aggro. Because GetShortPathName isn't recognised as a Win32 // function by Win32s, we must NOT have any explicit references to it in the program, // or the app won't load under Win32s. Instead, we will try to dynamically link to it. HMODULE hlib = ::GetModuleHandle(TEXT("KERNEL32")); if (hlib == NULL) { TRACEUSER( "Ollie", _T("MakeShortPath: GetModuleHandle failed (error: %lu)\n"), (UINT32) ::GetLastError()); return FALSE; } // OK, we've loaded the relevant library. Now try to link to the function it contains. typedef DWORD (WINAPI *GSPNFUNC)(LPCTSTR, LPTSTR, DWORD); GSPNFUNC lpfn = (GSPNFUNC) ::GetProcAddress(hlib, GETSHORTPATHNAME); if (lpfn == NULL) { TRACEUSER( "Ollie", _T("MakeShortPath: GetProcAddress failed (error: %lu)\n"), (UINT32) ::GetLastError()); return FALSE; } // Now call the GetShortPathName function and return a success code. DWORD dwResult = (*lpfn)(lpszPath, lpszPath, cchMaxLen); return dwResult != 0 && dwResult < cchMaxLen; #else return FALSE; #endif }

static BOOL RunOilHelp (  LPCTSTR  lpcszHelpPath, UINT32  nCommand, DWORD  dwData )  [static]

Private helper function that runs the system's help engine, whatever that might be, passing the given command. On Windows this is WINHELP.EXE or WINHLP32.EXE, on RISCOS it's get-the-manual-out time . . . Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/5/95 Parameters: lpcszHelpPath  string containing the path to the helpfile to display. [INPUTS] nCommand the command identifier to pass to the help engine, eg HELP_CONTEXT or HELP_CONTENTS. dwData extra data to pass to the help engine, eg. the topic index, or zero. Returns: TRUE if the help engine was run successfully, FALSE otherwise. See also: HelpUser Definition at line 435 of file helpuser.cpp. { #if !defined(EXCLUDE_FROM_XARALX) // Firing up the help engine can take a while, so show an hour-glass cursor. HCURSOR hOldCursor; HCURSOR hBusyCursor = ::LoadCursor(NULL, _R(IDC_WAIT)); if (hBusyCursor != NULL) hOldCursor = ::SetCursor(hBusyCursor); // We always pass the handle of the main-frame window as the "owning" window. HWND hwndInvoker = GetMainFrame()->GetSafeHwnd(); #endif // If we are running on a pure 32-bit platform such as Windows NT then we must fake // the WinHelp() function, as we want the 16-bit engine to be run, not WINHLP32.EXE. // The current help-file build includes references to 16-bit DLLs that seem to be // almost too much for the 32-bit engine. We don't have to do this if we aren't // running the engine to browse a file, but simply issuing a command, such as // HELP_HELPONHELP. BOOL fOk; // Running under Chicago or Win32s, or the helpfile parameter is NULL, so run the // "normal" engine. Here we should really "thunk" (translate) the 32-bit HWND // to a 16-bit HWND, I think? // TRACEUSER( "JustinF", _T("Help being invoked normally\n")); fOk = TRUE; if(nCommand != HELP_QUIT) { wxString strHelpFileName(lpcszHelpPath); wxString Context = _T(""); if (dwData) { Context = PCTSTR(String_256( dwData )); if (_T("") != Context) // so that the string table contains a bit less, the ::/xarax/ and .htm // are here, because they are common to every HTML help path. strHelpFileName += _T("xarax/") + Context + _T(".htm"); } CCamApp::LaunchWebBrowser( strHelpFileName ); } #if !defined(EXCLUDE_FROM_XARALX) // Get some slightly useful information if it all goes horribly wrong. #ifdef _DEBUG if (!fOk) TRACEUSER( "Ollie", _T("RunOilHelp failed - last error: %lu\n"), (UINT32) ::GetLastError()); #endif // Undo the hour-glass cursor and return a success code. if (hBusyCursor != NULL) ::SetCursor(hOldCursor); #endif return fOk; }

void SetNextMsgHelpContext (  UINT32  nMessageID  )

Remembers the last format string passed to MakeMsg. If a call is made to InformWarning, InformError etc and no string resource ID is passed then we have a problem using the string resource as an index into the help file. This remembers that last one, which we use if the "error ID" is zero. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 15/5/95 Parameters: nMessageID  the last message format string passed to MakeMsg [INPUTS] See also: StringBase::MakeMsg Definition at line 983 of file helpuser.cpp. { nNextMessageHelpContext = nMessageID; //TRACEUSER( "Andy", _T("\tSetNextMsgHelpContext(%d)\n"), nMessageID); }

static BOOL ShowHelp (  UINT32  nCommand, DWORD  dwData )  [static]

Called to display the given topic in the Xara Studio general help file. Makes a note if help is run successfully that we have to shut it down when we quit. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 11/6/95 Parameters: nCommand  the command to pass to the help engine, eg. HELP_CONTENTS [INPUTS] Returns: TRUE if successful. Definition at line 566 of file helpuser.cpp. { BOOL fResult = RunOilHelp(achzHelpPath, nCommand, dwData); if (!fHaveUsedHelp && fResult) fHaveUsedHelp = TRUE; return fResult; }

---

Variable Documentation

String_256 achzHelpPath [static]

Definition at line 173 of file helpuser.cpp.

TCHAR achzMoviesHelpPath[_MAX_PATH] [static]

Definition at line 177 of file helpuser.cpp.

BOOL fHaveUsedHelp = FALSE [static]

Definition at line 190 of file helpuser.cpp.

HHOOK hF1Hook = NULL [static]

Definition at line 185 of file helpuser.cpp.

UINT32 nNextMessageHelpContext = 0 [static]

Definition at line 199 of file helpuser.cpp.

---