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