Language:

Categories

Getting Started

General Use

JavaScript Integration

WPF

Windows Forms

MonoMac

Unity

Changelogs

Using the WPF WebControl

.NET Language:

Index

Introduction

The WPF WebControl is our official WPF wrapper of an Awesomium Web-View.

The WPF WebControl is available through the Awesomium.Windows.Controls assembly and provides WPF developers with a ready to use, drag-and-drop, standalone WPF control that handles all the basic embedding tasks (mouse/keyboard input, rendering, resizing, cursors, focusing, etc.) and various utilities that can help WPF developers take advantage of all Awesomium features.

Creating a WebControl

When you install the Awesomium SDK , the WPF WebControl is automatically added to Visual Studio’s Toolbox. You should be able to see it under the Awesomium.NET toolbox tab when a Window or Control is open in the WPF designer.

If you cannot find the WebControl or the Awesomium.NET tab in your toolbox, please read: Visual Studio Toolbox.

All you have to do is drag and drop the WebControl from the Toolbox to your container in the designer, or in XAML. The appropriate references will automatically be added to your project.

To easily make the control fill its container, right-click the control in the designer and from the context menu select: Reset Layout > All

Create in XAML

If you want to add a WebControl directly in XAML without using the Toolbox, you will have to make sure your project references the following assemblies:

  • Awesomium.Core.dll
  • Awesomium.Windows.Controls.dll

Then, in XAML, add the appropriate XAML Namespace and the WebControl, like this:

<Window 
    x:Class="WpfApplication1.MainWindow" 
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:osm="http://schemas.awesomium.com/winfx"
    Height="480" 
    Width="640">
    <osm:WebControl Name="webControl" />
</Window>

Create at Runtime

You can create a WebControl at runtime and add it to the visual tree, just as you would with any other WPF control.

WebControls created programmatically will not initialize and wrap a native web-view, until they are added to the visual tree and loaded for presentation. This allows you to set properties that can only be set when the view is not yet alive (see IsLive), right after creating the WebControl, but also poses some limitations. For details, read the Initialization section below.

Initialization

It is important to understand the sequence of events that occur when a native web-view is being wrapped by an Awesomium.NET component, such as the WPF WebControl. The WPF WebControl, will not initialize and wrap a native web-view until it is added to the visual tree and loaded for presentation. This means that you cannot perform actions against the native web-view instance (see IWebView), until the WebControl is loaded for presenation and IsLive is true.

Below is a list of events in the Awesomium.NET API, that are being fired once during the initialization of all IWebView instances, in that order:

  1. IWebView.InitializeView: Fired right before a native web-view is wrapped. This is the last moment that properties that cannot be changed when IsLive is true, can be set.
  2. WebCore.CreatedView: Fired when the new Web-View component is added to the WebCore.Views collection.
  3. IWebView.NativeViewInitialized: Fired after the native web-view is created, initialization is complete and settings have been applied to view.
  4. IWebView.ProcessCreated: Fired when it’s certain that the child process of the view (awesomium_process), has been started. This is usually when the first page starts loading.

The complete initialization sequence of the WPF WebControl, helps you decide the moment certain operations can be performed on the component.

For the complete sequence, read Web-View Initialization Sequence - WPF WebControl Component.

Summary

To summarize, the following list provides some guidance of how to manually create and/or initialize your WebControl:

  1. If you need to programmatically create a WebControl, do so right after the IntializeComponent method call, inside your container’s constructor.
  2. To initialize your WebControl, do so in any of the following places:
    • In the designer, by setting properties in XAML or by selecting the control and using the Properties window. WebControl properties in the Properties window, are properly categorized.
    • In code, right after its creation (if the control was created programmatically. - See above).
    • In code, right after the InitializeComponent method call inside your container’s constructor. This also applies for controls created in the designer or XAML. Settings applied at this point, will of course override the settings of properties set in the designer (which are applied during InitializeComponent).
    • Inside a WebControl.InitializeView event handler. This is the last event fired before the native web-view is created and initialization settings are applied to it. You can set a handler for InitializeView in either the designer/XAML, or right after the InitializeComponent method call inside your container’s constructor.
  3. To access members of the native IWebView instance, do so in any of the following moments:
  4. To execute JavaScript on a loaded page, do so right after the WebControl.DocumentReady event is fired. This is the case for all subsequent navigations after the initial one, if any.

To easily access your WebControl programmatically, make sure you set a Name for it in the designer/XAML.

For a complete example, see the Example section below.

WebCore Initialization

If you need to explicitly initialize the Awesomium WebCore in a WPF application using WebControls, you can do so in any of the following places:

  • Inside an Application.Startup event handler, in your App.xaml.cs (or Application.xaml.vb in Visual Basic) code file.
  • Inside an Application.OnStartup override, before or after calling the base method.
  • Before the InitializeComponent method call inside your main window’s constructor.

Irrespective of the place you choose, make sure that you use the WebCore.Initialize(WebConfig) overload, that only accepts a WebConfig. This method performs lazy initialization which means that the core will actually be initialized when the first view or WebSession are created.

