include/wx/webview.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        webview.h
   3 // Purpose:     Common interface and events for web view component
   4 // Author:      Marianne Gagnon
   5 // Id:          $Id$
   6 // Copyright:   (c) 2010 Marianne Gagnon
   7 // Licence:     wxWindows licence
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 #ifndef _WX_WEB_VIEW_H_
  11 #define _WX_WEB_VIEW_H_
  12
  13 #include <wx/control.h>
  14 #include <wx/event.h>
  15 #include <wx/sstream.h>
  16
  17 /**
  18  * Zoom level in web view component
  19  */
  20 enum wxWebViewZoom
  21 {
  22     wxWEB_VIEW_ZOOM_TINY,
  23     wxWEB_VIEW_ZOOM_SMALL,
  24     wxWEB_VIEW_ZOOM_MEDIUM,
  25     wxWEB_VIEW_ZOOM_LARGE,
  26     wxWEB_VIEW_ZOOM_LARGEST
  27 };
  28
  29 /**
  30  * The type of zooming that the web view control can perform
  31  */
  32 enum wxWebViewZoomType
  33 {
  34     /** The entire layout scales when zooming, including images */
  35     wxWEB_VIEW_ZOOM_TYPE_LAYOUT,
  36     /** Only the text changes in size when zooming, images and other layout
  37       * elements retain their initial size */
  38     wxWEB_VIEW_ZOOM_TYPE_TEXT
  39 };
  40
  41 /** Types of errors that can cause navigation to fail */
  42 enum wxWebNavigationError
  43 {
  44     /** Connection error (timeout, etc.) */
  45     wxWEB_NAV_ERR_CONNECTION = 1,
  46     /** Invalid certificate */
  47     wxWEB_NAV_ERR_CERTIFICATE = 2,
  48     /** Authentication required */
  49     wxWEB_NAV_ERR_AUTH = 3,
  50     /** Other security error */
  51     wxWEB_NAV_ERR_SECURITY = 4,
  52     /** Requested resource not found */
  53     wxWEB_NAV_ERR_NOT_FOUND = 5,
  54     /** Invalid request/parameters (e.g. bad URL, bad protocol,
  55       * unsupported resource type) */
  56     wxWEB_NAV_ERR_REQUEST = 6,
  57     /** The user cancelled (e.g. in a dialog) */
  58     wxWEB_NAV_ERR_USER_CANCELLED = 7,
  59     /** Another (exotic) type of error that didn't fit in other categories*/
  60     wxWEB_NAV_ERR_OTHER = 8
  61 };
  62
  63 /** Type of refresh */
  64 enum wxWebViewReloadFlags
  65 {
  66   /** Reload the current view without accessing the cache */
  67   wxWEB_VIEW_RELOAD_NO_CACHE = 1
  68 };
  69
  70
  71 /**
  72  * List of available backends for wxWebView
  73  */
  74 enum wxWebViewBackend
  75 {
  76     /** Value that may be passed to wxWebView to let it pick an appropriate
  77      * engine for the current platform*/
  78     wxWEB_VIEW_BACKEND_DEFAULT,
  79
  80     /** The OSX-native WebKit web engine */
  81     wxWEB_VIEW_BACKEND_OSX_WEBKIT,
  82
  83     /** The GTK port of the WebKit engine */
  84     wxWEB_VIEW_BACKEND_GTK_WEBKIT,
  85
  86     /** Use Microsoft Internet Explorer as web engine */
  87     wxWEB_VIEW_BACKEND_IE
  88 };
  89
  90 extern WXDLLIMPEXP_DATA_CORE(const char) wxWebViewNameStr[];
  91 extern WXDLLIMPEXP_DATA_CORE(const char) wxWebViewDefaultURLStr[];
  92
  93 /**
  94   * @class wxWebView
  95   *
  96   * This control may be used to render web (HTML / CSS / javascript) documents.
  97   * Capabilities of the HTML renderer will depend upon the backed.
  98   * TODO: describe each backend and its capabilities here
  99   *
 100   * Note that errors are generally reported asynchronously though the
 101   * wxEVT_COMMAND_WEB_VIEW_ERROR event described below.
 102   *
 103   * @beginEventEmissionTable{wxWebNavigationEvent}
 104   * @event{EVT_BUTTON(id, func)}
 105   *
 106   * @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
 107   * Process a wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
 108   * to get a resource. This event may be vetoed to prevent navigating to this
 109   * resource. Note that if the displayed HTML document has several frames, one
 110   * such event will be generated per frame.
 111   *
 112   * @event{EVT_WEB_VIEW_NAVIGATED(id, func)}
 113   * Process a wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was
 114   * confirmed that a resource would be requested. This event may not be vetoed.
 115   * Note that if the displayed HTML document has several frames, one such event
 116   * will be generated per frame.
 117   *
 118   * @event{EVT_WEB_VIEW_LOADED(id, func)}
 119   * Process a wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document
 120   * is fully loaded and displayed.
 121   *
 122   * @event{EVT_WEB_VIEW_ERRROR(id, func)}
 123   * Process a wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
 124   * error occurs.
 125   * The integer associated with this event will be a wxWebNavigationError item.
 126   * The string associated with this event may contain a backend-specific more
 127   * precise error message/code.
 128   *
 129   * @endEventTable
 130   */
 131 class wxWebView : public wxControl
 132 {
 133 public:
 134
 135     /**
 136      *  Creation function for two-step creation.
 137      */
 138     virtual bool Create(wxWindow* parent,
 139            wxWindowID id,
 140            const wxString& url,
 141            const wxPoint& pos,
 142            const wxSize& size,
 143            long style,
 144            const wxString& name) = 0;
 145
 146     /**
 147      * Factory function to create a new wxWebView for two-step creation
 148      * (you need to call wxWebView::Create on the returned object)
 149      * @param backend which web engine to use as backend for wxWebView
 150      * @return the created wxWebView, or NULL if the requested backend is
 151      *         not available
 152      */
 153     static wxWebView* New(wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT);
 154
 155     // TODO: clarify what styles can do, or remove this flag
 156     /**
 157      * Factory function to create a new wxWebView
 158      * @param parent parent window to create this view in
 159      * @param id ID of this control
 160      * @param url URL to load by default in the web view
 161      * @param pos position to create this control at
 162      *            (you may use wxDefaultPosition if you use sizers)
 163      * @param size size to create this control with
 164      *             (you may use wxDefaultSize if you use sizers)
 165      * @param backend which web engine to use as backend for wxWebView
 166      * @return the created wxWebView, or NULL if the requested backend
 167      *         is not available
 168      */
 169     static wxWebView* New(wxWindow* parent,
 170            wxWindowID id,
 171            const wxString& url = wxWebViewDefaultURLStr,
 172            const wxPoint& pos = wxDefaultPosition,
 173            const wxSize& size = wxDefaultSize,
 174            wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT,
 175            long style = 0,
 176            const wxString& name = wxWebViewNameStr);
 177
 178
 179     /** Get whether it is possible to navigate back in the history of
 180       * visited pages
 181       */
 182     virtual bool CanGoBack() = 0;
 183
 184     /** Get whether it is possible to navigate forward in the history of
 185       * visited pages
 186       */
 187     virtual bool CanGoForward() = 0;
 188
 189     /** Navigate back in the history of visited pages.
 190       * Only valid if CanGoBack() returned true.
 191       */
 192     virtual void GoBack() = 0;
 193
 194     /** Navigate forwardin the history of visited pages.
 195       * Only valid if CanGoForward() returned true.
 196       */
 197     virtual void GoForward() = 0;
 198
 199     /**
 200      * Load a HTMl document (web page) from a URL
 201      * @param url the URL where the HTML document to display can be found
 202      * @note web engines generally report errors asynchronously, so if you wish
 203      *       to know whether loading the URL was successful, register to receive
 204      *       navigation error events
 205      */
 206     virtual void LoadUrl(const wxString& url) = 0;
 207
 208     /**
 209      * Stop the current page loading process, if any.
 210      * May trigger an error event of type wxWEB_NAV_ERR_USER_CANCELLED.
 211      * TODO: make wxWEB_NAV_ERR_USER_CANCELLED errors uniform across ports.
 212      */
 213     virtual void Stop() = 0;
 214
 215     /**
 216      * Reload the currently displayed URL.
 217      * @param flags A bit array that may optionnally contain reload options
 218      */
 219     virtual void Reload(wxWebViewReloadFlags flags=0) = 0;
 220
 221
 222     /**
 223      * Get the URL of the currently displayed document
 224      */
 225     virtual wxString GetCurrentURL() = 0;
 226
 227     /**
 228      * Get the title of the current web page, or its URL/path if title is not
 229      * available
 230      */
 231     virtual wxString GetCurrentTitle() = 0;
 232
 233     // TODO: handle choosing a frame when calling GetPageSource()?
 234     /**
 235      * Get the HTML source code of the currently displayed document
 236      * @return the HTML source code, or an empty string if no page is currently
 237      *         shown
 238      */
 239     virtual wxString GetPageSource() = 0;
 240
 241    /**
 242      * Get the zoom factor of the page
 243      * @return How much the HTML document is zoomed (scaleed)
 244      */
 245     virtual wxWebViewZoom GetZoom() = 0;
 246
 247     /**
 248      * Set the zoom factor of the page
 249      * @param zoom How much to zoom (scale) the HTML document
 250      */
 251     virtual void SetZoom(wxWebViewZoom zoom) = 0;
 252
 253     /**
 254      * Set how to interpret the zoom factor
 255      * @param zoomType how the zoom factor should be interpreted by the
 256      *                 HTML engine
 257      * @note invoke    canSetZoomType() first, some HTML renderers may not
 258      *                 support all zoom types
 259      */
 260     virtual void SetZoomType(wxWebViewZoomType zoomType) = 0;
 261
 262     /**
 263      * Get how the zoom factor is currently interpreted
 264      * @return how the zoom factor is currently interpreted by the HTML engine
 265      */
 266     virtual wxWebViewZoomType GetZoomType() const = 0;
 267
 268     /**
 269      * Retrieve whether the current HTML engine supports a type of zoom
 270      * @param type the type of zoom to test
 271      * @return whether this type of zoom is supported by this HTML engine
 272      *         (and thus can be set through setZoomType())
 273      */
 274     virtual bool CanSetZoomType(wxWebViewZoomType type) const = 0;
 275
 276     // TODO: allow 'SetPage' to find files (e.g. images) from a virtual file
 277     // system if possible
 278     /**
 279      * Set the displayed page source to the contents of the given string
 280      * @param html    the string that contains the HTML data to display
 281      * @param baseUrl URL assigned to the HTML data, to be used to resolve
 282      *                relative paths, for instance
 283      */
 284     virtual void SetPage(const wxString& html, const wxString& baseUrl) = 0;
 285
 286     /**
 287      * Set the displayed page source to the contents of the given stream
 288      * @param html    the stream to read HTML data from
 289      * @param baseUrl URL assigned to the HTML data, to be used to resolve
 290      *                relative paths, for instance
 291      */
 292     virtual void SetPage(wxInputStream& html, wxString baseUrl)
 293     {
 294         wxStringOutputStream stream;
 295         stream.Write(html);
 296         SetPage(stream.GetString(), baseUrl);
 297     }
 298
 299     // TODO:
 300     //     wxString GetSelection();                         // maybe?
 301     //     void SetSelection(...);                          // maybe?
 302
 303     //     void MakeEditable(bool enable = true);           // maybe?
 304     //     bool IsEditable();                               // maybe?
 305
 306     //     void EnableJavascript(bool enabled);             // maybe?
 307     //     wxString RunScript(const wxString& javascript);  // maybe?
 308
 309     //     void SetScrollPos(int pos);                      // maybe?
 310     //     int GetScrollPos();                              // maybe?
 311
 312     //     wxString GetStatusText();                        // maybe?
 313     //     void SetStatusText(wxString text);               // maybe?
 314     //     * status text changed event?
 315     //     * title changed event?
 316
 317     //    virtual bool IsOfflineMode() = 0;                 // maybe?
 318     //     virtual void SetOfflineMode(bool offline) = 0;   // maybe?
 319
 320     // TODO: offer API to control the opening of new frames
 321     //       (through <a target="..."> as well as through javascript), OR
 322     //       provide a behavior consistent across ports.
 323     // - OSX : I receive an event for new frames opened with HTML target, and
 324     //           currently block them all.
 325     // - IE  : The DISPID_NEWWINDOW2 event looks like it should work, but I
 326     //           receive way too many of them. A new IE instance opens.
 327     // - GTK : All frame open requests are blocked. A slot exists that I could
 328     //           connect to to be notified if ever needed
 329
 330     /**
 331      * Opens a print dialog so that the user may print the currently
 332      * displayed page.
 333      */
 334     virtual void Print() = 0;
 335
 336     /**
 337      * Returns whether the web control is currently busy (e.g. loading a page)
 338      */
 339     virtual bool IsBusy() = 0;
 340 };
 341
 342 //class WXDLLIMPEXP_FWD_HTML wxWebNavigationEvent;
 343
 344 // FIXME: get those WXDLLIMPEXP_HTML & DECLARE_DYNAMIC_CLASS right...
 345 //wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_HTML, wxEVT_COMMAND_WEB_VIEW_NAVIGATE,
 346 //                         wxWebNavigationEvent );
 347
 348
 349 // FIXME: get those WXDLLIMPEXP_HTML & DECLARE_DYNAMIC_CLASS right...
 350 class wxWebNavigationEvent : public wxCommandEvent
 351 {
 352 public:
 353     wxWebNavigationEvent() {}
 354     wxWebNavigationEvent(wxEventType type, int id, const wxString href,
 355                          const wxString target, bool canVeto)
 356         : wxCommandEvent(type, id)
 357     {
 358         m_href = href;
 359         m_target = target;
 360         m_vetoed = false;
 361         m_canVeto = canVeto;
 362     }
 363
 364     /**
 365      *  Get the URL being visited
 366      */
 367     const wxString& GetHref() const { return m_href; }
 368
 369     /**
 370      * Get the target (frame or window) in which the URL that caused this event
 371      * is viewed, or an empty string if not available.
 372      */
 373     const wxString& GetTarget() const { return m_target; }
 374
 375     // default copy ctor, assignment operator and dtor are ok
 376     virtual wxEvent* Clone() const { return new wxWebNavigationEvent(*this); }
 377
 378     /** Get whether this event may be vetoed (stopped/prevented). Only
 379       *  meaningful for events fired before navigation takes place.
 380       */
 381     bool CanVeto() const { return m_canVeto; }
 382
 383     /** Whether this event was vetoed (stopped/prevented). Only meaningful for
 384      *  events fired before navigation takes place.
 385      */
 386     bool IsVetoed() const { return m_vetoed; }
 387
 388     /** Veto (prevent/stop) this event. Only meaningful for events fired
 389      *  before navigation takes place. Only valid if CanVeto() returned true.
 390      */
 391     void Veto() { wxASSERT(m_canVeto); m_vetoed = true; }
 392
 393 private:
 394     wxString m_href;
 395     wxString m_target;
 396     bool m_canVeto;
 397     bool m_vetoed;
 398
 399     wxDECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxWebNavigationEvent);
 400 };
 401
 402 wxDECLARE_EVENT( wxEVT_COMMAND_WEB_VIEW_NAVIGATING, wxWebNavigationEvent );
 403 wxDECLARE_EVENT( wxEVT_COMMAND_WEB_VIEW_NAVIGATED, wxWebNavigationEvent );
 404 wxDECLARE_EVENT( wxEVT_COMMAND_WEB_VIEW_LOADED, wxWebNavigationEvent );
 405 wxDECLARE_EVENT( wxEVT_COMMAND_WEB_VIEW_ERROR, wxWebNavigationEvent );
 406
 407 typedef void (wxEvtHandler::*wxWebNavigationEventFunction)
 408              (wxWebNavigationEvent&);
 409
 410 #define wxWebNavigationEventHandler(func) \
 411     wxEVENT_HANDLER_CAST(wxWebNavigationEventFunction, func)
 412
 413 #define EVT_WEB_VIEW_NAVIGATING(id, fn) \
 414     wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_NAVIGATING, id,
 415                      wxHtmlNavigatingEventHandler(fn))
 416
 417 #define EVT_WEB_VIEW_NAVIGATED(id, fn) \
 418     wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_NAVIGATED, id,
 419                      wxHtmlNavigatingEventHandler(fn))
 420
 421 #define EVT_WEB_VIEW_LOADED(id, fn) \
 422     wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_LOADED, id,
 423                      wxHtmlNavigatingEventHandler(fn))
 424
 425 #define EVT_WEB_VIEW_ERRROR(id, fn) \
 426     wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_ERROR, id,
 427                      wxHtmlNavigatingEventHandler(fn))
 428
 429 #endif