interface/wx/html/htmlwin.h

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