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