Getting Started

General Use

JavaScript Integration


Windows Forms




Introduction to Web-Views

.NET Language:

What is a Web-View?

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

There are two different types of Web-Views:

  • Offscreen Views

    Offscreen Views are rendered continuously to a pixel-buffer surface (see 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).

    In Awesomium.NET, we provide predefined surfaces for every technology that take care of copying the native pixel buffer to managed equivalent bitmaps and help you render the buffer to technology specific surfaces.

  • Windowed Views

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

    When using a windowed WebView on MS Windows, you should call WebView.ParentWindow immediately after creating this type of view (the view cannot create a window until a parent is set). Technology specific WebControls, handle this internally.

The IWebView Interface

The IWebView interface exposes the full API of a native Awesomium Web-View, as well as .NET specific API added to web-views. It is provided for advanced coding and in certain scenarios, it allows you to override much of the .NET internal logic and call on the native web-view directly.

All managed Web-View components, implement this interface. It provides most of the common API of all Awesomium.NET Web-View components. It also exposes all the events that a web-view component can fire.

In Awesomium.NET documentation and articles, a Web-View instance is usually referred to as an IWebView instance and common members of this interface implemented by each Awesomium.NET Web-View component, are referenced through this interface.

For more details, read the documentation of IWebView.

Awesomium.NET Web-View Components

Awesomium.NET provides 3 different web-view components for MS Windows, 2 for Mac OSX and 2 for the Unity game engine. The following presents these components:

"WebView" Component

Compatible With
All (WinForms, WPF, Mono, etc.)
Provided by the Awesomium.Core assembly on MS Windows and by the equivalent Awesomium.Mono assembly for all platforms, it can be used in any technology. For more details, read Using the WebView.
View Types
  • Offscreen (Default)
  • Windowed

The type is defined during creation.

WPF "WebControl" Component

Compatible With
WPF Only
Provided by the Awesomium.Windows.Controls assembly. It can be used in WPF applications. For more details, read Using the WPF WebControl.
View Types
  • Offscreen (Default. Uses 100% WPF logic to copy and render the pixel buffer. This maintains the advantages of the Presentation Framework.)
  • Windowed (Renders a windowed web-view using a HwndHost. Misses many presentation features but supports full hardware acceleration.)

The type is defined by setting the WebControl.ViewType property.

WinForms "WebControl" Component

Compatible With
WinForms Only
Provided by the Awesomium.Windows.Forms assembly. It can be used in Windows Forms applications. For more details, read Using the Windows Forms WebControl.
View Types
  • Windowed (Default)
  • Offscreen

The type is defined by setting the WebControl.ViewType property.

MonoMac "OSMWebView" Component

Compatible With
MonoMac (OSX) Only
Provided by the Awesomium.Mono.Mac assembly on Mac OSX. It can be used in Cocoa applications on OSX using Mono. For more details, read Using the MonoMac OSMWebView.
View Types
  • Windowed (NSView)

Unity "WebUIComponent" Component

Compatible With
Unity Game Engine Only
Provided by the Awesomium.Unity assembly. It can be used in Unity games on Windows and Mac OSX. For more details, read Using the Unity WebUIComponent.
View Types
  • Offscreen (Renders to a Unity Texture)

Asynchronous API

Awesomium adopts a similar multi-process architecture to Chrome. Each IWebView instance 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, read the Handling Events section below.

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

// Execute some Javascript that returns a result.
JSValue result = webView.ExecuteJavascriptWithResult( scriptString );

// Check for any errors
if ( webView.GetLastError() != Error.None )
    System.Diagnostics.Debug.Print( "There was an error calling this synchronous method" );

Handling Events

The IWebView interface exposes many events that you can handle and receive notifications. These events are implemented by all Awesomium.NET Web-View components. Here are some examples:

Using a WebView component:

bool finishedLoading = false;

// Load some content.
view.Source = new Uri( "" );

// Handle the LoadingFrameComplete event.
// For this example, we use a lambda expression.
view.LoadingFrameComplete += ( s, e ) =>
    // The main frame always finishes loading last for a given page load.
    if ( e.IsMainFrame )
        finishedLoading = true;

