helpuser.h File Reference

(r1785/r1729)

Go to the source code of this file.

Functions
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=0)
	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	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.

---

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; }

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 }

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 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 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 }

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); }

---