README

muWebView is a thin wrapper around native web browser technology with a wxWidgets API. It allows you to create controls displaying web content and react to various events. Client code inside the web views can communicate with the host process through asynchronous messages. On Windows, muWebView uses the WebView2 libraries, on Unix it uses WebKitGTK+ by default.

Client APIs

wxFileSystem paths are accessible read-only via the wxfs: URI scheme. Since browser URIs can only have one fragment, the syntax is slightly different from the paths used by wxWidgets: Instead of scheme1:some/path1#scheme2:some/path2#fragment write wxfs://scheme1/some/path1//scheme2/some/path2#fragment.

Call window.external.sendMessage(<data>) from client JavaScript to send a string (or JSON serializable object) to the host. Callbacks can be attached to each web view through the muEVT_WEBVIEW_MESSAGE event.

Call window.external.recvMessage(<callback>) to register a callback that is invoked with any data the host sends to the web view. Host code can send a message through muWebView::SendMessage.

Using the Browser

The mubrowser executable serves as an example how to integrate muWebView functionality into a program, and can be used as a standalone web browser or application shell. You can pass the URL of a page to load on the command line. An application manifest can be loaded through the --manifest command line option. Inter-process remote control can be activated through the -rwb command line options. Developer tools can be activated with the --devtools command line option.

Application manifests are JSON documents specifying settings for the muWebAppEnvironment class. They also allow setting up event handlers that call into native libraries, without compiling a complete host application. Refer to the plotter.* example files and the source code of muWebAppEnvironment::LoadManifest for details.

If you pass -r|--stdout to mubrowser, events describing the creation and closing of web views, as well as incoming message events wil be written to standard output for a client process to read. If you pass -w|--stdin, the mubrowser will read commands in the form {"id":WEBVIEW,"uri":STRING} or {"id":WEBVIEW,"message":JSON}, identify the webview as in the outgoing events and navigate to a new URI or inject a message for the content to process. The "id":… property can be omitted, in which case mubrowser will direct the event to the muWebView of the current "top" window.

If you pass -b|--binary to mubrowser, standard input/output data is always prefixed with a native std::size_t indicating the length of the following utf-8-encoded data; otherwise, standard input/output data uses netstring framing.

Using the Library

To use the muWebView functionality in your own programs, you need to create a muWebEnvironment object. This can be done either through the C++ constructor muWebEnvironment::muWebEnvironment(const wxString &temporaryDirectory, const wxString &runtimeDirectory) or through the corresponding two-step creation function. Normally, there should only be one muWebEnvironment per program, so the application initialization functions are a good place to create it.

Web content is displayed inside instances of muWebView, whose constructors take either a muWebEnvironment or an existing muWebView for reference. If you respond to a muEVT_WEBVIEW_WINDOW_NEW event, you must use the muWebView::muWebView(wxWindow *parent, wxWindowID id, muWebView *view, const wxPoint &pos, const wxSize &size, long style, const wxValidator &validator, const wxString &name) constructor, or the equivalent two-step creation function.

A new muWebView is initially empty. Content can be loaded from URLs or strings of HTML, for example with muWebView::LoadURI(const wxString &uri) or muWebView::LoadHTML(const wxString &html).

The C++ API uses exceptions to represent fatal error conditions. Such exceptions are usually derived from the std::exception class, platform-specific errors are more specifically thrown as instances of muWebException.

For details, refer to the mu/webview.hpp header or the API documentation generated with Doxygen.

C API

Based on the reflection capabilities of the C++ library, a plain C API can also be used to embed muWebEnvironment and muWebView functionality into your program.

Use the functions mu_webappenvironment_new(int *argc, char **argv) or mu_webappenvironment_new_win32(HINSTANCE hInstance, char *pCmdLine, int nCmdShow) to create a combined wxApp / muWebEnvironment object. Once you are ready to hand over control to the wxWidgets event loop, call mu_webappenvironment_run(muIReflexive *app).

Use the function mu_webwindow_new(muIReflexive *env, const muJSON *features) to create a combined wxWindow / muWebView object and don't forget to call mu_webwindow_show(muIReflexive *win, bool show) to actually make the window visible to the user.

Objects returned from these functions can be deleted with mu_reflexive_delete(muIReflexive *self) and support several operations corresponding to the muIReflexive methods.

For details, refer to the mu/cwebview.h header or the API documentation generated with Doxygen.