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