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 WebKit web engine */
  83     wxWEB_VIEW_BACKEND_WEBKIT,
  84
  85     /** Use Microsoft Internet Explorer as web engine */
  86     wxWEB_VIEW_BACKEND_IE
  87 };
  88
  89 /**
  90     @class wxWebHistoryItem
  91
  92     A simple class that contains the URL and title of an element of the history
  93     of a wxWebView.
  94
  95     @library{wxweb}
  96     @category{web}
  97
  98     @see wxWebView
  99  */
 100 class wxWebHistoryItem
 101 {
 102 public:
 103     /**
 104         Construtor.
 105     */
 106     wxWebHistoryItem(const wxString& url, const wxString& title);
 107
 108     /**
 109         @return The url of the page.
 110     */
 111     wxString GetUrl();
 112
 113     /**
 114         @return The title of the page.
 115     */
 116     wxString GetTitle();
 117 };
 118
 119 /**
 120     @class wxWebHandler
 121
 122     The base class for handling custom schemes in wxWebView, for example to
 123     allow virtual file system support.
 124
 125     @library{wxweb}
 126     @category{web}
 127
 128     @see wxWebView
 129  */
 130 class wxWebHandler
 131 {
 132 public:
 133     /**
 134         @return A pointer to the file represented by @c uri.
 135     */
 136     virtual wxFSFile* GetFile(const wxString &uri) = 0;
 137
 138     /**
 139         @return The name of the scheme, for example @c file or @c http.
 140     */
 141     virtual wxString GetName() const = 0;
 142 };
 143
 144 /**
 145     @class wxWebView
 146
 147     This control may be used to render web (HTML / CSS / javascript) documents.
 148
 149     @section descriptions Backend Descriptions
 150
 151     @par wxWEB_VIEW_BACKEND_IE (MSW)
 152
 153     The IE backend uses Microsoft's Trident rendering engine, specifically the
 154     version used by the locally installed copy of Internet Explorer. As such it
 155     is only available for the MSW port. By default recent versions of the
 156     <a href="http://msdn.microsoft.com/en-us/library/aa752085%28v=VS.85%29.aspx">WebBrowser</a>
 157     control, which this backend uses, emulate Internet Explorer 7. This can be
 158     changed with a registry setting, see
 159     <a href="http://msdn.microsoft.com/en-us/library/ee330730%28v=vs.85%29.aspx#browser_emulation">
 160     this</a> article for more information. This backend has full support for
 161     custom schemes and virtual file systems.
 162
 163     @par wxWEB_VIEW_WEBKIT (GTK)
 164
 165     Under GTK the WebKit backend uses
 166     <a href="http://webkitgtk.org/">WebKitGTK+</a>. The current minimum version
 167     required is 1.3.1 which ships by default with Ubuntu Natty and Debian
 168     Wheezy and has the package name libwebkitgtk-dev. Custom schemes and
 169     virtual files systems are supported under this backend, however embedded
 170     resources such as images and stylesheets are currently extracted to a
 171     temporary file before being loaded.
 172
 173     @par wxWEB_VIEW_WEBKIT (OSX)
 174
 175     The OSX WebKit backend uses Apple's
 176     <a href="http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/WebKit/Classes/WebView_Class/Reference/Reference.html#//apple_ref/doc/uid/20001903">WebView</a>
 177     class. Currently it does not support custom schemes and virtual file systems.
 178
 179     @section async Asynchronous Notifications
 180
 181     Many of the methods in wxWebView are asynchronous, i.e. they return
 182     immediately and perform their work in the background. This includes
 183     functions such as LoadUrl() and Reload(). To receive notification of the
 184     progress and completion of these functions you need to handle the events
 185     that are provided. Specifically @c wxEVT_COMMAND_WEB_VIEW_LOADED notifies
 186     when the page or a sub-frame has finished loading and
 187     @c wxEVT_COMMAND_WEB_VIEW_ERROR notifies that an error has occurred.
 188
 189     @section vfs Virtual File Systems and Custom Schemes
 190
 191     wxWebView supports the registering of custom scheme handlers, for example
 192     @c file or @c http. To do this create a new class which inherits from
 193     wxWebHandler, where the wxWebHandler::GetName() method returns the scheme
 194     you wish to handle and wxWebHandler::GetFile() returns a pointer to a
 195     wxFSFile which represents the given url. You can then register your handler
 196     with RegisterHandler() it will be called for all pages and resources.
 197
 198     wxWebFileHandler is provided to allow the navigation of pages inside a zip
 199     archive. It overrides the @c file scheme and provides support for the
 200     standard @c file syntax as well as paths to archives of the form
 201     @c file:///C:/exmaple/docs.zip;protocol=zip/main.htm
 202
 203     @beginEventEmissionTable{wxWebNavigationEvent}
 204     @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
 205        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
 206        to get a resource. This event may be vetoed to prevent navigating to this
 207        resource. Note that if the displayed HTML document has several frames, one
 208        such event will be generated per frame.
 209     @event{EVT_WEB_VIEW_NAVIGATED(id, func)}
 210        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was
 211        confirmed that a resource would be requested. This event may not be vetoed.
 212        Note that if the displayed HTML document has several frames, one such event
 213        will be generated per frame.
 214     @event{EVT_WEB_VIEW_LOADED(id, func)}
 215        Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document
 216        is fully loaded and displayed. Note that if the displayed HTML document has
 217        several frames, one such event will be generated per frame.
 218     @event{EVT_WEB_VIEW_ERRROR(id, func)}
 219        Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
 220        error occurs.
 221        The integer associated with this event will be a wxWebNavigationError item.
 222        The string associated with this event may contain a backend-specific more
 223        precise error message/code.
 224     @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
 225        Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
 226        window is created. You must handle this event if you want anything to
 227        happen, for example to load the page in a new window or tab.
 228     @event{EVT_WEB_VIEW_TITLE_CHANGED(id, func)}
 229        Process a @c wxEVT_COMMAND_WEB_VIEW_TITLE_CHANGED event, generated when
 230        the page title changes. Use GetString to get the title.
 231     @endEventTable
 232
 233     @library{wxweb}
 234     @category{ctrl,web}
 235     @see wxWebHandler, wxWebNavigationEvent
 236  */
 237 class wxWebView : public wxControl
 238 {
 239 public:
 240
 241     /**
 242         Creation function for two-step creation.
 243     */
 244     virtual bool Create(wxWindow* parent,
 245                         wxWindowID id,
 246                         const wxString& url,
 247                         const wxPoint& pos,
 248                         const wxSize& size,
 249                         long style,
 250                         const wxString& name) = 0;
 251
 252     /**
 253         Factory function to create a new wxWebView for two-step creation
 254         (you need to call wxWebView::Create on the returned object)
 255         @param backend which web engine to use as backend for wxWebView
 256         @return the created wxWebView, or NULL if the requested backend is
 257                 not available
 258      */
 259     static wxWebView* New(wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT);
 260
 261     /**
 262         Factory function to create a new wxWebView
 263         @param parent parent window to create this view in
 264         @param id ID of this control
 265         @param url URL to load by default in the web view
 266         @param pos position to create this control at
 267                (you may use wxDefaultPosition if you use sizers)
 268         @param size size to create this control with
 269                (you may use wxDefaultSize if you use sizers)
 270         @param backend which web engine to use as backend for wxWebView
 271         @return the created wxWebView, or NULL if the requested backend
 272                 is not available
 273     */
 274     static wxWebView* New(wxWindow* parent,
 275            wxWindowID id,
 276            const wxString& url = wxWebViewDefaultURLStr,
 277            const wxPoint& pos = wxDefaultPosition,
 278            const wxSize& size = wxDefaultSize,
 279            wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT,
 280            long style = 0,
 281            const wxString& name = wxWebViewNameStr);
 282
 283     /**
 284         Get the title of the current web page, or its URL/path if title is not
 285         available.
 286     */
 287     virtual wxString GetCurrentTitle() = 0;
 288
 289    /**
 290         Get the URL of the currently displayed document.
 291     */
 292     virtual wxString GetCurrentURL() = 0;
 293
 294     /**
 295         Get the HTML source code of the currently displayed document.
 296         @return The HTML source code, or an empty string if no page is currently
 297                 shown.
 298     */
 299     virtual wxString GetPageSource() = 0;
 300
 301     /**
 302         Get the text of the current page.
 303     */
 304     virtual wxString GetPageText() = 0;
 305
 306     /**
 307         Returns whether the web control is currently busy (e.g. loading a page).
 308     */
 309     virtual bool IsBusy() = 0;
 310
 311     /**
 312         Returns whether the web control is currently editable
 313     */
 314     virtual bool IsEditable() = 0;
 315
 316     /**
 317         Load a web page from a URL
 318         @param url The URL of the page to be loaded.
 319         @note Web engines generally report errors asynchronously, so if you wish
 320             to know whether loading the URL was successful, register to receive
 321             navigation error events.
 322     */
 323     virtual void LoadUrl(const wxString& url) = 0;
 324
 325     /**
 326         Opens a print dialog so that the user may print the currently
 327         displayed page.
 328     */
 329     virtual void Print() = 0;
 330
 331     /**
 332         Registers a custom scheme handler.
 333         @param handler A pointer to a heap allocated wxWebHandler.
 334     */
 335     virtual void RegisterHandler(wxWebHandler* handler) = 0;
 336
 337     /**
 338         Reload the currently displayed URL.
 339         @param flags A bit array that may optionally contain reload options.
 340     */
 341     virtual void Reload(wxWebViewReloadFlags flags = wxWEB_VIEW_RELOAD_DEFAULT) = 0;
 342
 343     /**
 344         Runs the given javascript code.
 345     */
 346     virtual void RunScript(const wxString& javascript) = 0;
 347
 348     /**
 349         Set the editable property of the web control. Enabling allows the user
 350         to edit the page even if the @c contenteditable attribute is not set.
 351         The exact capabilities vary with the backend being used.
 352     */
 353     virtual void SetEditable(bool enable = true) = 0;
 354
 355     /**
 356         Set the displayed page source to the contents of the given string.
 357         @param html    The string that contains the HTML data to display.
 358         @param baseUrl URL assigned to the HTML data, to be used to resolve
 359                     relative paths, for instance.
 360     */
 361     virtual void SetPage(const wxString& html, const wxString& baseUrl) = 0;
 362
 363     /**
 364         Set the displayed page source to the contents of the given stream.
 365         @param html    The stream to read HTML data from.
 366         @param baseUrl URL assigned to the HTML data, to be used to resolve
 367                     relative paths, for instance.
 368     */
 369     virtual void SetPage(wxInputStream& html, wxString baseUrl);
 370
 371     /**
 372         Stop the current page loading process, if any.
 373         May trigger an error event of type @c wxWEB_NAV_ERR_USER_CANCELLED.
 374         TODO: make @c wxWEB_NAV_ERR_USER_CANCELLED errors uniform across ports.
 375     */
 376     virtual void Stop() = 0;
 377
 378     /**
 379         @name Clipboard
 380     */
 381
 382     /**
 383         Returns @true if the current selection can be copied.
 384     */
 385     virtual bool CanCopy() = 0;
 386
 387     /**
 388         Returns @true if the current selection can be cut.
 389     */
 390     virtual bool CanCut() = 0;
 391
 392     /**
 393         Returns @true if data can be pasted.
 394     */
 395     virtual bool CanPaste() = 0;
 396
 397     /**
 398         Copies the current selection.
 399     */
 400     virtual void Copy() = 0;
 401
 402     /**
 403         Cuts the current selection.
 404     */
 405     virtual void Cut() = 0;
 406
 407     /**
 408         Pastes the current data.
 409     */
 410     virtual void Paste() = 0;
 411
 412     /**
 413         @name History
 414     */
 415
 416     /**
 417         Returns @true if it is possible to navigate backward in the history of
 418         visited pages.
 419     */
 420     virtual bool CanGoBack() = 0;
 421
 422     /**
 423         Returns @true if it is possible to navigate forward in the history of
 424         visited pages.
 425     */
 426     virtual bool CanGoForward() = 0;
 427
 428     /**
 429         Clear the history, this will also remove the visible page.
 430     */
 431     virtual void ClearHistory() = 0;
 432
 433     /**
 434         Enable or disable the history. This will also clear the history.
 435     */
 436     virtual void EnableHistory(bool enable = true) = 0;
 437
 438     /**
 439         Returns a list of items in the back history. The first item in the
 440         vector is the first page that was loaded by the control.
 441     */
 442     virtual wxVector<wxSharedPtr<wxWebHistoryItem> > GetBackwardHistory() = 0;
 443
 444     /**
 445         Returns a list of items in the forward history. The first item in the
 446         vector is the next item in the history with respect to the curently
 447         loaded page.
 448     */
 449     virtual wxVector<wxSharedPtr<wxWebHistoryItem> > GetForwardHistory() = 0;
 450
 451     /**
 452         Navigate back in the history of visited pages.
 453         Only valid if CanGoBack() returns true.
 454     */
 455     virtual void GoBack() = 0;
 456
 457     /**
 458         Navigate forward in the history of visited pages.
 459         Only valid if CanGoForward() returns true.
 460     */
 461     virtual void GoForward() = 0;
 462
 463     /**
 464         Loads a history item.
 465     */
 466     virtual void LoadHistoryItem(wxSharedPtr<wxWebHistoryItem> item) = 0;
 467
 468     /**
 469         @name Selection
 470     */
 471
 472     /**
 473         Clears the current selection.
 474     */
 475     virtual void ClearSelection() = 0;
 476
 477     /**
 478         Deletes the current selection. Note that for @c wxWEB_VIEW_BACKEND_WEBKIT
 479         the selection must be editable, either through SetEditable or the
 480         correct HTML attribute.
 481     */
 482     virtual void DeleteSelection() = 0;
 483
 484     /**
 485         Returns the currently selected source, if any.
 486     */
 487     virtual wxString GetSelectedSource() = 0;
 488
 489     /**
 490         Returns the currently selected text, if any.
 491     */
 492     virtual wxString GetSelectedText() = 0;
 493
 494     /**
 495         Returns @true if there is a current selection.
 496     */
 497     virtual bool HasSelection() = 0;
 498
 499     /**
 500         Selects the entire page.
 501     */
 502     virtual void SelectAll() = 0;
 503
 504     /**
 505         @name Undo / Redo
 506     */
 507
 508     /**
 509         Returns @true if there is an action to redo.
 510     */
 511     virtual bool CanRedo() = 0;
 512
 513     /**
 514         Returns @true if there is an action to undo.
 515     */
 516     virtual bool CanUndo() = 0;
 517
 518     /**
 519         Redos the last action.
 520     */
 521     virtual void Redo() = 0;
 522
 523     /**
 524         Undos the last action.
 525     */
 526     virtual void Undo() = 0;
 527
 528     /**
 529         @name Zoom
 530     */
 531
 532     /**
 533         Retrieve whether the current HTML engine supports a zoom type.
 534         @param type The zoom type to test.
 535         @return Whether this type of zoom is supported by this HTML engine
 536                 (and thus can be set through SetZoomType()).
 537     */
 538     virtual bool CanSetZoomType(wxWebViewZoomType type) const = 0;
 539
 540     /**
 541         Get the zoom factor of the page.
 542         @return The current level of zoom.
 543     */
 544     virtual wxWebViewZoom GetZoom() = 0;
 545
 546     /**
 547         Get how the zoom factor is currently interpreted.
 548         @return How the zoom factor is currently interpreted by the HTML engine.
 549     */
 550     virtual wxWebViewZoomType GetZoomType() const = 0;
 551
 552     /**
 553         Set the zoom factor of the page.
 554         @param zoom How much to zoom (scale) the HTML document.
 555     */
 556     virtual void SetZoom(wxWebViewZoom zoom) = 0;
 557
 558     /**
 559         Set how to interpret the zoom factor.
 560         @param zoomType How the zoom factor should be interpreted by the
 561                         HTML engine.
 562         @note invoke    CanSetZoomType() first, some HTML renderers may not
 563                         support all zoom types.
 564     */
 565     virtual void SetZoomType(wxWebViewZoomType zoomType) = 0;
 566 };
 567
 568
 569
 570
 571 /**
 572     @class wxWebNavigationEvent
 573
 574     A navigation  event holds information about events associated with
 575     wxWebView objects.
 576
 577     @beginEventEmissionTable{wxWebNavigationEvent}
 578     @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
 579        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
 580        to get a resource. This event may be vetoed to prevent navigating to this
 581        resource. Note that if the displayed HTML document has several frames, one
 582        such event will be generated per frame.
 583     @event{EVT_WEB_VIEW_NAVIGATED(id, func)}
 584        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was
 585        confirmed that a resource would be requested. This event may not be vetoed.
 586        Note that if the displayed HTML document has several frames, one such event
 587        will be generated per frame.
 588     @event{EVT_WEB_VIEW_LOADED(id, func)}
 589        Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document
 590        is fully loaded and displayed. Note that if the displayed HTML document has
 591        several frames, one such event will be generated per frame.
 592     @event{EVT_WEB_VIEW_ERRROR(id, func)}
 593        Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
 594        error occurs.
 595        The integer associated with this event will be a wxWebNavigationError item.
 596        The string associated with this event may contain a backend-specific more
 597        precise error message/code.
 598     @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
 599        Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
 600        window is created. You must handle this event if you want anything to
 601        happen, for example to load the page in a new window or tab.
 602     @event{EVT_WEB_VIEW_TITLE_CHANGED(id, func)}
 603        Process a @c wxEVT_COMMAND_WEB_VIEW_TITLE_CHANGED event, generated when
 604        the page title changes. Use GetString to get the title.
 605     @endEventTable
 606
 607     @library{wxweb}
 608     @category{events,web}
 609
 610     @see wxWebView
 611 */
 612 class wxWebNavigationEvent : public wxCommandEvent
 613 {
 614 public:
 615     wxWebNavigationEvent();
 616     wxWebNavigationEvent(wxEventType type, int id, const wxString href,
 617                          const wxString target, bool canVeto);
 618
 619     /**
 620         Get the name of the target frame which the url of this event
 621         has been or will be loaded into. This may return an emptry string
 622         if the frame is not avaliable.
 623     */
 624     const wxString& GetTarget() const;
 625
 626     /**
 627         Get the URL being visited
 628     */
 629     const wxString& GetURL() const;
 630
 631     virtual wxEvent* Clone() const;
 632
 633     /**
 634         Get whether this event may be vetoed (stopped/prevented). Only
 635         meaningful for events fired before navigation takes place.
 636      */
 637     bool CanVeto() const;
 638
 639     /**
 640         Whether this event was vetoed (stopped/prevented). Only meaningful for
 641         events fired before navigation takes place or new window events.
 642      */
 643     bool IsVetoed() const;
 644
 645     /**
 646         Veto (prevent/stop) this event. Only meaningful for events fired
 647         before navigation takes place. Only valid if CanVeto() returned true.
 648      */
 649     void Veto();
 650 };