1wxWebView(3)               Erlang Module Definition               wxWebView(3)
2
3
4

NAME

6       wxWebView - Functions for wxWebView class
7

DESCRIPTION

9       This  control may be used to render web (HTML / CSS / javascript) docu‐
10       ments. It is designed to allow the creation of  multiple  backends  for
11       each  port,  although  currently just one is available. It differs from
12       wxHtmlWindow in that each backend is actually a full rendering  engine,
13       Trident  on  MSW  and  Webkit on macOS and GTK. This allows the correct
14       viewing of complex pages with javascript and css.
15
16       Backend Descriptions
17
18       Par: The IE backend uses Microsoft's Trident rendering engine, specifi‐
19       cally  the  version  used by the locally installed copy of Internet Ex‐
20       plorer. As such it is only available for the MSW port. By  default  re‐
21       cent  versions of the WebBrowser control, which this backend uses, emu‐
22       late Internet Explorer 7. This can be changed with a  registry  setting
23       by wxWebView::MSWSetEmulationLevel() see this article for more informa‐
24       tion. This backend has full support for custom schemes and virtual file
25       systems.
26
27       Par:  The Edge (Chromium) backend uses Microsoft's Edge WebView2. It is
28       available for Windows 7 and newer. The following features are currently
29       unsupported with this backend: virtual filesystems, custom urls, find.
30
31       This backend is not enabled by default, to build it follow these steps:
32
33       Par:  Under GTK the WebKit backend uses WebKitGTK+. The current minimum
34       version required is 1.3.1 which ships by default with Ubuntu Natty  and
35       Debian Wheezy and has the package name libwebkitgtk-dev. Custom schemes
36       and virtual files systems are supported under this backend, however em‐
37       bedded  resources  such  as images and stylesheets are currently loaded
38       using the data:// scheme.
39
40       Par: Under GTK3 the WebKit2 version of WebKitGTK+ is  used.  In  Ubuntu
41       the  required package name is libwebkit2gtk-4.0-dev and under Fedora it
42       is webkitgtk4-devel. All wxWEBVIEW_WEBKIT features are supported except
43       for clearing and enabling / disabling the history.
44
45       Par:  The macOS WebKit backend uses Apple's WebView class. This backend
46       has full support for custom schemes and virtual file systems.
47
48       Asynchronous Notifications
49
50       Many of the methods in wxWebView are asynchronous, i.e. they return im‐
51       mediately and perform their work in the background. This includes func‐
52       tions such as loadURL/2 and reload/2. To receive  notification  of  the
53       progress  and  completion  of  these  functions  you need to handle the
54       events that are provided.  Specifically  wxEVT_WEBVIEW_LOADED  notifies
55       when the page or a sub-frame has finished loading and wxEVT_WEBVIEW_ER‐
56       ROR notifies that an error has occurred.
57
58       Virtual File Systems and Custom Schemes
59
60       wxWebView supports the registering of custom scheme handlers, for exam‐
61       ple  file  or  http.  To do this create a new class which inherits from
62       wxWebViewHandler (not implemented in wx), where wxWebHandler::GetFile()
63       returns  a  pointer  to a wxFSFile (not implemented in wx) which repre‐
64       sents the given url. You can then register your handler with  Register‐
65       Handler()  (not  implemented in wx) it will be called for all pages and
66       resources.
67
68       wxWebViewFSHandler (not implemented in wx) is provided  to  access  the
69       virtual  file  system  encapsulated by wxFileSystem (not implemented in
70       wx). The wxMemoryFSHandler (not implemented in wx) documentation  gives
71       an example of how this may be used.
72
73       wxWebViewArchiveHandler  (not  implemented  in wx) is provided to allow
74       the navigation of pages inside a zip archive. It supports paths of  the
75       form: scheme:///C:/example/docs.zip;protocol=zip/main.htm
76
77       Since: 2.9.3
78
79       See: wxWebViewHandler (not implemented in wx), wxWebViewEvent
80
81       This  class is derived (and can use functions) from: wxControl wxWindow
82       wxEvtHandler
83
84       wxWidgets docs: wxWebView
85

EVENTS

87       Event types emitted from this class: webview_navigating,  webview_navi‐
88       gated,  webview_loaded,  webview_error,  webview_newwindow, webview_ti‐
89       tle_changed
90

DATA TYPES

92       wxWebView() = wx:wx_object()
93

EXPORTS

