interface/wx/webview.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        webview.h
   3 // Purpose:     interface of wxWebView
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Zoom levels availiable in wxWebView
  11 */
  12 enum wxWebViewZoom
  13 {
  14     wxWEB_VIEW_ZOOM_TINY,
  15     wxWEB_VIEW_ZOOM_SMALL,
  16     wxWEB_VIEW_ZOOM_MEDIUM, //!< default size
  17     wxWEB_VIEW_ZOOM_LARGE,
  18     wxWEB_VIEW_ZOOM_LARGEST
  19 };
  20
  21 /**
  22     The type of zooming that the web view control can perform
  23 */
  24 enum wxWebViewZoomType
  25 {
  26     /**
  27         The entire layout scales when zooming, including images
  28     */
  29     wxWEB_VIEW_ZOOM_TYPE_LAYOUT,
  30     /**
  31         Only the text changes in size when zooming, images and other layout
  32         elements retain their initial size
  33     */
  34     wxWEB_VIEW_ZOOM_TYPE_TEXT
  35 };
  36
  37 /**
  38     Types of errors that can cause navigation to fail
  39 */
  40 enum wxWebNavigationError
  41 {
  42     /** Connection error (timeout, etc.) */
  43     wxWEB_NAV_ERR_CONNECTION,
  44     /** Invalid certificate */
  45     wxWEB_NAV_ERR_CERTIFICATE,
  46     /** Authentication required */
  47     wxWEB_NAV_ERR_AUTH,
  48     /** Other security error */
  49     wxWEB_NAV_ERR_SECURITY,
  50     /** Requested resource not found */
  51     wxWEB_NAV_ERR_NOT_FOUND,
  52     /** Invalid request/parameters (e.g. bad URL, bad protocol,
  53         unsupported resource type) */
  54     wxWEB_NAV_ERR_REQUEST,
  55     /** The user cancelled (e.g. in a dialog) */
  56     wxWEB_NAV_ERR_USER_CANCELLED,
  57     /** Another (exotic) type of error that didn't fit in other categories*/
  58     wxWEB_NAV_ERR_OTHER
  59 };
  60
  61 /**
  62     Type of refresh
  63 */
  64 enum wxWebViewReloadFlags
  65 {
  66     /** Default reload, will access cache */
  67     wxWEB_VIEW_RELOAD_DEFAULT,
  68     /** Reload the current view without accessing the cache */
  69     wxWEB_VIEW_RELOAD_NO_CACHE
  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 /**
  93     @class wxWebHistoryItem
  94
  95     A simple class that contains the URL and title of an element of the history
  96     of a wxWebView.
  97
  98     @library{wxweb}
  99     @category{web}
 100
 101     @see wxWebView
 102  */
 103 class wxWebHistoryItem
 104 {
 105 public:
 106     /**
 107         Construtor.
 108     */
 109     wxWebHistoryItem(const wxString& url, const wxString& title);
 110
 111     /**
 112         @return The url of the page.
 113     */
 114     wxString GetUrl();
 115
 116     /**
 117         @return The title of the page.
 118     */
 119     wxString GetTitle();
 120 };
 121
 122 /**
 123     @class wxWebView
 124
 125     This control may be used to render web (HTML / CSS / javascript) documents.
 126     Capabilities of the HTML renderer will depend upon the backed.
 127     TODO: describe each backend and its capabilities here
 128
 129     Note that errors are generally reported asynchronously though the
 130     @c wxEVT_COMMAND_WEB_VIEW_ERROR event described below.
 131
 132     @beginEventEmissionTable{wxWebNavigationEvent}
 133     @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
 134        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
 135        to get a resource. This event may be vetoed to prevent navigating to this
 136        resource. Note that if the displayed HTML document has several frames, one
 137        such event will be generated per frame.
 138     @event{EVT_WEB_VIEW_NAVIGATED(id, func)}
 139        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was
 140        confirmed that a resource would be requested. This event may not be vetoed.
 141        Note that if the displayed HTML document has several frames, one such event
 142        will be generated per frame.
 143     @event{EVT_WEB_VIEW_LOADED(id, func)}
 144        Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document
 145        is fully loaded and displayed.
 146     @event{EVT_WEB_VIEW_ERRROR(id, func)}
 147        Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
 148        error occurs.
 149        The integer associated with this event will be a wxWebNavigationError item.
 150        The string associated with this event may contain a backend-specific more
 151        precise error message/code.
 152     @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
 153        Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
 154        window is created. This event may be vetoed to prevent a new window showing,
 155        for example if you want to open the url in the existing window or a new tab.
 156     @endEventTable
 157
 158     @library{wxweb}
 159     @category{ctrl,web}
 160  */
 161 class wxWebView : public wxControl
 162 {
 163 public:
 164
 165     /**
 166         Creation function for two-step creation.
 167     */
 168     virtual bool Create(wxWindow* parent,
 169                         wxWindowID id,
 170                         const wxString& url,
 171                         const wxPoint& pos,
 172                         const wxSize& size,
 173                         long style,
 174                         const wxString& name) = 0;
 175
 176     /**
 177         Factory function to create a new wxWebView for two-step creation
 178         (you need to call wxWebView::Create on the returned object)
 179         @param backend which web engine to use as backend for wxWebView
 180         @return the created wxWebView, or NULL if the requested backend is
 181                 not available
 182      */
 183     static wxWebView* New(wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT);
 184
 185     /**
 186         Factory function to create a new wxWebView
 187         @param parent parent window to create this view in
 188         @param id ID of this control
 189         @param url URL to load by default in the web view
 190         @param pos position to create this control at
 191                (you may use wxDefaultPosition if you use sizers)
 192         @param size size to create this control with
 193                (you may use wxDefaultSize if you use sizers)
 194         @param backend which web engine to use as backend for wxWebView
 195         @return the created wxWebView, or NULL if the requested backend
 196                 is not available
 197     */
 198     static wxWebView* New(wxWindow* parent,
 199            wxWindowID id,
 200            const wxString& url = wxWebViewDefaultURLStr,
 201            const wxPoint& pos = wxDefaultPosition,
 202            const wxSize& size = wxDefaultSize,
 203            wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT,
 204            long style = 0,
 205            const wxString& name = wxWebViewNameStr);
 206
 207     /**
 208         Get the title of the current web page, or its URL/path if title is not
 209         available.
 210     */
 211     virtual wxString GetCurrentTitle() = 0;
 212
 213    /**
 214         Get the URL of the currently displayed document.
 215     */
 216     virtual wxString GetCurrentURL() = 0;
 217
 218     /**
 219         Get the HTML source code of the currently displayed document.
 220         @return The HTML source code, or an empty string if no page is currently
 221                 shown.
 222     */
 223     virtual wxString GetPageSource() = 0;
 224
 225     /**
 226         Returns whether the web control is currently busy (e.g. loading a page).
 227     */
 228     virtual bool IsBusy() = 0;
 229
 230     /**
 231         Load a web page from a URL
 232         @param url The URL of the page to be loaded.
 233         @note Web engines generally report errors asynchronously, so if you wish
 234             to know whether loading the URL was successful, register to receive
 235             navigation error events.
 236     */
 237     virtual void LoadUrl(const wxString& url) = 0;
 238
 239     /**
 240         Opens a print dialog so that the user may print the currently
 241         displayed page.
 242     */
 243     virtual void Print() = 0;
 244
 245     /**
 246         Reload the currently displayed URL.
 247         @param flags A bit array that may optionally contain reload options.
 248     */
 249     virtual void Reload(wxWebViewReloadFlags flags = wxWEB_VIEW_RELOAD_DEFAULT) = 0;
 250
 251     /**
 252         Set the displayed page source to the contents of the given string.
 253         @param html    The string that contains the HTML data to display.
 254         @param baseUrl URL assigned to the HTML data, to be used to resolve
 255                     relative paths, for instance.
 256     */
 257     virtual void SetPage(const wxString& html, const wxString& baseUrl) = 0;
 258
 259     /**
 260         Set the displayed page source to the contents of the given stream.
 261         @param html    The stream to read HTML data from.
 262         @param baseUrl URL assigned to the HTML data, to be used to resolve
 263                     relative paths, for instance.
 264     */
 265     virtual void SetPage(wxInputStream& html, wxString baseUrl)
 266     {
 267         wxStringOutputStream stream;
 268         stream.Write(html);
 269         SetPage(stream.GetString(), baseUrl);
 270     }
 271
 272     /**
 273         Stop the current page loading process, if any.
 274         May trigger an error event of type @c wxWEB_NAV_ERR_USER_CANCELLED.
 275         TODO: make @c wxWEB_NAV_ERR_USER_CANCELLED errors uniform across ports.
 276     */
 277     virtual void Stop() = 0;
 278
 279     /**
 280         @name Clipboard
 281     */
 282
 283     /**
 284         Returns @true if the current selection can be copied.
 285     */
 286     virtual bool CanCopy() = 0;
 287
 288     /**
 289         Returns @true if the current selection can be cut.
 290     */
 291     virtual bool CanCut() = 0;
 292
 293     /**
 294         Returns @true if data can be pasted.
 295     */
 296     virtual bool CanPaste() = 0;
 297
 298     /**
 299         Copies the current selection.
 300     */
 301     virtual void Copy() = 0;
 302
 303     /**
 304         Cuts the current selection.
 305     */
 306     virtual void Cut() = 0;
 307
 308     /**
 309         Pastes the current data.
 310     */
 311     virtual void Paste() = 0;
 312
 313     /**
 314         @name History
 315     */
 316
 317     /**
 318         Returns @true if it is possible to navigate backward in the history of
 319         visited pages.
 320     */
 321     virtual bool CanGoBack() = 0;
 322
 323     /**
 324         Returns @true if it is possible to navigate forward in the history of
 325         visited pages.
 326     */
 327     virtual bool CanGoForward() = 0;
 328
 329     /**
 330         Clear the history, this will also remove the visible page.
 331     */
 332     virtual void ClearHistory() = 0;
 333
 334     /**
 335         Enable or disable the history. This will also clear the history.
 336     */
 337     virtual void EnableHistory(bool enable = true) = 0;
 338
 339     /**
 340         Returns a list of items in the back history. The first item in the
 341         vector is the first page that was loaded by the control.
 342     */
 343     virtual wxVector<wxSharedPtr<wxWebHistoryItem> > GetBackwardHistory() = 0;
 344
 345     /**
 346         Returns a list of items in the forward history. The first item in the
 347         vector is the next item in the history with respect to the curently
 348         loaded page.
 349     */
 350     virtual wxVector<wxSharedPtr<wxWebHistoryItem> > GetForwardHistory() = 0;
 351
 352     /**
 353         Navigate back in the history of visited pages.
 354         Only valid if CanGoBack() returns true.
 355     */
 356     virtual void GoBack() = 0;
 357
 358     /**
 359         Navigate forward in the history of visited pages.
 360         Only valid if CanGoForward() returns true.
 361     */
 362     virtual void GoForward() = 0;
 363
 364     /**
 365         Loads a history item.
 366     */
 367     virtual void LoadHistoryItem(wxSharedPtr<wxWebHistoryItem> item) = 0;
 368
 369     /**
 370         @name Undo / Redo
 371     */
 372
 373     /**
 374         Returns @true if there is an action to redo.
 375     */
 376     virtual bool CanRedo() = 0;
 377
 378     /**
 379         Returns @true if there is an action to undo.
 380     */
 381     virtual bool CanUndo() = 0;
 382
 383     /**
 384         Redos the last action.
 385     */
 386     virtual void Redo() = 0;
 387
 388     /**
 389         Undos the last action.
 390     */
 391     virtual void Undo() = 0;
 392
 393     /**
 394         @name Zoom
 395     */
 396
 397     /**
 398         Retrieve whether the current HTML engine supports a zoom type.
 399         @param type The zoom type to test.
 400         @return Whether this type of zoom is supported by this HTML engine
 401                 (and thus can be set through SetZoomType()).
 402     */
 403     virtual bool CanSetZoomType(wxWebViewZoomType type) const = 0;
 404
 405     /**
 406         Get the zoom factor of the page.
 407         @return The current level of zoom.
 408     */
 409     virtual wxWebViewZoom GetZoom() = 0;
 410
 411     /**
 412         Get how the zoom factor is currently interpreted.
 413         @return How the zoom factor is currently interpreted by the HTML engine.
 414     */
 415     virtual wxWebViewZoomType GetZoomType() const = 0;
 416
 417     /**
 418         Set the zoom factor of the page.
 419         @param zoom How much to zoom (scale) the HTML document.
 420     */
 421     virtual void SetZoom(wxWebViewZoom zoom) = 0;
 422
 423     /**
 424         Set how to interpret the zoom factor.
 425         @param zoomType How the zoom factor should be interpreted by the
 426                         HTML engine.
 427         @note invoke    CanSetZoomType() first, some HTML renderers may not
 428                         support all zoom types.
 429     */
 430     virtual void SetZoomType(wxWebViewZoomType zoomType) = 0;
 431 };
 432
 433
 434
 435
 436 /**
 437     @class wxWebNavigationEvent
 438
 439     A navigation  event holds information about events associated with
 440     wxWebView objects.
 441
 442     @beginEventEmissionTable{wxWebNavigationEvent}
 443     @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
 444        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
 445        to get a resource. This event may be vetoed to prevent navigating to this
 446        resource. Note that if the displayed HTML document has several frames, one
 447        such event will be generated per frame.
 448     @event{EVT_WEB_VIEW_NAVIGATED(id, func)}
 449        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was
 450        confirmed that a resource would be requested. This event may not be vetoed.
 451        Note that if the displayed HTML document has several frames, one such event
 452        will be generated per frame.
 453     @event{EVT_WEB_VIEW_LOADED(id, func)}
 454        Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document
 455        is fully loaded and displayed.
 456     @event{EVT_WEB_VIEW_ERRROR(id, func)}
 457        Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
 458        error occurs.
 459        The integer associated with this event will be a wxWebNavigationError item.
 460        The string associated with this event may contain a backend-specific more
 461        precise error message/code.
 462     @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
 463        Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
 464        window is created. This event may be vetoed to prevent a new window showing,
 465        for example if you want to open the url in the existing window or a new tab.
 466     @endEventTable
 467
 468     @library{wxweb}
 469     @category{events,web}
 470
 471     @see wxWebView
 472 */
 473 class wxWebNavigationEvent : public wxCommandEvent
 474 {
 475 public:
 476     wxWebNavigationEvent();
 477     wxWebNavigationEvent(wxEventType type, int id, const wxString href,
 478                          const wxString target, bool canVeto);
 479     /**
 480         Get the URL being visited
 481     */
 482     const wxString& GetHref() const { return m_href; }
 483
 484     /**
 485         Get the target (frame or window) in which the URL that caused this event
 486         is viewed, or an empty string if not available.
 487     */
 488     const wxString& GetTarget() const;
 489
 490     virtual wxEvent* Clone() const;
 491
 492     /**
 493         Get whether this event may be vetoed (stopped/prevented). Only
 494         meaningful for events fired before navigation takes place or new
 495         window events.
 496      */
 497     bool CanVeto() const;
 498
 499     /**
 500         Whether this event was vetoed (stopped/prevented). Only meaningful for
 501         events fired before navigation takes place or new window events.
 502      */
 503     bool IsVetoed() const;
 504
 505     /**
 506         Veto (prevent/stop) this event. Only meaningful for events fired
 507         before navigation takes place or new window events. Only valid
 508         if CanVeto() returned true.
 509      */
 510     void Veto();
 511 };