interface/html/helpctrl.h

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