95       new(Parent, Id) -> wxWebView()
96
97              Types:
98
99                 Parent = wxWindow:wxWindow()
100                 Id = integer()
101
102       new(Parent, Id, Options :: [Option]) -> wxWebView()
103
104              Types:
105
106                 Parent = wxWindow:wxWindow()
107                 Id = integer()
108                 Option =
109                     {url, unicode:chardata()} |
110                     {pos, {X :: integer(), Y :: integer()}} |
111                     {size, {W :: integer(), H :: integer()}} |
112                     {backend, unicode:chardata()} |
113                     {style, integer()}
114
115              Factory function to create a new wxWebView using a wxWebViewFac‐
116              tory (not implemented in wx).
117
118              Return:  The created wxWebView, or NULL if the requested backend
119              is not available
120
121              Since: 2.9.5
122
123       getCurrentTitle(This) -> unicode:charlist()
124
125              Types:
126
127                 This = wxWebView()
128
129              Get the title of the current web page, or its URL/path if  title
130              is not available.
131
132       getCurrentURL(This) -> unicode:charlist()
133
134              Types:
135
136                 This = wxWebView()
137
138              Get the URL of the currently displayed document.
139
140       getPageSource(This) -> unicode:charlist()
141
142              Types:
143
144                 This = wxWebView()
145
146              Get the HTML source code of the currently displayed document.
147
148              Return:  The  HTML source code, or an empty string if no page is
149              currently shown.
150
151       getPageText(This) -> unicode:charlist()
152
153              Types:
154
155                 This = wxWebView()
156
157              Get the text of the current page.
158
159       isBusy(This) -> boolean()
160
161              Types:
162
163                 This = wxWebView()
164
165              Returns whether the web control is currently busy (e.g.  loading
166              a page).
167
168       isEditable(This) -> boolean()
169
170              Types:
171
172                 This = wxWebView()
173
174              Returns whether the web control is currently editable.
175
176       loadURL(This, Url) -> ok
177
178              Types:
179
180                 This = wxWebView()
181                 Url = unicode:chardata()
182
183              Load a web page from a URL.
184
185              Note:  Web engines generally report errors asynchronously, so if
186              you wish to know whether loading the URL was successful,  regis‐
187              ter to receive navigation error events.
188
189       print(This) -> ok
190
191              Types:
192
193                 This = wxWebView()
194
195              Opens  a  print  dialog so that the user may print the currently
196              displayed page.
197
198       reload(This) -> ok
199
200              Types:
201
202                 This = wxWebView()
203
204       reload(This, Options :: [Option]) -> ok
205
206              Types:
207
208                 This = wxWebView()
209                 Option = {flags, wx:wx_enum()}
210
211              Reload the currently displayed URL.
212
213              Note: The flags are ignored by the edge backend.
214
215       runScript(This, Javascript) -> Result
216
217              Types:
218
219                 Result = {Res :: boolean(), Output :: unicode:charlist()}
220                 This = wxWebView()
221                 Javascript = unicode:chardata()
222
223              Runs the given JavaScript code.
224
225              JavaScript code is executed inside the browser control  and  has
226              full access to DOM and other browser-provided functionality. For
227              example, this code will replace the current page  contents  with
228              the provided string.
229
230              If output is non-null, it is filled with the result of executing
231              this code on success, e.g. a JavaScript value such as a  string,
232              a  number  (integer or floating point), a boolean or JSON repre‐
233              sentation for non-primitive types such as  arrays  and  objects.
234              For example:
235
236              This function has a few platform-specific limitations:
237
238              Also notice that under MSW converting JavaScript objects to JSON
239              is not supported in the default emulation mode. wxWebView imple‐
240              ments  its  own object-to-JSON conversion as a fallback for this
241              case, however it is not as full-featured,  well-tested  or  per‐
242              forming  as  the  implementation  of  this  functionality in the
243              browser control itself, so it is recommended to use MSWSetEmula‐
244              tionLevel()  to  change  emulation level to a more modern one in
245              which JSON conversion is done by the control itself.
246
247              Return: true if there is a result, false if there is an error.
248
249       setEditable(This) -> ok
250
251              Types:
252
253                 This = wxWebView()
254
255       setEditable(This, Options :: [Option]) -> ok
256
257              Types:
258
259                 This = wxWebView()
260                 Option = {enable, boolean()}
261
262              Set the editable property of the web control.
263
264              Enabling allows the user to edit the page even if the contented‐
265              itable  attribute  is  not set. The exact capabilities vary with
266              the backend being used.
267
268       setPage(This, Html, BaseUrl) -> ok
269
270              Types:
271
272                 This = wxWebView()
273                 Html = BaseUrl = unicode:chardata()
274
275              Set the displayed page source  to  the  contents  of  the  given
276              string.
277
278              Note: When using wxWEBVIEW_BACKEND_IE you must wait for the cur‐
279              rent page  to  finish  loading  before  calling  setPage/3.  The
280              baseURL parameter is not used in this backend and the edge back‐
281              end.
282
283       stop(This) -> ok
284
285              Types:
286
287                 This = wxWebView()
288
289              Stop the current page loading process, if any.
290
291              May trigger an error event of  type  wxWEBVIEW_NAV_ERR_USER_CAN‐
292              CELLED.  TODO: make wxWEBVIEW_NAV_ERR_USER_CANCELLED errors uni‐
293              form across ports.
294
295       canCopy(This) -> boolean()
296
297              Types:
298
299                 This = wxWebView()
300
301              Returns true if the current selection can be copied.
302
303              Note: This always returns true on the macOS WebKit backend.
304
305       canCut(This) -> boolean()
306
307              Types:
308
309                 This = wxWebView()
310
311              Returns true if the current selection can be cut.
312
313              Note: This always returns true on the macOS WebKit backend.
314
315       canPaste(This) -> boolean()
316
317              Types:
318
319                 This = wxWebView()
320
321              Returns true if data can be pasted.
322
323              Note: This always returns true on the macOS WebKit backend.
324
325       copy(This) -> ok
326
327              Types:
328
329                 This = wxWebView()
330
331              Copies the current selection.
332
333       cut(This) -> ok
334
335              Types:
336
337                 This = wxWebView()
338
339              Cuts the current selection.
340
341       paste(This) -> ok
342
343              Types:
344
345                 This = wxWebView()
346
347              Pastes the current data.
348
349       enableContextMenu(This) -> ok
350
351              Types:
352
353                 This = wxWebView()
354
355       enableContextMenu(This, Options :: [Option]) -> ok
356
357              Types:
358
359                 This = wxWebView()
360                 Option = {enable, boolean()}
361
362              Enable or disable the right click context menu.
363
364              By default the standard context menu is enabled, this method can
365              be used to disable it or re-enable it later.
366
367              Since: 2.9.5
368
369       isContextMenuEnabled(This) -> boolean()
370
371              Types:
372
373                 This = wxWebView()
374
375              Returns true if a context menu will be shown on right click.
376
377              Since: 2.9.5
378
379       canGoBack(This) -> boolean()
380
381              Types:
382
383                 This = wxWebView()
384
385              Returns  true if it is possible to navigate backward in the his‐
386              tory of visited pages.
387
388       canGoForward(This) -> boolean()
389
390              Types:
391
392                 This = wxWebView()
393
394              Returns true if it is possible to navigate forward in  the  his‐
395              tory of visited pages.
396
397       clearHistory(This) -> ok
398
399              Types:
400
401                 This = wxWebView()
402
403              Clear the history, this will also remove the visible page.
404
405              Note: This is not implemented on the WebKit2GTK+ backend.
406
407       enableHistory(This) -> ok
408
409              Types:
410
411                 This = wxWebView()
412
413       enableHistory(This, Options :: [Option]) -> ok
414
415              Types:
416
417                 This = wxWebView()
418                 Option = {enable, boolean()}
419
420              Enable or disable the history.
421
422              This will also clear the history.
423
424              Note: This is not implemented on the WebKit2GTK+ backend.
425
426       goBack(This) -> ok
427
428              Types:
429
430                 This = wxWebView()
431
432              Navigate back in the history of visited pages.
433
434              Only valid if canGoBack/1 returns true.
435
436       goForward(This) -> ok
437
438              Types:
439
440                 This = wxWebView()
441
442              Navigate forward in the history of visited pages.
443
444              Only valid if canGoForward/1 returns true.
445
446       clearSelection(This) -> ok
447
448              Types:
449
450                 This = wxWebView()
451
452              Clears the current selection.
453
454       deleteSelection(This) -> ok
455
456              Types:
457
458                 This = wxWebView()
459
460              Deletes the current selection.
461
462              Note that for wxWEBVIEW_BACKEND_WEBKIT the selection must be ed‐
463              itable, either through SetEditable or the  correct  HTML  attri‐
464              bute.
465
466       getSelectedSource(This) -> unicode:charlist()
467
468              Types:
469
470                 This = wxWebView()
471
472              Returns the currently selected source, if any.
473
474       getSelectedText(This) -> unicode:charlist()
475
476              Types:
477
478                 This = wxWebView()
479
480              Returns the currently selected text, if any.
481
482       hasSelection(This) -> boolean()
483
484              Types:
485
486                 This = wxWebView()
487
488              Returns true if there is a current selection.
489
490       selectAll(This) -> ok
491
492              Types:
493
494                 This = wxWebView()
495
496              Selects the entire page.
497
498       canRedo(This) -> boolean()
499
500              Types:
501
502                 This = wxWebView()
503
504              Returns true if there is an action to redo.
505
506       canUndo(This) -> boolean()
507
508              Types:
509
510                 This = wxWebView()
511
512              Returns true if there is an action to undo.
513
514       redo(This) -> ok
515
516              Types:
517
518                 This = wxWebView()
519
520              Redos the last action.
521
522       undo(This) -> ok
523
524              Types:
525
526                 This = wxWebView()
527
528              Undos the last action.
529
530       find(This, Text) -> integer()
531
532              Types:
533
534                 This = wxWebView()
535                 Text = unicode:chardata()
536
537       find(This, Text, Options :: [Option]) -> integer()
538
539              Types:
540
541                 This = wxWebView()
542                 Text = unicode:chardata()
543                 Option = {flags, wx:wx_enum()}
544
545              Finds  a  phrase  on  the current page and if found, the control
546              will scroll the phrase into view and select it.
547
548              Return: If search phrase was not found in combination  with  the
549              flags then wxNOT_FOUND is returned. If called for the first time
550              with search phrase then the total number of results will be  re‐
551              turned.  Then  for  every  time  its called with the same search
552              phrase it will return the number of the current match.
553
554              Note: This function will restart the search if the flags  wxWEB‐
555              VIEW_FIND_ENTIRE_WORD  or wxWEBVIEW_FIND_MATCH_CASE are changed,
556              since this will require a new search. To reset the  search,  for
557              example resetting the highlights call the function with an empty
558              search phrase. This always returns wxNOT_FOUND on the macOS  We‐
559              bKit backend.
560
561              Since: 2.9.5
562
563       canSetZoomType(This, Type) -> boolean()
564
565              Types:
566
567                 This = wxWebView()
568                 Type = wx:wx_enum()
569
570              Retrieve whether the current HTML engine supports a zoom type.
571
572              Return:  Whether this type of zoom is supported by this HTML en‐
573              gine (and thus can be set through setZoomType/2).
574
575       getZoom(This) -> wx:wx_enum()
576
577              Types:
578
579                 This = wxWebView()
580
581              Get the zoom level of the page.
582
583              See getZoomFactor/1 to get more precise zoom scale  value  other
584              than as provided by wxWebViewZoom.
585
586              Return: The current level of zoom.
587
588       getZoomType(This) -> wx:wx_enum()
589
590              Types:
591
592                 This = wxWebView()
593
594              Get how the zoom factor is currently interpreted.
595
596              Return: How the zoom factor is currently interpreted by the HTML
597              engine.
598
599       setZoom(This, Zoom) -> ok
600
601              Types:
602
603                 This = wxWebView()
604                 Zoom = wx:wx_enum()
605
606              Set the zoom level of the page.
607
608              See setZoomFactor/2 for more precise scaling other than the mea‐
609              sured steps provided by wxWebViewZoom.
610
611       setZoomType(This, ZoomType) -> ok
612
613              Types:
614
615                 This = wxWebView()
616                 ZoomType = wx:wx_enum()
617
618              Set how to interpret the zoom factor.
619
620              Note: invoke canSetZoomType/2 first, some HTML renderers may not
621              support all zoom types.
622
623       getZoomFactor(This) -> number()
624
625              Types:
626
627                 This = wxWebView()
628
629              Get the zoom factor of the page.
630
631              Return: The current factor of zoom.
632
633              Since: 3.1.4
634
635       setZoomFactor(This, Zoom) -> ok
636
637              Types:
638
639                 This = wxWebView()
640                 Zoom = number()
641
642              Set the zoom factor of the page.
643
644              Note: zoom scale in IE will be converted into wxWebViewZoom lev‐
645              els for wxWebViewZoomType of wxWEBVIEW_ZOOM_TYPE_TEXT.
646
647              Since: 3.1.4
648
649       isBackendAvailable(Backend) -> boolean()
650
651              Types:
652
653                 Backend = unicode:chardata()
654
655              Allows to check if a specific backend is currently available.
656
657              Since: 3.1.4
658
659
660
661wxWidgets team.                     wx 2.1                        wxWebView(3)