interface/html/htmlwin.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/htmlwin.h
   3 // Purpose:     documentation for wxHtmlWindow class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlWindow
  11     @headerfile htmlwin.h wx/html/htmlwin.h
  12
  13     wxHtmlWindow is probably the only class you will directly use
  14     unless you want to do something special (like adding new tag
  15     handlers or MIME filters).
  16
  17     The purpose of this class is to display HTML pages (either local
  18     file or downloaded via HTTP protocol) in a window. The width
  19     of the window is constant - given in the constructor - and virtual height
  20     is changed dynamically depending on page size.
  21     Once the window is created you can set its content by calling
  22     @ref wxHtmlWindow::setpage SetPage(text),
  23     @ref wxHtmlWindow::loadpage LoadPage(filename) or
  24     wxHtmlWindow::LoadFile.
  25
  26     @beginStyleTable
  27     @style{wxHW_SCROLLBAR_NEVER}:
  28            Never display scrollbars, not even when the page is larger than the
  29            window.
  30     @style{wxHW_SCROLLBAR_AUTO}:
  31            Display scrollbars only if page's size exceeds window's size.
  32     @style{wxHW_NO_SELECTION}:
  33            Don't allow the user to select text.
  34     @endStyleTable
  35
  36     @library{wxhtml}
  37     @category{html}
  38
  39     @seealso
  40     wxHtmlLinkEvent, wxHtmlCellEvent
  41 */
  42 class wxHtmlWindow : public wxScrolledWindow
  43 {
  44 public:
  45     //@{
  46     /**
  47         Constructor. The parameters are the same as for the wxScrolledWindow
  48         constructor.
  49
  50         @param style
  51         Window style. See wxHtmlWindow.
  52     */
  53     wxHtmlWindow();
  54     wxHtmlWindow(wxWindow parent, wxWindowID id = -1,
  55                  const wxPoint& pos = wxDefaultPosition,
  56                  const wxSize& size = wxDefaultSize,
  57                  long style = wxHW_DEFAULT_STYLE,
  58                  const wxString& name = "htmlWindow");
  59     //@}
  60
  61     /**
  62         Adds @ref overview_filters "input filter" to the static list of available
  63         filters. These filters are present by default:
  64
  65          @c text/html MIME type
  66          @c image/* MIME types
  67          Plain Text filter (this filter is used if no other filter matches)
  68     */
  69     static void AddFilter(wxHtmlFilter filter);
  70
  71     /**
  72         Appends HTML fragment to currently displayed text and refreshes the window.
  73
  74         @param source
  75         HTML code fragment
  76
  77         @returns @false if an error occurred, @true otherwise.
  78     */
  79     bool AppendToPage(const wxString& source);
  80
  81     /**
  82         Returns pointer to the top-level container.
  83
  84         See also: @ref overview_cells "Cells Overview",
  85         @ref overview_printing "Printing Overview"
  86     */
  87     wxHtmlContainerCell* GetInternalRepresentation();
  88
  89     /**
  90         Returns anchor within currently opened page
  91         (see wxHtmlWindow::GetOpenedPage).
  92         If no page is opened or if the displayed page wasn't
  93         produced by call to LoadPage, empty string is returned.
  94     */
  95     wxString GetOpenedAnchor();
  96
  97     /**
  98         Returns full location of the opened page. If no page is opened or if the
  99         displayed page wasn't
 100         produced by call to LoadPage, empty string is returned.
 101     */
 102     wxString GetOpenedPage();
 103
 104     /**
 105         Returns title of the opened page or wxEmptyString if current page does not
 106         contain @c TITLE tag.
 107     */
 108     wxString GetOpenedPageTitle();
 109
 110     /**
 111         Returns the related frame.
 112     */
 113     wxFrame* GetRelatedFrame();
 114
 115     /**
 116         Moves back to the previous page. (each page displayed using
 117         LoadPage() is stored in history list.)
 118     */
 119     bool HistoryBack();
 120
 121     /**
 122         Returns @true if it is possible to go back in the history (i.e. HistoryBack()
 123         won't fail).
 124     */
 125     bool HistoryCanBack();
 126
 127     /**
 128         Returns @true if it is possible to go forward in the history (i.e. HistoryBack()
 129         won't fail).
 130     */
 131     bool HistoryCanForward();
 132
 133     /**
 134         Clears history.
 135     */
 136     void HistoryClear();
 137
 138     /**
 139         Moves to next page in history.
 140     */
 141     bool HistoryForward();
 142
 143     /**
 144         Loads HTML page from file and displays it.
 145
 146         @returns @false if an error occurred, @true otherwise
 147
 148         @sa LoadPage()
 149     */
 150     virtual bool LoadFile(const wxFileName& filename);
 151
 152     /**
 153         Unlike SetPage this function first loads HTML page from @e location
 154         and then displays it. See example:
 155
 156         @param location
 157         The address of document. See wxFileSystem for details on address format and
 158         behaviour of "opener".
 159
 160         @returns @false if an error occurred, @true otherwise
 161
 162         @sa LoadFile()
 163     */
 164     virtual bool LoadPage(const wxString& location);
 165
 166     /**
 167         This method is called when a mouse button is clicked inside wxHtmlWindow.
 168
 169         The default behaviour is to emit a wxHtmlCellEvent
 170         and, if the event was not processed or skipped, call
 171         OnLinkClicked() if the cell contains an
 172         hypertext link.
 173
 174         Overloading this method is deprecated; intercept the event instead.
 175
 176         @param cell
 177         The cell inside which the mouse was clicked, always a simple
 178         (i.e. non-container) cell
 179
 180         @param x, y
 181         The logical coordinates of the click point
 182
 183         @param event
 184         The mouse event containing other information about the click
 185
 186         @returns @true if a link was clicked, @false otherwise.
 187     */
 188     virtual bool OnCellClicked(wxHtmlCell cell, wxCoord x, wxCoord y,
 189                                const wxMouseEvent& event);
 190
 191     /**
 192         This method is called when a mouse moves over an HTML cell.
 193         Default behaviour is to emit a wxHtmlCellEvent.
 194         Overloading this method is deprecated; intercept the event instead.
 195
 196         @param cell
 197         The cell inside which the mouse is currently, always a simple
 198         (i.e. non-container) cell
 199
 200         @param x, y
 201         The logical coordinates of the click point
 202     */
 203     virtual void OnCellMouseHover(wxHtmlCell cell, wxCoord x,
 204                                   wxCoord y);
 205
 206     /**
 207         Called when user clicks on hypertext link. Default behaviour is to emit a
 208         wxHtmlLinkEvent and, if the event was not processed
 209         or skipped, call LoadPage() and do nothing else.
 210         Overloading this method is deprecated; intercept the event instead.
 211
 212         Also see wxHtmlLinkInfo.
 213     */
 214     virtual void OnLinkClicked(const wxHtmlLinkInfo& link);
 215
 216     /**
 217         Called when an URL is being opened (either when the user clicks on a link or
 218         an image is loaded). The URL will be opened only if OnOpeningURL returns
 219         @c wxHTML_OPEN. This method is called by
 220         wxHtmlParser::OpenURL.
 221         You can override OnOpeningURL to selectively block some
 222         URLs (e.g. for security reasons) or to redirect them elsewhere. Default
 223         behaviour is to always return @c wxHTML_OPEN.
 224
 225         @param type
 226         Indicates type of the resource. Is one of
 227
 228
 229         wxHTML_URL_PAGE
 230
 231
 232         Opening a HTML page.
 233
 234         wxHTML_URL_IMAGE
 235
 236
 237         Opening an image.
 238
 239         wxHTML_URL_OTHER
 240
 241
 242         Opening a resource that doesn't fall into
 243         any other category.
 244
 245         @param url
 246         URL being opened.
 247
 248         @param redirect
 249         Pointer to wxString variable that must be filled with an
 250         URL if OnOpeningURL returns wxHTML_REDIRECT.
 251     */
 252     virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type,
 253             const wxString& url,
 254             wxString * redirect);
 255
 256     /**
 257         Called on parsing @c TITLE tag.
 258     */
 259     virtual void OnSetTitle(const wxString& title);
 260
 261     /**
 262         This reads custom settings from wxConfig. It uses the path 'path'
 263         if given, otherwise it saves info into currently selected path.
 264         The values are stored in sub-path @c wxHtmlWindow
 265
 266         Read values: all things set by SetFonts, SetBorders.
 267
 268         @param cfg
 269         wxConfig from which you want to read the configuration.
 270
 271         @param path
 272         Optional path in config tree. If not given current path is used.
 273     */
 274     virtual void ReadCustomization(wxConfigBase cfg,
 275                                    wxString path = wxEmptyString);
 276
 277     /**
 278         Selects all text in the window.
 279
 280         @sa SelectLine(), SelectWord()
 281     */
 282     void SelectAll();
 283
 284     /**
 285         Selects the line of text that @e pos points at. Note that @e pos
 286         is relative to the top of displayed page, not to window's origin, use
 287         wxScrolledWindow::CalcUnscrolledPosition
 288         to convert physical coordinate.
 289
 290         @sa SelectAll(), SelectWord()
 291     */
 292     void SelectLine(const wxPoint& pos);
 293
 294     /**
 295         Selects the word at position @e pos. Note that @e pos
 296         is relative to the top of displayed page, not to window's origin, use
 297         wxScrolledWindow::CalcUnscrolledPosition
 298         to convert physical coordinate.
 299
 300         @sa SelectAll(), SelectLine()
 301     */
 302     void SelectWord(const wxPoint& pos);
 303
 304     /**
 305         Returns current selection as plain text. Returns empty string if no text
 306         is currently selected.
 307     */
 308     wxString SelectionToText();
 309
 310     /**
 311         This function sets the space between border of window and HTML contents. See
 312         image:
 313
 314         @param b
 315         indentation from borders in pixels
 316     */
 317     void SetBorders(int b);
 318
 319     /**
 320         This function sets font sizes and faces.
 321
 322         @param normal_face
 323         This is face name for normal (i.e. non-fixed) font.
 324         It can be either empty string (then the default face is chosen) or
 325         platform-specific face name. Examples are "helvetica" under Unix or
 326         "Times New Roman" under Windows.
 327
 328         @param fixed_face
 329         The same thing for fixed face ( TT../TT )
 330
 331         @param sizes
 332         This is an array of 7 items of int type.
 333         The values represent size of font with HTML size from -2 to +4
 334         ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes
 335         is @NULL.
 336     */
 337     void SetFonts(const wxString& normal_face,
 338                   const wxString& fixed_face,
 339                   const int sizes = @NULL);
 340
 341     /**
 342         Sets HTML page and display it. This won't @b load the page!!
 343         It will display the @e source. See example:
 344         If you want to load a document from some location use
 345         LoadPage() instead.
 346
 347         @param source
 348         The HTML document source to be displayed.
 349
 350         @returns @false if an error occurred, @true otherwise.
 351     */
 352     bool SetPage(const wxString& source);
 353
 354     /**
 355         Sets the frame in which page title will be displayed. @e format is format of
 356         frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This
 357         %s is substituted with HTML page title.
 358     */
 359     void SetRelatedFrame(wxFrame* frame, const wxString& format);
 360
 361     /**
 362         @b After calling SetRelatedFrame(),
 363         this sets statusbar slot where messages will be displayed.
 364         (Default is -1 = no messages.)
 365
 366         @param bar
 367         statusbar slot number (0..n)
 368     */
 369     void SetRelatedStatusBar(int bar);
 370
 371     /**
 372         Returns content of currently displayed page as plain text.
 373     */
 374     wxString ToText();
 375
 376     /**
 377         Saves custom settings into wxConfig. It uses the path 'path'
 378         if given, otherwise it saves info into currently selected path.
 379         Regardless of whether the path is given or not, the function creates sub-path
 380         @c wxHtmlWindow.
 381
 382         Saved values: all things set by SetFonts, SetBorders.
 383
 384         @param cfg
 385         wxConfig to which you want to save the configuration.
 386
 387         @param path
 388         Optional path in config tree. If not given, the current path is used.
 389     */
 390     virtual void WriteCustomization(wxConfigBase cfg,
 391                                     wxString path = wxEmptyString);
 392 };
 393
 394
 395 /**
 396     @class wxHtmlLinkEvent
 397     @headerfile htmlwin.h wx/html/htmlwin.h
 398
 399     This event class is used for the events generated by wxHtmlWindow.
 400
 401     @library{wxhtml}
 402     @category{FIXME}
 403 */
 404 class wxHtmlLinkEvent : public wxCommandEvent
 405 {
 406 public:
 407     /**
 408         The constructor is not normally used by the user code.
 409     */
 410     wxHyperlinkEvent(int id, const wxHtmlLinkInfo & linkinfo);
 411
 412     /**
 413         Returns the wxHtmlLinkInfo which contains info about the cell clicked and the
 414         hyperlink it contains.
 415     */
 416     const wxHtmlLinkInfo GetLinkInfo();
 417 };
 418
 419
 420 /**
 421     @class wxHtmlCellEvent
 422     @headerfile htmlwin.h wx/html/htmlwin.h
 423
 424     This event class is used for the events generated by wxHtmlWindow.
 425
 426     @library{wxhtml}
 427     @category{FIXME}
 428 */
 429 class wxHtmlCellEvent : public wxCommandEvent
 430 {
 431 public:
 432     /**
 433         The constructor is not normally used by the user code.
 434     */
 435     wxHtmlCellEvent(wxEventType commandType, int id,
 436                     wxHtmlCell * cell,
 437                     const wxPoint & point);
 438
 439     /**
 440         Returns the wxHtmlCellEvent associated with the event.
 441     */
 442     wxHtmlCell * GetCell();
 443
 444     /**
 445         Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously
 446         been called;
 447         @false otherwise.
 448     */
 449     bool GetLinkClicked();
 450
 451     /**
 452         Returns the wxPoint associated with the event.
 453     */
 454     wxPoint GetPoint();
 455
 456     /**
 457         Call this function with @c linkclicked set to @true if the cell which has
 458         been clicked contained a link or
 459         @false otherwise (which is the default). With this function the event handler
 460         can return info to the
 461         wxHtmlWindow which sent the event.
 462     */
 463     bool SetLinkClicked(bool linkclicked);
 464 };