Introduction to Web-Views

What is a WebView?

A WebView is like a tab in a browser. You load pages into a WebView, interact with it, and display it in some pre-defined manner.

There are two different types of WebViews:

Offscreen Views

Offscreen Views are rendered continuously to a pixel-buffer surface (see WebView::surface()). It is your responsibility to display this surface in your application and pass all mouse/keyboard events. This gives you the flexibility to display web-content in any environment (such as a 3D engine or headless renderer).

All WebViews are Offscreen by default.

Windowed Views

Windowed Views are rendered directly to a platform window (HWND, NSView, etc.) and capture all input themselves.

On MS Windows, you should call WebView::set_parent_window immediately after creating this type of WebView (the view cannot create a window until a parent is set).

On Mac OSX, you will need to retrieve WebView::window after creating this type of WebView and add it to your own container to display the view in your application.

Creating a WebView

You create WebViews using the WebCore, here’s an example:

// Create an offscreen WebView
WebView* view = web_core->CreateWebView(500, 500);

Here’s an example of how to create a windowed WebView on MS Windows:

// Create a windowed WebView
WebView* view = web_core->CreateWebView(500, 500, 0, kWebViewType_Window);
view->set_parent_window(parent_hwnd);

Loading Content

The primary way to load content into a WebView is via WebView::LoadURL. For example, to begin navigating a WebView to Google, you would call:

WebURL url(WSLit("http://www.google.com"));
view->LoadURL(url);

All URLs should be properly formatted before passing it to LoadURL. You can check if a URL is valid via WebURL::IsValid:

WebURL url(some_url_string);
if (!url.IsValid())
  std::cerr << "Error! URL was unable to be parsed.";

LoadURL makes it really easy to load remote content on the Internet, but what about local resources?

Defining a Custom DataSource

If you would like to load local resources with your application we recommend using DataSource. This powerful bit of API allows you to provide a custom resource loader for a set of URLs that match a certain prefix.

See this article for more information on using DataSource.

Asynchronous API

Awesomium adopts a similar multi-process architecture to Chrome. Each WebView is actually isolated and rendered in a separate process.

Most method calls are sent via a piped message to the child-process and may not complete immediately. To be notified of different events, see the following section on event listeners.

You should take extra care with the few methods that are actually synchronous, you can use WebView::last_error() to check if there was an error dispatching a synchronous method call. For example, WebView::ExecuteJavascriptWithResult is sent synchronously because it must return a value:

JSValue result = view->ExecuteJavascriptWithResult(script, frame);
if (view->last_error())
  std::cerr << "There was an error calling this synchronous method".

Registering Listeners

The WebViewListener namespace contains a suite of special classes that you can use to respond to certain events in a WebView.

For example, to listen for all load-related events, you would simply make your own subclass of WebViewListener::Load and then register an instance of it to a certain WebView using WebView::set_load_listener. Here’s a psuedo-example:

// Define our WebViewListener::Load subclass
class MyLoadListener : public Awesomium::WebViewListener::Load {
  // ... All the overriden WebViewListener::Load methods go here
};

// Create an instance of MyLoadListener and register it to a certain WebView
MyLoadListener* my_load_listener = new MyLoadListener();
my_web_view->set_load_listener(my_load_listener);

Please note that all WebViewListener events are dispatched asynchronously (meaning that the event may arrive a few milliseconds after the event actually happened in the child-process).

Cleaning Up

You should call WebView::Destroy once you are done using the WebView. You should try to avoid making this call from one of the WebViewListener or JSMethodHandler callbacks.

The Wiki

Language:

Categories