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