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"
25 class WXDLLIMPEXP_WEB wxWebHistoryItem
28 wxWebHistoryItem(const wxString
& url
, const wxString
& title
) :
29 m_url(url
), m_title(title
) {}
30 wxString
GetUrl() { return m_url
; }
31 wxString
GetTitle() { return m_title
; }
34 wxString m_url
, m_title
;
38 * Zoom level in web view component
43 wxWEB_VIEW_ZOOM_SMALL
,
44 wxWEB_VIEW_ZOOM_MEDIUM
,
45 wxWEB_VIEW_ZOOM_LARGE
,
46 wxWEB_VIEW_ZOOM_LARGEST
50 * The type of zooming that the web view control can perform
52 enum wxWebViewZoomType
54 /** The entire layout scales when zooming, including images */
55 wxWEB_VIEW_ZOOM_TYPE_LAYOUT
,
56 /** Only the text changes in size when zooming, images and other layout
57 * elements retain their initial size */
58 wxWEB_VIEW_ZOOM_TYPE_TEXT
61 /** Types of errors that can cause navigation to fail */
62 enum wxWebNavigationError
64 /** Connection error (timeout, etc.) */
65 wxWEB_NAV_ERR_CONNECTION
,
66 /** Invalid certificate */
67 wxWEB_NAV_ERR_CERTIFICATE
,
68 /** Authentication required */
70 /** Other security error */
71 wxWEB_NAV_ERR_SECURITY
,
72 /** Requested resource not found */
73 wxWEB_NAV_ERR_NOT_FOUND
,
74 /** Invalid request/parameters (e.g. bad URL, bad protocol,
75 * unsupported resource type) */
76 wxWEB_NAV_ERR_REQUEST
,
77 /** The user cancelled (e.g. in a dialog) */
78 wxWEB_NAV_ERR_USER_CANCELLED
,
79 /** Another (exotic) type of error that didn't fit in other categories*/
83 /** Type of refresh */
84 enum wxWebViewReloadFlags
86 /** Default reload, will access cache */
87 wxWEB_VIEW_RELOAD_DEFAULT
,
88 /** Reload the current view without accessing the cache */
89 wxWEB_VIEW_RELOAD_NO_CACHE
94 * List of available backends for wxWebView
98 /** Value that may be passed to wxWebView to let it pick an appropriate
99 * engine for the current platform*/
100 wxWEB_VIEW_BACKEND_DEFAULT
,
102 /** The WebKit web engine */
103 wxWEB_VIEW_BACKEND_WEBKIT
,
105 /** Use Microsoft Internet Explorer as web engine */
106 wxWEB_VIEW_BACKEND_IE
109 class WXDLLIMPEXP_WEB wxWebProtocolHandler
112 virtual wxString
GetProtocol() = 0;
113 virtual wxFSFile
* GetFile(const wxString
&uri
) = 0;
114 virtual wxString
CombineURIs(const wxString
&baseuri
, const wxString
&newuri
) = 0;
117 extern WXDLLIMPEXP_DATA_WEB(const char) wxWebViewNameStr
[];
118 extern WXDLLIMPEXP_DATA_WEB(const char) wxWebViewDefaultURLStr
[];
120 class WXDLLIMPEXP_WEB wxWebView
: public wxControl
125 * Creation function for two-step creation.
127 virtual bool Create(wxWindow
* parent
,
133 const wxString
& name
) = 0;
136 * Factory function to create a new wxWebView for two-step creation
137 * (you need to call wxWebView::Create on the returned object)
138 * @param backend which web engine to use as backend for wxWebView
139 * @return the created wxWebView, or NULL if the requested backend is
142 static wxWebView
* New(wxWebViewBackend backend
= wxWEB_VIEW_BACKEND_DEFAULT
);
144 // TODO: clarify what styles can do, or remove this flag
146 * Factory function to create a new wxWebView
147 * @param parent parent window to create this view in
148 * @param id ID of this control
149 * @param url URL to load by default in the web view
150 * @param pos position to create this control at
151 * (you may use wxDefaultPosition if you use sizers)
152 * @param size size to create this control with
153 * (you may use wxDefaultSize if you use sizers)
154 * @param backend which web engine to use as backend for wxWebView
155 * @return the created wxWebView, or NULL if the requested backend
158 static wxWebView
* New(wxWindow
* parent
,
160 const wxString
& url
= wxWebViewDefaultURLStr
,
161 const wxPoint
& pos
= wxDefaultPosition
,
162 const wxSize
& size
= wxDefaultSize
,
163 wxWebViewBackend backend
= wxWEB_VIEW_BACKEND_DEFAULT
,
165 const wxString
& name
= wxWebViewNameStr
);
168 /** Get whether it is possible to navigate back in the history of
171 virtual bool CanGoBack() = 0;
173 /** Get whether it is possible to navigate forward in the history of
176 virtual bool CanGoForward() = 0;
178 /** Navigate back in the history of visited pages.
179 * Only valid if CanGoBack() returned true.
181 virtual void GoBack() = 0;
183 /** Navigate forwardin the history of visited pages.
184 * Only valid if CanGoForward() returned true.
186 virtual void GoForward() = 0;
189 * Load a HTMl document (web page) from a URL
190 * @param url the URL where the HTML document to display can be found
191 * @note web engines generally report errors asynchronously, so if you wish
192 * to know whether loading the URL was successful, register to receive
193 * navigation error events
195 virtual void LoadUrl(const wxString
& url
) = 0;
197 virtual void ClearHistory() = 0;
198 virtual void EnableHistory(bool enable
= true) = 0;
199 virtual wxVector
<wxSharedPtr
<wxWebHistoryItem
> > GetBackwardHistory() = 0;
200 virtual wxVector
<wxSharedPtr
<wxWebHistoryItem
> > GetForwardHistory() = 0;
201 virtual void LoadHistoryItem(wxSharedPtr
<wxWebHistoryItem
> item
) = 0;
204 * Stop the current page loading process, if any.
205 * May trigger an error event of type wxWEB_NAV_ERR_USER_CANCELLED.
206 * TODO: make wxWEB_NAV_ERR_USER_CANCELLED errors uniform across ports.
208 virtual void Stop() = 0;
211 * Reload the currently displayed URL.
212 * @param flags A bit array that may optionnally contain reload options
214 virtual void Reload(wxWebViewReloadFlags flags
= wxWEB_VIEW_RELOAD_DEFAULT
) = 0;
218 * Get the URL of the currently displayed document
220 virtual wxString
GetCurrentURL() = 0;
223 * Get the title of the current web page, or its URL/path if title is not
226 virtual wxString
GetCurrentTitle() = 0;
228 // TODO: handle choosing a frame when calling GetPageSource()?
230 * Get the HTML source code of the currently displayed document
231 * @return the HTML source code, or an empty string if no page is currently
234 virtual wxString
GetPageSource() = 0;
235 virtual wxString
GetPageText() = 0;
238 * Get the zoom factor of the page
239 * @return How much the HTML document is zoomed (scaleed)
241 virtual wxWebViewZoom
GetZoom() = 0;
244 * Set the zoom factor of the page
245 * @param zoom How much to zoom (scale) the HTML document
247 virtual void SetZoom(wxWebViewZoom zoom
) = 0;
250 * Set how to interpret the zoom factor
251 * @param zoomType how the zoom factor should be interpreted by the
253 * @note invoke canSetZoomType() first, some HTML renderers may not
254 * support all zoom types
256 virtual void SetZoomType(wxWebViewZoomType zoomType
) = 0;
259 * Get how the zoom factor is currently interpreted
260 * @return how the zoom factor is currently interpreted by the HTML engine
262 virtual wxWebViewZoomType
GetZoomType() const = 0;
265 * Retrieve whether the current HTML engine supports a type of zoom
266 * @param type the type of zoom to test
267 * @return whether this type of zoom is supported by this HTML engine
268 * (and thus can be set through setZoomType())
270 virtual bool CanSetZoomType(wxWebViewZoomType type
) const = 0;
272 // TODO: allow 'SetPage' to find files (e.g. images) from a virtual file
273 // system if possible
275 * Set the displayed page source to the contents of the given string
276 * @param html the string that contains the HTML data to display
277 * @param baseUrl URL assigned to the HTML data, to be used to resolve
278 * relative paths, for instance
280 virtual void SetPage(const wxString
& html
, const wxString
& baseUrl
) = 0;
283 * Set the displayed page source to the contents of the given stream
284 * @param html the stream to read HTML data from
285 * @param baseUrl URL assigned to the HTML data, to be used to resolve
286 * relative paths, for instance
288 virtual void SetPage(wxInputStream
& html
, wxString baseUrl
)
290 wxStringOutputStream stream
;
292 SetPage(stream
.GetString(), baseUrl
);
295 virtual void SetEditable(bool enable
= true) = 0;
296 virtual bool IsEditable() = 0;
298 virtual void SelectAll() = 0;
299 virtual bool HasSelection() = 0;
300 virtual void DeleteSelection() = 0;
301 virtual wxString
GetSelectedText() = 0;
302 virtual wxString
GetSelectedSource() = 0;
303 virtual void ClearSelection() = 0;
305 virtual void RunScript(const wxString
& javascript
) = 0;
308 // void EnableJavascript(bool enabled); // maybe?
311 // void SetScrollPos(int pos); // maybe?
312 // int GetScrollPos(); // maybe?
314 // wxString GetStatusText(); // maybe?
315 // void SetStatusText(wxString text); // maybe?
316 // * status text changed event?
317 // * title changed event?
319 // virtual bool IsOfflineMode() = 0; // maybe?
320 // virtual void SetOfflineMode(bool offline) = 0; // maybe?
323 * Opens a print dialog so that the user may print the currently
326 virtual void Print() = 0;
329 * Returns whether the web control is currently busy (e.g. loading a page)
331 virtual bool IsBusy() = 0;
333 //Clipboard functions
334 virtual bool CanCut() = 0;
335 virtual bool CanCopy() = 0;
336 virtual bool CanPaste() = 0;
337 virtual void Cut() = 0;
338 virtual void Copy() = 0;
339 virtual void Paste() = 0;
341 //Undo / redo functionality
342 virtual bool CanUndo() = 0;
343 virtual bool CanRedo() = 0;
344 virtual void Undo() = 0;
345 virtual void Redo() = 0;
348 class WXDLLIMPEXP_WEB wxWebNavigationEvent
: public wxCommandEvent
351 wxWebNavigationEvent() {}
352 wxWebNavigationEvent(wxEventType type
, int id
, const wxString url
,
353 const wxString target
, bool canVeto
)
354 : wxCommandEvent(type
, id
)
363 * Get the URL being visited
365 const wxString
& GetURL() const { return m_url
; }
368 * Get the target (frame or window) in which the URL that caused this event
369 * is viewed, or an empty string if not available.
371 const wxString
& GetTarget() const { return m_target
; }
373 // default copy ctor, assignment operator and dtor are ok
374 virtual wxEvent
* Clone() const { return new wxWebNavigationEvent(*this); }
376 /** Get whether this event may be vetoed (stopped/prevented). Only
377 * meaningful for events fired before navigation takes place.
379 bool CanVeto() const { return m_canVeto
; }
381 /** Whether this event was vetoed (stopped/prevented). Only meaningful for
382 * events fired before navigation takes place.
384 bool IsVetoed() const { return m_vetoed
; }
386 /** Veto (prevent/stop) this event. Only meaningful for events fired
387 * before navigation takes place. Only valid if CanVeto() returned true.
389 void Veto() { wxASSERT(m_canVeto
); m_vetoed
= true; }
397 wxDECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxWebNavigationEvent
);
400 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_NAVIGATING
, wxWebNavigationEvent
);
401 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_NAVIGATED
, wxWebNavigationEvent
);
402 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_LOADED
, wxWebNavigationEvent
);
403 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_ERROR
, wxWebNavigationEvent
);
404 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_WEB
, wxEVT_COMMAND_WEB_VIEW_NEWWINDOW
, wxWebNavigationEvent
);
406 typedef void (wxEvtHandler
::*wxWebNavigationEventFunction
)
407 (wxWebNavigationEvent
&);
409 #define wxWebNavigationEventHandler(func) \
410 wxEVENT_HANDLER_CAST(wxWebNavigationEventFunction, func)
412 #define EVT_WEB_VIEW_NAVIGATING(id, fn) \
413 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_NAVIGATING, id, \
414 wxHtmlNavigatingEventHandler(fn))
416 #define EVT_WEB_VIEW_NAVIGATED(id, fn) \
417 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_NAVIGATED, id, \
418 wxHtmlNavigatingEventHandler(fn))
420 #define EVT_WEB_VIEW_LOADED(id, fn) \
421 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_LOADED, id, \
422 wxHtmlNavigatingEventHandler(fn))
424 #define EVT_WEB_VIEW_ERRROR(id, fn) \
425 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_ERROR, id, \
426 wxHtmlNavigatingEventHandler(fn))
428 #define EVT_WEB_VIEW_NEWWINDOW(id, fn) \
429 wx__DECLARE_EVT1(wxEVT_COMMAND_WEB_VIEW_NEWWINDOW, id, \
430 wxHtmlNavigatingEventHandler(fn))
434 #endif // _WX_WEB_VIEW_H_