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