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