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