1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Common interface and events for web view component
4 // Author: Marianne Gagnon
6 // Copyright: (c) 2010 Marianne Gagnon
7 // Licence: wxWindows licence
8 /////////////////////////////////////////////////////////////////////////////
10 #ifndef _WX_WEB_VIEW_H_
11 #define _WX_WEB_VIEW_H_
17 #include <wx/control.h>
19 #include <wx/sstream.h>
20 #include "wx/sharedptr.h"
21 #include "wx/vector.h"
26 class WXDLLIMPEXP_WEB wxWebHistoryItem
29 wxWebHistoryItem(const wxString
& url
, const wxString
& title
) :
30 m_url(url
), m_title(title
) {}
31 wxString
GetUrl() { return m_url
; }
32 wxString
GetTitle() { return m_title
; }
35 wxString m_url
, m_title
;
39 * Zoom level in web view component
44 wxWEB_VIEW_ZOOM_SMALL
,
45 wxWEB_VIEW_ZOOM_MEDIUM
,
46 wxWEB_VIEW_ZOOM_LARGE
,
47 wxWEB_VIEW_ZOOM_LARGEST
51 * The type of zooming that the web view control can perform
53 enum wxWebViewZoomType
55 /** The entire layout scales when zooming, including images */
56 wxWEB_VIEW_ZOOM_TYPE_LAYOUT
,
57 /** Only the text changes in size when zooming, images and other layout
58 * elements retain their initial size */
59 wxWEB_VIEW_ZOOM_TYPE_TEXT
62 /** Types of errors that can cause navigation to fail */
63 enum wxWebNavigationError
65 /** Connection error (timeout, etc.) */
66 wxWEB_NAV_ERR_CONNECTION
,
67 /** Invalid certificate */
68 wxWEB_NAV_ERR_CERTIFICATE
,
69 /** Authentication required */
71 /** Other security error */
72 wxWEB_NAV_ERR_SECURITY
,
73 /** Requested resource not found */
74 wxWEB_NAV_ERR_NOT_FOUND
,
75 /** Invalid request/parameters (e.g. bad URL, bad protocol,
76 * unsupported resource type) */
77 wxWEB_NAV_ERR_REQUEST
,
78 /** The user cancelled (e.g. in a dialog) */
79 wxWEB_NAV_ERR_USER_CANCELLED
,
80 /** Another (exotic) type of error that didn't fit in other categories*/
84 /** Type of refresh */
85 enum wxWebViewReloadFlags
87 /** Default reload, will access cache */
88 wxWEB_VIEW_RELOAD_DEFAULT
,
89 /** Reload the current view without accessing the cache */
90 wxWEB_VIEW_RELOAD_NO_CACHE
95 * List of available backends for wxWebView
99 /** Value that may be passed to wxWebView to let it pick an appropriate
100 * engine for the current platform*/
101 wxWEB_VIEW_BACKEND_DEFAULT
,
103 /** The WebKit web engine */
104 wxWEB_VIEW_BACKEND_WEBKIT
,
106 /** Use Microsoft Internet Explorer as web engine */
107 wxWEB_VIEW_BACKEND_IE
110 //Base class for custom protocol handlers
111 class WXDLLIMPEXP_WEB wxWebProtocolHandler
114 virtual wxString
GetProtocol() = 0;
115 virtual wxFSFile
* GetFile(const wxString
&uri
) = 0;
116 virtual wxString
CombineURIs(const wxString
&baseuri
, const wxString
&newuri
) = 0;
119 //Loads from uris such as file:///C:/example/example.html or archives such as
120 //file:///C:/example/example.zip?protocol=zip;path=example.html
121 class WXDLLIMPEXP_WEB wxWebFileProtocolHandler
: public wxWebProtocolHandler
124 wxWebFileProtocolHandler();
125 virtual wxString
GetProtocol() { return m_protocol
; }
126 virtual wxFSFile
* GetFile(const wxString
&uri
);
127 virtual wxString
CombineURIs(const wxString
&baseuri
, const wxString
&newuri
);
130 wxFileSystem
* m_fileSystem
;
133 extern WXDLLIMPEXP_DATA_WEB(const char) wxWebViewNameStr
[];
134 extern WXDLLIMPEXP_DATA_WEB(const char) wxWebViewDefaultURLStr
[];
136 class WXDLLIMPEXP_WEB wxWebView
: public wxControl
141 * Creation function for two-step creation.
143 virtual bool Create(wxWindow
* parent
,
149 const wxString
& name
) = 0;
152 * Factory function to create a new wxWebView for two-step creation
153 * (you need to call wxWebView::Create on the returned object)
154 * @param backend which web engine to use as backend for wxWebView
155 * @return the created wxWebView, or NULL if the requested backend is
158 static wxWebView
* New(wxWebViewBackend backend
= wxWEB_VIEW_BACKEND_DEFAULT
);
160 // TODO: clarify what styles can do, or remove this flag
162 * Factory function to create a new wxWebView
163 * @param parent parent window to create this view in
164 * @param id ID of this control
165 * @param url URL to load by default in the web view
166 * @param pos position to create this control at
167 * (you may use wxDefaultPosition if you use sizers)
168 * @param size size to create this control with
169 * (you may use wxDefaultSize if you use sizers)
170 * @param backend which web engine to use as backend for wxWebView
171 * @return the created wxWebView, or NULL if the requested backend
174 static wxWebView
* New(wxWindow
* parent
,
176 const wxString
& url
= wxWebViewDefaultURLStr
,
177 const wxPoint
& pos
= wxDefaultPosition
,
178 const wxSize
& size
= wxDefaultSize
,
179 wxWebViewBackend backend
= wxWEB_VIEW_BACKEND_DEFAULT
,
181 const wxString
& name
= wxWebViewNameStr
);
184 /** Get whether it is possible to navigate back in the history of
187 virtual bool CanGoBack() = 0;
189 /** Get whether it is possible to navigate forward in the history of
192 virtual bool CanGoForward() = 0;
194 /** Navigate back in the history of visited pages.
195 * Only valid if CanGoBack() returned true.
197 virtual void GoBack() = 0;
199 /** Navigate forwardin the history of visited pages.
200 * Only valid if CanGoForward() returned true.
202 virtual void GoForward() = 0;
205 * Load a HTMl document (web page) from a URL
206 * @param url the URL where the HTML document to display can be found
207 * @note web engines generally report errors asynchronously, so if you wish
208 * to know whether loading the URL was successful, register to receive
209 * navigation error events
211 virtual void LoadUrl(const wxString
& url
) = 0;
213 virtual void ClearHistory() = 0;
214 virtual void EnableHistory(bool enable
= true) = 0;
215 virtual wxVector
<wxSharedPtr
<wxWebHistoryItem
> > GetBackwardHistory() = 0;
216 virtual wxVector
<wxSharedPtr
<wxWebHistoryItem
> > GetForwardHistory() = 0;
217 virtual void LoadHistoryItem(wxSharedPtr
<wxWebHistoryItem
> item
) = 0;
220 * Stop the current page loading process, if any.
221 * May trigger an error event of type wxWEB_NAV_ERR_USER_CANCELLED.
222 * TODO: make wxWEB_NAV_ERR_USER_CANCELLED errors uniform across ports.
224 virtual void Stop() = 0;
227 * Reload the currently displayed URL.
228 * @param flags A bit array that may optionnally contain reload options
230 virtual void Reload(wxWebViewReloadFlags flags
= wxWEB_VIEW_RELOAD_DEFAULT
) = 0;
234 * Get the URL of the currently displayed document
236 virtual wxString
GetCurrentURL() = 0;
239 * Get the title of the current web page, or its URL/path if title is not
242 virtual wxString
GetCurrentTitle() = 0;
244 // TODO: handle choosing a frame when calling GetPageSource()?
246 * Get the HTML source code of the currently displayed document
247 * @return the HTML source code, or an empty string if no page is currently
250 virtual wxString
GetPageSource() = 0;
251 virtual wxString
GetPageText() = 0;
254 * Get the zoom factor of the page
255 * @return How much the HTML document is zoomed (scaleed)
257 virtual wxWebViewZoom
GetZoom() = 0;
260 * Set the zoom factor of the page
261 * @param zoom How much to zoom (scale) the HTML document
263 virtual void SetZoom(wxWebViewZoom zoom
) = 0;
266 * Set how to interpret the zoom factor
267 * @param zoomType how the zoom factor should be interpreted by the
269 * @note invoke canSetZoomType() first, some HTML renderers may not
270 * support all zoom types
272 virtual void SetZoomType(wxWebViewZoomType zoomType
) = 0;
275 * Get how the zoom factor is currently interpreted
276 * @return how the zoom factor is currently interpreted by the HTML engine
278 virtual wxWebViewZoomType
GetZoomType() const = 0;
281 * Retrieve whether the current HTML engine supports a type of zoom
282 * @param type the type of zoom to test
283 * @return whether this type of zoom is supported by this HTML engine
284 * (and thus can be set through setZoomType())
286 virtual bool CanSetZoomType(wxWebViewZoomType type
) const = 0;
288 // TODO: allow 'SetPage' to find files (e.g. images) from a virtual file
289 // system if possible
291 * Set the displayed page source to the contents of the given string
292 * @param html the string that contains the HTML data to display
293 * @param baseUrl URL assigned to the HTML data, to be used to resolve
294 * relative paths, for instance
296 virtual void SetPage(const wxString
& html
, const wxString
& baseUrl
) = 0;
299 * Set the displayed page source to the contents of the given stream
300 * @param html the stream to read HTML data from
301 * @param baseUrl URL assigned to the HTML data, to be used to resolve
302 * relative paths, for instance
304 virtual void SetPage(wxInputStream
& html
, wxString baseUrl
)
306 wxStringOutputStream stream
;
308 SetPage(stream
.GetString(), baseUrl
);
311 virtual void SetEditable(bool enable
= true) = 0;
312 virtual bool IsEditable() = 0;
314 virtual void SelectAll() = 0;
315 virtual bool HasSelection() = 0;
316 virtual void DeleteSelection() = 0;
317 virtual wxString
GetSelectedText() = 0;
318 virtual wxString
GetSelectedSource() = 0;
319 virtual void ClearSelection() = 0;
321 virtual void RunScript(const wxString
& javascript
) = 0;
324 // void EnableJavascript(bool enabled); // maybe?
327 // void SetScrollPos(int pos); // maybe?
328 // int GetScrollPos(); // maybe?
330 // wxString GetStatusText(); // maybe?
331 // void SetStatusText(wxString text); // maybe?
332 // * status text changed event?
333 // * title changed event?
335 // virtual bool IsOfflineMode() = 0; // maybe?
336 // virtual void SetOfflineMode(bool offline) = 0; // maybe?
339 * Opens a print dialog so that the user may print the currently
342 virtual void Print() = 0;
345 * Returns whether the web control is currently busy (e.g. loading a page)
347 virtual bool IsBusy() = 0;
349 //Clipboard functions
350 virtual bool CanCut() = 0;
351 virtual bool CanCopy() = 0;
352 virtual bool CanPaste() = 0;
353 virtual void Cut() = 0;
354 virtual void Copy() = 0;
355 virtual void Paste() = 0;
357 //Undo / redo functionality
358 virtual bool CanUndo() = 0;
359 virtual bool CanRedo() = 0;
360 virtual void Undo() = 0;
361 virtual void Redo() = 0;
363 //Virtual Filesystem Support
364 virtual void RegisterProtocol(wxWebProtocolHandler
* handler
) = 0;
367 class WXDLLIMPEXP_WEB wxWebNavigationEvent
: public wxCommandEvent
370 wxWebNavigationEvent() {}
371 wxWebNavigationEvent(wxEventType type
, int id
, const wxString url
,
372 const wxString target
, bool canVeto
)
373 : wxCommandEvent(type
, id
)
382 * Get the URL being visited
384 const wxString
& GetURL() const { return m_url
; }
387 * Get the target (frame or window) in which the URL that caused this event
388 * is viewed, or an empty string if not available.
390 const wxString
& GetTarget() const { return m_target
; }
392 // default copy ctor, assignment operator and dtor are ok
393 virtual wxEvent
* Clone() const { return new wxWebNavigationEvent(*this); }
395 /** Get whether this event may be vetoed (stopped/prevented). Only
396 * meaningful for events fired before navigation takes place.
398 bool CanVeto() const { return m_canVeto
; }
400 /** Whether this event was vetoed (stopped/prevented). Only meaningful for
401 * events fired before navigation takes place.
403 bool IsVetoed() const { return m_vetoed
; }
405 /** Veto (prevent/stop) this event. Only meaningful for events fired
406 * before navigation takes place. Only valid if CanVeto() returned true.
408 void Veto() { wxASSERT(m_canVeto
); m_vetoed
= true; }
416 wxDECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxWebNavigationEvent
);
419 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_NAVIGATING
, wxWebNavigationEvent
);
420 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_NAVIGATED
, wxWebNavigationEvent
);
421 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_LOADED
, wxWebNavigationEvent
);
422 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_ERROR
, wxWebNavigationEvent
);
423 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_NEWWINDOW
, wxWebNavigationEvent
);
425 typedef void (wxEvtHandler::*wxWebNavigationEventFunction
)
426 (wxWebNavigationEvent
&);
428 #define wxWebNavigationEventHandler(func) \
429 wxEVENT_HANDLER_CAST(wxWebNavigationEventFunction, func)
431 #define EVT_WEB_VIEW_NAVIGATING(id, fn) \
432 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_NAVIGATING, id, \
433 wxHtmlNavigatingEventHandler(fn))
435 #define EVT_WEB_VIEW_NAVIGATED(id, fn) \
436 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_NAVIGATED, id, \
437 wxHtmlNavigatingEventHandler(fn))
439 #define EVT_WEB_VIEW_LOADED(id, fn) \
440 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_LOADED, id, \
441 wxHtmlNavigatingEventHandler(fn))
443 #define EVT_WEB_VIEW_ERRROR(id, fn) \
444 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_ERROR, id, \
445 wxHtmlNavigatingEventHandler(fn))
447 #define EVT_WEB_VIEW_NEWWINDOW(id, fn) \
448 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_NEWWINDOW, id, \
449 wxHtmlNavigatingEventHandler(fn))
453 #endif // _WX_WEB_VIEW_H_