The Role of the Property:

It is your responsibility to wrap and display this new view in your application.

The event must always be handled in your application to wrap views created by Awesomium in response to users clicking a link or JavaScript window.open calls.

If you don't handle this event, the unused web-view instance will be immediately destroyed. There are a number of facts you need to take into consideration, before taking the appropriate actions in response to a event. The following list presents these facts and some general suggestions: The created child view, has the same type (see ) and is assigned to the same session (see ) as its parent (opener) view. Therefore, you should not attempt to set these properties if you are wrapping the new child view with a technology specific WebControl. In order to maintain the relationship with their parent view, child views execute and render under the same process (awesomium_process) as their parent view. If for any reason the child process crashes, all views related to it will be affected. If is fired as a result of a Javascript window.open, will be true. In this scenario, you should always wrap the created child view instance (), to maintain the parent-child window relationship (the child page can access the parent through the window.opener property; the parent can manipulate the child through the window object returned from the window.open call, which is why window.open was most probably used in the first place). If is fired as a result of an HTML form with target="_blank" and method="post", will be true. In this scenario, you should always wrap the created child view instance (), to allow POST data be properly passed. When or are false, it most possibly indicates that the event is the result of a user clicking on a link with target="_blank". Since maintaining a parent-child relationship is not important in this scenario, you should cancel the event by setting to true (this tells the core to destroy the unused web-view instance), then create a new (using ) or WebControl and navigate to the provided , if any. This allows you to take advantage of the isolated process architecture of Awesomium and let each view be rendered in a separate process. Failing to cancel the event when you are not wrapping the new child view instance, will keep the native instance alive until the is shut down. This can result in numerous unused views being spawned, but never actually used. When or is true, navigation to the , if any, is already queued on the created child view. Therefore you should not attempt to set the when you are wrapping the child view, as this would again break the parent-child relationship (window.opener on the child page and the window object returned from the window.open call on the parent page, will be rendered invalid) or prevent passing POST data to the server respectively. Also note that since navigation to the , if any, has already started by the moment the child view is wrapped, will not be fired for the main frame of the new instance. Navigation to the , if any, is blocked on the created child view, when and are false. As applications will generally choose to cancel the event and create a new instance to navigate to the target URL (or even choose to navigate to the target URL on the same instance that fired the event), Awesomium.NET does this to prevent false hits to the target URL, that would have occurred by the time the event handler returns and the unused child view instance, is destroyed. What's more, users may also implement and cancel requests to new views that are the result of JavaScript window.open (see ). Therefore, if your application chooses to wrap the created child view even though it is most possibly the result of a user clicking on a link with target="_blank" or navigation to the target URL has already been canceled by an (see ), you should in this scenario only, after wrapping the child view, set the property to to resume navigation to the target URL. Applications can occasionally choose to wrap a child view even when is false or is true, if they want to apply a single process architecture where all new views created will be rendered by the same awesomium_process. When is true, returns a valid, initialized instance. This may be initialized to default values if is false, or reflect the specs specified to the window.open call, if is true. If is true, applications should generally wrap and present the native view in a new popup application window. This window should have the size and location specified in , if this is not empty. They should also respect the rest of the specs available through , when creating the new application window that will host the child view. When is true, is always also true. will only be true, if specs were specified to the window.open call. These can be standard specs such as width=400,height=400,menubar=no, only user defined, non-standard specs such as background=black or a combination of both. These specs are available through the property. If only user defined, non-standard specs were specified to the window.open call, will be true. In this scenario, if your application does not recognize user defined, non-standard specs, it can ignore the value of all together and wrap the new child view in a regular new application window, tab or control. When is true, returns an array of , representing the upload data passed to the using POST. Finally note that only an empty name parameter or a _blank target attribute specified as the name parameter in a window.open call or in a link or form, will fire a event. Other target attributes (such as _top), passed to either a window.open call, a link or a form, are handled by Awesomium internally. Several members of , may not return valid values if Javascript is disabled. For details, read the documentation of: . Given the facts and suggestions presented before, if your application is about to wrap the created child view, the following table shows the methods available, to wrap the created child view using any of the Awesomium.NET web-view components: Technology Method and Notes Core Pass to to wrap the new view with a . For windowed views (see ), you should now assign a . Offscreen views have a assigned by default but depending on your application's design, you may have to assign a new by either monitoring the event, or setting the property. Resize the to match its container. WPF Create a new and assign to the property. Note that you should assign the created child view instance to , before the goes live (see ), or else the will create and wrap a new, underlying web-view instance. The appropriate way to do this, is either by binding the property in XAML (see examples in the Awesomium.NET Samples solution available with the SDK), or by monitoring the event, the last fired before the control goes live. Resize the or its container. Windows Forms Create a new and assign to the property. Note that you should assign the created child view instance to , before the goes live (see ), or else the will create and wrap a new, underlying web-view instance. The appropriate way to do this, is either by assigning the property right after the is created (see examples in the Awesomium.NET Samples solution available with the SDK),or by monitoring the event, the last fired before the control goes live. Resize the or its container. The following example illustrates handling the event in a WPF application that uses controls. In this example, we create a ChildWindow window that hosts a . This window and its hosted will be used to wrap and present the child view passed to , or navigate to the target URL, if is the result of a link with target="_blank".

