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