interface/html/helpwnd.h

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