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