interface/wx/html/helpwnd.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/helpwnd.h
   3 // Purpose:     interface of wxHtmlHelpWindow
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlHelpWindow
  11
  12     This class is used by wxHtmlHelpController to display help within a frame or
  13     dialog, but you can use it yourself to create an embedded HTML help window.
  14
  15     For example:
  16     @code
  17         // m_embeddedHelpWindow is a wxHtmlHelpWindow
  18         // m_embeddedHtmlHelp is a wxHtmlHelpController
  19
  20         // Create embedded HTML Help window
  21         m_embeddedHelpWindow = new wxHtmlHelpWindow;
  22         m_embeddedHtmlHelp.UseConfig(config, rootPath); // Set your own config object here
  23         m_embeddedHtmlHelp.SetHelpWindow(m_embeddedHelpWindow);
  24         m_embeddedHelpWindow->Create(this, wxID_ANY, wxDefaultPosition, GetClientSize(),
  25                                      wxTAB_TRAVERSAL|wxBORDER_NONE, wxHF_DEFAULT_STYLE);
  26         m_embeddedHtmlHelp.AddBook(wxFileName(_T("doc.zip")));
  27     @endcode
  28
  29     You should pass the style wxHF_EMBEDDED to the style parameter of
  30     wxHtmlHelpController to allow the embedded window to be destroyed
  31     independently of the help controller.
  32
  33     @library{wxhtml}
  34     @category{help,html}
  35 */
  36 class wxHtmlHelpWindow : public wxWindow
  37 {
  38 public:
  39     wxHtmlHelpWindow(wxHtmlHelpData* data = NULL);
  40
  41     /**
  42         Constructor.
  43
  44         For the values of @a helpStyle, please see the documentation for
  45         wxHtmlHelpController.
  46     */
  47     wxHtmlHelpWindow(wxWindow* parent, int wxWindowID,
  48                      const wxPoint& pos = wxDefaultPosition,
  49                      const wxSize& pos = wxDefaultSize,
  50                      int style = wxTAB_TRAVERSAL|wxBORDER_NONE,
  51                      int helpStyle = wxHF_DEFAULT_STYLE,
  52                      wxHtmlHelpData* data = NULL);
  53
  54     /**
  55         You may override this virtual method to add more buttons to the help window's
  56         toolbar. @a toolBar is a pointer to the toolbar and @a style is the style
  57         flag as passed to the Create() method.
  58
  59         wxToolBar::Realize is called immediately after returning from this function.
  60         See @c samples/html/helpview for an example.
  61     */
  62     virtual void AddToolbarButtons(wxToolBar* toolBar, int style);
  63
  64     /**
  65         Creates the help window. See @ref wxHtmlHelpWindow() "the constructor"
  66         for a description of the parameters.
  67     */
  68     bool Create(wxWindow* parent, wxWindowID id,
  69                 const wxPoint& pos = wxDefaultPosition,
  70                 const wxSize& pos = wxDefaultSize,
  71                 int style = wxTAB_TRAVERSAL|wxBORDER_NONE,
  72                 int helpStyle = wxHF_DEFAULT_STYLE,
  73                 wxHtmlHelpData* data = NULL);
  74
  75     /**
  76         Creates search panel.
  77     */
  78     void CreateSearch();
  79
  80     /**
  81         Displays page x.
  82         If not found it will give the user the choice of searching books.
  83         Looking for the page runs in these steps:
  84         -# try to locate file named x (if x is for example "doc/howto.htm")
  85         -# try to open starting page of book x
  86         -# try to find x in contents (if x is for example "How To ...")
  87         -# try to find x in index (if x is for example "How To ...")
  88     */
  89     bool Display(const wxString& x);
  90
  91     /**
  92         @overload
  93
  94         This form takes numeric ID as the parameter (uses an extension to MS format,
  95         param name="ID" value=id).
  96     */
  97     bool Display(const int id);
  98
  99     /**
 100         Displays contents panel.
 101     */
 102     bool DisplayContents();
 103
 104     /**
 105         Displays index panel.
 106     */
 107     bool DisplayIndex();
 108
 109     /**
 110         Returns the wxHtmlHelpData object, which is usually a pointer to the
 111         controller's data.
 112     */
 113     wxHtmlHelpData* GetData();
 114
 115     /**
 116         Search for given keyword. Optionally it searches through the index
 117         (mode = @c wxHELP_SEARCH_INDEX), default the content (mode = @c wxHELP_SEARCH_ALL).
 118     */
 119     bool KeywordSearch(const wxString& keyword,
 120                        wxHelpSearchMode mode = wxHELP_SEARCH_ALL);
 121
 122     /**
 123         Reads the user's settings for this window.
 124
 125         @see wxHtmlHelpController::ReadCustomization
 126     */
 127     void ReadCustomization(wxConfigBase* cfg,
 128                            const wxString& path = wxEmptyString);
 129
 130     /**
 131         Sets the frame's title format.
 132
 133         @a format must contain exactly one "%s" (it will be replaced by the page title).
 134     */
 135     void SetTitleFormat(const wxString& format);
 136
 137     /**
 138         Associates a wxConfig object with the help window. It is recommended that you
 139         use wxHtmlHelpController::UseConfig instead.
 140     */
 141     void UseConfig(wxConfigBase* config,
 142                    const wxString& rootpath = wxEmptyString);
 143
 144     /**
 145         Saves the user's settings for this window.
 146
 147         @see wxHtmlHelpController::WriteCustomization
 148     */
 149     void WriteCustomization(wxConfigBase* cfg,
 150                             const wxString& path = wxEmptyString);
 151
 152 protected:
 153
 154     /**
 155         Creates contents panel. (May take some time.)
 156     */
 157     void CreateContents();
 158
 159     /**
 160         Creates index panel. (May take some time.)
 161     */
 162     void CreateIndex();
 163
 164     /**
 165         Refresh all panels. This is necessary if a new book was added.
 166     */
 167     void RefreshLists();
 168 };
 169