interface/help.h

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