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