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