interface/wx/html/htmlwin.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/htmlwin.h
   3 // Purpose:     interface of wxHtmlWindow
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 // wxHtmlWindow flags:
  10 #define wxHW_SCROLLBAR_NEVER    0x0002
  11 #define wxHW_SCROLLBAR_AUTO     0x0004
  12 #define wxHW_NO_SELECTION       0x0008
  13
  14 #define wxHW_DEFAULT_STYLE      wxHW_SCROLLBAR_AUTO
  15
  16
  17 /// Enum for wxHtmlWindow::OnOpeningURL and wxHtmlWindowInterface::OnOpeningURL
  18 enum wxHtmlOpeningStatus
  19 {
  20     /// Open the requested URL
  21     wxHTML_OPEN,
  22     /// Do not open the URL
  23     wxHTML_BLOCK,
  24     /// Redirect to another URL (returned from OnOpeningURL)
  25     wxHTML_REDIRECT
  26 };
  27
  28
  29 /**
  30    @class wxHtmlWindowInterface
  31
  32    Abstract interface to a HTML rendering window (such as wxHtmlWindow or
  33    wxHtmlListBox) that is passed to wxHtmlWinParser. It encapsulates all
  34    communication from the parser to the window.
  35  */
  36 class wxHtmlWindowInterface
  37 {
  38 public:
  39     /// Ctor
  40     wxHtmlWindowInterface();
  41     virtual ~wxHtmlWindowInterface();
  42
  43     /**
  44         Called by the parser to set window's title to given text.
  45      */
  46     virtual void SetHTMLWindowTitle(const wxString& title) = 0;
  47
  48     /**
  49         Called when a link is clicked.
  50
  51         @param link information about the clicked link
  52      */
  53     virtual void OnHTMLLinkClicked(const wxHtmlLinkInfo& link) = 0;
  54
  55     /**
  56         Called when the parser needs to open another URL (e.g. an image).
  57
  58         @param type     Type of the URL request (e.g. image)
  59         @param url      URL the parser wants to open
  60         @param redirect If the return value is wxHTML_REDIRECT, then the
  61                         URL to redirect to will be stored in this variable
  62                         (the pointer must never be NULL)
  63
  64         @return indicator of how to treat the request
  65      */
  66     virtual wxHtmlOpeningStatus OnHTMLOpeningURL(wxHtmlURLType type,
  67                                                  const wxString& url,
  68                                                  wxString *redirect) const = 0;
  69
  70     /**
  71         Converts coordinates @a pos relative to given @a cell to
  72         physical coordinates in the window.
  73      */
  74     virtual wxPoint HTMLCoordsToWindow(wxHtmlCell *cell,
  75                                        const wxPoint& pos) const = 0;
  76
  77     /// Returns the window used for rendering (may be NULL).
  78     virtual wxWindow* GetHTMLWindow() = 0;
  79
  80     /// Returns background colour to use by default.
  81     virtual wxColour GetHTMLBackgroundColour() const = 0;
  82
  83     /// Sets window's background to colour @a clr.
  84     virtual void SetHTMLBackgroundColour(const wxColour& clr) = 0;
  85
  86     /// Sets window's background to given bitmap.
  87     virtual void SetHTMLBackgroundImage(const wxBitmap& bmpBg) = 0;
  88
  89     /// Sets status bar text.
  90     virtual void SetHTMLStatusText(const wxString& text) = 0;
  91
  92     /// Type of mouse cursor
  93     enum HTMLCursor
  94     {
  95         /// Standard mouse cursor (typically an arrow)
  96         HTMLCursor_Default,
  97         /// Cursor shown over links
  98         HTMLCursor_Link,
  99         /// Cursor shown over selectable text
 100         HTMLCursor_Text
 101     };
 102
 103     /**
 104         Returns mouse cursor of given @a type.
 105      */
 106     virtual wxCursor GetHTMLCursor(wxHtmlWindowInterface::HTMLCursor type) const = 0;
 107 };
 108
 109
 110
 111 /**
 112     @class wxHtmlWindow
 113
 114     wxHtmlWindow is probably the only class you will directly use unless you want
 115     to do something special (like adding new tag handlers or MIME filters).
 116
 117     The purpose of this class is to display rich content pages (either local file or
 118     downloaded via HTTP protocol) in a window based on a subset of the HTML standard.
 119     The width of the window is constant - given in the constructor - and virtual height
 120     is changed dynamically depending on page size.
 121     Once the window is created you can set its content by calling SetPage() with raw HTML,
 122     LoadPage() with a wxFileSystem location or LoadFile() with a filename.
 123
 124     @note
 125     If you want complete HTML/CSS support as well as a Javascript engine, see instead
 126     wxWebView.
 127
 128     @note
 129     wxHtmlWindow uses the wxImage class for displaying images, as such you need to
 130     initialize the handlers for any image formats you use before loading a page.
 131     See ::wxInitAllImageHandlers and wxImage::AddHandler.
 132
 133     @beginStyleTable
 134     @style{wxHW_SCROLLBAR_NEVER}
 135            Never display scrollbars, not even when the page is larger than the
 136            window.
 137     @style{wxHW_SCROLLBAR_AUTO}
 138            Display scrollbars only if page's size exceeds window's size.
 139     @style{wxHW_NO_SELECTION}
 140            Don't allow the user to select text.
 141     @endStyleTable
 142
 143
 144     @beginEventEmissionTable{wxHtmlCellEvent, wxHtmlLinkEvent}
 145     @event{EVT_HTML_CELL_CLICKED(id, func)}
 146         A wxHtmlCell was clicked.
 147     @event{EVT_HTML_CELL_HOVER(id, func)}
 148         The mouse passed over a wxHtmlCell.
 149     @event{EVT_HTML_LINK_CLICKED(id, func)}
 150         A wxHtmlCell which contains an hyperlink was clicked.
 151     @endEventTable
 152
 153     @library{wxhtml}
 154     @category{html}
 155
 156     @see wxHtmlLinkEvent, wxHtmlCellEvent
 157 */
 158 class wxHtmlWindow : public wxScrolledWindow, public wxHtmlWindowInterface
 159 {
 160 public:
 161     /**
 162         Default ctor.
 163     */
 164     wxHtmlWindow();
 165
 166     /**
 167         Constructor.
 168         The parameters are the same as wxScrolled::wxScrolled() constructor.
 169     */
 170     wxHtmlWindow(wxWindow *parent, wxWindowID id = wxID_ANY,
 171                  const wxPoint& pos = wxDefaultPosition,
 172                  const wxSize& size = wxDefaultSize,
 173                  long style = wxHW_DEFAULT_STYLE,
 174                  const wxString& name = "htmlWindow");
 175
 176     /**
 177         Adds @ref overview_html_filters "input filter" to the static list of available
 178         filters. These filters are present by default:
 179         - @c text/html MIME type
 180         - @c image/* MIME types
 181         - Plain Text filter (this filter is used if no other filter matches)
 182     */
 183     static void AddFilter(wxHtmlFilter* filter);
 184
 185     /**
 186         Appends HTML fragment to currently displayed text and refreshes the window.
 187
 188         @param source
 189             HTML code fragment
 190
 191         @return @false if an error occurred, @true otherwise.
 192     */
 193     bool AppendToPage(const wxString& source);
 194
 195     /**
 196         Returns pointer to the top-level container.
 197
 198         @see @ref overview_html_cells, @ref overview_printing
 199     */
 200     wxHtmlContainerCell* GetInternalRepresentation() const;
 201
 202     /**
 203         Returns anchor within currently opened page (see wxHtmlWindow::GetOpenedPage).
 204         If no page is opened or if the displayed page wasn't produced by call to
 205         LoadPage(), empty string is returned.
 206     */
 207     wxString GetOpenedAnchor() const;
 208
 209     /**
 210         Returns full location of the opened page.
 211         If no page is opened or if the displayed page wasn't produced by call to
 212         LoadPage(), empty string is returned.
 213     */
 214     wxString GetOpenedPage() const;
 215
 216     /**
 217         Returns title of the opened page or wxEmptyString if the current page does not
 218         contain \<TITLE\> tag.
 219     */
 220     wxString GetOpenedPageTitle() const;
 221
 222     /**
 223         Returns the related frame.
 224     */
 225     wxFrame* GetRelatedFrame() const;
 226
 227     /**
 228         Moves back to the previous page. Only pages displayed using LoadPage()
 229         are stored in history list.
 230     */
 231     bool HistoryBack();
 232
 233     /**
 234         Returns @true if it is possible to go back in the history
 235         i.e. HistoryBack() won't fail.
 236     */
 237     bool HistoryCanBack();
 238
 239     /**
 240         Returns @true if it is possible to go forward in the history
 241         i.e. HistoryForward() won't fail.
 242     */
 243     bool HistoryCanForward();
 244
 245     /**
 246         Clears history.
 247     */
 248     void HistoryClear();
 249
 250     /**
 251         Moves to next page in history. Only pages displayed using LoadPage()
 252         are stored in history list.
 253     */
 254     bool HistoryForward();
 255
 256     /**
 257         Loads an HTML page from a file and displays it.
 258
 259         @return @false if an error occurred, @true otherwise
 260
 261         @see LoadPage()
 262     */
 263     bool LoadFile(const wxFileName& filename);
 264
 265     /**
 266         Unlike SetPage() this function first loads the HTML page from @a location
 267         and then displays it.
 268
 269         @param location
 270             The address of the document.
 271             See the @ref overview_fs for details on the address format
 272             and wxFileSystem for a description of how the file is opened.
 273
 274         @return @false if an error occurred, @true otherwise
 275
 276         @see LoadFile()
 277     */
 278     virtual bool LoadPage(const wxString& location);
 279
 280     /**
 281         Called when user clicks on hypertext link.
 282         Default behaviour is to emit a wxHtmlLinkEvent and, if the event was not
 283         processed or skipped, call LoadPage() and do nothing else.
 284
 285         Overloading this method is deprecated; intercept the event instead.
 286
 287         Also see wxHtmlLinkInfo.
 288     */
 289     virtual void OnLinkClicked(const wxHtmlLinkInfo& link);
 290
 291     /**
 292         Called when an URL is being opened (either when the user clicks on a link or
 293         an image is loaded). The URL will be opened only if OnOpeningURL() returns
 294         @c wxHTML_OPEN. This method is called by wxHtmlParser::OpenURL.
 295
 296         You can override OnOpeningURL() to selectively block some URLs
 297         (e.g. for security reasons) or to redirect them elsewhere.
 298         Default behaviour is to always return @c wxHTML_OPEN.
 299
 300         @param type
 301             Indicates type of the resource. Is one of
 302             - wxHTML_URL_PAGE: Opening a HTML page.
 303             - wxHTML_URL_IMAGE: Opening an image.
 304             - wxHTML_URL_OTHER: Opening a resource that doesn't fall into
 305                                 any other category.
 306         @param url
 307             URL being opened.
 308         @param redirect
 309             Pointer to wxString variable that must be filled with an
 310             URL if OnOpeningURL() returns @c wxHTML_REDIRECT.
 311
 312         The return value is:
 313         - wxHTML_OPEN: Open the URL.
 314         - wxHTML_BLOCK: Deny access to the URL, wxHtmlParser::OpenURL will return @NULL.
 315         - wxHTML_REDIRECT: Don't open url, redirect to another URL.
 316           OnOpeningURL() must fill *redirect with the new URL.
 317           OnOpeningURL() will be called again on returned URL.
 318     */
 319     virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type,
 320                                              const wxString& url,
 321                                              wxString* redirect) const;
 322
 323     /**
 324         Called on parsing \<TITLE\> tag.
 325     */
 326     virtual void OnSetTitle(const wxString& title);
 327
 328     /**
 329         This reads custom settings from wxConfig. It uses the path 'path'
 330         if given, otherwise it saves info into currently selected path.
 331         The values are stored in sub-path @c wxHtmlWindow.
 332         Read values: all things set by SetFonts(), SetBorders().
 333
 334         @param cfg
 335             wxConfig from which you want to read the configuration.
 336         @param path
 337             Optional path in config tree. If not given current path is used.
 338     */
 339     virtual void ReadCustomization(wxConfigBase* cfg,
 340                                    wxString path = wxEmptyString);
 341
 342     /**
 343         Selects all text in the window.
 344
 345         @see SelectLine(), SelectWord()
 346     */
 347     void SelectAll();
 348
 349     /**
 350         Selects the line of text that @a pos points at. Note that @e pos
 351         is relative to the top of displayed page, not to window's origin, use
 352         wxScrolled::CalcUnscrolledPosition()
 353         to convert physical coordinate.
 354
 355         @see SelectAll(), SelectWord()
 356     */
 357     void SelectLine(const wxPoint& pos);
 358
 359     /**
 360         Selects the word at position @a pos.
 361         Note that @a pos is relative to the top of displayed page, not to window's
 362         origin, use wxScrolled::CalcUnscrolledPosition() to convert physical coordinate.
 363
 364         @see SelectAll(), SelectLine()
 365     */
 366     void SelectWord(const wxPoint& pos);
 367
 368     /**
 369         Returns the current selection as plain text.
 370         Returns an empty string if no text is currently selected.
 371     */
 372     wxString SelectionToText();
 373
 374     /**
 375         This function sets the space between border of window and HTML contents.
 376         See image:
 377         @image html htmlwin_border.png
 378
 379         @param b
 380             indentation from borders in pixels
 381     */
 382     void SetBorders(int b);
 383
 384     /**
 385         This function sets font sizes and faces. See wxHtmlDCRenderer::SetFonts
 386         for detailed description.
 387
 388         @see SetSize()
 389     */
 390     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 391                   const int* sizes = NULL);
 392
 393     /**
 394         Sets default font sizes and/or default font size.
 395         See wxHtmlDCRenderer::SetStandardFonts for detailed description.
 396         @see SetFonts()
 397     */
 398     void SetStandardFonts(int size = -1,
 399                           const wxString& normal_face = wxEmptyString,
 400                           const wxString& fixed_face = wxEmptyString);
 401
 402     /**
 403         Sets the source of a page and displays it, for example:
 404         @code
 405         htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
 406         @endcode
 407
 408         If you want to load a document from some location use LoadPage() instead.
 409
 410         @param source
 411             The HTML to be displayed.
 412
 413         @return @false if an error occurred, @true otherwise.
 414     */
 415     virtual bool SetPage(const wxString& source);
 416
 417     /**
 418         Sets the frame in which page title will be displayed.
 419         @a format is the format of the frame title, e.g. "HtmlHelp : %s".
 420         It must contain exactly one %s.
 421         This %s is substituted with HTML page title.
 422     */
 423     void SetRelatedFrame(wxFrame* frame, const wxString& format);
 424
 425     /**
 426         @b After calling SetRelatedFrame(), this sets statusbar slot where messages
 427         will be displayed. (Default is -1 = no messages.)
 428
 429         @param index
 430             Statusbar slot number (0..n)
 431     */
 432     void SetRelatedStatusBar(int index);
 433
 434     /**
 435         @b Sets the associated statusbar where messages will be displayed.
 436         Call this instead of SetRelatedFrame() if you want statusbar updates only,
 437         no changing of the frame title.
 438
 439         @param statusbar
 440             Statusbar pointer
 441         @param index
 442             Statusbar slot number (0..n)
 443
 444         @since 2.9.0
 445     */
 446     void SetRelatedStatusBar(wxStatusBar* statusbar, int index = 0);
 447
 448     /**
 449         Returns content of currently displayed page as plain text.
 450     */
 451     wxString ToText();
 452
 453     /**
 454         Saves custom settings into wxConfig.
 455         It uses the path 'path' if given, otherwise it saves info into currently
 456         selected path.
 457         Regardless of whether the path is given or not, the function creates
 458         sub-path @c wxHtmlWindow.
 459
 460         Saved values: all things set by SetFonts(), SetBorders().
 461
 462         @param cfg
 463             wxConfig to which you want to save the configuration.
 464         @param path
 465             Optional path in config tree. If not given, the current path is used.
 466     */
 467     virtual void WriteCustomization(wxConfigBase* cfg,
 468                                     wxString path = wxEmptyString);
 469
 470 protected:
 471
 472     /**
 473         This method is called when a mouse button is clicked inside wxHtmlWindow.
 474         The default behaviour is to emit a wxHtmlCellEvent and, if the event was
 475         not processed or skipped, call OnLinkClicked() if the cell contains an
 476         hypertext link.
 477
 478         Overloading this method is deprecated; intercept the event instead.
 479
 480         @param cell
 481             The cell inside which the mouse was clicked, always a simple
 482             (i.e. non-container) cell
 483         @param x
 484             The logical x coordinate of the click point
 485         @param y
 486             The logical y coordinate of the click point
 487         @param event
 488             The mouse event containing other information about the click
 489
 490         @return @true if a link was clicked, @false otherwise.
 491     */
 492     virtual bool OnCellClicked(wxHtmlCell* cell, wxCoord x, wxCoord y,
 493                                const wxMouseEvent& event);
 494
 495     /**
 496         This method is called when a mouse moves over an HTML cell.
 497         Default behaviour is to emit a wxHtmlCellEvent.
 498
 499         Overloading this method is deprecated; intercept the event instead.
 500
 501         @param cell
 502             The cell inside which the mouse is currently, always a simple
 503             (i.e. non-container) cell
 504         @param x
 505             The logical x coordinate of the click point
 506         @param y
 507             The logical y coordinate of the click point
 508     */
 509     virtual void OnCellMouseHover(wxHtmlCell* cell, wxCoord x, wxCoord y);
 510 };
 511
 512
 513
 514 wxEventType wxEVT_HTML_CELL_CLICKED;
 515 wxEventType wxEVT_HTML_CELL_HOVER;
 516 wxEventType wxEVT_HTML_LINK_CLICKED;
 517
 518
 519 /**
 520     @class wxHtmlLinkEvent
 521
 522     This event class is used for the events generated by wxHtmlWindow.
 523
 524     @beginEventTable{wxHtmlLinkEvent}
 525     @event{EVT_HTML_LINK_CLICKED(id, func)}
 526         User clicked on an hyperlink.
 527     @endEventTable
 528
 529     @library{wxhtml}
 530     @category{html}
 531 */
 532 class wxHtmlLinkEvent : public wxCommandEvent
 533 {
 534 public:
 535     /**
 536         The constructor is not normally used by the user code.
 537     */
 538     wxHtmlLinkEvent(int id, const wxHtmlLinkInfo& linkinfo);
 539
 540     /**
 541         Returns the wxHtmlLinkInfo which contains info about the cell clicked
 542         and the hyperlink it contains.
 543     */
 544     const wxHtmlLinkInfo& GetLinkInfo() const;
 545 };
 546
 547
 548
 549 /**
 550     @class wxHtmlCellEvent
 551
 552     This event class is used for the events generated by wxHtmlWindow.
 553
 554     @beginEventTable{wxHtmlCellEvent}
 555     @event{EVT_HTML_CELL_HOVER(id, func)}
 556         User moved the mouse over a wxHtmlCell.
 557     @event{EVT_HTML_CELL_CLICKED(id, func)}
 558         User clicked on a wxHtmlCell. When handling this event, remember to use
 559         wxHtmlCell::SetLinkClicked(true) if the cell contains a link.
 560     @endEventTable
 561
 562     @library{wxhtml}
 563     @category{html}
 564 */
 565 class wxHtmlCellEvent : public wxCommandEvent
 566 {
 567 public:
 568     /**
 569         The constructor is not normally used by the user code.
 570     */
 571     wxHtmlCellEvent(wxEventType commandType, int id,
 572                     wxHtmlCell* cell,
 573                     const wxPoint& point,
 574                     const wxMouseEvent& ev);
 575
 576     /**
 577         Returns the wxHtmlCellEvent associated with the event.
 578     */
 579     wxHtmlCell* GetCell() const;
 580
 581     /**
 582         Returns @true if SetLinkClicked(@true) has previously been called;
 583         @false otherwise.
 584     */
 585     bool GetLinkClicked() const;
 586
 587     /**
 588         Returns the wxPoint associated with the event.
 589     */
 590     wxPoint GetPoint() const;
 591
 592     /**
 593         Call this function with @a linkclicked set to @true if the cell which has
 594         been clicked contained a link or @false otherwise (which is the default).
 595
 596         With this function the event handler can return info to the wxHtmlWindow
 597         which sent the event.
 598     */
 599     void SetLinkClicked(bool linkclicked);
 600 };
 601