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         @a bookFile or @a bookUrl  may be either .hhp file or ZIP archive
  57         that contains arbitrary number of .hhp files in
  58         top-level directory. This ZIP archive must have .zip or .htb extension
  59         (the latter stands for "HTML book"). In other words, @c
  60         AddBook(wxFileName("help.zip"))
  61         is possible and is the recommended way.
  62
  63         @param showWaitMsg
  64             If @true then a decoration-less window with progress message is displayed.
  65         @param bookFile
  66             Help book filename. It is recommended to use this prototype
  67             instead of the one taking URL, because it is less error-prone.
  68         @param bookUrl
  69             Help book URL (note that syntax of filename and URL is
  70             different on most platforms)
  71     */
  72     bool AddBook(const wxFileName& bookFile, bool showWaitMsg);
  73     bool AddBook(const wxString& bookUrl, bool showWaitMsg);
  74     //@}
  75
  76     /**
  77         This protected virtual method may be overridden so that when specifying the
  78         wxHF_DIALOG style, the controller
  79         uses a different dialog.
  80     */
  81     virtual wxHtmlHelpDialog* CreateHelpDialog(wxHtmlHelpData* data);
  82
  83     /**
  84         This protected virtual method may be overridden so that the controller
  85         uses a different frame.
  86     */
  87     virtual wxHtmlHelpFrame* CreateHelpFrame(wxHtmlHelpData* data);
  88
  89     //@{
  90     /**
  91         This alternative form is used to search help contents by numeric IDs.
  92     */
  93     void Display(const wxString& x);
  94     void Display(const int id);
  95     //@}
  96
  97     /**
  98         Displays help window and focuses contents panel.
  99     */
 100     void DisplayContents();
 101
 102     /**
 103         Displays help window and focuses index panel.
 104     */
 105     void DisplayIndex();
 106
 107     /**
 108         Displays help window, focuses search panel and starts searching.  Returns @true
 109         if the keyword was found. Optionally it searches through the index (mode =
 110         wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL).
 111         @b Important: KeywordSearch searches only pages listed in .hhc file(s).
 112         You should list all pages in the contents file.
 113     */
 114     bool KeywordSearch(const wxString& keyword,
 115                        wxHelpSearchMode mode = wxHELP_SEARCH_ALL);
 116
 117     /**
 118         Reads the controller's setting (position of window, etc.)
 119     */
 120     void ReadCustomization(wxConfigBase* cfg,
 121                            wxString path = wxEmptyString);
 122
 123     /**
 124         Sets the path for storing temporary files - cached binary versions of index and
 125         contents files. These binary
 126         forms are much faster to read. Default value is empty string (empty string means
 127         that no cached data are stored). Note that these files are @e not
 128         deleted when program exits.
 129         Once created these cached files will be used in all subsequent executions
 130         of your application. If cached files become older than corresponding .hhp
 131         file (e.g. if you regenerate documentation) it will be refreshed.
 132     */
 133     void SetTempDir(const wxString& path);
 134
 135     /**
 136         Sets format of title of the frame. Must contain exactly one "%s"
 137         (for title of displayed HTML page).
 138     */
 139     void SetTitleFormat(const wxString& format);
 140
 141     /**
 142         Associates @a config object with the controller.
 143         If there is associated config object, wxHtmlHelpController automatically
 144         reads and writes settings (including wxHtmlWindow's settings) when needed.
 145         The only thing you must do is create wxConfig object and call UseConfig.
 146         If you do not use @e UseConfig, wxHtmlHelpController will use
 147         default wxConfig object if available (for details see
 148         wxConfigBase::Get and
 149         wxConfigBase::Set).
 150     */
 151     void UseConfig(wxConfigBase* config,
 152                    const wxString& rootpath = wxEmptyString);
 153
 154     /**
 155         Stores controllers setting (position of window etc.)
 156     */
 157     void WriteCustomization(wxConfigBase* cfg,
 158                             wxString path = wxEmptyString);
 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 };