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