1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxWebView
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 Zoom levels available in wxWebView
16 wxWEBVIEW_ZOOM_MEDIUM
, //!< default size
18 wxWEBVIEW_ZOOM_LARGEST
22 The type of zooming that the web view control can perform
24 enum wxWebViewZoomType
27 The entire layout scales when zooming, including images
29 wxWEBVIEW_ZOOM_TYPE_LAYOUT
,
31 Only the text changes in size when zooming, images and other layout
32 elements retain their initial size
34 wxWEBVIEW_ZOOM_TYPE_TEXT
38 Types of errors that can cause navigation to fail
40 enum wxWebViewNavigationError
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
64 enum wxWebViewReloadFlags
66 /** Default reload, will access cache */
67 wxWEBVIEW_RELOAD_DEFAULT
,
68 /** Reload the current view without accessing the cache */
69 wxWEBVIEW_RELOAD_NO_CACHE
73 Find flags used when searching for text on page.
75 enum wxWebViewFindFlags
77 /** Causes the search to restart when end or beginning reached */
78 wxWEBVIEW_FIND_WRAP
= 0x0001,
80 /** Matches an entire word when searching */
81 wxWEBVIEW_FIND_ENTIRE_WORD
= 0x0002,
83 /** Match case, i.e. case sensitive searching */
84 wxWEBVIEW_FIND_MATCH_CASE
= 0x0004,
86 /** Highlights the search results */
87 wxWEBVIEW_FIND_HIGHLIGHT_RESULT
= 0x0008,
89 /** Searches for phrase in backward direction */
90 wxWEBVIEW_FIND_BACKWARDS
= 0x0010,
92 /** The default flag, which is simple searching */
93 wxWEBVIEW_FIND_DEFAULT
= 0
98 @class wxWebViewHistoryItem
100 A simple class that contains the URL and title of an element of the history
109 class wxWebViewHistoryItem
115 wxWebViewHistoryItem(const wxString
& url
, const wxString
& title
);
118 @return The url of the page.
123 @return The title of the page.
129 @class wxWebViewFactory
131 An abstract factory class for creating wxWebView backends. Each
132 implementation of wxWebView should have its own factory.
140 class wxWebViewFactory
: public wxObject
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
148 virtual wxWebView
* Create() = 0;
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 @return the created wxWebView
159 virtual wxWebView
* Create(wxWindow
* parent
,
161 const wxString
& url
= wxWebViewDefaultURLStr
,
162 const wxPoint
& pos
= wxDefaultPosition
,
163 const wxSize
& size
= wxDefaultSize
,
165 const wxString
& name
= wxWebViewNameStr
) = 0;
169 @class wxWebViewHandler
171 The base class for handling custom schemes in wxWebView, for example to
172 allow virtual file system support.
180 class wxWebViewHandler
184 Constructor. Takes the name of the scheme that will be handled by this
185 class for example @c file or @c zip.
187 wxWebViewHandler(const wxString
& scheme
);
190 @return A pointer to the file represented by @c uri.
192 virtual wxFSFile
* GetFile(const wxString
&uri
) = 0;
195 @return The name of the scheme, as passed to the constructor.
197 virtual wxString
GetName() const;
203 This control may be used to render web (HTML / CSS / javascript) documents.
204 It is designed to allow the creation of multiple backends for each port,
205 although currently just one is available. It differs from wxHtmlWindow in
206 that each backend is actually a full rendering engine, Trident on MSW and
207 Webkit on OSX and GTK. This allows the correct viewing complex pages with
210 @section descriptions Backend Descriptions
212 @par wxWEBVIEW_BACKEND_IE (MSW)
214 The IE backend uses Microsoft's Trident rendering engine, specifically the
215 version used by the locally installed copy of Internet Explorer. As such it
216 is only available for the MSW port. By default recent versions of the
217 <a href="http://msdn.microsoft.com/en-us/library/aa752085%28v=VS.85%29.aspx">WebBrowser</a>
218 control, which this backend uses, emulate Internet Explorer 7. This can be
219 changed with a registry setting, see
220 <a href="http://msdn.microsoft.com/en-us/library/ee330730%28v=vs.85%29.aspx#browser_emulation">
221 this</a> article for more information. This backend has full support for
222 custom schemes and virtual file systems.
224 @par wxWEBVIEW_WEBKIT (GTK)
226 Under GTK the WebKit backend uses
227 <a href="http://webkitgtk.org/">WebKitGTK+</a>. The current minimum version
228 required is 1.3.1 which ships by default with Ubuntu Natty and Debian
229 Wheezy and has the package name libwebkitgtk-dev. Custom schemes and
230 virtual files systems are supported under this backend, however embedded
231 resources such as images and stylesheets are currently loaded using the
234 @par wxWEBVIEW_WEBKIT (OSX)
236 The OSX WebKit backend uses Apple's
237 <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>
238 class. This backend has full support for custom schemes and virtual file
241 @section async Asynchronous Notifications
243 Many of the methods in wxWebView are asynchronous, i.e. they return
244 immediately and perform their work in the background. This includes
245 functions such as LoadUrl() and Reload(). To receive notification of the
246 progress and completion of these functions you need to handle the events
247 that are provided. Specifically @c wxEVT_COMMAND_WEBVIEW_LOADED notifies
248 when the page or a sub-frame has finished loading and
249 @c wxEVT_COMMAND_WEBVIEW_ERROR notifies that an error has occurred.
251 @section vfs Virtual File Systems and Custom Schemes
253 wxWebView supports the registering of custom scheme handlers, for example
254 @c file or @c http. To do this create a new class which inherits from
255 wxWebViewHandler, where wxWebHandler::GetFile() returns a pointer to a
256 wxFSFile which represents the given url. You can then register your handler
257 with RegisterHandler() it will be called for all pages and resources.
259 wxWebViewFSHandler is provided to access the virtual file system encapsulated by
260 wxFileSystem. The wxMemoryFSHandler documentation gives an example of how this
263 wxWebViewArchiveHandler is provided to allow the navigation of pages inside a zip
264 archive. It supports paths of the form:
265 @c scheme:///C:/example/docs.zip;protocol=zip/main.htm
267 @beginEventEmissionTable{wxWebViewEvent}
268 @event{EVT_WEBVIEW_NAVIGATING(id, func)}
269 Process a @c wxEVT_COMMAND_WEBVIEW_NAVIGATING event, generated before trying
270 to get a resource. This event may be vetoed to prevent navigating to this
271 resource. Note that if the displayed HTML document has several frames, one
272 such event will be generated per frame.
273 @event{EVT_WEBVIEW_NAVIGATED(id, func)}
274 Process a @c wxEVT_COMMAND_WEBVIEW_NAVIGATED event generated after it was
275 confirmed that a resource would be requested. This event may not be vetoed.
276 Note that if the displayed HTML document has several frames, one such event
277 will be generated per frame.
278 @event{EVT_WEBVIEW_LOADED(id, func)}
279 Process a @c wxEVT_COMMAND_WEBVIEW_LOADED event generated when the document
280 is fully loaded and displayed. Note that if the displayed HTML document has
281 several frames, one such event will be generated per frame.
282 @event{EVT_WEBVIEW_ERROR(id, func)}
283 Process a @c wxEVT_COMMAND_WEBVIEW_ERROR event generated when a navigation
285 The integer associated with this event will be a wxWebNavigationError item.
286 The string associated with this event may contain a backend-specific more
287 precise error message/code.
288 @event{EVT_WEBVIEW_NEWWINDOW(id, func)}
289 Process a @c wxEVT_COMMAND_WEBVIEW_NEWWINDOW event, generated when a new
290 window is created. You must handle this event if you want anything to
291 happen, for example to load the page in a new window or tab.
292 @event{EVT_WEBVIEW_TITLE_CHANGED(id, func)}
293 Process a @c wxEVT_COMMAND_WEBVIEW_TITLE_CHANGED event, generated when
294 the page title changes. Use GetString to get the title.
299 @category{ctrl,webview}
300 @see wxWebViewHandler, wxWebViewEvent
302 class wxWebView
: public wxControl
307 Creation function for two-step creation.
309 virtual bool Create(wxWindow
* parent
,
311 const wxString
& url
= wxWebViewDefaultURLStr
,
312 const wxPoint
& pos
= wxDefaultPosition
,
313 const wxSize
& size
= wxDefaultSize
,
315 const wxString
& name
= wxWebViewNameStr
) = 0;
318 Factory function to create a new wxWebView with two-step creation,
319 wxWebView::Create should be called on the returned object.
320 @param backend The backend web rendering engine to use.
321 @c wxWebViewBackendDefault, @c wxWebViewBackendIE and
322 @c wxWebViewBackendWebKit are predefined where appropriate.
323 @return The created wxWebView
326 static wxWebView
* New(const wxString
& backend
= wxWebViewBackendDefault
);
329 Factory function to create a new wxWebView using a wxWebViewFactory.
330 @param parent Parent window for the control
331 @param id ID of this control
332 @param url Initial URL to load
333 @param pos Position of the control
334 @param size Size of the control
335 @param backend The backend web rendering engine to use.
336 @c wxWebViewBackendDefault, @c wxWebViewBackendIE and
337 @c wxWebViewBackendWebKit are predefined where appropriate.
338 @return The created wxWebView, or @c NULL if the requested backend
342 static wxWebView
* New(wxWindow
* parent
,
344 const wxString
& url
= wxWebViewDefaultURLStr
,
345 const wxPoint
& pos
= wxDefaultPosition
,
346 const wxSize
& size
= wxDefaultSize
,
347 const wxString
& backend
= wxWebViewBackendDefault
,
349 const wxString
& name
= wxWebViewNameStr
);
352 Allows the registering of new backend for wxWebView. @a backend can be
353 used as an argument to New().
354 @param backend The name for the new backend to be registered under
355 @param factory A shared pointer to the factory which creates the
359 static void RegisterFactory(const wxString
& backend
,
360 wxSharedPtr
<wxWebViewFactory
> factory
);
363 Get the title of the current web page, or its URL/path if title is not
366 virtual wxString
GetCurrentTitle() const = 0;
369 Get the URL of the currently displayed document.
371 virtual wxString
GetCurrentURL() const = 0;
374 Return the pointer to the native backend used by this control.
376 This method can be used to retrieve the pointer to the native rendering
377 engine used by this control. The return value needs to be down-casted
378 to the appropriate type depending on the platform: under Windows, it's
379 a pointer to IWebBrowser2 interface, under OS X it's a WebView pointer
380 and under GTK it's a WebKitWebView.
382 For example, you could set the WebKit options using this method:
384 #include <webkit/webkit.h>
388 wv = static_cast<WebKitWebView*>(m_window->GetNativeBackend());
390 WebKitWebSettings* settings = webkit_web_view_get_settings(wv);
391 g_object_set(G_OBJECT(settings),
392 "enable-frame-flattening", TRUE,
399 virtual void* GetNativeBackend() const = 0;
402 Get the HTML source code of the currently displayed document.
403 @return The HTML source code, or an empty string if no page is currently
406 virtual wxString
GetPageSource() const = 0;
409 Get the text of the current page.
411 virtual wxString
GetPageText() const = 0;
414 Returns whether the web control is currently busy (e.g.\ loading a page).
416 virtual bool IsBusy() const = 0;
419 Returns whether the web control is currently editable
421 virtual bool IsEditable() const = 0;
424 Load a web page from a URL
425 @param url The URL of the page to be loaded.
426 @note Web engines generally report errors asynchronously, so if you wish
427 to know whether loading the URL was successful, register to receive
428 navigation error events.
430 virtual void LoadURL(const wxString
& url
) = 0;
433 Opens a print dialog so that the user may print the currently
436 virtual void Print() = 0;
439 Registers a custom scheme handler.
440 @param handler A shared pointer to a wxWebHandler.
442 virtual void RegisterHandler(wxSharedPtr
<wxWebViewHandler
> handler
) = 0;
445 Reload the currently displayed URL.
446 @param flags A bit array that may optionally contain reload options.
448 virtual void Reload(wxWebViewReloadFlags flags
= wxWEBVIEW_RELOAD_DEFAULT
) = 0;
451 Runs the given javascript code.
452 @note When using wxWEBVIEW_BACKEND_IE you must wait for the current
453 page to finish loading before calling RunScript().
455 virtual void RunScript(const wxString
& javascript
) = 0;
458 Set the editable property of the web control. Enabling allows the user
459 to edit the page even if the @c contenteditable attribute is not set.
460 The exact capabilities vary with the backend being used.
462 virtual void SetEditable(bool enable
= true) = 0;
465 Set the displayed page source to the contents of the given string.
466 @param html The string that contains the HTML data to display.
467 @param baseUrl URL assigned to the HTML data, to be used to resolve
468 relative paths, for instance.
469 @note When using wxWEBVIEW_BACKEND_IE you must wait for the current
470 page to finish loading before calling SetPage().
472 virtual void SetPage(const wxString
& html
, const wxString
& baseUrl
) = 0;
475 Set the displayed page source to the contents of the given stream.
476 @param html The stream to read HTML data from.
477 @param baseUrl URL assigned to the HTML data, to be used to resolve
478 relative paths, for instance.
480 virtual void SetPage(wxInputStream
& html
, wxString baseUrl
);
483 Stop the current page loading process, if any.
484 May trigger an error event of type @c wxWEBVIEW_NAV_ERR_USER_CANCELLED.
485 TODO: make @c wxWEBVIEW_NAV_ERR_USER_CANCELLED errors uniform across ports.
487 virtual void Stop() = 0;
494 Returns @true if the current selection can be copied.
496 @note This always returns @c true on the OSX WebKit backend.
498 virtual bool CanCopy() const = 0;
501 Returns @true if the current selection can be cut.
503 @note This always returns @c true on the OSX WebKit backend.
505 virtual bool CanCut() const = 0;
508 Returns @true if data can be pasted.
510 @note This always returns @c true on the OSX WebKit backend.
512 virtual bool CanPaste() const = 0;
515 Copies the current selection.
517 virtual void Copy() = 0;
520 Cuts the current selection.
522 virtual void Cut() = 0;
525 Pastes the current data.
527 virtual void Paste() = 0;
534 Enable or disable the right click context menu.
536 By default the standard context menu is enabled, this method can be
537 used to disable it or re-enable it later.
541 virtual void EnableContextMenu(bool enable
= true);
544 Returns @true if a context menu will be shown on right click.
548 virtual bool IsContextMenuEnabled() const;
555 Returns @true if it is possible to navigate backward in the history of
558 virtual bool CanGoBack() const = 0;
561 Returns @true if it is possible to navigate forward in the history of
564 virtual bool CanGoForward() const = 0;
567 Clear the history, this will also remove the visible page.
569 virtual void ClearHistory() = 0;
572 Enable or disable the history. This will also clear the history.
574 virtual void EnableHistory(bool enable
= true) = 0;
577 Returns a list of items in the back history. The first item in the
578 vector is the first page that was loaded by the control.
580 virtual wxVector
<wxSharedPtr
<wxWebViewHistoryItem
> > GetBackwardHistory() = 0;
583 Returns a list of items in the forward history. The first item in the
584 vector is the next item in the history with respect to the curently
587 virtual wxVector
<wxSharedPtr
<wxWebViewHistoryItem
> > GetForwardHistory() = 0;
590 Navigate back in the history of visited pages.
591 Only valid if CanGoBack() returns true.
593 virtual void GoBack() = 0;
596 Navigate forward in the history of visited pages.
597 Only valid if CanGoForward() returns true.
599 virtual void GoForward() = 0;
602 Loads a history item.
604 virtual void LoadHistoryItem(wxSharedPtr
<wxWebViewHistoryItem
> item
) = 0;
611 Clears the current selection.
613 virtual void ClearSelection() = 0;
616 Deletes the current selection. Note that for @c wxWEBVIEW_BACKEND_WEBKIT
617 the selection must be editable, either through SetEditable or the
618 correct HTML attribute.
620 virtual void DeleteSelection() = 0;
623 Returns the currently selected source, if any.
625 virtual wxString
GetSelectedSource() const = 0;
628 Returns the currently selected text, if any.
630 virtual wxString
GetSelectedText() const = 0;
633 Returns @true if there is a current selection.
635 virtual bool HasSelection() const = 0;
638 Selects the entire page.
640 virtual void SelectAll() = 0;
647 Returns @true if there is an action to redo.
649 virtual bool CanRedo() const = 0;
652 Returns @true if there is an action to undo.
654 virtual bool CanUndo() const = 0;
657 Redos the last action.
659 virtual void Redo() = 0;
662 Undos the last action.
664 virtual void Undo() = 0;
671 Finds a phrase on the current page and if found, the control will
672 scroll the phrase into view and select it.
673 @param text The phrase to search for.
674 @param flags The flags for the search.
675 @return If search phrase was not found in combination with the flags
676 then @c wxNOT_FOUND is returned. If called for the first time
677 with search phrase then the total number of results will be
678 returned. Then for every time its called with the same search
679 phrase it will return the number of the current match.
680 @note This function will restart the search if the flags
681 @c wxWEBVIEW_FIND_ENTIRE_WORD or @c wxWEBVIEW_FIND_MATCH_CASE
682 are changed, since this will require a new search. To reset the
683 search, for example reseting the highlights call the function
684 with an empty search phrase. This always returns @c wxNOT_FOUND
685 on the OSX WebKit backend.
688 virtual long Find(const wxString
& text
, wxWebViewFindFlags flags
= wxWEBVIEW_FIND_DEFAULT
) = 0;
695 Retrieve whether the current HTML engine supports a zoom type.
696 @param type The zoom type to test.
697 @return Whether this type of zoom is supported by this HTML engine
698 (and thus can be set through SetZoomType()).
700 virtual bool CanSetZoomType(wxWebViewZoomType type
) const = 0;
703 Get the zoom factor of the page.
704 @return The current level of zoom.
706 virtual wxWebViewZoom
GetZoom() const = 0;
709 Get how the zoom factor is currently interpreted.
710 @return How the zoom factor is currently interpreted by the HTML engine.
712 virtual wxWebViewZoomType
GetZoomType() const = 0;
715 Set the zoom factor of the page.
716 @param zoom How much to zoom (scale) the HTML document.
718 virtual void SetZoom(wxWebViewZoom zoom
) = 0;
721 Set how to interpret the zoom factor.
722 @param zoomType How the zoom factor should be interpreted by the
724 @note invoke CanSetZoomType() first, some HTML renderers may not
725 support all zoom types.
727 virtual void SetZoomType(wxWebViewZoomType zoomType
) = 0;
734 @class wxWebViewEvent
736 A navigation event holds information about events associated with
739 @beginEventEmissionTable{wxWebViewEvent}
740 @event{EVT_WEBVIEW_NAVIGATING(id, func)}
741 Process a @c wxEVT_COMMAND_WEBVIEW_NAVIGATING event, generated before trying
742 to get a resource. This event may be vetoed to prevent navigating to this
743 resource. Note that if the displayed HTML document has several frames, one
744 such event will be generated per frame.
745 @event{EVT_WEBVIEW_NAVIGATED(id, func)}
746 Process a @c wxEVT_COMMAND_WEBVIEW_NAVIGATED event generated after it was
747 confirmed that a resource would be requested. This event may not be vetoed.
748 Note that if the displayed HTML document has several frames, one such event
749 will be generated per frame.
750 @event{EVT_WEBVIEW_LOADED(id, func)}
751 Process a @c wxEVT_COMMAND_WEBVIEW_LOADED event generated when the document
752 is fully loaded and displayed. Note that if the displayed HTML document has
753 several frames, one such event will be generated per frame.
754 @event{EVT_WEBVIEW_ERROR(id, func)}
755 Process a @c wxEVT_COMMAND_WEBVIEW_ERROR event generated when a navigation
757 The integer associated with this event will be a wxWebNavigationError item.
758 The string associated with this event may contain a backend-specific more
759 precise error message/code.
760 @event{EVT_WEBVIEW_NEWWINDOW(id, func)}
761 Process a @c wxEVT_COMMAND_WEBVIEW_NEWWINDOW event, generated when a new
762 window is created. You must handle this event if you want anything to
763 happen, for example to load the page in a new window or tab.
764 @event{EVT_WEBVIEW_TITLE_CHANGED(id, func)}
765 Process a @c wxEVT_COMMAND_WEBVIEW_TITLE_CHANGED event, generated when
766 the page title changes. Use GetString to get the title.
771 @category{events,webview}
775 class wxWebViewEvent
: public wxNotifyEvent
779 wxWebViewEvent(wxEventType type
, int id
, const wxString href
,
780 const wxString target
);
783 Get the name of the target frame which the url of this event
784 has been or will be loaded into. This may return an emptry string
785 if the frame is not available.
787 const wxString
& GetTarget() const;
790 Get the URL being visited
792 const wxString
& GetURL() const;
796 wxEventType wxEVT_COMMAND_WEBVIEW_NAVIGATING
;
797 wxEventType wxEVT_COMMAND_WEBVIEW_NAVIGATED
;
798 wxEventType wxEVT_COMMAND_WEBVIEW_LOADED
;
799 wxEventType wxEVT_COMMAND_WEBVIEW_ERROR
;
800 wxEventType wxEVT_COMMAND_WEBVIEW_NEWWINDOW
;
801 wxEventType wxEVT_COMMAND_WEBVIEW_TITLE_CHANGED
;