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