interface/html/helpctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/helpctrl.h
   3 // Purpose:     interface of wxHtmlHelpController
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlHelpController
  11     @headerfile helpctrl.h wx/html/helpctrl.h
  12
  13     This help controller provides an easy way of displaying HTML help in your
  14     application (see @e test sample). The help system is based on @b books
  15     (see wxHtmlHelpController::AddBook). A book is a logical
  16     section of documentation (for example "User's Guide" or "Programmer's Guide" or
  17     "C++ Reference" or "wxWidgets Reference"). The help controller can handle as
  18     many books as you want.
  19
  20     Although this class has an API compatible with other wxWidgets
  21     help controllers as documented by wxHelpController, it
  22     is recommended that you use the enhanced capabilities of wxHtmlHelpController's
  23     API.
  24
  25     wxHTML uses Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc) as
  26     its
  27     native format. The file format is described here().
  28     Have a look at docs/html/ directory where sample project files are stored.
  29
  30     You can use Tex2RTF to produce these files when generating HTML, if you set @b
  31     htmlWorkshopFiles to @b @true in
  32     your tex2rtf.ini file. The commercial tool HelpBlocks (www.helpblocks.com) can
  33     also create these files.
  34
  35     @library{wxhtml}
  36     @category{help}
  37
  38     @see @ref overview_wxhelpcontroller "Information about wxBestHelpController",
  39     wxHtmlHelpFrame, wxHtmlHelpDialog, wxHtmlHelpWindow, wxHtmlModalHelp
  40 */
  41 class wxHtmlHelpController
  42 {
  43 public:
  44     /**
  45         Constructor.
  46     */
  47     wxHtmlHelpController(int style = wxHF_DEFAULT_STYLE,
  48                          wxWindow* parentWindow = NULL);
  49
  50     //@{
  51     /**
  52         Adds book (@ref overview_helpformat ".hhp file" - HTML Help Workshop project
  53         file) into the list of loaded books.
  54         This must be called at least once before displaying  any help.
  55         @a bookFile or @a bookUrl  may be either .hhp file or ZIP archive
  56         that contains arbitrary number of .hhp files in
  57         top-level directory. This ZIP archive must have .zip or .htb extension
  58         (the latter stands for "HTML book"). In other words, @c
  59         AddBook(wxFileName("help.zip"))
  60         is possible and is the recommended way.
  61
  62         @param showWaitMsg
  63             If @true then a decoration-less window with progress message is displayed.
  64         @param bookFile
  65             Help book filename. It is recommended to use this prototype
  66             instead of the one taking URL, because it is less error-prone.
  67         @param bookUrl
  68             Help book URL (note that syntax of filename and URL is
  69             different on most platforms)
  70     */
  71     bool AddBook(const wxFileName& bookFile, bool showWaitMsg);
  72     bool AddBook(const wxString& bookUrl, bool showWaitMsg);
  73     //@}
  74
  75     /**
  76         This protected virtual method may be overridden so that when specifying the
  77         wxHF_DIALOG style, the controller
  78         uses a different dialog.
  79     */
  80     virtual wxHtmlHelpDialog* CreateHelpDialog(wxHtmlHelpData* data);
  81
  82     /**
  83         This protected virtual method may be overridden so that the controller
  84         uses a different frame.
  85     */
  86     virtual wxHtmlHelpFrame* CreateHelpFrame(wxHtmlHelpData* data);
  87
  88     //@{
  89     /**
  90         This alternative form is used to search help contents by numeric IDs.
  91     */
  92     void Display(const wxString& x);
  93     void Display(const int id);
  94     //@}
  95
  96     /**
  97         Displays help window and focuses contents panel.
  98     */
  99     void DisplayContents();
 100
 101     /**
 102         Displays help window and focuses index panel.
 103     */
 104     void DisplayIndex();
 105
 106     /**
 107         Displays help window, focuses search panel and starts searching.  Returns @true
 108         if the keyword was found. Optionally it searches through the index (mode =
 109         wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL).
 110         @b Important: KeywordSearch searches only pages listed in .hhc file(s).
 111         You should list all pages in the contents file.
 112     */
 113     bool KeywordSearch(const wxString& keyword,
 114                        wxHelpSearchMode mode = wxHELP_SEARCH_ALL);
 115
 116     /**
 117         Reads the controller's setting (position of window, etc.)
 118     */
 119     void ReadCustomization(wxConfigBase* cfg,
 120                            wxString path = wxEmptyString);
 121
 122     /**
 123         Sets the path for storing temporary files - cached binary versions of index and
 124         contents files. These binary
 125         forms are much faster to read. Default value is empty string (empty string means
 126         that no cached data are stored). Note that these files are @e not
 127         deleted when program exits.
 128         Once created these cached files will be used in all subsequent executions
 129         of your application. If cached files become older than corresponding .hhp
 130         file (e.g. if you regenerate documentation) it will be refreshed.
 131     */
 132     void SetTempDir(const wxString& path);
 133
 134     /**
 135         Sets format of title of the frame. Must contain exactly one "%s"
 136         (for title of displayed HTML page).
 137     */
 138     void SetTitleFormat(const wxString& format);
 139
 140     /**
 141         Associates @a config object with the controller.
 142         If there is associated config object, wxHtmlHelpController automatically
 143         reads and writes settings (including wxHtmlWindow's settings) when needed.
 144         The only thing you must do is create wxConfig object and call UseConfig.
 145         If you do not use @e UseConfig, wxHtmlHelpController will use
 146         default wxConfig object if available (for details see
 147         wxConfigBase::Get and
 148         wxConfigBase::Set).
 149     */
 150     void UseConfig(wxConfigBase* config,
 151                    const wxString& rootpath = wxEmptyString);
 152
 153     /**
 154         Stores controllers setting (position of window etc.)
 155     */
 156     void WriteCustomization(wxConfigBase* cfg,
 157                             wxString path = wxEmptyString);
 158 };
 159
 160
 161
 162 /**
 163     @class wxHtmlModalHelp
 164     @headerfile helpctrl.h wx/html/helpctrl.h
 165
 166     This class uses wxHtmlHelpController
 167     to display help in a modal dialog. This is useful on platforms such as wxMac
 168     where if you display help from a modal dialog, the help window must itself be a
 169     modal
 170     dialog.
 171
 172     Create objects of this class on the stack, for example:
 173
 174     @code
 175     // The help can be browsed during the lifetime of this object; when the user
 176     quits
 177         // the help, program execution will continue.
 178         wxHtmlModalHelp help(parent, wxT("help"), wxT("My topic"));
 179     @endcode
 180
 181     @library{wxhtml}
 182     @category{FIXME}
 183 */
 184 class wxHtmlModalHelp
 185 {
 186 public:
 187     /**
 188         @param parent
 189             is the parent of the dialog.
 190         @param helpFile
 191             is the HTML help file to show.
 192         @param topic
 193             is an optional topic. If this is empty, the help contents will be shown.
 194         @param style
 195             is a combination of the flags described in the wxHtmlHelpController
 196         documentation.
 197     */
 198     wxHtmlModalHelp(wxWindow* parent, const wxString& helpFile,
 199                     const wxString& topic = wxEmptyString,
 200                     int style = wxHF_DEFAULT_STYLE | wxHF_DIALOG | wxHF_MODAL);
 201 };
 202