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
  42 // enums for wxHtmlWindow::OnOpeningURL
  43 enum wxHtmlOpeningStatus
  44 {
  45     wxHTML_OPEN,
  46     wxHTML_BLOCK,
  47     wxHTML_REDIRECT
  48 };
  49
  50 // ----------------------------------------------------------------------------
  51 // wxHtmlWindow
  52 //                  (This is probably the only class you will directly use.)
  53 //                  Purpose of this class is to display HTML page (either local
  54 //                  file or downloaded via HTTP protocol) in a window. Width of
  55 //                  window is constant - given in constructor - virtual height
  56 //                  is changed dynamicly depending on page size.  Once the
  57 //                  window is created you can set it's content by calling
  58 //                  SetPage(text) or LoadPage(filename).
  59 // ----------------------------------------------------------------------------
  60
  61 class WXDLLIMPEXP_HTML wxHtmlWindow : public wxScrolledWindow
  62 {
  63     DECLARE_DYNAMIC_CLASS(wxHtmlWindow)
  64     friend class wxHtmlWinModule;
  65
  66 public:
  67     wxHtmlWindow() { Init(); }
  68     wxHtmlWindow(wxWindow *parent, wxWindowID id = wxID_ANY,
  69                  const wxPoint& pos = wxDefaultPosition,
  70                  const wxSize& size = wxDefaultSize,
  71                  long style = wxHW_DEFAULT_STYLE,
  72                  const wxString& name = wxT("htmlWindow"))
  73     {
  74         Init();
  75         Create(parent, id, pos, size, style, name);
  76     }
  77     ~wxHtmlWindow();
  78
  79     bool Create(wxWindow *parent, wxWindowID id = wxID_ANY,
  80                 const wxPoint& pos = wxDefaultPosition,
  81                 const wxSize& size = wxDefaultSize,
  82                 long style = wxHW_SCROLLBAR_AUTO,
  83                 const wxString& name = wxT("htmlWindow"));
  84
  85     // Set HTML page and display it. !! source is HTML document itself,
  86     // it is NOT address/filename of HTML document. If you want to
  87     // specify document location, use LoadPage() istead
  88     // Return value : false if an error occurred, true otherwise
  89     virtual bool SetPage(const wxString& source);
  90
  91     // Append to current page
  92     bool AppendToPage(const wxString& source);
  93
  94     // Load HTML page from given location. Location can be either
  95     // a) /usr/wxGTK2/docs/html/wx.htm
  96     // b) http://www.somewhere.uk/document.htm
  97     // c) ftp://ftp.somesite.cz/pub/something.htm
  98     // In case there is no prefix (http:,ftp:), the method
  99     // will try to find it itself (1. local file, then http or ftp)
 100     // After the page is loaded, the method calls SetPage() to display it.
 101     // Note : you can also use path relative to previously loaded page
 102     // Return value : same as SetPage
 103     virtual bool LoadPage(const wxString& location);
 104
 105     // Loads HTML page from file
 106     bool LoadFile(const wxFileName& filename);
 107
 108     // Returns full location of opened page
 109     wxString GetOpenedPage() const {return m_OpenedPage;}
 110     // Returns anchor within opened page
 111     wxString GetOpenedAnchor() const {return m_OpenedAnchor;}
 112     // Returns <TITLE> of opened page or empty string otherwise
 113     wxString GetOpenedPageTitle() const {return m_OpenedPageTitle;}
 114
 115     // Sets frame in which page title will  be displayed. Format is format of
 116     // frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s
 117     void SetRelatedFrame(wxFrame* frame, const wxString& format);
 118     wxFrame* GetRelatedFrame() const {return m_RelatedFrame;}
 119
 120 #if wxUSE_STATUSBAR
 121     // After(!) calling SetRelatedFrame, this sets statusbar slot where messages
 122     // will be displayed. Default is -1 = no messages.
 123     void SetRelatedStatusBar(int bar);
 124 #endif // wxUSE_STATUSBAR
 125
 126     // Sets fonts to be used when displaying HTML page.
 127     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 128                   const int *sizes = NULL);
 129
 130     // Sets font sizes to be relative to the given size or the system
 131     // default size; use either specified or default font
 132     void SetStandardFonts(int size = -1,
 133                           const wxString& normal_face = wxEmptyString,
 134                           const wxString& fixed_face = wxEmptyString);
 135
 136     // Sets space between text and window borders.
 137     void SetBorders(int b) {m_Borders = b;}
 138
 139     // Sets the bitmap to use for background (currnetly it will be tiled,
 140     // when/if we have CSS support we could add other possibilities...)
 141     void SetBackgroundImage(const wxBitmap& bmpBg) { m_bmpBg = bmpBg; }
 142
 143     // Saves custom settings into cfg config. it will use the path 'path'
 144     // if given, otherwise it will save info into currently selected path.
 145     // saved values : things set by SetFonts, SetBorders.
 146     virtual void ReadCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 147     // ...
 148     virtual void WriteCustomization(wxConfigBase *cfg, wxString path = wxEmptyString);
 149
 150     // Goes to previous/next page (in browsing history)
 151     // Returns true if successful, false otherwise
 152     bool HistoryBack();
 153     bool HistoryForward();
 154     bool HistoryCanBack();
 155     bool HistoryCanForward();
 156     // Resets history
 157     void HistoryClear();
 158
 159     // Returns pointer to conteiners/cells structure.
 160     // It should be used ONLY when printing
 161     wxHtmlContainerCell* GetInternalRepresentation() const {return m_Cell;}
 162
 163     // Adds input filter
 164     static void AddFilter(wxHtmlFilter *filter);
 165
 166     // Returns a pointer to the parser.
 167     wxHtmlWinParser *GetParser() const { return m_Parser; }
 168
 169     // Adds HTML processor to this instance of wxHtmlWindow:
 170     void AddProcessor(wxHtmlProcessor *processor);
 171     // Adds HTML processor to wxHtmlWindow class as whole:
 172     static void AddGlobalProcessor(wxHtmlProcessor *processor);
 173
 174
 175     // -- Callbacks --
 176
 177     // Sets the title of the window
 178     // (depending on the information passed to SetRelatedFrame() method)
 179     virtual void OnSetTitle(const wxString& title);
 180
 181     // Called when the mouse hovers over a cell: (x, y) are logical coords
 182     // Default behaviour is to do nothing at all
 183     virtual void OnCellMouseHover(wxHtmlCell *cell, wxCoord x, wxCoord y);
 184
 185     // Called when user clicks on a cell. Default behavior is to call
 186     // OnLinkClicked() if this cell corresponds to a hypertext link
 187     virtual void OnCellClicked(wxHtmlCell *cell,
 188                                wxCoord x, wxCoord y,
 189                                const wxMouseEvent& event);
 190
 191     // Called when user clicked on hypertext link. Default behavior is to
 192     // call LoadPage(loc)
 193     virtual void OnLinkClicked(const wxHtmlLinkInfo& link);
 194
 195     // Called when wxHtmlWindow wants to fetch data from an URL (e.g. when
 196     // loading a page or loading an image). The data are downloaded if and only if
 197     // OnOpeningURL returns true. If OnOpeningURL returns wxHTML_REDIRECT,
 198     // it must set *redirect to the new URL
 199     virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType WXUNUSED(type),
 200                                              const wxString& WXUNUSED(url),
 201                                              wxString *WXUNUSED(redirect)) const
 202         { return wxHTML_OPEN; }
 203
 204 #if wxUSE_CLIPBOARD
 205     // Helper functions to select parts of page:
 206     void SelectWord(const wxPoint& pos);
 207     void SelectLine(const wxPoint& pos);
 208     void SelectAll();
 209
 210     // Convert selection to text:
 211     wxString SelectionToText() { return DoSelectionToText(m_selection); }
 212
 213     // Converts current page to text:
 214     wxString ToText();
 215 #endif // wxUSE_CLIPBOARD
 216
 217     virtual void OnInternalIdle();
 218
 219 protected:
 220     void Init();
 221
 222     // Scrolls to anchor of this name. (Anchor is #news
 223     // or #features etc. it is part of address sometimes:
 224     // http://www.ms.mff.cuni.cz/~vsla8348/wxhtml/index.html#news)
 225     // Return value : true if anchor exists, false otherwise
 226     bool ScrollToAnchor(const wxString& anchor);
 227
 228     // Prepares layout (= fill m_PosX, m_PosY for fragments) based on
 229     // actual size of window. This method also setup scrollbars
 230     void CreateLayout();
 231
 232     void OnEraseBackground(wxEraseEvent& event);
 233     void OnPaint(wxPaintEvent& event);
 234     void OnSize(wxSizeEvent& event);
 235     void OnMouseMove(wxMouseEvent& event);
 236     void OnMouseDown(wxMouseEvent& event);
 237     void OnMouseUp(wxMouseEvent& event);
 238 #if wxUSE_CLIPBOARD
 239     void OnKeyUp(wxKeyEvent& event);
 240     void OnDoubleClick(wxMouseEvent& event);
 241     void OnCopy(wxCommandEvent& event);
 242     void OnMouseEnter(wxMouseEvent& event);
 243     void OnMouseLeave(wxMouseEvent& event);
 244 #endif // wxUSE_CLIPBOARD
 245
 246     // Returns new filter (will be stored into m_DefaultFilter variable)
 247     virtual wxHtmlFilter *GetDefaultFilter() {return new wxHtmlFilterPlainText;}
 248
 249     // cleans static variables
 250     static void CleanUpStatics();
 251
 252     // Returns true if text selection is enabled (wxClipboard must be available
 253     // and wxHW_NO_SELECTION not used)
 254     bool IsSelectionEnabled() const;
 255
 256     enum ClipboardType
 257     {
 258         Primary,
 259         Secondary
 260     };
 261
 262     // Copies selection to clipboard if the clipboard support is available
 263     //
 264     // returns true if anything was copied to clipboard, false otherwise
 265     bool CopySelection(ClipboardType t = Secondary);
 266
 267 #if wxUSE_CLIPBOARD
 268     // Automatic scrolling during selection:
 269     void StopAutoScrolling();
 270 #endif // wxUSE_CLIPBOARD
 271
 272     wxString DoSelectionToText(wxHtmlSelection *sel);
 273
 274 private:
 275     // implementation of SetPage()
 276     bool DoSetPage(const wxString& source);
 277
 278 protected:
 279     // This is pointer to the first cell in parsed data.  (Note: the first cell
 280     // is usually top one = all other cells are sub-cells of this one)
 281     wxHtmlContainerCell *m_Cell;
 282     // parser which is used to parse HTML input.
 283     // Each wxHtmlWindow has it's own parser because sharing one global
 284     // parser would be problematic (because of reentrancy)
 285     wxHtmlWinParser *m_Parser;
 286     // contains name of actualy opened page or empty string if no page opened
 287     wxString m_OpenedPage;
 288     // contains name of current anchor within m_OpenedPage
 289     wxString m_OpenedAnchor;
 290     // contains title of actualy opened page or empty string if no <TITLE> tag
 291     wxString m_OpenedPageTitle;
 292     // class for opening files (file system)
 293     wxFileSystem* m_FS;
 294
 295     wxFrame *m_RelatedFrame;
 296     wxString m_TitleFormat;
 297 #if wxUSE_STATUSBAR
 298     // frame in which page title should be displayed & number of it's statusbar
 299     // reserved for usage with this html window
 300     int m_RelatedStatusBar;
 301 #endif // wxUSE_STATUSBAR
 302
 303     // borders (free space between text and window borders)
 304     // defaults to 10 pixels.
 305     int m_Borders;
 306
 307     int m_Style;
 308
 309     // current text selection or NULL
 310     wxHtmlSelection *m_selection;
 311
 312     // true if the user is dragging mouse to select text
 313     bool m_makingSelection;
 314
 315 #if wxUSE_CLIPBOARD
 316     // time of the last doubleclick event, used to detect tripleclicks
 317     // (tripleclicks are used to select whole line):
 318     wxMilliClock_t m_lastDoubleClick;
 319
 320     // helper class to automatically scroll the window if the user is selecting
 321     // text and the mouse leaves wxHtmlWindow:
 322     wxHtmlWinAutoScrollTimer *m_timerAutoScroll;
 323 #endif // wxUSE_CLIPBOARD
 324
 325 private:
 326     // window content for double buffered rendering:
 327     wxBitmap *m_backBuffer;
 328
 329     // background image, may be invalid
 330     wxBitmap m_bmpBg;
 331
 332     // variables used when user is selecting text
 333     wxPoint     m_tmpSelFromPos;
 334     wxHtmlCell *m_tmpSelFromCell;
 335
 336     // contains last link name
 337     wxHtmlLinkInfo *m_tmpLastLink;
 338     // contains the last (terminal) cell which contained the mouse
 339     wxHtmlCell *m_tmpLastCell;
 340     // if >0 contents of the window is not redrawn
 341     // (in order to avoid ugly blinking)
 342     int m_tmpCanDrawLocks;
 343
 344     // list of HTML filters
 345     static wxList m_Filters;
 346     // this filter is used when no filter is able to read some file
 347     static wxHtmlFilter *m_DefaultFilter;
 348
 349     // html processors array:
 350     wxHtmlProcessorList *m_Processors;
 351     static wxHtmlProcessorList *m_GlobalProcessors;
 352
 353     // browser history
 354     wxHtmlHistoryArray *m_History;
 355     int m_HistoryPos;
 356     // if this FLAG is false, items are not added to history
 357     bool m_HistoryOn;
 358
 359     // a flag indicated if mouse moved
 360     // (if true we will try to change cursor in last call to OnIdle)
 361     bool m_tmpMouseMoved;
 362
 363     // a flag set if we need to erase background in OnPaint() (otherwise this
 364     // is supposed to have been done in OnEraseBackground())
 365     bool m_eraseBgInOnPaint;
 366
 367     DECLARE_EVENT_TABLE()
 368     DECLARE_NO_COPY_CLASS(wxHtmlWindow)
 369 };
 370
 371
 372 #endif // wxUSE_HTML
 373
 374 #endif // _WX_HTMLWIN_H_
 375