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     @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.
 278
 279         @param normal_face
 280             This is face name for normal (i.e. non-fixed) font.
 281             It can be either empty string (then the default face is chosen) or
 282             platform-specific face name. Examples are "helvetica" under Unix or
 283             "Times New Roman" under Windows.
 284         @param fixed_face
 285             The same thing for fixed face ( \<TT\>..\</TT\> )
 286         @param sizes
 287             This is an array of 7 items of int type.
 288             The values represent size of font with HTML size from -2 to +4
 289             ( \<FONT SIZE=-2\> to \<FONT SIZE=+4\> ).
 290             Default sizes are used if sizes is @NULL.
 291
 292         Default font sizes are defined by constants wxHTML_FONT_SIZE_1,
 293         wxHTML_FONT_SIZE_2, ..., wxHTML_FONT_SIZE_7.
 294         Note that they differ among platforms. Default face names are empty strings.
 295     */
 296     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 297                   const int* sizes = NULL);
 298
 299     /**
 300         Sets HTML page and display it. This won't @b load the page!!
 301         It will display the @e source. See 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 document source 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