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