docs/latex/wx/helpinst.tex

   1 \section{\class{wxHelpController}}\label{wxhelpcontroller}
   2
   3 This is a family of classes by which
   4 applications may invoke a help viewer to provide on-line help.
   5
   6 A help controller allows an application to display help, at the contents
   7 or at a particular topic, and shut the help program down on termination.
   8 This avoids proliferation of many instances of the help viewer whenever the
   9 user requests a different topic via the application's menus or buttons.
  10
  11 Typically, an application will create a help controller instance
  12 when it starts, and immediately call {\bf Initialize}\rtfsp
  13 to associate a filename with it. The help viewer will only get run, however,
  14 just before the first call to display something.
  15
  16 Most help controller classes actually derive from wxHelpControllerBase and have
  17 names of the form wxXXXHelpController or wxHelpControllerXXX. An
  18 appropriate class is aliased to the name wxHelpController for each platform, as follows:
  19
  20 \begin{itemize}\itemsep=0pt
  21 \item On desktop Windows, wxCHMHelpController is used (MS HTML Help).
  22 \item On Windows CE, wxWinceHelpController is used.
  23 \item On all other platforms, wxHtmlHelpController is used if wxHTML is
  24 compiled into wxWidgets; otherwise wxExtHelpController is used (for invoking an external
  25 browser).
  26 \end{itemize}
  27
  28 The remaining help controller classes need to be named
  29 explicitly by an application that wishes to make use of them.
  30
  31 There are currently the following help controller classes defined:
  32
  33 \begin{itemize}\itemsep=0pt
  34 \item wxWinHelpController, for controlling Windows Help.
  35 \item wxCHMHelpController, for controlling MS HTML Help. To use this, you need to set wxUSE\_MS\_HTML\_HELP
  36 to 1 in setup.h and have htmlhelp.h header from Microsoft's HTML Help kit (you don't need
  37 VC++ specific htmlhelp.lib because wxWidgets loads necessary DLL at runtime and so it
  38 works with all compilers).
  39 \item wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime is
  40 not available, \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}. You need to provide
  41 {\bf both} CHM and HTB versions of the help file. For 32bit Windows only.
  42 \item wxExtHelpController, for controlling external browsers under Unix.
  43 The default browser is Netscape Navigator. The 'help' sample shows its use.
  44 \item wxWinceHelpController, for controlling a simple {\tt .htm} help controller for Windows CE applications.
  45 \item \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, a sophisticated help controller using \helpref{wxHTML}{wxhtml}, in
  46 a similar style to the Microsoft HTML Help viewer and using some of the same files.
  47 Although it has an API compatible with other help controllers, it has more advanced features, so it is
  48 recommended that you use the specific API for this class instead. Note that if you
  49 use .zip or .htb formats for your books, you
  50 must add this line to your application initialization: {\tt wxFileSystem::AddHandler(new wxZipFSHandler);}
  51 or nothing will be shown in your help window.
  52 \end{itemize}
  53
  54 \wxheading{Derived from}
  55
  56 wxHelpControllerBase\\
  57 \helpref{wxObject}{wxobject}
  58
  59 \wxheading{Include files}
  60
  61 <wx/help.h> (wxWidgets chooses the appropriate help controller class)\\
  62 <wx/helpbase.h> (wxHelpControllerBase class)\\
  63 <wx/helpwin.h> (Windows Help controller)\\
  64 <wx/msw/helpchm.h> (MS HTML Help controller)\\
  65 <wx/generic/helpext.h> (external HTML browser controller)\\
  66 <wx/html/helpctrl.h> (wxHTML based help controller: wxHtmlHelpController)
  67
  68 \wxheading{See also}
  69
  70 \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, \helpref{wxHTML}{wxhtml}
  71
  72 \latexignore{\rtfignore{\wxheading{Members}}}
  73
  74 \membersection{wxHelpController::wxHelpController}\label{wxhelpcontrollerctor}
  75
  76 \func{}{wxHelpController}{\void}
  77
  78 Constructs a help instance object, but does not invoke the help viewer.
  79
  80 \membersection{wxHelpController::\destruct{wxHelpController}}\label{wxhelpcontrollerdtor}
  81
  82 \func{}{\destruct{wxHelpController}}{\void}
  83
  84 Destroys the help instance, closing down the viewer if it is running.
  85
  86 \membersection{wxHelpController::Initialize}\label{wxhelpcontrollerinitialize}
  87
  88 \func{virtual void}{Initialize}{\param{const wxString\& }{file}}
  89
  90 \func{virtual void}{Initialize}{\param{const wxString\& }{file}, \param{int}{ server}}
  91
  92 Initializes the help instance with a help filename, and optionally a server socket
  93 number if using wxHelp (now obsolete). Does not invoke the help viewer.
  94 This must be called directly after the help instance object is created and before
  95 any attempts to communicate with the viewer.
  96
  97 You may omit the file extension and a suitable one will be chosen. For
  98 wxHtmlHelpController, the extensions zip, htb and hhp will be appended while searching for
  99 a suitable file. For WinHelp, the hlp extension is appended.
 100
 101 \membersection{wxHelpController::DisplayBlock}\label{wxhelpcontrollerdisplayblock}
 102
 103 \func{virtual bool}{DisplayBlock}{\param{long}{ blockNo}}
 104
 105 If the help viewer is not running, runs it and displays the file at the given block number.
 106
 107 {\it WinHelp:} Refers to the context number.
 108
 109 {\it MS HTML Help:} Refers to the context number.
 110
 111 {\it External HTML help:} the same as for \helpref{wxHelpController::DisplaySection}{wxhelpcontrollerdisplaysection}.
 112
 113 {\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}.
 114
 115 This function is for backward compatibility only, and applications should use \helpref{wxHelpController}{wxhelpcontrollerdisplaysection} instead.
 116
 117 \membersection{wxHelpController::DisplayContents}\label{wxhelpcontrollerdisplaycontents}
 118
 119 \func{virtual bool}{DisplayContents}{\void}
 120
 121 If the help viewer is not running, runs it and displays the
 122 contents.
 123
 124 \membersection{wxHelpController::DisplayContextPopup}\label{wxhelpcontrollerdisplaycontextpopup}
 125
 126 \func{virtual bool}{DisplayContextPopup}{\param{int }{contextId}}
 127
 128 Displays the section as a popup window using a context id.
 129
 130 Returns false if unsuccessful or not implemented.
 131
 132 \membersection{wxHelpController::DisplaySection}\label{wxhelpcontrollerdisplaysection}
 133
 134 \func{virtual bool}{DisplaySection}{\param{const wxString\&}{ section}}
 135
 136 If the help viewer is not running, runs it and displays the given section.
 137
 138 The interpretation of {\it section} differs between help viewers. For most viewers,
 139 this call is equivalent to KeywordSearch. For MS HTML Help, wxHTML help and external HTML help,
 140 if {\it section} has a .htm
 141 or .html extension, that HTML file will be displayed; otherwise
 142 a keyword search is done.
 143
 144 \func{virtual bool}{DisplaySection}{\param{int}{ sectionNo}}
 145
 146 If the help viewer is not running, runs it and displays the given section.
 147
 148 {\it WinHelp, MS HTML Help} {\it sectionNo} is a context id.
 149
 150 {\it External HTML help:} wxExtHelpController implements {\it sectionNo} as an id in a map file, which is of the form:
 151
 152 \begin{verbatim}
 153 0  wx.html             ; Index
 154 1  wx34.html#classref  ; Class reference
 155 2  wx204.html          ; Function reference
 156 \end{verbatim}
 157
 158 {\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}.
 159
 160 See also the help sample for notes on how to specify section numbers for various help file formats.
 161
 162 \membersection{wxHelpController::DisplayTextPopup}\label{wxhelpcontrollerdisplaytextpopup}
 163
 164 \func{virtual bool}{DisplayTextPopup}{\param{const wxString\&}{ text}, \param{const wxPoint\& }{pos}}
 165
 166 Displays the text in a popup window, if possible.
 167
 168 Returns false if unsuccessful or not implemented.
 169
 170 \membersection{wxHelpController::GetFrameParameters}\label{wxhelpcontrollergetframeparameters}
 171
 172 \func{virtual wxFrame *}{GetFrameParameters}{\param{const wxSize * }{size = NULL}, \param{const wxPoint * }{pos = NULL},
 173  \param{bool *}{newFrameEachTime = NULL}}
 174
 175 wxHtmlHelpController returns the frame, size and position.
 176
 177 For all other help controllers, this function does nothing
 178 and just returns NULL.
 179
 180 \wxheading{Parameters}
 181
 182 \docparam{viewer}{This defaults to "netscape" for wxExtHelpController.}
 183
 184 \docparam{flags}{This defaults to wxHELP\_NETSCAPE for wxExtHelpController, indicating
 185 that the viewer is a variant of Netscape Navigator.}
 186
 187 \membersection{wxHelpController::KeywordSearch}\label{wxhelpcontrollerkeywordsearch}
 188
 189 \func{virtual bool}{KeywordSearch}{\param{const wxString\& }{keyWord}, \param{wxHelpSearchMode }{mode = wxHELP\_SEARCH\_ALL}}
 190
 191 If the help viewer is not running, runs it, and searches for sections matching
 192 the given keyword. If one match is found, the file is displayed at this
 193 section. The optional parameter allows the search the index
 194 (wxHELP\_SEARCH\_INDEX) but this currently only supported by the
 195 wxHtmlHelpController.
 196
 197 {\it WinHelp, MS HTML Help:} If more than one match is found,
 198 the first topic is displayed.
 199
 200 {\it External HTML help, simple wxHTML help:} If more than one match is found,
 201 a choice of topics is displayed.
 202
 203 {\it wxHtmlHelpController:} see \helpref{wxHtmlHelpController::KeywordSearch}{wxhtmlhelpcontrollerkeywordsearch}.
 204
 205 \membersection{wxHelpController::LoadFile}\label{wxhelpcontrollerloadfile}
 206
 207 \func{virtual bool}{LoadFile}{\param{const wxString\& }{file = ""}}
 208
 209 If the help viewer is not running, runs it and loads the given file.
 210 If the filename is not supplied or is
 211 empty, the file specified in {\bf Initialize} is used. If the viewer is
 212 already displaying the specified file, it will not be reloaded. This
 213 member function may be used before each display call in case the user
 214 has opened another file.
 215
 216 wxHtmlHelpController ignores this call.
 217
 218 \membersection{wxHelpController::OnQuit}\label{wxhelpcontrolleronquit}
 219
 220 \func{virtual bool}{OnQuit}{\void}
 221
 222 Overridable member called when this application's viewer is quit by the user.
 223
 224 This does not work for all help controllers.
 225
 226 \membersection{wxHelpController::SetFrameParameters}\label{wxhelpcontrollersetframeparameters}
 227
 228 \func{virtual void}{SetFrameParameters}{\param{const wxString \& }{title},
 229  \param{const wxSize \& }{size}, \param{const wxPoint \& }{pos = wxDefaultPosition},
 230  \param{bool }{newFrameEachTime = false}}
 231
 232 For wxHtmlHelpController, the title is set (again with \%s indicating the
 233 page title) and also the size and position of the frame if the frame is already
 234 open. {\it newFrameEachTime} is ignored.
 235
 236 For all other help controllers this function has no effect.
 237
 238 \membersection{wxHelpController::SetViewer}\label{wxhelpcontrollersetviewer}
 239
 240 \func{virtual void}{SetViewer}{\param{const wxString\& }{viewer}, \param{long}{ flags}}
 241
 242 Sets detailed viewer information. So far this is only relevant to wxExtHelpController.
 243
 244 Some examples of usage:
 245
 246 \begin{verbatim}
 247   m_help.SetViewer("kdehelp");
 248   m_help.SetViewer("gnome-help-browser");
 249   m_help.SetViewer("netscape", wxHELP_NETSCAPE);
 250 \end{verbatim}
 251
 252 \membersection{wxHelpController::Quit}\label{wxhelpcontrollerquit}
 253
 254 \func{virtual bool}{Quit}{\void}
 255
 256 If the viewer is running, quits it by disconnecting.
 257
 258 For Windows Help, the viewer will only close if no other application is using it.
 259