For details, read the WebCore Initialization article.

If you choose to initialize the WebCore before the InitializeComponent method call inside your main window’s constructor, make sure that your code checks for WebCore.IsInitialized before attempting to call WebCore.Initialize. Your application may create more than one instances of your main window but the Awesomium WebCore can only be initialized once. Attempting to call WebCore.Initialize when the WebCore is already initialized and running, will throw an exception.

For a complete example, see the Example section below.

Example

Loading Content

The primary way to load content into any IWebView instance, is via the Source property. For example, to begin navigating a WPF WebControl to Google, select the WebControl in the WPF designer and in the Properties window, set the Source property:

WPF WebControl.Source

Likewise in XAML:

<Window 
    x:Class="WpfApplication1.MainWindow" 
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:osm="http://schemas.awesomium.com/winfx"
    Height="480" 
    Width="640">
    <osm:WebControl 
        Name="webControl"
        Source="http://www.google.com/" />
</Window>

It is practically easier to set the Source property in the Properties window rather than directly in XAML. If you type just google.com in the Properties window, we automatically add the http:// protocol for you.

Loading Content at Runtime

At runtime, you can navigate to a new address anytime, still by setting the Source property. The property accepts a Uri but we have provided some extensions that make it easy to pass a string:

using Awesomium.Core;

[...]

webControl.Source = "http://www.awesomium.com".ToUri();

ToUri will return a blank URI (about:blank), if the string does not represent a properly formatted URI.

Loading Resources

WebControl.Source makes it really easy to load remote content on the Internet, but what about local resources? If you would like to load local resources with your application, we recommend using a 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 an introduction to DataSource and the available, predefined DataSource classes that come with Awesomium.NET.

In WPF, we provide a WebSession provider (see Using Web-Sessions) and DataSource providers for all the available Awesomium.NET DataSource classes, that can be used in XAML.

For details, read the Using DataSource Providers article.

Rendering

The WPF WebControl supports both offscreen and windowed rendering (for details, read Introduction to Web-Views).

The rendering mode is defined by setting the WebControl.ViewType property. By default, the WPF WebControl wraps an offscreen native web-view, which means that ViewType is set to Offscreen.

Hardware acceleration is only supported by windowed native web-views. For details about using hardware aceleration, read Hardware Acceleration in the WebViewHost section below.

Presenters

The WPF WebControl uses WPF specific presenters (IWebViewPresenter), depending on the specified ViewType. Presenters are used in the visual tree when styling a WPF WebControl. These can be custom WPF surfaces also implementing ISurface (for offscreen views) or any other control providing custom presentation of an IWebView instance. When the custom control is added to the visual tree and loaded for presentation, the IWebView instance (typically a WPF WebControl) uses the IWebViewPresenter interface to communicate with the presentation control.

Awesomium.Windows.Controls already provides 2 such presenters. These are:

WebViewPresenter

Used when ViewType is set to Offscreen (default). This is an ISurface component that uses 100% WPF logic to copy the view's pixel buffer to a bitmap that it then renders for presentation.

WebViewPresenter inherits FrameworkElement and is part of the WPF WebControl's default style. When the visual tree is loaded for presentation, the WPF WebControl uses the IWebViewPresenter interface to communicate with the WebViewPresenter that takes care of all UI related operations which besides rendering include:

  • Handling user input
  • Presentation of dialogs
  • Presentation of menus
Pixel Buffer

The WebViewPresenter exposes an Image property which represents the WPF ImageSource wrapping the pixel buffer currently rendered by the surface. Users can use this image to either save a snapshot on disk, or create mirror presentations of the view.

For an example, see: Getting a snapshot using the WPF WebControl.

User Input

It is important to note that in WPF, it is the WebViewPresenter and not the WebControl itself that handles user input. This means that handling user input related events on the WebControl, will not prevent the WebViewPresenter from handling these events and passing them to the native view.

Since the WebViewPresenter is part of the WebControl's visual tree, the appropriate way to handle such events yourself, is by handling the Preview events.

Native windowed views handle user input themselves and there's no way to handle or simulate user input on the managed side. If you need to handle or simulate user input, make sure that WebControl.ViewType is set to Offscreen (default).

For an example, see: Handling or Simulating User Input with the WPF WebControl.

WebViewHost

Used when ViewType is set to Window. This is a HwndHost wrapping the Win32 Window (IWebView.NativeWindow) a windowed native IWebView instance creates to render to. The WebViewHost then takes care of parenting the windowed view to the container WPF Window the WebControl belongs to. The parent WPF Window is internally assigned as IWebView.ParentWindow.

The WebViewHost implements IWebViewPresenter and is part of the WPF WebControl's default style. When the visual tree is loaded for presentation, the WPF WebControl uses the IWebViewPresenter interface to communicate with the WebViewHost that takes care of all UI related operations such as:

  • Presentation of dialogs
  • Presentation of menus

Unlike offscreen views, rendering in windowed views is not handled on the managed side. This provides several benefits such as better performance and hardware acceleration, but also poses many presentation limitations in WPF.

