1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxWebView
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 Zoom levels availiable in wxWebView
15 wxWEB_VIEW_ZOOM_SMALL
,
16 wxWEB_VIEW_ZOOM_MEDIUM
, //!< default size
17 wxWEB_VIEW_ZOOM_LARGE
,
18 wxWEB_VIEW_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 wxWEB_VIEW_ZOOM_TYPE_LAYOUT
,
31 Only the text changes in size when zooming, images and other layout
32 elements retain their initial size
34 wxWEB_VIEW_ZOOM_TYPE_TEXT
38 Types of errors that can cause navigation to fail
40 enum wxWebNavigationError
42 /** Connection error (timeout, etc.) */
43 wxWEB_NAV_ERR_CONNECTION
,
44 /** Invalid certificate */
45 wxWEB_NAV_ERR_CERTIFICATE
,
46 /** Authentication required */
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*/
64 enum wxWebViewReloadFlags
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
74 * List of available backends for wxWebView
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
,
82 /** The WebKit web engine */
83 wxWEB_VIEW_BACKEND_WEBKIT
,
85 /** Use Microsoft Internet Explorer as web engine */
90 @class wxWebHistoryItem
92 A simple class that contains the URL and title of an element of the history
100 class wxWebHistoryItem
106 wxWebHistoryItem(const wxString
& url
, const wxString
& title
);
109 @return The url of the page.
114 @return The title of the page.
122 The base class for handling custom schemes in wxWebView, for example to
123 allow virtual file system support.
134 @return A pointer to the file represented by @c uri.
136 virtual wxFSFile
* GetFile(const wxString
&uri
) = 0;
139 @return The name of the scheme, for example @c file or @c http.
141 virtual wxString
GetName() const = 0;
147 This control may be used to render web (HTML / CSS / javascript) documents.
148 Capabilities of the HTML renderer will depend upon the backed.
150 @c wxWEB_VIEW_BACKEND_IE uses the the Trident rendering engine, which
151 is also used by Internet Explorer. It is important to note that by default
152 it emulates Internet Explorer 7, this can be chaged with a registry
154 <a href="http://msdn.microsoft.com/en-us/library/ee330730%28v=vs.85%29.aspx#browser_emulation">
155 this</a> article for more information.
157 Note that errors are generally reported asynchronously though the
158 @c wxEVT_COMMAND_WEB_VIEW_ERROR event described below.
160 @section vfs Virtual File Systems and Custom Schemes
162 wxWebView supports the registering of custom scheme handlers, for example
163 @c file or @c http. To do this create a new class which inherits from
164 wxWebHandler, where the wxWebHandler::GetName() method returns the scheme
165 you wish to handle and wxWebHandler::GetFile() returns a pointer to a
166 wxFSFile which represents the given url. You can then register your handler
167 with RegisterHandler() it will be called for all pages and resources.
169 wxWebFileHandler is provided to allow the navigation of pages inside a zip
170 archive. It overrides the @c file scheme and provides support for the
171 standard @c file syntax as well as paths to archives of the form
172 @c file:///C:/exmaple/docs.zip;protocol=zip/main.htm
174 @beginEventEmissionTable{wxWebNavigationEvent}
175 @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
176 Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
177 to get a resource. This event may be vetoed to prevent navigating to this
178 resource. Note that if the displayed HTML document has several frames, one
179 such event will be generated per frame.
180 @event{EVT_WEB_VIEW_NAVIGATED(id, func)}
181 Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was
182 confirmed that a resource would be requested. This event may not be vetoed.
183 Note that if the displayed HTML document has several frames, one such event
184 will be generated per frame.
185 @event{EVT_WEB_VIEW_LOADED(id, func)}
186 Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document
187 is fully loaded and displayed. Note that if the displayed HTML document has
188 several frames, one such event will be generated per frame.
189 @event{EVT_WEB_VIEW_ERRROR(id, func)}
190 Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
192 The integer associated with this event will be a wxWebNavigationError item.
193 The string associated with this event may contain a backend-specific more
194 precise error message/code.
195 @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
196 Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
197 window is created. You must handle this event if you want anything to
198 happen, for example to load the page in a new window or tab.
199 @event{EVT_WEB_VIEW_TITLE_CHANGED(id, func)}
200 Process a @c wxEVT_COMMAND_WEB_VIEW_TITLE_CHANGED event, generated when
201 the page title changes. Use GetString to get the title.
206 @see wxWebHandler, wxWebNavigationEvent
208 class wxWebView
: public wxControl
213 Creation function for two-step creation.
215 virtual bool Create(wxWindow
* parent
,
221 const wxString
& name
) = 0;
224 Factory function to create a new wxWebView for two-step creation
225 (you need to call wxWebView::Create on the returned object)
226 @param backend which web engine to use as backend for wxWebView
227 @return the created wxWebView, or NULL if the requested backend is
230 static wxWebView
* New(wxWebViewBackend backend
= wxWEB_VIEW_BACKEND_DEFAULT
);
233 Factory function to create a new wxWebView
234 @param parent parent window to create this view in
235 @param id ID of this control
236 @param url URL to load by default in the web view
237 @param pos position to create this control at
238 (you may use wxDefaultPosition if you use sizers)
239 @param size size to create this control with
240 (you may use wxDefaultSize if you use sizers)
241 @param backend which web engine to use as backend for wxWebView
242 @return the created wxWebView, or NULL if the requested backend
245 static wxWebView
* New(wxWindow
* parent
,
247 const wxString
& url
= wxWebViewDefaultURLStr
,
248 const wxPoint
& pos
= wxDefaultPosition
,
249 const wxSize
& size
= wxDefaultSize
,
250 wxWebViewBackend backend
= wxWEB_VIEW_BACKEND_DEFAULT
,
252 const wxString
& name
= wxWebViewNameStr
);
255 Get the title of the current web page, or its URL/path if title is not
258 virtual wxString
GetCurrentTitle() = 0;
261 Get the URL of the currently displayed document.
263 virtual wxString
GetCurrentURL() = 0;
266 Get the HTML source code of the currently displayed document.
267 @return The HTML source code, or an empty string if no page is currently
270 virtual wxString
GetPageSource() = 0;
273 Get the text of the current page.
275 virtual wxString
GetPageText() = 0;
278 Returns whether the web control is currently busy (e.g. loading a page).
280 virtual bool IsBusy() = 0;
283 Returns whether the web control is currently editable
285 virtual bool IsEditable() = 0;
288 Load a web page from a URL
289 @param url The URL of the page to be loaded.
290 @note Web engines generally report errors asynchronously, so if you wish
291 to know whether loading the URL was successful, register to receive
292 navigation error events.
294 virtual void LoadUrl(const wxString
& url
) = 0;
297 Opens a print dialog so that the user may print the currently
300 virtual void Print() = 0;
303 Registers a custom scheme handler.
304 @param handler A pointer to a heap allocated wxWebHandler.
306 virtual void RegisterHandler(wxWebHandler
* handler
) = 0;
309 Reload the currently displayed URL.
310 @param flags A bit array that may optionally contain reload options.
312 virtual void Reload(wxWebViewReloadFlags flags
= wxWEB_VIEW_RELOAD_DEFAULT
) = 0;
315 Runs the given javascript code.
317 virtual void RunScript(const wxString
& javascript
) = 0;
320 Set the editable property of the web control. Enabling allows the user
321 to edit the page even if the @c contenteditable attribute is not set.
322 The exact capabilities vary with the backend being used.
324 virtual void SetEditable(bool enable
= true) = 0;
327 Set the displayed page source to the contents of the given string.
328 @param html The string that contains the HTML data to display.
329 @param baseUrl URL assigned to the HTML data, to be used to resolve
330 relative paths, for instance.
332 virtual void SetPage(const wxString
& html
, const wxString
& baseUrl
) = 0;
335 Set the displayed page source to the contents of the given stream.
336 @param html The stream to read HTML data from.
337 @param baseUrl URL assigned to the HTML data, to be used to resolve
338 relative paths, for instance.
340 virtual void SetPage(wxInputStream
& html
, wxString baseUrl
);
343 Stop the current page loading process, if any.
344 May trigger an error event of type @c wxWEB_NAV_ERR_USER_CANCELLED.
345 TODO: make @c wxWEB_NAV_ERR_USER_CANCELLED errors uniform across ports.
347 virtual void Stop() = 0;
354 Returns @true if the current selection can be copied.
356 virtual bool CanCopy() = 0;
359 Returns @true if the current selection can be cut.
361 virtual bool CanCut() = 0;
364 Returns @true if data can be pasted.
366 virtual bool CanPaste() = 0;
369 Copies the current selection.
371 virtual void Copy() = 0;
374 Cuts the current selection.
376 virtual void Cut() = 0;
379 Pastes the current data.
381 virtual void Paste() = 0;
388 Returns @true if it is possible to navigate backward in the history of
391 virtual bool CanGoBack() = 0;
394 Returns @true if it is possible to navigate forward in the history of
397 virtual bool CanGoForward() = 0;
400 Clear the history, this will also remove the visible page.
402 virtual void ClearHistory() = 0;
405 Enable or disable the history. This will also clear the history.
407 virtual void EnableHistory(bool enable
= true) = 0;
410 Returns a list of items in the back history. The first item in the
411 vector is the first page that was loaded by the control.
413 virtual wxVector
<wxSharedPtr
<wxWebHistoryItem
> > GetBackwardHistory() = 0;
416 Returns a list of items in the forward history. The first item in the
417 vector is the next item in the history with respect to the curently
420 virtual wxVector
<wxSharedPtr
<wxWebHistoryItem
> > GetForwardHistory() = 0;
423 Navigate back in the history of visited pages.
424 Only valid if CanGoBack() returns true.
426 virtual void GoBack() = 0;
429 Navigate forward in the history of visited pages.
430 Only valid if CanGoForward() returns true.
432 virtual void GoForward() = 0;
435 Loads a history item.
437 virtual void LoadHistoryItem(wxSharedPtr
<wxWebHistoryItem
> item
) = 0;
444 Clears the current selection.
446 virtual void ClearSelection() = 0;
449 Deletes the current selection. Note that for @c wxWEB_VIEW_BACKEND_WEBKIT
450 the selection must be editable, either through SetEditable or the
451 correct HTML attribute.
453 virtual void DeleteSelection() = 0;
456 Returns the currently selected source, if any.
458 virtual wxString
GetSelectedSource() = 0;
461 Returns the currently selected text, if any.
463 virtual wxString
GetSelectedText() = 0;
466 Returns @true if there is a current selection.
468 virtual bool HasSelection() = 0;
471 Selects the entire page.
473 virtual void SelectAll() = 0;
480 Returns @true if there is an action to redo.
482 virtual bool CanRedo() = 0;
485 Returns @true if there is an action to undo.
487 virtual bool CanUndo() = 0;
490 Redos the last action.
492 virtual void Redo() = 0;
495 Undos the last action.
497 virtual void Undo() = 0;
504 Retrieve whether the current HTML engine supports a zoom type.
505 @param type The zoom type to test.
506 @return Whether this type of zoom is supported by this HTML engine
507 (and thus can be set through SetZoomType()).
509 virtual bool CanSetZoomType(wxWebViewZoomType type
) const = 0;
512 Get the zoom factor of the page.
513 @return The current level of zoom.
515 virtual wxWebViewZoom
GetZoom() = 0;
518 Get how the zoom factor is currently interpreted.
519 @return How the zoom factor is currently interpreted by the HTML engine.
521 virtual wxWebViewZoomType
GetZoomType() const = 0;
524 Set the zoom factor of the page.
525 @param zoom How much to zoom (scale) the HTML document.
527 virtual void SetZoom(wxWebViewZoom zoom
) = 0;
530 Set how to interpret the zoom factor.
531 @param zoomType How the zoom factor should be interpreted by the
533 @note invoke CanSetZoomType() first, some HTML renderers may not
534 support all zoom types.
536 virtual void SetZoomType(wxWebViewZoomType zoomType
) = 0;
543 @class wxWebNavigationEvent
545 A navigation event holds information about events associated with
548 @beginEventEmissionTable{wxWebNavigationEvent}
549 @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
550 Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
551 to get a resource. This event may be vetoed to prevent navigating to this
552 resource. Note that if the displayed HTML document has several frames, one
553 such event will be generated per frame.
554 @event{EVT_WEB_VIEW_NAVIGATED(id, func)}
555 Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was
556 confirmed that a resource would be requested. This event may not be vetoed.
557 Note that if the displayed HTML document has several frames, one such event
558 will be generated per frame.
559 @event{EVT_WEB_VIEW_LOADED(id, func)}
560 Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document
561 is fully loaded and displayed. Note that if the displayed HTML document has
562 several frames, one such event will be generated per frame.
563 @event{EVT_WEB_VIEW_ERRROR(id, func)}
564 Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
566 The integer associated with this event will be a wxWebNavigationError item.
567 The string associated with this event may contain a backend-specific more
568 precise error message/code.
569 @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
570 Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
571 window is created. You must handle this event if you want anything to
572 happen, for example to load the page in a new window or tab.
573 @event{EVT_WEB_VIEW_TITLE_CHANGED(id, func)}
574 Process a @c wxEVT_COMMAND_WEB_VIEW_TITLE_CHANGED event, generated when
575 the page title changes. Use GetString to get the title.
579 @category{events,web}
583 class wxWebNavigationEvent
: public wxCommandEvent
586 wxWebNavigationEvent();
587 wxWebNavigationEvent(wxEventType type
, int id
, const wxString href
,
588 const wxString target
, bool canVeto
);
591 Get the name of the target frame which the url of this event
592 has been or will be loaded into. This may return an emptry string
593 if the frame is not avaliable.
595 const wxString
& GetTarget() const;
598 Get the URL being visited
600 const wxString
& GetURL() const;
602 virtual wxEvent
* Clone() const;
605 Get whether this event may be vetoed (stopped/prevented). Only
606 meaningful for events fired before navigation takes place.
608 bool CanVeto() const;
611 Whether this event was vetoed (stopped/prevented). Only meaningful for
612 events fired before navigation takes place or new window events.
614 bool IsVetoed() const;
617 Veto (prevent/stop) this event. Only meaningful for events fired
618 before navigation takes place. Only valid if CanVeto() returned true.