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 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 are rendered directly to a platform window (
NSView, etc.) and capture all input themselves.
When using a windowed
WebViewon MS Windows, you should call
WebView.ParentWindowimmediately after creating this type of view (the view cannot create a window until a parent is set). Technology specific
WebControls, handle this internally.
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
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:
Compatible WithAll (WinForms, WPF, Mono, etc.)
DescriptionProvided 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.
- Offscreen (Default)
The type is defined during creation.
WPF "WebControl" Component
Compatible WithWPF Only
DescriptionProvided by the Awesomium.Windows.Controls assembly. It can be used in WPF applications. For more details, read Using the WPF WebControl.
- 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
WinForms "WebControl" Component
Compatible WithWinForms Only
DescriptionProvided by the Awesomium.Windows.Forms assembly. It can be used in Windows Forms applications. For more details, read Using the Windows Forms WebControl.
- Windowed (Default)
The type is defined by setting the
MonoMac "OSMWebView" Component
Compatible WithMonoMac (OSX) Only
DescriptionProvided 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.
- Windowed (
Unity "WebUIComponent" Component
Compatible WithUnity Game Engine Only
DescriptionProvided 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.
Offscreen (Renders to a Unity
- Offscreen (Renders to a Unity
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 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 the Windows Forms
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.HasTargetURL properties, have already been updated.
WebView component and the Windows Forms
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
Here is an example of setting bindings in Windows Forms programmatically, using a
And here is an equivalent WPF example:
IWebViewevents 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
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.
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.
ISurfaceinstance currently assigned to
IWebView.Surfaceis disposed when the view is disposed.
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.
IWebView.IsDisposedproperty can be used to check if a view has been disposed.
Here is an example using the WPF
All views maintained by the
WebCoreare automatically disposed when