interface/wx/webview.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        webview.h
   3 // Purpose:     interface of wxWebView
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     Zoom levels available in wxWebView
  10 */
  11 enum wxWebViewZoom
  12 {
  13     wxWEBVIEW_ZOOM_TINY,
  14     wxWEBVIEW_ZOOM_SMALL,
  15     wxWEBVIEW_ZOOM_MEDIUM, //!< default size
  16     wxWEBVIEW_ZOOM_LARGE,
  17     wxWEBVIEW_ZOOM_LARGEST
  18 };
  19
  20 /**
  21     The type of zooming that the web view control can perform
  22 */
  23 enum wxWebViewZoomType
  24 {
  25     /**
  26         The entire layout scales when zooming, including images
  27     */
  28     wxWEBVIEW_ZOOM_TYPE_LAYOUT,
  29     /**
  30         Only the text changes in size when zooming, images and other layout
  31         elements retain their initial size
  32     */
  33     wxWEBVIEW_ZOOM_TYPE_TEXT
  34 };
  35
  36 /**
  37     Types of errors that can cause navigation to fail
  38 */
  39 enum wxWebViewNavigationError
  40 {
  41     /** Connection error (timeout, etc.) */
  42     wxWEBVIEW_NAV_ERR_CONNECTION,
  43     /** Invalid certificate */
  44     wxWEBVIEW_NAV_ERR_CERTIFICATE,
  45     /** Authentication required */
  46     wxWEBVIEW_NAV_ERR_AUTH,
  47     /** Other security error */
  48     wxWEBVIEW_NAV_ERR_SECURITY,
  49     /** Requested resource not found */
  50     wxWEBVIEW_NAV_ERR_NOT_FOUND,
  51     /** Invalid request/parameters (e.g. bad URL, bad protocol,
  52         unsupported resource type) */
  53     wxWEBVIEW_NAV_ERR_REQUEST,
  54     /** The user cancelled (e.g. in a dialog) */
  55     wxWEBVIEW_NAV_ERR_USER_CANCELLED,
  56     /** Another (exotic) type of error that didn't fit in other categories*/
  57     wxWEBVIEW_NAV_ERR_OTHER
  58 };
  59
  60 /**
  61     Type of refresh
  62 */
  63 enum wxWebViewReloadFlags
  64 {
  65     /** Default reload, will access cache */
  66     wxWEBVIEW_RELOAD_DEFAULT,
  67     /** Reload the current view without accessing the cache */
  68     wxWEBVIEW_RELOAD_NO_CACHE
  69 };
  70
  71 /**
  72     Find flags used when searching for text on page.
  73 */
  74 enum wxWebViewFindFlags
  75 {
  76     /** Causes the search to restart when end or beginning reached */
  77     wxWEBVIEW_FIND_WRAP =             0x0001,
  78
  79     /** Matches an entire word when searching */
  80     wxWEBVIEW_FIND_ENTIRE_WORD =      0x0002,
  81
  82     /** Match case, i.e. case sensitive searching */
  83     wxWEBVIEW_FIND_MATCH_CASE =       0x0004,
  84
  85     /** Highlights the search results */
  86     wxWEBVIEW_FIND_HIGHLIGHT_RESULT = 0x0008,
  87
  88     /** Searches for phrase in backward direction */
  89     wxWEBVIEW_FIND_BACKWARDS =        0x0010,
  90
  91     /** The default flag, which is simple searching */
  92     wxWEBVIEW_FIND_DEFAULT =          0
  93 };
  94
  95
  96 /**
  97     @class wxWebViewHistoryItem
  98
  99     A simple class that contains the URL and title of an element of the history
 100     of a wxWebView.
 101
 102     @since 2.9.3
 103     @library{wxwebview}
 104     @category{webview}
 105
 106     @see wxWebView
 107  */
 108 class wxWebViewHistoryItem
 109 {
 110 public:
 111     /**
 112         Construtor.
 113     */
 114     wxWebViewHistoryItem(const wxString& url, const wxString& title);
 115
 116     /**
 117         @return The url of the page.
 118     */
 119     wxString GetUrl();
 120
 121     /**
 122         @return The title of the page.
 123     */
 124     wxString GetTitle();
 125 };
 126
 127 /**
 128     @class wxWebViewFactory
 129
 130     An abstract factory class for creating wxWebView backends. Each
 131     implementation of wxWebView should have its own factory.
 132
 133     @since 2.9.5
 134     @library{wxwebview}
 135     @category{webview}
 136
 137     @see wxWebView
 138  */
 139 class wxWebViewFactory : public wxObject
 140 {
 141 public:
 142     /**
 143         Function to create a new wxWebView with two-step creation,
 144         wxWebView::Create should be called on the returned object.
 145         @return the created wxWebView
 146      */
 147     virtual wxWebView* Create() = 0;
 148
 149     /**
 150         Function to create a new wxWebView with parameters.
 151         @param parent Parent window for the control
 152         @param id ID of this control
 153         @param url Initial URL to load
 154         @param pos Position of the control
 155         @param size Size of the control
 156         @param style
 157             Window style. For generic window styles, please see wxWindow.
 158         @param name Window name.
 159         @return the created wxWebView
 160     */
 161     virtual wxWebView* Create(wxWindow* parent,
 162                               wxWindowID id,
 163                               const wxString& url = wxWebViewDefaultURLStr,
 164                               const wxPoint& pos = wxDefaultPosition,
 165                               const wxSize& size = wxDefaultSize,
 166                               long style = 0,
 167                               const wxString& name = wxWebViewNameStr) = 0;
 168 };
 169
 170 /**
 171     @class wxWebViewHandler
 172
 173     The base class for handling custom schemes in wxWebView, for example to
 174     allow virtual file system support.
 175
 176     @since 2.9.3
 177     @library{wxwebview}
 178     @category{webview}
 179
 180     @see wxWebView
 181  */
 182 class wxWebViewHandler
 183 {
 184 public:
 185     /**
 186         Constructor. Takes the name of the scheme that will be handled by this
 187         class for example @c file or @c zip.
 188     */
 189     wxWebViewHandler(const wxString& scheme);
 190
 191     /**
 192         @return A pointer to the file represented by @c uri.
 193     */
 194     virtual wxFSFile* GetFile(const wxString &uri) = 0;
 195
 196     /**
 197         @return The name of the scheme, as passed to the constructor.
 198     */
 199     virtual wxString GetName() const;
 200 };
 201
 202 /**
 203     @class wxWebView
 204
 205     This control may be used to render web (HTML / CSS / javascript) documents.
 206     It is designed to allow the creation of multiple backends for each port,
 207     although currently just one is available. It differs from wxHtmlWindow in
 208     that each backend is actually a full rendering engine, Trident on MSW and
 209     Webkit on OSX and GTK. This allows the correct viewing complex pages with
 210     javascript and css.
 211
 212     @section descriptions Backend Descriptions
 213
 214     @par wxWEBVIEW_BACKEND_IE (MSW)
 215
 216     The IE backend uses Microsoft's Trident rendering engine, specifically the
 217     version used by the locally installed copy of Internet Explorer. As such it
 218     is only available for the MSW port. By default recent versions of the
 219     <a href="http://msdn.microsoft.com/en-us/library/aa752085%28v=VS.85%29.aspx">WebBrowser</a>
 220     control, which this backend uses, emulate Internet Explorer 7. This can be
 221     changed with a registry setting, see
 222     <a href="http://msdn.microsoft.com/en-us/library/ee330730%28v=vs.85%29.aspx#browser_emulation">
 223     this</a> article for more information. This backend has full support for
 224     custom schemes and virtual file systems.
 225
 226     @par wxWEBVIEW_WEBKIT (GTK)
 227
 228     Under GTK the WebKit backend uses
 229     <a href="http://webkitgtk.org/">WebKitGTK+</a>. The current minimum version
 230     required is 1.3.1 which ships by default with Ubuntu Natty and Debian
 231     Wheezy and has the package name libwebkitgtk-dev. Custom schemes and
 232     virtual files systems are supported under this backend, however embedded
 233     resources such as images and stylesheets are currently loaded using the
 234     data:// scheme.
 235
 236     @par wxWEBVIEW_WEBKIT (OSX)
 237
 238     The OSX WebKit backend uses Apple's
 239     <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>
 240     class. This backend has full support for custom schemes and virtual file
 241     systems.
 242
 243     @section async Asynchronous Notifications
 244
 245     Many of the methods in wxWebView are asynchronous, i.e. they return
 246     immediately and perform their work in the background. This includes
 247     functions such as LoadURL() and Reload(). To receive notification of the
 248     progress and completion of these functions you need to handle the events
 249     that are provided. Specifically @c wxEVT_WEBVIEW_LOADED notifies
 250     when the page or a sub-frame has finished loading and
 251     @c wxEVT_WEBVIEW_ERROR notifies that an error has occurred.
 252
 253     @section vfs Virtual File Systems and Custom Schemes
 254
 255     wxWebView supports the registering of custom scheme handlers, for example
 256     @c file or @c http. To do this create a new class which inherits from
 257     wxWebViewHandler, where wxWebHandler::GetFile() returns a pointer to a
 258     wxFSFile which represents the given url. You can then register your handler
 259     with RegisterHandler() it will be called for all pages and resources.
 260
 261     wxWebViewFSHandler is provided to access the virtual file system encapsulated by
 262     wxFileSystem. The wxMemoryFSHandler documentation gives an example of how this
 263     may be used.
 264
 265     wxWebViewArchiveHandler is provided to allow the navigation of pages inside a zip
 266     archive. It supports paths of the form:
 267     @c scheme:///C:/example/docs.zip;protocol=zip/main.htm
 268
 269     @beginEventEmissionTable{wxWebViewEvent}
 270     @event{EVT_WEBVIEW_NAVIGATING(id, func)}
 271        Process a @c wxEVT_WEBVIEW_NAVIGATING event, generated before trying
 272        to get a resource. This event may be vetoed to prevent navigating to this
 273        resource. Note that if the displayed HTML document has several frames, one
 274        such event will be generated per frame.
 275     @event{EVT_WEBVIEW_NAVIGATED(id, func)}
 276        Process a @c wxEVT_WEBVIEW_NAVIGATED event generated after it was
 277        confirmed that a resource would be requested. This event may not be vetoed.
 278        Note that if the displayed HTML document has several frames, one such event
 279        will be generated per frame.
 280     @event{EVT_WEBVIEW_LOADED(id, func)}
 281        Process a @c wxEVT_WEBVIEW_LOADED event generated when the document
 282        is fully loaded and displayed. Note that if the displayed HTML document has
 283        several frames, one such event will be generated per frame.
 284     @event{EVT_WEBVIEW_ERROR(id, func)}
 285        Process a @c wxEVT_WEBVIEW_ERROR event generated when a navigation
 286        error occurs.
 287        The integer associated with this event will be a wxWebNavigationError item.
 288        The string associated with this event may contain a backend-specific more
 289        precise error message/code.
 290     @event{EVT_WEBVIEW_NEWWINDOW(id, func)}
 291        Process a @c wxEVT_WEBVIEW_NEWWINDOW event, generated when a new
 292        window is created. You must handle this event if you want anything to
 293        happen, for example to load the page in a new window or tab.
 294     @event{EVT_WEBVIEW_TITLE_CHANGED(id, func)}
 295        Process a @c wxEVT_WEBVIEW_TITLE_CHANGED event, generated when
 296        the page title changes. Use GetString to get the title.
 297     @endEventTable
 298
 299     @since 2.9.3
 300     @library{wxwebview}
 301     @category{ctrl,webview}
 302     @see wxWebViewHandler, wxWebViewEvent
 303  */
 304 class wxWebView : public wxControl
 305 {
 306 public:
 307
 308     /**
 309         Creation function for two-step creation.
 310     */
 311     virtual bool Create(wxWindow* parent,
 312                         wxWindowID id,
 313                         const wxString& url = wxWebViewDefaultURLStr,
 314                         const wxPoint& pos = wxDefaultPosition,
 315                         const wxSize& size = wxDefaultSize,
 316                         long style = 0,
 317                         const wxString& name = wxWebViewNameStr) = 0;
 318
 319     /**
 320         Factory function to create a new wxWebView with two-step creation,
 321         wxWebView::Create should be called on the returned object.
 322         @param backend The backend web rendering engine to use.
 323                        @c wxWebViewBackendDefault, @c wxWebViewBackendIE and
 324                        @c wxWebViewBackendWebKit are predefined where appropriate.
 325         @return The created wxWebView
 326         @since 2.9.5
 327      */
 328     static wxWebView* New(const wxString& backend = wxWebViewBackendDefault);
 329
 330     /**
 331         Factory function to create a new wxWebView using a wxWebViewFactory.
 332         @param parent Parent window for the control
 333         @param id ID of this control
 334         @param url Initial URL to load
 335         @param pos Position of the control
 336         @param size Size of the control
 337         @param backend The backend web rendering engine to use.
 338                        @c wxWebViewBackendDefault, @c wxWebViewBackendIE and
 339                        @c wxWebViewBackendWebKit are predefined where appropriate.
 340         @param style
 341             Window style. For generic window styles, please see wxWindow.
 342         @param name Window name.
 343         @return The created wxWebView, or @c NULL if the requested backend
 344                 is not available
 345         @since 2.9.5
 346     */
 347     static wxWebView* New(wxWindow* parent,
 348                           wxWindowID id,
 349                           const wxString& url = wxWebViewDefaultURLStr,
 350                           const wxPoint& pos = wxDefaultPosition,
 351                           const wxSize& size = wxDefaultSize,
 352                           const wxString& backend = wxWebViewBackendDefault,
 353                           long style = 0,
 354                           const wxString& name = wxWebViewNameStr);
 355
 356     /**
 357         Allows the registering of new backend for wxWebView. @a backend can be
 358         used as an argument to New().
 359         @param backend The name for the new backend to be registered under
 360         @param factory A shared pointer to the factory which creates the
 361                        appropriate backend.
 362         @since 2.9.5
 363     */
 364     static void RegisterFactory(const wxString& backend,
 365                                 wxSharedPtr<wxWebViewFactory> factory);
 366
 367     /**
 368         Get the title of the current web page, or its URL/path if title is not
 369         available.
 370     */
 371     virtual wxString GetCurrentTitle() const = 0;
 372
 373    /**
 374         Get the URL of the currently displayed document.
 375     */
 376     virtual wxString GetCurrentURL() const = 0;
 377
 378     /**
 379         Return the pointer to the native backend used by this control.
 380
 381         This method can be used to retrieve the pointer to the native rendering
 382         engine used by this control. The return value needs to be down-casted
 383         to the appropriate type depending on the platform: under Windows, it's
 384         a pointer to IWebBrowser2 interface, under OS X it's a WebView pointer
 385         and under GTK it's a WebKitWebView.
 386
 387         For example, you could set the WebKit options using this method:
 388         @code
 389             #include <webkit/webkit.h>
 390
 391             #ifdef __WXGTK__
 392                WebKitWebView*
 393                 wv = static_cast<WebKitWebView*>(m_window->GetNativeBackend());
 394
 395                WebKitWebSettings* settings = webkit_web_view_get_settings(wv);
 396                g_object_set(G_OBJECT(settings),
 397                             "enable-frame-flattening", TRUE,
 398                             NULL);
 399             #endif
 400         @endcode
 401
 402         @since 2.9.5
 403      */
 404     virtual void* GetNativeBackend() const = 0;
 405
 406     /**
 407         Get the HTML source code of the currently displayed document.
 408         @return The HTML source code, or an empty string if no page is currently
 409                 shown.
 410     */
 411     virtual wxString GetPageSource() const = 0;
 412
 413     /**
 414         Get the text of the current page.
 415     */
 416     virtual wxString GetPageText() const = 0;
 417
 418     /**
 419         Returns whether the web control is currently busy (e.g.\ loading a page).
 420     */
 421     virtual bool IsBusy() const = 0;
 422
 423     /**
 424         Returns whether the web control is currently editable
 425     */
 426     virtual bool IsEditable() const = 0;
 427
 428     /**
 429         Load a web page from a URL
 430         @param url The URL of the page to be loaded.
 431         @note Web engines generally report errors asynchronously, so if you wish
 432             to know whether loading the URL was successful, register to receive
 433             navigation error events.
 434     */
 435     virtual void LoadURL(const wxString& url) = 0;
 436
 437     /**
 438         Opens a print dialog so that the user may print the currently
 439         displayed page.
 440     */
 441     virtual void Print() = 0;
 442
 443     /**
 444         Registers a custom scheme handler.
 445         @param handler A shared pointer to a wxWebHandler.
 446     */
 447     virtual void RegisterHandler(wxSharedPtr<wxWebViewHandler> handler) = 0;
 448
 449     /**
 450         Reload the currently displayed URL.
 451         @param flags A bit array that may optionally contain reload options.
 452     */
 453     virtual void Reload(wxWebViewReloadFlags flags = wxWEBVIEW_RELOAD_DEFAULT) = 0;
 454
 455     /**
 456         Runs the given javascript code.
 457         @note When using wxWEBVIEW_BACKEND_IE you must wait for the current
 458               page to finish loading before calling RunScript().
 459     */
 460     virtual void RunScript(const wxString& javascript) = 0;
 461
 462     /**
 463         Set the editable property of the web control. Enabling allows the user
 464         to edit the page even if the @c contenteditable attribute is not set.
 465         The exact capabilities vary with the backend being used.
 466     */
 467     virtual void SetEditable(bool enable = true) = 0;
 468
 469     /**
 470         Set the displayed page source to the contents of the given string.
 471         @param html    The string that contains the HTML data to display.
 472         @param baseUrl URL assigned to the HTML data, to be used to resolve
 473                     relative paths, for instance.
 474         @note When using @c wxWEBVIEW_BACKEND_IE you must wait for the current
 475               page to finish loading before calling SetPage(). The baseURL
 476               parameter is not used in this backend.
 477     */
 478     virtual void SetPage(const wxString& html, const wxString& baseUrl) = 0;
 479
 480     /**
 481         Set the displayed page source to the contents of the given stream.
 482         @param html    The stream to read HTML data from.
 483         @param baseUrl URL assigned to the HTML data, to be used to resolve
 484                     relative paths, for instance.
 485     */
 486     virtual void SetPage(wxInputStream& html, wxString baseUrl);
 487
 488     /**
 489         Stop the current page loading process, if any.
 490         May trigger an error event of type @c wxWEBVIEW_NAV_ERR_USER_CANCELLED.
 491         TODO: make @c wxWEBVIEW_NAV_ERR_USER_CANCELLED errors uniform across ports.
 492     */
 493     virtual void Stop() = 0;
 494
 495     /**
 496         @name Clipboard
 497     */
 498
 499     /**
 500         Returns @true if the current selection can be copied.
 501
 502         @note This always returns @c true on the OSX WebKit backend.
 503     */
 504     virtual bool CanCopy() const = 0;
 505
 506     /**
 507         Returns @true if the current selection can be cut.
 508
 509          @note This always returns @c true on the OSX WebKit backend.
 510     */
 511     virtual bool CanCut() const = 0;
 512
 513     /**
 514         Returns @true if data can be pasted.
 515
 516         @note This always returns @c true on the OSX WebKit backend.
 517     */
 518     virtual bool CanPaste() const = 0;
 519
 520     /**
 521         Copies the current selection.
 522     */
 523     virtual void Copy() = 0;
 524
 525     /**
 526         Cuts the current selection.
 527     */
 528     virtual void Cut() = 0;
 529
 530     /**
 531         Pastes the current data.
 532     */
 533     virtual void Paste() = 0;
 534
 535     /**
 536         @name Context Menu
 537     */
 538
 539     /**
 540         Enable or disable the right click context menu.
 541
 542         By default the standard context menu is enabled, this method can be
 543         used to disable it or re-enable it later.
 544
 545         @since 2.9.5
 546     */
 547     virtual void EnableContextMenu(bool enable = true);
 548
 549    /**
 550         Returns @true if a context menu will be shown on right click.
 551
 552         @since 2.9.5
 553     */
 554     virtual bool IsContextMenuEnabled() const;
 555
 556     /**
 557         @name History
 558     */
 559
 560     /**
 561         Returns @true if it is possible to navigate backward in the history of
 562         visited pages.
 563     */
 564     virtual bool CanGoBack() const = 0;
 565
 566     /**
 567         Returns @true if it is possible to navigate forward in the history of
 568         visited pages.
 569     */
 570     virtual bool CanGoForward() const = 0;
 571
 572     /**
 573         Clear the history, this will also remove the visible page.
 574     */
 575     virtual void ClearHistory() = 0;
 576
 577     /**
 578         Enable or disable the history. This will also clear the history.
 579     */
 580     virtual void EnableHistory(bool enable = true) = 0;
 581
 582     /**
 583         Returns a list of items in the back history. The first item in the
 584         vector is the first page that was loaded by the control.
 585     */
 586     virtual wxVector<wxSharedPtr<wxWebViewHistoryItem> > GetBackwardHistory() = 0;
 587
 588     /**
 589         Returns a list of items in the forward history. The first item in the
 590         vector is the next item in the history with respect to the curently
 591         loaded page.
 592     */
 593     virtual wxVector<wxSharedPtr<wxWebViewHistoryItem> > GetForwardHistory() = 0;
 594
 595     /**
 596         Navigate back in the history of visited pages.
 597         Only valid if CanGoBack() returns true.
 598     */
 599     virtual void GoBack() = 0;
 600
 601     /**
 602         Navigate forward in the history of visited pages.
 603         Only valid if CanGoForward() returns true.
 604     */
 605     virtual void GoForward() = 0;
 606
 607     /**
 608         Loads a history item.
 609     */
 610     virtual void LoadHistoryItem(wxSharedPtr<wxWebViewHistoryItem> item) = 0;
 611
 612     /**
 613         @name Selection
 614     */
 615
 616     /**
 617         Clears the current selection.
 618     */
 619     virtual void ClearSelection() = 0;
 620
 621     /**
 622         Deletes the current selection. Note that for @c wxWEBVIEW_BACKEND_WEBKIT
 623         the selection must be editable, either through SetEditable or the
 624         correct HTML attribute.
 625     */
 626     virtual void DeleteSelection() = 0;
 627
 628     /**
 629         Returns the currently selected source, if any.
 630     */
 631     virtual wxString GetSelectedSource() const = 0;
 632
 633     /**
 634         Returns the currently selected text, if any.
 635     */
 636     virtual wxString GetSelectedText() const = 0;
 637
 638     /**
 639         Returns @true if there is a current selection.
 640     */
 641     virtual bool HasSelection() const = 0;
 642
 643     /**
 644         Selects the entire page.
 645     */
 646     virtual void SelectAll() = 0;
 647
 648     /**
 649         @name Undo / Redo
 650     */
 651
 652     /**
 653         Returns @true if there is an action to redo.
 654     */
 655     virtual bool CanRedo() const = 0;
 656
 657     /**
 658         Returns @true if there is an action to undo.
 659     */
 660     virtual bool CanUndo() const = 0;
 661
 662     /**
 663         Redos the last action.
 664     */
 665     virtual void Redo() = 0;
 666
 667     /**
 668         Undos the last action.
 669     */
 670     virtual void Undo() = 0;
 671
 672     /**
 673         @name Finding
 674     */
 675
 676     /**
 677         Finds a phrase on the current page and if found, the control will
 678         scroll the phrase into view and select it.
 679         @param text The phrase to search for.
 680         @param flags The flags for the search.
 681         @return If search phrase was not found in combination with the flags
 682                 then @c wxNOT_FOUND is returned. If called for the first time
 683                 with search phrase then the total number of results will be
 684                 returned. Then for every time its called with the same search
 685                 phrase it will return the number of the current match.
 686         @note This function will restart the search if the flags
 687               @c wxWEBVIEW_FIND_ENTIRE_WORD or @c wxWEBVIEW_FIND_MATCH_CASE
 688               are changed, since this will require a new search. To reset the
 689               search, for example reseting the highlights call the function
 690               with an empty search phrase. This always returns @c wxNOT_FOUND
 691               on the OSX WebKit backend.
 692         @since 2.9.5
 693     */
 694     virtual long Find(const wxString& text, wxWebViewFindFlags flags = wxWEBVIEW_FIND_DEFAULT) = 0;
 695
 696     /**
 697         @name Zoom
 698     */
 699
 700     /**
 701         Retrieve whether the current HTML engine supports a zoom type.
 702         @param type The zoom type to test.
 703         @return Whether this type of zoom is supported by this HTML engine
 704                 (and thus can be set through SetZoomType()).
 705     */
 706     virtual bool CanSetZoomType(wxWebViewZoomType type) const = 0;
 707
 708     /**
 709         Get the zoom factor of the page.
 710         @return The current level of zoom.
 711     */
 712     virtual wxWebViewZoom GetZoom() const = 0;
 713
 714     /**
 715         Get how the zoom factor is currently interpreted.
 716         @return How the zoom factor is currently interpreted by the HTML engine.
 717     */
 718     virtual wxWebViewZoomType GetZoomType() const = 0;
 719
 720     /**
 721         Set the zoom factor of the page.
 722         @param zoom How much to zoom (scale) the HTML document.
 723     */
 724     virtual void SetZoom(wxWebViewZoom zoom) = 0;
 725
 726     /**
 727         Set how to interpret the zoom factor.
 728         @param zoomType How the zoom factor should be interpreted by the
 729                         HTML engine.
 730         @note invoke    CanSetZoomType() first, some HTML renderers may not
 731                         support all zoom types.
 732     */
 733     virtual void SetZoomType(wxWebViewZoomType zoomType) = 0;
 734 };
 735
 736
 737
 738
 739 /**
 740     @class wxWebViewEvent
 741
 742     A navigation  event holds information about events associated with
 743     wxWebView objects.
 744
 745     @beginEventEmissionTable{wxWebViewEvent}
 746     @event{EVT_WEBVIEW_NAVIGATING(id, func)}
 747        Process a @c wxEVT_WEBVIEW_NAVIGATING event, generated before trying
 748        to get a resource. This event may be vetoed to prevent navigating to this
 749        resource. Note that if the displayed HTML document has several frames, one
 750        such event will be generated per frame.
 751     @event{EVT_WEBVIEW_NAVIGATED(id, func)}
 752        Process a @c wxEVT_WEBVIEW_NAVIGATED event generated after it was
 753        confirmed that a resource would be requested. This event may not be vetoed.
 754        Note that if the displayed HTML document has several frames, one such event
 755        will be generated per frame.
 756     @event{EVT_WEBVIEW_LOADED(id, func)}
 757        Process a @c wxEVT_WEBVIEW_LOADED event generated when the document
 758        is fully loaded and displayed. Note that if the displayed HTML document has
 759        several frames, one such event will be generated per frame.
 760     @event{EVT_WEBVIEW_ERROR(id, func)}
 761        Process a @c wxEVT_WEBVIEW_ERROR event generated when a navigation
 762        error occurs.
 763        The integer associated with this event will be a #wxWebViewNavigationError item.
 764        The string associated with this event may contain a backend-specific more
 765        precise error message/code.
 766     @event{EVT_WEBVIEW_NEWWINDOW(id, func)}
 767        Process a @c wxEVT_WEBVIEW_NEWWINDOW event, generated when a new
 768        window is created. You must handle this event if you want anything to
 769        happen, for example to load the page in a new window or tab.
 770     @event{EVT_WEBVIEW_TITLE_CHANGED(id, func)}
 771        Process a @c wxEVT_WEBVIEW_TITLE_CHANGED event, generated when
 772        the page title changes. Use GetString to get the title.
 773     @endEventTable
 774
 775     @since 2.9.3
 776     @library{wxwebview}
 777     @category{events,webview}
 778
 779     @see wxWebView
 780 */
 781 class wxWebViewEvent : public wxNotifyEvent
 782 {
 783 public:
 784     wxWebViewEvent();
 785     wxWebViewEvent(wxEventType type, int id, const wxString href,
 786                    const wxString target);
 787
 788     /**
 789         Get the name of the target frame which the url of this event
 790         has been or will be loaded into. This may return an emptry string
 791         if the frame is not available.
 792     */
 793     const wxString& GetTarget() const;
 794
 795     /**
 796         Get the URL being visited
 797     */
 798     const wxString& GetURL() const;
 799 };
 800
 801
 802 wxEventType wxEVT_WEBVIEW_NAVIGATING;
 803 wxEventType wxEVT_WEBVIEW_NAVIGATED;
 804 wxEventType wxEVT_WEBVIEW_LOADED;
 805 wxEventType wxEVT_WEBVIEW_ERROR;
 806 wxEventType wxEVT_WEBVIEW_NEWWINDOW;
 807 wxEventType wxEVT_WEBVIEW_TITLE_CHANGED;