For details, read Hwnds inside WPF .

Pixel Buffer

On MS Windows, windowed native web-views render directly to a native Win32 window (that the WebViewHost hosts) and no Surface is used (for details, read Introduction to Web-Views). When WebControl.ViewType is set to Window, WebControl.Surface returns a null reference.

To get a snapshot of the web content of a WPF WebControl when ViewType is set to Window, you will need to reference System.Drawing and use some Win32 API.

For an example, see: Getting a snapshot using the WPF WebControl.

User Input

Native windowed views handle user input themselves and there's no straightforward way to handle or simulate user input on the managed side. If you need to handle or simulate user input, make sure that WebControl.ViewType is set to Offscreen (default).

For details, read Hwnds inside WPF - Notable Differences in Input Behavior .

Hardware Acceleration

Hardware acceleration is only supported by windowed native web-views. When ViewType is set to Window, you can take advantage of hardware acceleration which will also significantly improve WebGL performance, by following these steps:

  1. Assign a WebSession to the WebControl. You can use a WebSessionProvider in XAML for the purpose. For details, read Using Web-Sessions.
  2. Assign WebPreferences to WebSession.Preferences (or WebSessionProvider.Preferences in XAML) and set the following properties to true:
  3. Make sure you set WebControl.ViewType to Window to create and wrap a windowed native web-view.

Using WPF Presenters with a WebView

Offscreen vs Windowed in WPF

UI Integration

Routed Commands

The WebControlCommands static class, exposes routed UI commands that are common to a WPF WebControl. The commands call important methods on the WPF WebControl they target. This class is an important utility when implementing a WPF UI hosting a WebControl.

For details about these commands and any required command parameters, read the WebControlCommands API reference.

In addition to the WebControl-specific routed UI commands defined in WebControlCommands, the WebControl reuses many of the ApplicationCommands and NavigationCommands available with the .NET Framework. In particular, these are:

Command Method Called Notes
ApplicationCommands.Copy Copy
ApplicationCommands.Cut Cut
ApplicationCommands.Paste Paste
ApplicationCommands.SelectAll SelectAll
ApplicationCommands.Print PrintToFile Shows up a dialog to choose where to save the PDF file.
Uses default configuration (see PrintConfig).
NavigationCommands.BrowseHome GoToHome
NavigationCommands.BrowseBack GoBack
NavigationCommands.BrowseForward GoForward
NavigationCommands.BrowseStop Stop
NavigationCommands.Refresh Reload Requires a CommandParameter which is a boolean value specifying if cache should be ignored when reloading the page.

In order to get the text of these commands displayed in your system’s locale, you may need to download a Microsoft .NET Framework 4 Client Language Pack (x86 x64) . Future versions will allow developers to also provide localization for the text of WebControlCommands.

For a complete usage example and how to override bindings, see Integrating the WebControl to a WPF GUI.

Predefined Controls

The Awesomium.Windows.Controls assembly, includes several out-of-the-box WPF controls that are used to present additional UI one would expect to find in a browser window. Many of these controls, are also highly customizable. These are:

Control Usage Customizable
WebControlContextMenu Context menu shown when you right-click in a `WebControl`. The menu items shown depend on the element you right-clicked. Yes (Allows full or partial customizsation)
WebPopupMenu Drop-down (popup) menu presented for HTML select elements. Yes
WebPageInfoControl Presents security and certificate information for the loaded page. Yes
WebPageInfoPopup Popup menu attached to control (usually a Button) and presents security and certificate information for the loaded page (includes a WebPageInfoControl). No
WebControlLoginLayer Presents a login dialog whenever requested. No (It can be completely substituted by your own dialog by handling the LoginRequest event. See Customizing Dialogs below.)
WebControlJSDialogLayer Presents JavaScript dialogs (alert, confirm and prompt). No (They can be completely substituted by your own dialogs by handling the ShowJavascriptDialog event. See Customizing Dialogs below.)
WebDialogsLayer A container control that unifies the presentation of JavaScript dialogs. For details, read: Using the WebDialogsLayer. No (You can choose the style of the presented dialogs. A new Metro style has been added.)

Some of the controls allow full or even simple partial customization, but all controls can be substituted by your own. For details, read the Customizations section below.

Awesomium is primarily a Web UI renderer; it is not a browser. The ideal scenario would expect HTML pages presented in Awesomium, to design and present their secondary UI (menus, popups etc.), using web technologies (HTML, JavaScript) and let only the rendering part to Awesomium and Awesomium.NET.

The Awesomium API provides all the API and information necessary to build and present your own assisting, additional UI. Predefined controls available by Awesomium.NET for every technology, are only there to provide an out-of-the-box experience for those who do not want to go through designing this UI themselves. They are not premium controls supported by Awesomium and you can at any time use the available Awesomium API to substitute them with your own.

Utilities

For a complete usage example, see Integrating the WebControl to a WPF GUI.

Customizations

Customizing the Context Menu

Customizing Popup Menus

Customizing Dialogs

Additional Resources