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(text),
  20     LoadPage(filename) or wxHtmlWindow::LoadFile.
  21
  22     @note
  23     wxHtmlWindow uses the wxImage class for displaying images.
  24     Don't forget to initialize all image formats you need before loading any 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 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.
 123         (each page displayed using LoadPage() is 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. HistoryBack() 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.
 146     */
 147     bool HistoryForward();
 148
 149     /**
 150         Loads HTML page from file and displays it.
 151
 152         @return @false if an error occurred, @true otherwise
 153
 154         @see LoadPage()
 155     */
 156     bool LoadFile(const wxFileName& filename);
 157
 158     /**
 159         Unlike SetPage() this function first loads HTML page from @a location
 160         and then displays it. See example:
 161
 162         @param location
 163             The address of document.
 164             See wxFileSystem for details on address format and behaviour of "opener".
 165
 166         @return @false if an error occurred, @true otherwise
 167
 168         @see LoadFile()
 169     */
 170     virtual bool LoadPage(const wxString& location);
 171
 172     /**
 173         Called when user clicks on hypertext link.
 174         Default behaviour is to emit a wxHtmlLinkEvent and, if the event was not
 175         processed or skipped, call LoadPage() and do nothing else.
 176
 177         Overloading this method is deprecated; intercept the event instead.
 178
 179         Also see wxHtmlLinkInfo.
 180     */
 181     virtual void OnLinkClicked(const wxHtmlLinkInfo& link);
 182
 183     /**
 184         Called when an URL is being opened (either when the user clicks on a link or
 185         an image is loaded). The URL will be opened only if OnOpeningURL() returns
 186         @c wxHTML_OPEN. This method is called by wxHtmlParser::OpenURL.
 187
 188         You can override OnOpeningURL() to selectively block some URLs
 189         (e.g. for security reasons) or to redirect them elsewhere.
 190         Default behaviour is to always return @c wxHTML_OPEN.
 191
 192         @param type
 193             Indicates type of the resource. Is one of
 194             - wxHTML_URL_PAGE: Opening a HTML page.
 195             - wxHTML_URL_IMAGE: Opening an image.
 196             - wxHTML_URL_OTHER: Opening a resource that doesn't fall into
 197                                 any other category.
 198         @param url
 199             URL being opened.
 200         @param redirect
 201             Pointer to wxString variable that must be filled with an
 202             URL if OnOpeningURL() returns @c wxHTML_REDIRECT.
 203
 204         The return value is:
 205         - wxHTML_OPEN: Open the URL.
 206         - wxHTML_BLOCK: Deny access to the URL, wxHtmlParser::OpenURL will return @NULL.
 207         - wxHTML_REDIRECT: Don't open url, redirect to another URL.
 208           OnOpeningURL() must fill *redirect with the new URL.
 209           OnOpeningURL() will be called again on returned URL.
 210     */
 211     virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type,
 212                                              const wxString& url,
 213                                              wxString* redirect) const;
 214
 215     /**
 216         Called on parsing \<TITLE\> tag.
 217     */
 218     virtual void OnSetTitle(const wxString& title);
 219
 220     /**
 221         This reads custom settings from wxConfig. It uses the path 'path'
 222         if given, otherwise it saves info into currently selected path.
 223         The values are stored in sub-path @c wxHtmlWindow.
 224         Read values: all things set by SetFonts(), SetBorders().
 225
 226         @param cfg
 227             wxConfig from which you want to read the configuration.
 228         @param path
 229             Optional path in config tree. If not given current path is used.
 230     */
 231     virtual void ReadCustomization(wxConfigBase* cfg,
 232                                    wxString path = wxEmptyString);
 233
 234     /**
 235         Selects all text in the window.
 236
 237         @see SelectLine(), SelectWord()
 238     */
 239     void SelectAll();
 240
 241     /**
 242         Selects the line of text that @a pos points at. Note that @e pos
 243         is relative to the top of displayed page, not to window's origin, use
 244         wxScrolled::CalcUnscrolledPosition()
 245         to convert physical coordinate.
 246
 247         @see SelectAll(), SelectWord()
 248     */
 249     void SelectLine(const wxPoint& pos);
 250
 251     /**
 252         Selects the word at position @a pos.
 253         Note that @a pos is relative to the top of displayed page, not to window's
 254         origin, use wxScrolled::CalcUnscrolledPosition() to convert physical coordinate.
 255
 256         @see SelectAll(), SelectLine()
 257     */
 258     void SelectWord(const wxPoint& pos);
 259
 260     /**
 261         Returns current selection as plain text.
 262         Returns empty string if no text is currently selected.
 263     */
 264     wxString SelectionToText();
 265
 266     /**
 267         This function sets the space between border of window and HTML contents.
 268         See image:
 269         @image html htmlwin_border.png
 270
 271         @param b
 272             indentation from borders in pixels
 273     */
 274     void SetBorders(int b);
 275
 276     /**
 277         This function sets font sizes and faces. See wxHtmlDCRenderer::SetFonts
 278         for detailed description.
 279
 280         @see SetSize()
 281     */
 282     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 283                   const int* sizes = NULL);
 284
 285     /**
 286         Sets default font sizes and/or default font size.
 287         See wxHtmlDCRenderer::SetStandardFonts for detailed description.
 288         @see SetFonts()
 289     */
 290     void SetStandardFonts(int size = -1,
 291                           const wxString& normal_face = wxEmptyString,
 292                           const wxString& fixed_face = wxEmptyString);
 293
 294     /**
 295         Sets HTML page and display it. This won't @b load the page!!
 296         It will display the @e source. See example:
 297         @code
 298         htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
 299         @endcode
 300
 301         If you want to load a document from some location use LoadPage() instead.
 302
 303         @param source
 304             The HTML document source to be displayed.
 305
 306         @return @false if an error occurred, @true otherwise.
 307     */
 308     virtual bool SetPage(const wxString& source);
 309
 310     /**
 311         Sets the frame in which page title will be displayed.
 312         @a format is the format of the frame title, e.g. "HtmlHelp : %s".
 313         It must contain exactly one %s.
 314         This %s is substituted with HTML page title.
 315     */
 316     void SetRelatedFrame(wxFrame* frame, const wxString& format);
 317
 318     /**
 319         @b After calling SetRelatedFrame(), this sets statusbar slot where messages
 320         will be displayed. (Default is -1 = no messages.)
 321
 322         @param index
 323             Statusbar slot number (0..n)
 324     */
 325     void SetRelatedStatusBar(int index);
 326
 327     /**
 328         @b Sets the associated statusbar where messages will be displayed.
 329         Call this instead of SetRelatedFrame() if you want statusbar updates only,
 330         no changing of the frame title.
 331
 332         @param statusbar
 333             Statusbar pointer
 334         @param index
 335             Statusbar slot number (0..n)
 336
 337         @since 2.9.0
 338     */
 339     void SetRelatedStatusBar(wxStatusBar* statusbar, int index = 0);
 340
 341     /**
 342         Returns content of currently displayed page as plain text.
 343     */
 344     wxString ToText();
 345
 346     /**
 347         Saves custom settings into wxConfig.
 348         It uses the path 'path' if given, otherwise it saves info into currently
 349         selected path.
 350         Regardless of whether the path is given or not, the function creates
 351         sub-path @c wxHtmlWindow.
 352
 353         Saved values: all things set by SetFonts(), SetBorders().
 354
 355         @param cfg
 356             wxConfig to which you want to save the configuration.
 357         @param path
 358             Optional path in config tree. If not given, the current path is used.
 359     */
 360     virtual void WriteCustomization(wxConfigBase* cfg,
 361                                     wxString path = wxEmptyString);
 362
 363 protected:
 364
 365     /**
 366         This method is called when a mouse button is clicked inside wxHtmlWindow.
 367         The default behaviour is to emit a wxHtmlCellEvent and, if the event was
 368         not processed or skipped, call OnLinkClicked() if the cell contains an
 369         hypertext link.
 370
 371         Overloading this method is deprecated; intercept the event instead.
 372
 373         @param cell
 374             The cell inside which the mouse was clicked, always a simple
 375             (i.e. non-container) cell
 376         @param x
 377             The logical x coordinate of the click point
 378         @param y
 379             The logical y coordinate of the click point
 380         @param event
 381             The mouse event containing other information about the click
 382
 383         @return @true if a link was clicked, @false otherwise.
 384     */
 385     virtual bool OnCellClicked(wxHtmlCell* cell, wxCoord x, wxCoord y,
 386                                const wxMouseEvent& event);
 387
 388     /**
 389         This method is called when a mouse moves over an HTML cell.
 390         Default behaviour is to emit a wxHtmlCellEvent.
 391
 392         Overloading this method is deprecated; intercept the event instead.
 393
 394         @param cell
 395             The cell inside which the mouse is currently, always a simple
 396             (i.e. non-container) cell
 397         @param x
 398             The logical x coordinate of the click point
 399         @param y
 400             The logical y coordinate of the click point
 401     */
 402     virtual void OnCellMouseHover(wxHtmlCell* cell, wxCoord x, wxCoord y);
 403 };
 404
 405
 406
 407 /**
 408     @class wxHtmlLinkEvent
 409
 410     This event class is used for the events generated by wxHtmlWindow.
 411
 412     @beginEventTable{wxHtmlLinkEvent}
 413     @event{EVT_HTML_LINK_CLICKED(id, func)}
 414         User clicked on an hyperlink.
 415     @endEventTable
 416
 417     @library{wxhtml}
 418     @category{html}
 419 */
 420 class wxHtmlLinkEvent : public wxCommandEvent
 421 {
 422 public:
 423     /**
 424         The constructor is not normally used by the user code.
 425     */
 426     wxHtmlLinkEvent(int id, const wxHtmlLinkInfo& linkinfo);
 427
 428     /**
 429         Returns the wxHtmlLinkInfo which contains info about the cell clicked
 430         and the hyperlink it contains.
 431     */
 432     const wxHtmlLinkInfo& GetLinkInfo() const;
 433 };
 434
 435
 436
 437 /**
 438     @class wxHtmlCellEvent
 439
 440     This event class is used for the events generated by wxHtmlWindow.
 441
 442     @beginEventTable{wxHtmlCellEvent}
 443     @event{EVT_HTML_CELL_HOVER(id, func)}
 444         User moved the mouse over a wxHtmlCell.
 445     @event{EVT_HTML_CELL_CLICKED(id, func)}
 446         User clicked on a wxHtmlCell. When handling this event, remember to use
 447         wxHtmlCell::SetLinkClicked(true) if the cell contains a link.
 448     @endEventTable
 449
 450     @library{wxhtml}
 451     @category{html}
 452 */
 453 class wxHtmlCellEvent : public wxCommandEvent
 454 {
 455 public:
 456     /**
 457         The constructor is not normally used by the user code.
 458     */
 459     wxHtmlCellEvent(wxEventType commandType, int id,
 460                     wxHtmlCell* cell,
 461                     const wxPoint& point,
 462                     const wxMouseEvent& ev);
 463
 464     /**
 465         Returns the wxHtmlCellEvent associated with the event.
 466     */
 467     wxHtmlCell* GetCell() const;
 468
 469     /**
 470         Returns @true if SetLinkClicked(@true) has previously been called;
 471         @false otherwise.
 472     */
 473     bool GetLinkClicked() const;
 474
 475     /**
 476         Returns the wxPoint associated with the event.
 477     */
 478     wxPoint GetPoint() const;
 479
 480     /**
 481         Call this function with @a linkclicked set to @true if the cell which has
 482         been clicked contained a link or @false otherwise (which is the default).
 483
 484         With this function the event handler can return info to the wxHtmlWindow
 485         which sent the event.
 486     */
 487     void SetLinkClicked(bool linkclicked);
 488 };
 489