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