Below is the XAML of our ChildWindow. ]]> This is the code-behind of the ChildWindow: /// Interaction logic for ChildWindow.xaml /// public partial class ChildWindow : Window { public ChildWindow() { InitializeComponent(); // In this example, ShowCreatedWebView of all WebControls, // is handled by a common handler. webControl.ShowCreatedWebView += App.OnShowNewView; } protected override void OnClosed( EventArgs e ) { base.OnClosed( e ); // Destroy the WebControl and its underlying view. webControl.Dispose(); } // This will be set to the target URL, when this ChildWindow does not // host a created child view. The WebControl, is bound to this property. public Uri Source { get { return this.GetValue( SourceProperty ) as Uri; } set { SetValue( SourceProperty, value ); } } public static readonly DependencyProperty SourceProperty = DependencyProperty.Register( "Source", typeof( Uri ), typeof( ChildWindow ), new UIPropertyMetadata( null ) ); // This will be set to the created child view that the WebControl will wrap, // when ShowCreatedWebView is the result of 'window.open'. The WebControl, // is bound to this property. public IntPtr NativeView { get { return (IntPtr)this.GetValue( ChildWindow.NativeViewProperty ); } internal set { this.SetValue( ChildWindow.NativeViewPropertyKey, value ); } } private static readonly DependencyPropertyKey NativeViewPropertyKey = DependencyProperty.RegisterReadOnly( "NativeView", typeof( IntPtr ), typeof( ChildWindow ), new FrameworkPropertyMetadata( IntPtr.Zero ) ); public static readonly DependencyProperty NativeViewProperty = NativeViewPropertyKey.DependencyProperty; } } ]]> ''' Interaction logic for ChildWindow.xaml ''' Partial Public Class ChildWindow Inherits Window Public Sub New() InitializeComponent() ' In this example, ShowCreatedWebView of all WebControls, ' is handled by a common handler. AddHandler webControl.ShowCreatedWebView, AddressOf App.OnShowNewView End Sub Protected Overrides Sub OnClosed(ByVal e As EventArgs) MyBase.OnClosed(e) ' Destroy the WebControl and its underlying view. webControl.Dispose() End Sub ' This will be set to the target URL, when this ChildWindow does not ' host a created child view. The WebControl, is bound to this property. Public Property Source() As Uri Get Return TryCast(Me.GetValue(SourceProperty), Uri) End Get Set(ByVal value As Uri) SetValue(SourceProperty, value) End Set End Property Public Shared ReadOnly SourceProperty As DependencyProperty = DependencyProperty.Register("Source", GetType(Uri), GetType(ChildWindow), New UIPropertyMetadata(Nothing)) ' This will be set to the created child view that the WebControl will wrap, ' when ShowCreatedWebView is the result of 'window.open'. The WebControl, ' is bound to this property. Public Property NativeView() As IntPtr Get Return CType(Me.GetValue(ChildWindow.NativeViewProperty), IntPtr) End Get Friend Set(ByVal value As IntPtr) Me.SetValue(ChildWindow.NativeViewPropertyKey, value) End Set End Property Private Shared ReadOnly NativeViewPropertyKey As DependencyPropertyKey = DependencyProperty.RegisterReadOnly("NativeView", GetType(IntPtr), GetType(ChildWindow), New FrameworkPropertyMetadata(IntPtr.Zero)) Public Shared ReadOnly NativeViewProperty As DependencyProperty = NativeViewPropertyKey.DependencyProperty End Class End Namespace ]]> Below is the common handler, defined in our object code-behind: /// Interaction logic for App.xaml /// public partial class App : Application { private void Application_Exit( object sender, ExitEventArgs e ) { // Shutdown the Core. WebCore.Shutdown(); } // This static handler, will handle the ShowCreatedWebView event for both the // WebControl of our main application window, as well as for any other windows // hosting WebControls. internal static void OnShowNewView( object sender, ShowCreatedWebViewEventArgs e ) { WebControl webControl = sender as WebControl; if ( webControl == null ) return; if ( !webControl.IsLive ) return; // Create an instance of our application's child window, that will // host the new view instance, either we wrap the created child view, // or we let the WebControl create a new underlying web-view. ChildWindow newWindow = new ChildWindow(); // Treat popups differently. If IsPopup is true, the event is always // the result of 'window.open' (IsWindowOpen is also true, so no need to check it). // Our application does not recognize user defined, non-standard specs. // Therefore child views opened with non-standard specs, will not be presented as // popups but as regular new windows (still wrapping the child view however -- se below). if ( e.IsPopup && !e.IsUserSpecsOnly ) { // JSWindowOpenSpecs.InitialPosition indicates screen coordinates. Int32Rect screenRect = e.Specs.InitialPosition.GetInt32Rect(); // Set the created native view as the underlying view of the // WebControl. This will maintain the relationship between // the parent view and the child, usually required when the new view // is the result of 'window.open' (JS can access the parent window through // 'window.opener'; the parent window can manipulate the child through the 'window' // object returned from the 'window.open' call). newWindow.NativeView = e.NewViewInstance; // Do not show in the taskbar. newWindow.ShowInTaskbar = false; // Set a border-style to indicate a popup. newWindow.WindowStyle = System.Windows.WindowStyle.ToolWindow; // Set resizing mode depending on the indicated specs. newWindow.ResizeMode = e.Specs.Resizable ? ResizeMode.CanResizeWithGrip : ResizeMode.NoResize; // If the caller has not indicated a valid size for the new popup window, // let it be opened with the default size specified at design time. if ( ( screenRect.Width > 0 ) && ( screenRect.Height > 0 ) ) { // Assign the indicated size. newWindow.Width = screenRect.Width; newWindow.Height = screenRect.Height; } // Show the window. newWindow.Show(); // If the caller has not indicated a valid position for the new popup window, // let it be opened in the default position specified at design time. if ( ( screenRect.Y > 0 ) && ( screenRect.X > 0 ) ) { // Move it to the indicated coordinates. newWindow.Top = screenRect.Y; newWindow.Left = screenRect.X; } } else if ( e.IsWindowOpen || e.IsPost ) { // No specs or only non-standard specs were specified, but the event is still // the result of 'window.open', or of an HTML form with tagret="_blank" and method="post". // We will open a normal window but we will still wrap the new native child view, // maintaining its relationship with the parent window. newWindow.NativeView = e.NewViewInstance; // Show the window. newWindow.Show(); } else { // The event is not the result of 'window.open' or of an HTML form with tagret="_blank" // and method="post"., therefore it's most probably the result of a link with target='_blank'. // We will not be wrapping the created view; we let the WebControl hosted in ChildWindow // create its own underlying view. Setting Cancel to true tells the core to destroy the // created child view. // // Why don't we always wrap the native view passed to ShowCreatedWebView? // // - In order to maintain the relationship with their parent view, // child views execute and render under the same process (awesomium_process) // as their parent view. If for any reason this child process crashes, // all views related to it will be affected. When maintaining a parent-child // relationship is not important, we prefer taking advantage of the isolated process // architecture of Awesomium and let each view be rendered in a separate process. e.Cancel = true; // Note that we only explicitly navigate to the target URL, when a new view is // about to be created, not when we wrap the created child view. This is because // navigation to the target URL (if any), is already queued on created child views. // We must not interrupt this navigation as we would still be breaking the parent-child // relationship. newWindow.Source = e.TargetURL; // Show the window. newWindow.Show(); } } } } ]]> ''' Interaction logic for App.xaml ''' Partial Public Class App Inherits Application Private Sub Application_Exit(ByVal sender As Object, ByVal e As ExitEventArgs) ' Shutdown the Core. WebCore.Shutdown() End Sub ' This static handler, will handle the ShowCreatedWebView event for both the ' WebControl of our main application window, as well as for any other windows ' hosting WebControls. Friend Shared Sub OnShowNewView(ByVal sender As Object, ByVal e As ShowCreatedWebViewEventArgs) Dim webControl As WebControl = TryCast(sender, WebControl) If webControl Is Nothing Then Return If Not webControl.IsLive Then Return ' Create an instance of our application's child window, that will ' host the new view instance, either we wrap the created child view, ' or we let the WebControl create a new underlying web-view. Dim newWindow As New ChildWindow() ' Treat popups differently. If IsPopup is true, the event is always ' the result of 'window.open' (IsWindowOpen is also true, so no need to check it). ' Our application does not recognize user defined, non-standard specs. ' Therefore child views opened with non-standard specs, will not be presented as ' popups but as regular new windows (still wrapping the child view however -- se below). If e.IsPopup AndAlso (Not e.IsUserSpecsOnly) Then ' JSWindowOpenSpecs.InitialPosition indicates screen coordinates. Dim screenRect As Int32Rect = e.Specs.InitialPosition.GetInt32Rect() ' Set the created native view as the underlying view of the ' WebControl. This will maintain the relationship between ' the parent view and the child, usually required when the new view ' is the result of 'window.open' (JS can access the parent window through ' 'window.opener'; the parent window can manipulate the child through the 'window' ' object returned from the 'window.open' call). newWindow.NativeView = e.NewViewInstance ' Do not show in the taskbar. newWindow.ShowInTaskbar = False ' Set a border-style to indicate a popup. newWindow.WindowStyle = System.Windows.WindowStyle.ToolWindow ' Set resizing mode depending on the indicated specs. newWindow.ResizeMode = If(e.Specs.Resizable, ResizeMode.CanResizeWithGrip, ResizeMode.NoResize) ' If the caller has not indicated a valid size for the new popup window, ' let it be opened with the default size specified at design time. If (screenRect.Width > 0) AndAlso (screenRect.Height > 0) Then ' Assign the indicated size. newWindow.Width = screenRect.Width newWindow.Height = screenRect.Height End If ' Show the window. newWindow.Show() ' If the caller has not indicated a valid position for the new popup window, ' let it be opened in the default position specified at design time. If (screenRect.Y > 0) AndAlso (screenRect.X > 0) Then ' Move it to the indicated coordinates. newWindow.Top = screenRect.Y newWindow.Left = screenRect.X End If ElseIf (e.IsWindowOpen OrElse e.IsPost) Then ' No specs or only non-standard specs were specified, but the event is still ' the result of 'window.open' or of an HTML form with tagret="_blank" and method="post". ' We will open a normal window but we will still wrap the new native child view, ' maintaining its relationship with the parent window. newWindow.NativeView = e.NewViewInstance ' Show the window. newWindow.Show() Else ' The event is not the result of 'window.open' or of an HTML form with tagret="_blank" ' and method="post"., therefore it's most probably the result of a link with target='_blank'. ' We will not be wrapping the created view; we let the WebControl hosted in ChildWindow ' create its own underlying view. Setting Cancel to true tells the core to destroy the ' created child view. ' ' Why don't we always wrap the native view passed to ShowCreatedWebView? ' ' - In order to maintain the relationship with their parent view, ' child views execute and render under the same process (awesomium_process) ' as their parent view. If for any reason this child process crashes, ' all views related to it will be affected. When maintaining a parent-child ' relationship is not important, we prefer taking advantage of the isolated process ' architecture of Awesomium and let each view be rendered in a separate process. e.Cancel = True ' Note that we only explicitly navigate to the target URL, when a new view is ' about to be created, not when we wrap the created child view. This is because ' navigation to the target URL (if any), is already queued on created child views. ' We must not interrupt this navigation as we would still be breaking the parent-child ' relationship. newWindow.Source = e.TargetURL ' Show the window. newWindow.Show() End If End Sub End Class End Namespace ]]> For the complete sample, see the C# WebControlSample of the Awesomium.NET Samples solution, available with the SDK.

The associated will be terminated when this instance is disposed and destroyed.

The default priority of the , is . This may be automatically lowered to when is false. In a technology-specific WebControl, and the priority of the , are associated to the control's enabled status. Actions that may corrupt the execution state of the rendering process, will directly affect view's web content rendering. Manually killing this process, will mark the view as crashed (see ).