include/wx/html/htmlwin.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        htmlwin.h
   3 // Purpose:     wxHtmlWindow class for parsing & displaying HTML
   4 // Author:      Vaclav Slavik
   5 // RCS-ID:      $Id$
   6 // Copyright:   (c) 1999 Vaclav Slavik
   7 // Licence:     wxWindows licence
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 #ifndef _WX_HTMLWIN_H_
  11 #define _WX_HTMLWIN_H_
  12
  13 #include "wx/defs.h"
  14 #if wxUSE_HTML
  15
  16 #include "wx/window.h"
  17 #include "wx/scrolwin.h"
  18 #include "wx/config.h"
  19 #include "wx/stopwatch.h"
  20 #include "wx/html/winpars.h"
  21 #include "wx/html/htmlcell.h"
  22 #include "wx/filesys.h"
  23 #include "wx/html/htmlfilt.h"
  24 #include "wx/filename.h"
  25 #include "wx/bitmap.h"
  26
  27 class wxHtmlProcessor;
  28 class wxHtmlWinModule;
  29 class wxHtmlHistoryArray;
  30 class wxHtmlProcessorList;
  31 class WXDLLIMPEXP_HTML wxHtmlWinAutoScrollTimer;
  32
  33
  34 // wxHtmlWindow flags:
  35 #define wxHW_SCROLLBAR_NEVER    0x0002
  36 #define wxHW_SCROLLBAR_AUTO     0x0004
  37 #define wxHW_NO_SELECTION       0x0008
  38
  39 #define wxHW_DEFAULT_STYLE      wxHW_SCROLLBAR_AUTO
  40
  41 /// Enum for wxHtmlWindow::OnOpeningURL and wxHtmlWindowInterface::OnOpeningURL
  42 enum wxHtmlOpeningStatus
  43 {
  44     /// Open the requested URL
  45     wxHTML_OPEN,
  46     /// Do not open the URL
  47     wxHTML_BLOCK,
  48     /// Redirect to another URL (returned from OnOpeningURL)
  49     wxHTML_REDIRECT
  50 };
  51
  52 /**
  53     Abstract interface to a HTML rendering window (such as wxHtmlWindow or
  54     wxHtmlListBox) that is passed to wxHtmlWinParser. It encapsulates all
  55     communication from the parser to the window.
  56  */
  57 class WXDLLIMPEXP_HTML wxHtmlWindowInterface
  58 {
  59 public:
  60     /// Ctor
  61     wxHtmlWindowInterface() {}
  62     virtual ~wxHtmlWindowInterface() {}
  63
  64     /**
  65         Called by the parser to set window's title to given text.
  66      */
  67     virtual void SetHTMLWindowTitle(const wxString& title) = 0;
  68
  69     /**
  70         Called when a link is clicked.
  71
  72         @param link information about the clicked link
  73      */
  74     virtual void OnHTMLLinkClicked(const wxHtmlLinkInfo& link) = 0;
  75
  76     /**
  77         Called when the parser needs to open another URL (e.g. an image).
  78
  79         @param type     Type of the URL request (e.g. image)
  80         @param url      URL the parser wants to open
  81         @param redirect If the return value is wxHTML_REDIRECT, then the
  82                         URL to redirect to will be stored in this variable
  83                         (the pointer must never be NULL)
  84
  85         @return indicator of how to treat the request
  86      */
  87     virtual wxHtmlOpeningStatus OnHTMLOpeningURL(wxHtmlURLType type,
  88                                                  const wxString& url,
  89                                                  wxString *redirect) const = 0;
  90
  91     /**
  92         Converts coordinates @a pos relative to given @a cell to
  93         physical coordinates in the window.
  94      */
  95     virtual wxPoint HTMLCoordsToWindow(wxHtmlCell *cell,
  96                                        const wxPoint& pos) const = 0;
  97
  98     /// Returns the window used for rendering (may be NULL).
  99     virtual wxWindow* GetHTMLWindow() = 0;
 100
 101     /// Returns background colour to use by default.
 102     virtual wxColour GetHTMLBackgroundColour() const = 0;
 103
 104     /// Sets window's background to colour @a clr.
 105     virtual void SetHTMLBackgroundColour(const wxColour& clr) = 0;
 106
 107     /// Sets window's background to given bitmap.
 108     virtual void SetHTMLBackgroundImage(const wxBitmap& bmpBg) = 0;
 109
 110     /// Sets status bar text.
 111     virtual void SetHTMLStatusText(const wxString& text) = 0;
 112
 113     /// Type of mouse cursor
 114     enum HTMLCursor
 115     {
 116         /// Standard mouse cursor (typically an arrow)
 117         HTMLCursor_Default,
 118         /// Cursor shown over links
 119         HTMLCursor_Link,
 120         /// Cursor shown over selectable text
 121         HTMLCursor_Text
 122     };
 123
 124     /**
 125         Returns mouse cursor of given @a type.
 126      */
 127     virtual wxCursor GetHTMLCursor(HTMLCursor type) const = 0;
 128 };
 129
 130 /**
 131     Helper class that implements part of mouse handling for wxHtmlWindow and
 132     wxHtmlListBox. Cursor changes and clicking on links are handled, text
 133     selection is not.
 134  */
 135 class WXDLLIMPEXP_HTML wxHtmlWindowMouseHelper
 136 {
 137 protected:
 138     /**
 139         Ctor.
 140
 141         @param iface Interface to the owner window.
 142      */
 143     wxHtmlWindowMouseHelper(wxHtmlWindowInterface *iface);
 144
 145     /// Returns true if the mouse moved since the last call to HandleIdle
 146     bool DidMouseMove() const { return m_tmpMouseMoved; }
 147
 148     /// Call this from EVT_MOTION event handler
 149     void HandleMouseMoved();
 150
 151     /**
 152         Call this from EVT_LEFT_UP handler (or, alternatively, EVT_LEFT_DOWN).
 153
 154         @param rootCell HTML cell inside which the click occured. This doesn't
 155                         have to be the leaf cell, it can be e.g. toplevel
 156                         container, but the mouse must be inside the container's
 157                         area, otherwise the event would be ignored.
 158         @param pos      Mouse position in coordinates relative to @a cell
 159         @param event    The event that triggered the call
 160      */
 161     bool HandleMouseClick(wxHtmlCell *rootCell,
 162                           const wxPoint& pos, const wxMouseEvent& event);
 163
 164     /**
 165         Call this from OnInternalIdle of the HTML displaying window. Handles
 166         mouse movements and must be used together with HandleMouseMoved.
 167
 168         @param rootCell HTML cell inside which the click occured. This doesn't
 169                         have to be the leaf cell, it can be e.g. toplevel
 170                         container, but the mouse must be inside the container's
 171                         area, otherwise the event would be ignored.
 172         @param pos      Current mouse position in coordinates relative to
 173                         @a cell
 174      */
 175     void HandleIdle(wxHtmlCell *rootCell, const wxPoint& pos);
 176
 177     /**
 178         Called by HandleIdle when the mouse hovers over a cell. Default
 179         behaviour is to do nothing.
 180
 181         @param cell   the cell the mouse is over
 182         @param x, y   coordinates of mouse relative to the cell
 183      */
 184     virtual void OnCellMouseHover(wxHtmlCell *cell, wxCoord x, wxCoord y);
 185
 186     /**
 187         Called by HandleMouseClick when the user clicks on a cell.
 188         Default behavior is to call wxHtmlWindowInterface::OnLinkClicked()
 189         if this cell corresponds to a hypertext link.
 190
 191         @param cell   the cell the mouse is over
 192         @param x, y   coordinates of mouse relative to the cell
 193         @param event    The event that triggered the call
 194
 195
 196         @return true if a link was clicked, false otherwise.
 197      */
 198     virtual bool OnCellClicked(wxHtmlCell *cell,
 199                                wxCoord x, wxCoord y,
 200                                const wxMouseEvent& event);
 201
 202 protected:
 203     // this flag indicates if the mouse moved (used by HandleIdle)
 204     bool m_tmpMouseMoved;
 205     // contains last link name
 206     wxHtmlLinkInfo *m_tmpLastLink;
 207     // contains the last (terminal) cell which contained the mouse
 208     wxHtmlCell *m_tmpLastCell;
 209
 210 private:
 211     wxHtmlWindowInterface *m_interface;
 212 };
 213
 214 // ----------------------------------------------------------------------------
 215 // wxHtmlWindow
 216 //                  (This is probably the only class you will directly use.)
 217 //                  Purpose of this class is to display HTML page (either local
 218 //                  file or downloaded via HTTP protocol) in a window. Width of
 219 //                  window is constant - given in constructor - virtual height
 220 //                  is changed dynamicly depending on page size.  Once the
 221 //                  window is created you can set it's content by calling
 222 //                  SetPage(text) or LoadPage(filename).
 223 // ----------------------------------------------------------------------------
 224
 225 class WXDLLIMPEXP_HTML wxHtmlWindow : public wxScrolledWindow,
 226                                       public wxHtmlWindowInterface,
 227                                       public wxHtmlWindowMouseHelper
 228 {
 229     DECLARE_DYNAMIC_CLASS(wxHtmlWindow)
 230     friend class wxHtmlWinModule;
 231
 232 public:
 233     wxHtmlWindow() : wxHtmlWindowMouseHelper(this) { Init(); }
 234     wxHtmlWindow(wxWindow *parent, wxWindowID id = wxID_ANY,
 235                  const wxPoint& pos = wxDefaultPosition,
 236                  const wxSize& size = wxDefaultSize,
 237                  long style = wxHW_DEFAULT_STYLE,
 238                  const wxString& name = wxT("htmlWindow"))
 239         : wxHtmlWindowMouseHelper(this)
 240     {
 241         Init();
 242         Create(parent, id, pos, size, style, name);
 243     }
 244     ~wxHtmlWindow();
 245
 246     bool Create(wxWindow *parent, wxWindowID id = wxID_ANY,
 247                 const wxPoint& pos = wxDefaultPosition,
 248                 const wxSize& size = wxDefaultSize,
 249                 long style = wxHW_SCROLLBAR_AUTO,
 250                 const wxString& name = wxT("htmlWindow"));
 251
 252     // Set HTML page and display it. !! source is HTML document itself,
 253     // it is NOT address/filename of HTML document. If you want to
 254     // specify document location, use LoadPage() istead
 255     // Return value : false if an error occurred, true otherwise
 256     virtual bool SetPage(const wxString& source);
 257
 258     // Append to current page
 259     bool AppendToPage(const wxString& source);
 260
 261     // Load HTML page from given location. Location can be either
 262     // a) /usr/wxGTK2/docs/html/wx.htm
 263     // b) http://www.somewhere.uk/document.htm
 264     // c) ftp://ftp.somesite.cz/pub/something.htm
 265     // In case there is no prefix (http:,ftp:), the method
 266     // will try to find it itself (1. local file, then http or ftp)
 267     // After the page is loaded, the method calls SetPage() to display it.
 268     // Note : you can also use path relative to previously loaded page
 269     // Return value : same as SetPage
 270     virtual bool LoadPage(const wxString& location);
 271
 272     // Loads HTML page from file
 273     bool LoadFile(const wxFileName& filename);
 274
 275     // Returns full location of opened page
 276     wxString GetOpenedPage() const {return m_OpenedPage;}
 277     // Returns anchor within opened page
 278     wxString GetOpenedAnchor() const {return m_OpenedAnchor;}
 279     // Returns <TITLE> of opened page or empty string otherwise
 280     wxString GetOpenedPageTitle() const {return m_OpenedPageTitle;}
 281
 282     // Sets frame in which page title will  be displayed. Format is format of
 283     // frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s
 284     void SetRelatedFrame(wxFrame* frame, const wxString& format);
 285     wxFrame* GetRelatedFrame() const {return m_RelatedFrame;}
 286
 287 #if wxUSE_STATUSBAR
 288     // After(!) calling SetRelatedFrame, this sets statusbar slot where messages
 289     // will be displayed. Default is -1 = no messages.
 290     void SetRelatedStatusBar(int bar);
 291 #endif // wxUSE_STATUSBAR
 292
 293     // Sets fonts to be used when displaying HTML page.
 294     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 295                   const int *sizes = NULL);
 296
 297     // Sets font sizes to be relative to the given size or the system
 298     // default size; use either specified or default font
 299     void SetStandardFonts(int size = -1,
 300                           const wxString& normal_face = wxEmptyString,
 301                           const wxString& fixed_face = wxEmptyString);
 302
 303     // Sets space between text and window borders.
 304     void SetBorders(int b) {m_Borders = b;}
 305
 306     // Sets the bitmap to use for background (currnetly it will be tiled,
 307     // when/if we have CSS support we could add other possibilities...)
 308     void SetBackgroundImage(const wxBitmap& bmpBg) { m_bmpBg = bmpBg; }
 309
 310     // Saves custom settings into cfg config. it will use the path 'path'
 311     // if given, otherwise it will save info into currently selected path.
 312     // saved values : things set by SetFonts, SetBorders.
 313     virtual void ReadCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 314     // ...
 315     virtual void WriteCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 316
 317     // Goes to previous/next page (in browsing history)
 318     // Returns true if successful, false otherwise
 319     bool HistoryBack();
 320     bool HistoryForward();
 321     bool HistoryCanBack();
 322     bool HistoryCanForward();
 323     // Resets history
 324     void HistoryClear();
 325
 326     // Returns pointer to conteiners/cells structure.
 327     // It should be used ONLY when printing
 328     wxHtmlContainerCell* GetInternalRepresentation() const {return m_Cell;}
 329
 330     // Adds input filter
 331     static void AddFilter(wxHtmlFilter *filter);
 332
 333     // Returns a pointer to the parser.
 334     wxHtmlWinParser *GetParser() const { return m_Parser; }
 335
 336     // Adds HTML processor to this instance of wxHtmlWindow:
 337     void AddProcessor(wxHtmlProcessor *processor);
 338     // Adds HTML processor to wxHtmlWindow class as whole:
 339     static void AddGlobalProcessor(wxHtmlProcessor *processor);
 340
 341
 342     // -- Callbacks --
 343
 344     // Sets the title of the window
 345     // (depending on the information passed to SetRelatedFrame() method)
 346     virtual void OnSetTitle(const wxString& title);
 347
 348     // Called when user clicked on hypertext link. Default behavior is to
 349     // call LoadPage(loc)
 350     virtual void OnLinkClicked(const wxHtmlLinkInfo& link);
 351
 352     // Called when wxHtmlWindow wants to fetch data from an URL (e.g. when
 353     // loading a page or loading an image). The data are downloaded if and only if
 354     // OnOpeningURL returns true. If OnOpeningURL returns wxHTML_REDIRECT,
 355     // it must set *redirect to the new URL
 356     virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType WXUNUSED(type),
 357                                              const wxString& WXUNUSED(url),
 358                                              wxString *WXUNUSED(redirect)) const
 359         { return wxHTML_OPEN; }
 360
 361 #if wxUSE_CLIPBOARD
 362     // Helper functions to select parts of page:
 363     void SelectWord(const wxPoint& pos);
 364     void SelectLine(const wxPoint& pos);
 365     void SelectAll();
 366
 367     // Convert selection to text:
 368     wxString SelectionToText() { return DoSelectionToText(m_selection); }
 369
 370     // Converts current page to text:
 371     wxString ToText();
 372 #endif // wxUSE_CLIPBOARD
 373
 374     virtual void OnInternalIdle();
 375
 376     /// Returns standard HTML cursor as used by wxHtmlWindow
 377     static wxCursor GetDefaultHTMLCursor(HTMLCursor type);
 378
 379 protected:
 380     void Init();
 381
 382     // Scrolls to anchor of this name. (Anchor is #news
 383     // or #features etc. it is part of address sometimes:
 384     // http://www.ms.mff.cuni.cz/~vsla8348/wxhtml/index.html#news)
 385     // Return value : true if anchor exists, false otherwise
 386     bool ScrollToAnchor(const wxString& anchor);
 387
 388     // Prepares layout (= fill m_PosX, m_PosY for fragments) based on
 389     // actual size of window. This method also setup scrollbars
 390     void CreateLayout();
 391
 392     void OnEraseBackground(wxEraseEvent& event);
 393     void OnPaint(wxPaintEvent& event);
 394     void OnSize(wxSizeEvent& event);
 395     void OnMouseMove(wxMouseEvent& event);
 396     void OnMouseDown(wxMouseEvent& event);
 397     void OnMouseUp(wxMouseEvent& event);
 398 #if wxUSE_CLIPBOARD
 399     void OnKeyUp(wxKeyEvent& event);
 400     void OnDoubleClick(wxMouseEvent& event);
 401     void OnCopy(wxCommandEvent& event);
 402     void OnMouseEnter(wxMouseEvent& event);
 403     void OnMouseLeave(wxMouseEvent& event);
 404 #endif // wxUSE_CLIPBOARD
 405
 406     // Returns new filter (will be stored into m_DefaultFilter variable)
 407     virtual wxHtmlFilter *GetDefaultFilter() {return new wxHtmlFilterPlainText;}
 408
 409     // cleans static variables
 410     static void CleanUpStatics();
 411
 412     // Returns true if text selection is enabled (wxClipboard must be available
 413     // and wxHW_NO_SELECTION not used)
 414     bool IsSelectionEnabled() const;
 415
 416     enum ClipboardType
 417     {
 418         Primary,
 419         Secondary
 420     };
 421
 422     // Copies selection to clipboard if the clipboard support is available
 423     //
 424     // returns true if anything was copied to clipboard, false otherwise
 425     bool CopySelection(ClipboardType t = Secondary);
 426
 427 #if wxUSE_CLIPBOARD
 428     // Automatic scrolling during selection:
 429     void StopAutoScrolling();
 430 #endif // wxUSE_CLIPBOARD
 431
 432     wxString DoSelectionToText(wxHtmlSelection *sel);
 433
 434 private:
 435     // wxHtmlWindowInterface methods:
 436     virtual void SetHTMLWindowTitle(const wxString& title);
 437     virtual void OnHTMLLinkClicked(const wxHtmlLinkInfo& link);
 438     virtual wxHtmlOpeningStatus OnHTMLOpeningURL(wxHtmlURLType type,
 439                                                  const wxString& url,
 440                                                  wxString *redirect) const;
 441     virtual wxPoint HTMLCoordsToWindow(wxHtmlCell *cell,
 442                                        const wxPoint& pos) const;
 443     virtual wxWindow* GetHTMLWindow();
 444     virtual wxColour GetHTMLBackgroundColour() const;
 445     virtual void SetHTMLBackgroundColour(const wxColour& clr);
 446     virtual void SetHTMLBackgroundImage(const wxBitmap& bmpBg);
 447     virtual void SetHTMLStatusText(const wxString& text);
 448     virtual wxCursor GetHTMLCursor(HTMLCursor type) const;
 449
 450     // implementation of SetPage()
 451     bool DoSetPage(const wxString& source);
 452
 453 protected:
 454     // This is pointer to the first cell in parsed data.  (Note: the first cell
 455     // is usually top one = all other cells are sub-cells of this one)
 456     wxHtmlContainerCell *m_Cell;
 457     // parser which is used to parse HTML input.
 458     // Each wxHtmlWindow has it's own parser because sharing one global
 459     // parser would be problematic (because of reentrancy)
 460     wxHtmlWinParser *m_Parser;
 461     // contains name of actualy opened page or empty string if no page opened
 462     wxString m_OpenedPage;
 463     // contains name of current anchor within m_OpenedPage
 464     wxString m_OpenedAnchor;
 465     // contains title of actualy opened page or empty string if no <TITLE> tag
 466     wxString m_OpenedPageTitle;
 467     // class for opening files (file system)
 468     wxFileSystem* m_FS;
 469
 470     wxFrame *m_RelatedFrame;
 471     wxString m_TitleFormat;
 472 #if wxUSE_STATUSBAR
 473     // frame in which page title should be displayed & number of it's statusbar
 474     // reserved for usage with this html window
 475     int m_RelatedStatusBar;
 476 #endif // wxUSE_STATUSBAR
 477
 478     // borders (free space between text and window borders)
 479     // defaults to 10 pixels.
 480     int m_Borders;
 481
 482     int m_Style;
 483
 484     // current text selection or NULL
 485     wxHtmlSelection *m_selection;
 486
 487     // true if the user is dragging mouse to select text
 488     bool m_makingSelection;
 489
 490 #if wxUSE_CLIPBOARD
 491     // time of the last doubleclick event, used to detect tripleclicks
 492     // (tripleclicks are used to select whole line):
 493     wxMilliClock_t m_lastDoubleClick;
 494
 495     // helper class to automatically scroll the window if the user is selecting
 496     // text and the mouse leaves wxHtmlWindow:
 497     wxHtmlWinAutoScrollTimer *m_timerAutoScroll;
 498 #endif // wxUSE_CLIPBOARD
 499
 500 private:
 501     // window content for double buffered rendering:
 502     wxBitmap *m_backBuffer;
 503
 504     // background image, may be invalid
 505     wxBitmap m_bmpBg;
 506
 507     // variables used when user is selecting text
 508     wxPoint     m_tmpSelFromPos;
 509     wxHtmlCell *m_tmpSelFromCell;
 510
 511     // if >0 contents of the window is not redrawn
 512     // (in order to avoid ugly blinking)
 513     int m_tmpCanDrawLocks;
 514
 515     // list of HTML filters
 516     static wxList m_Filters;
 517     // this filter is used when no filter is able to read some file
 518     static wxHtmlFilter *m_DefaultFilter;
 519
 520     // html processors array:
 521     wxHtmlProcessorList *m_Processors;
 522     static wxHtmlProcessorList *m_GlobalProcessors;
 523
 524     // browser history
 525     wxHtmlHistoryArray *m_History;
 526     int m_HistoryPos;
 527     // if this FLAG is false, items are not added to history
 528     bool m_HistoryOn;
 529
 530     // a flag set if we need to erase background in OnPaint() (otherwise this
 531     // is supposed to have been done in OnEraseBackground())
 532     bool m_eraseBgInOnPaint;
 533
 534     // standard mouse cursors
 535     static wxCursor *ms_cursorLink;
 536     static wxCursor *ms_cursorText;
 537
 538     DECLARE_EVENT_TABLE()
 539     DECLARE_NO_COPY_CLASS(wxHtmlWindow)
 540 };
 541
 542
 543 #endif // wxUSE_HTML
 544
 545 #endif // _WX_HTMLWIN_H_
 546