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 wxWebView
 121
 122     This control may be used to render web (HTML / CSS / javascript) documents.
 123     Capabilities of the HTML renderer will depend upon the backed.
 124
 125     @c wxWEB_VIEW_BACKEND_IE uses the the Trident rendering engine, which
 126     is also used by Internet Explorer. It is important to note that by default
 127     it emulates Internet Explorer 7, this can be chaged with a registry
 128     setting, see
 129     <a href="http://msdn.microsoft.com/en-us/library/ee330730%28v=vs.85%29.aspx#browser_emulation">
 130     this</a> article for more information.
 131
 132     Note that errors are generally reported asynchronously though the
 133     @c wxEVT_COMMAND_WEB_VIEW_ERROR event described below.
 134
 135     @beginEventEmissionTable{wxWebNavigationEvent}
 136     @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
 137        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
 138        to get a resource. This event may be vetoed to prevent navigating to this
 139        resource. Note that if the displayed HTML document has several frames, one
 140        such event will be generated per frame.
 141     @event{EVT_WEB_VIEW_NAVIGATED(id, func)}
 142        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was
 143        confirmed that a resource would be requested. This event may not be vetoed.
 144        Note that if the displayed HTML document has several frames, one such event
 145        will be generated per frame.
 146     @event{EVT_WEB_VIEW_LOADED(id, func)}
 147        Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document
 148        is fully loaded and displayed. Note that if the displayed HTML document has
 149        several frames, one such event will be generated per frame.
 150     @event{EVT_WEB_VIEW_ERRROR(id, func)}
 151        Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
 152        error occurs.
 153        The integer associated with this event will be a wxWebNavigationError item.
 154        The string associated with this event may contain a backend-specific more
 155        precise error message/code.
 156     @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
 157        Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
 158        window is created. This event may be vetoed to prevent a new window showing,
 159        for example if you want to open the url in the existing window or a new tab.
 160     @endEventTable
 161
 162     @library{wxweb}
 163     @category{ctrl,web}
 164  */
 165 class wxWebView : public wxControl
 166 {
 167 public:
 168
 169     /**
 170         Creation function for two-step creation.
 171     */
 172     virtual bool Create(wxWindow* parent,
 173                         wxWindowID id,
 174                         const wxString& url,
 175                         const wxPoint& pos,
 176                         const wxSize& size,
 177                         long style,
 178                         const wxString& name) = 0;
 179
 180     /**
 181         Factory function to create a new wxWebView for two-step creation
 182         (you need to call wxWebView::Create on the returned object)
 183         @param backend which web engine to use as backend for wxWebView
 184         @return the created wxWebView, or NULL if the requested backend is
 185                 not available
 186      */
 187     static wxWebView* New(wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT);
 188
 189     /**
 190         Factory function to create a new wxWebView
 191         @param parent parent window to create this view in
 192         @param id ID of this control
 193         @param url URL to load by default in the web view
 194         @param pos position to create this control at
 195                (you may use wxDefaultPosition if you use sizers)
 196         @param size size to create this control with
 197                (you may use wxDefaultSize if you use sizers)
 198         @param backend which web engine to use as backend for wxWebView
 199         @return the created wxWebView, or NULL if the requested backend
 200                 is not available
 201     */
 202     static wxWebView* New(wxWindow* parent,
 203            wxWindowID id,
 204            const wxString& url = wxWebViewDefaultURLStr,
 205            const wxPoint& pos = wxDefaultPosition,
 206            const wxSize& size = wxDefaultSize,
 207            wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT,
 208            long style = 0,
 209            const wxString& name = wxWebViewNameStr);
 210
 211     /**
 212         Get the title of the current web page, or its URL/path if title is not
 213         available.
 214     */
 215     virtual wxString GetCurrentTitle() = 0;
 216
 217    /**
 218         Get the URL of the currently displayed document.
 219     */
 220     virtual wxString GetCurrentURL() = 0;
 221
 222     /**
 223         Get the HTML source code of the currently displayed document.
 224         @return The HTML source code, or an empty string if no page is currently
 225                 shown.
 226     */
 227     virtual wxString GetPageSource() = 0;
 228
 229     /**
 230         Returns whether the web control is currently busy (e.g. loading a page).
 231     */
 232     virtual bool IsBusy() = 0;
 233
 234     /**
 235         Load a web page from a URL
 236         @param url The URL of the page to be loaded.
 237         @note Web engines generally report errors asynchronously, so if you wish
 238             to know whether loading the URL was successful, register to receive
 239             navigation error events.
 240     */
 241     virtual void LoadUrl(const wxString& url) = 0;
 242
 243     /**
 244         Opens a print dialog so that the user may print the currently
 245         displayed page.
 246     */
 247     virtual void Print() = 0;
 248
 249     /**
 250         Reload the currently displayed URL.
 251         @param flags A bit array that may optionally contain reload options.
 252     */
 253     virtual void Reload(wxWebViewReloadFlags flags = wxWEB_VIEW_RELOAD_DEFAULT) = 0;
 254
 255     /**
 256         Set the displayed page source to the contents of the given string.
 257         @param html    The string that contains the HTML data to display.
 258         @param baseUrl URL assigned to the HTML data, to be used to resolve
 259                     relative paths, for instance.
 260     */
 261     virtual void SetPage(const wxString& html, const wxString& baseUrl) = 0;
 262
 263     /**
 264         Set the displayed page source to the contents of the given stream.
 265         @param html    The stream to read HTML data from.
 266         @param baseUrl URL assigned to the HTML data, to be used to resolve
 267                     relative paths, for instance.
 268     */
 269     virtual void SetPage(wxInputStream& html, wxString baseUrl)
 270     {
 271         wxStringOutputStream stream;
 272         stream.Write(html);
 273         SetPage(stream.GetString(), baseUrl);
 274     }
 275
 276     /**
 277         Stop the current page loading process, if any.
 278         May trigger an error event of type @c wxWEB_NAV_ERR_USER_CANCELLED.
 279         TODO: make @c wxWEB_NAV_ERR_USER_CANCELLED errors uniform across ports.
 280     */
 281     virtual void Stop() = 0;
 282
 283     /**
 284         @name Clipboard
 285     */
 286
 287     /**
 288         Returns @true if the current selection can be copied.
 289     */
 290     virtual bool CanCopy() = 0;
 291
 292     /**
 293         Returns @true if the current selection can be cut.
 294     */
 295     virtual bool CanCut() = 0;
 296
 297     /**
 298         Returns @true if data can be pasted.
 299     */
 300     virtual bool CanPaste() = 0;
 301
 302     /**
 303         Copies the current selection.
 304     */
 305     virtual void Copy() = 0;
 306
 307     /**
 308         Cuts the current selection.
 309     */
 310     virtual void Cut() = 0;
 311
 312     /**
 313         Pastes the current data.
 314     */
 315     virtual void Paste() = 0;
 316
 317     /**
 318         @name History
 319     */
 320
 321     /**
 322         Returns @true if it is possible to navigate backward in the history of
 323         visited pages.
 324     */
 325     virtual bool CanGoBack() = 0;
 326
 327     /**
 328         Returns @true if it is possible to navigate forward in the history of
 329         visited pages.
 330     */
 331     virtual bool CanGoForward() = 0;
 332
 333     /**
 334         Clear the history, this will also remove the visible page.
 335     */
 336     virtual void ClearHistory() = 0;
 337
 338     /**
 339         Enable or disable the history. This will also clear the history.
 340     */
 341     virtual void EnableHistory(bool enable = true) = 0;
 342
 343     /**
 344         Returns a list of items in the back history. The first item in the
 345         vector is the first page that was loaded by the control.
 346     */
 347     virtual wxVector<wxSharedPtr<wxWebHistoryItem> > GetBackwardHistory() = 0;
 348
 349     /**
 350         Returns a list of items in the forward history. The first item in the
 351         vector is the next item in the history with respect to the curently
 352         loaded page.
 353     */
 354     virtual wxVector<wxSharedPtr<wxWebHistoryItem> > GetForwardHistory() = 0;
 355
 356     /**
 357         Navigate back in the history of visited pages.
 358         Only valid if CanGoBack() returns true.
 359     */
 360     virtual void GoBack() = 0;
 361
 362     /**
 363         Navigate forward in the history of visited pages.
 364         Only valid if CanGoForward() returns true.
 365     */
 366     virtual void GoForward() = 0;
 367
 368     /**
 369         Loads a history item.
 370     */
 371     virtual void LoadHistoryItem(wxSharedPtr<wxWebHistoryItem> item) = 0;
 372
 373     /**
 374         @name Undo / Redo
 375     */
 376
 377     /**
 378         Returns @true if there is an action to redo.
 379     */
 380     virtual bool CanRedo() = 0;
 381
 382     /**
 383         Returns @true if there is an action to undo.
 384     */
 385     virtual bool CanUndo() = 0;
 386
 387     /**
 388         Redos the last action.
 389     */
 390     virtual void Redo() = 0;
 391
 392     /**
 393         Undos the last action.
 394     */
 395     virtual void Undo() = 0;
 396
 397     /**
 398         @name Zoom
 399     */
 400
 401     /**
 402         Retrieve whether the current HTML engine supports a zoom type.
 403         @param type The zoom type to test.
 404         @return Whether this type of zoom is supported by this HTML engine
 405                 (and thus can be set through SetZoomType()).
 406     */
 407     virtual bool CanSetZoomType(wxWebViewZoomType type) const = 0;
 408
 409     /**
 410         Get the zoom factor of the page.
 411         @return The current level of zoom.
 412     */
 413     virtual wxWebViewZoom GetZoom() = 0;
 414
 415     /**
 416         Get how the zoom factor is currently interpreted.
 417         @return How the zoom factor is currently interpreted by the HTML engine.
 418     */
 419     virtual wxWebViewZoomType GetZoomType() const = 0;
 420
 421     /**
 422         Set the zoom factor of the page.
 423         @param zoom How much to zoom (scale) the HTML document.
 424     */
 425     virtual void SetZoom(wxWebViewZoom zoom) = 0;
 426
 427     /**
 428         Set how to interpret the zoom factor.
 429         @param zoomType How the zoom factor should be interpreted by the
 430                         HTML engine.
 431         @note invoke    CanSetZoomType() first, some HTML renderers may not
 432                         support all zoom types.
 433     */
 434     virtual void SetZoomType(wxWebViewZoomType zoomType) = 0;
 435 };
 436
 437
 438
 439
 440 /**
 441     @class wxWebNavigationEvent
 442
 443     A navigation  event holds information about events associated with
 444     wxWebView objects.
 445
 446     @beginEventEmissionTable{wxWebNavigationEvent}
 447     @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
 448        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
 449        to get a resource. This event may be vetoed to prevent navigating to this
 450        resource. Note that if the displayed HTML document has several frames, one
 451        such event will be generated per frame.
 452     @event{EVT_WEB_VIEW_NAVIGATED(id, func)}
 453        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was
 454        confirmed that a resource would be requested. This event may not be vetoed.
 455        Note that if the displayed HTML document has several frames, one such event
 456        will be generated per frame.
 457     @event{EVT_WEB_VIEW_LOADED(id, func)}
 458        Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document
 459        is fully loaded and displayed. Note that if the displayed HTML document has
 460        several frames, one such event will be generated per frame.
 461     @event{EVT_WEB_VIEW_ERRROR(id, func)}
 462        Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
 463        error occurs.
 464        The integer associated with this event will be a wxWebNavigationError item.
 465        The string associated with this event may contain a backend-specific more
 466        precise error message/code.
 467     @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
 468        Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
 469        window is created. This event may be vetoed to prevent a new window showing,
 470        for example if you want to open the url in the existing window or a new tab.
 471     @endEventTable
 472
 473     @library{wxweb}
 474     @category{events,web}
 475
 476     @see wxWebView
 477 */
 478 class wxWebNavigationEvent : public wxCommandEvent
 479 {
 480 public:
 481     wxWebNavigationEvent();
 482     wxWebNavigationEvent(wxEventType type, int id, const wxString href,
 483                          const wxString target, bool canVeto);
 484     /**
 485         Get the URL being visited
 486     */
 487     const wxString& GetHref() const { return m_href; }
 488
 489     /**
 490         Get the target (frame or window) in which the URL that caused this event
 491         is viewed, or an empty string if not available.
 492     */
 493     const wxString& GetTarget() const;
 494
 495     virtual wxEvent* Clone() const;
 496
 497     /**
 498         Get whether this event may be vetoed (stopped/prevented). Only
 499         meaningful for events fired before navigation takes place or new
 500         window events.
 501      */
 502     bool CanVeto() const;
 503
 504     /**
 505         Whether this event was vetoed (stopped/prevented). Only meaningful for
 506         events fired before navigation takes place or new window events.
 507      */
 508     bool IsVetoed() const;
 509
 510     /**
 511         Veto (prevent/stop) this event. Only meaningful for events fired
 512         before navigation takes place or new window events. Only valid
 513         if CanVeto() returned true.
 514      */
 515     void Veto();
 516 };