// Update the core while the main frame
// is not yet loaded.
while ( !finishedLoading )
    Thread.Sleep( 100 );

// A BitmapSurface is assigned by default to all WebViews.
BitmapSurface surface = (BitmapSurface)view.Surface;
// Save the buffer to a PNG image.
surface.SaveToPNG( "result.png", true );

Using the Windows Forms WebControl:

webControl.TitleChanged += OnTitleChanged;
webControl.AddressChanged += OnAddressChanged;


private void OnTitleChanged( object sender, TitleChangedEventArgs e )
    // Reflect the page's title to the window text.
    this.Text = e.Title;

private void OnAddressChanged( object sender, UrlEventArgs e )
    // Reflect the current URL to the window text.
    // Normally, after the page loads, we will get a title.
    // But a page may as well not specify a title.
    this.Text = e.Url.ToString();

Binding to Notifications

Most events set relative properties that reflect the current status of an IWebView instance. For example, when IWebView.TargetURLChanged is fired, the IWebView.TargetURL and IWebView.HasTargetURL properties, have already been updated.

The WebView component and the Windows Forms WebControl, implement INotifyPropertyChanged. Likewise, the WPF WebControl can provide notifications through its dependency model.

This allows you to set bindings to properties of an IWebView instance, directly in the Visual Studio designer. For example, you can use the Data Bindings setting in the Properties window of the Windows Forms designer, to bind the text of UI elements of your Form to properties of a WebControl.

Here is an example of setting bindings in Windows Forms programmatically, using a WebView:

private BindingSource bindingSource;


// Create a BindingSource and set our WebView as DataSource.
bindingSource = new BindingSource() { DataSource = webView };

// Bind the Text property of the Form, to the Title property of the WebView.
    new Binding( "Text", bindingSource, "Title", true ) );

And here is an equivalent WPF example:

    Title="{Binding Title, ElementName=webControl}">
    <Grid SnapsToDevicePixels="True">
        <awe:WebControl Name="webControl" Source=""/>

All IWebView events are dispatched asynchronously (meaning that the event may arrive a few milliseconds after the event actually happened in the child-process).

Features as a Service

The availability of some features of an IWebView, occassionally depends on the current state of the view, or its type (offscreen or windowed). For this reason, the IWebView interface inherits IServiceProvider and provides these features in the form of a service.

Users can query for a service, through IServiceProvider.GetService, specifying the type of the requested service.

In the following example, we query for the IWebViewIMEComposition service that allows you to pass text input via IME and be notified of any IME-related events. This feature is only available in offscreen IWebView instances.

// Query for the IWebViewIMEComposition service.
IWebViewIMEComposition imeComposition = webControl.GetService( 
    typeof( IWebViewIMEComposition ) );

// GetService will return a null reference, if the service
// is not available.
if ( imeComposition != null )
    // Handle some events.
    imeComposition.Cancel += UserCanceledIME;
    // Activate IME.
    imeComposition.ActivateIME( true );

Native Web-View Wrapping Sequence

It is important to understand the sequence of events that occur when a native web-view is being wrapped by an Awesomium.NET component. This helps you decide the moment certain operations can be performed on the component.

For details, read the Web-View Initialization Sequence article.

Cleaning Up

All IWebView instances implement IDisposable and expose a Dispose method. You should generally call Dispose on an IWebView instance when you’re done using it. This allows the view to perform some cleanup and release resources.

For offscreen IWebView instances, the ISurface instance currently assigned to IWebView.Surface is disposed when the view is disposed.

When an IWebView instance is displayed in a graphical environment (like when using a WebControl), you should not call Dispose while the container of the view is still visible.

The IWebView.IsDisposed property can be used to check if a view has been disposed.

Here is an example using the WPF WebControl:

// Override Window.OnClosed.
protected override void OnClosed( EventArgs e )
    base.OnClosed( e );

    // Dispose the WebControl.

    // This was the only Window in our app.
    // Shutdown the WebCore while exiting.

All views maintained by the WebCore are automatically disposed when WebCore.Shutdown is called.