Table of Contents
Table of Contents
Handling New Window

A WebView may need to open a new browser window. For example:

  • When JavaScript code calls window.open method;
  • When user clicks a link whose target is set to a window name;

In both cases, the existing WebView will create a new WebView instance, then raises NewWindow event. The newly created WebView object is available through the event argument's WebView property.

Inside the event handler, you can:

  • Do nothing. If you do nothing, or do not handle this event at all, the newly created WebView object will be destroyed and new window will not be opened;

  • Keep and display the newly created WebView object. For example, the TabbedBrowser sample application creates a new tab to host the new WebView object. If you choose this option, you must also set Accepted to true. Below is the source code in the TabbedBrowser sample application that accepts the new WebView:

    Copy 
    //The new WebView has already been created (e.WebView). Here we
//associates it with a new WebViewItem object and creates a
//new tab button for it (by adding it to m_Pages)
WebViewItem item = NewWebViewItem(e.WebView);
m_WebViewsHost.Items.Add(item);
m_Pages.Add(item.Page);

//Select the newly created tab
mainTabs.SelectedIndex = m_Pages.Count - 1;

//Signifies that we accept the new WebView. Without this line
//the newly created WebView will be immediately destroyed
e.Accepted = true;

    If you use Windows.Forms, the following code demonstrates the basic concept of handling this event:

    Copy 
    //Step 1:
//Create a new Form with a blank WebControl
//This new Form is the popup window
Form form1 = new Form();
EO.WinForm.WebControl webControl = new EO.WinForm.WebControl();
webControl.Dock = DockStyle.Fill;
form1.Controls.Add(webControl);

//Step 2:
//Put the new WebView (created by the browser engine)
//in the new blank WebControl
webControl.WebView = e.WebView;

//Step 3:
//Display the new Form
form1.Show();

//Step 4:
//Notify the browser engine that you "accept" (and display)
//the popup
e.Accepted = true;

    The above code creates a new Form and display the new WebView inside the Form. You can customize step 1 and step 3 to your own need. For example, instead of creating a new Form in step 1 and display it in step 3, you can create a new tab in step 3 and switch to that tab in step 3 --- similar to what the TabbedBrowser sample application does.

    Note: do not call any blocking functions such as ShowDialog inside this event handler. Your event handling code must return to the browser engine as soon as possible so that it can continue to load (or discard) the new page.

    A common mistake in handling this event is to create a new WebView to load the Url. For example:

    Copy 
    //Assume BrowserWnd (in your code) is a Window class that contains a 
//WebView. Here the code creates a new BrowserWnd object thus creating 
//a new WebView
BrowserWnd wnd = new BrowserWnd();

//Load the target Url into the new WebView
wnd.WebView.Url = e.TargetUrl;

//Signifies that we accept the new window request
e.Accepted = true;

    The above code is wrong because it created a new WebView instead of just "accepting" the internally created WebView object passed to the event handler through e.WebView. If you wish to accept the new window request, you must "accept" this internally created WebView instead of creating your own. Only this internally created WebView is associated to the original WebView that triggered the NewWindow event. Any WebView you created in your code will not be associated to the original WebView. Since the above code has set e.Accepted to true, the browser engine will be waiting for e.WebView to be initialized (which would occur when it is displayed) before proceeding further. Since the above code did not perform any action that would result in e.WebView to be initialized, the above code would cause the browser engine to hang.

In addition to handling NewWindow event, you usually also need to handle Activate event. This event is raised when a WebView needs to be the active view. For example:

  • Right after NewWindow event, the newly created WebView needs to be activated;
  • When user click a link in another WebView, but the link's target points to this WebView;

Note that in case a new WebView is created when NewWindow event occurs, the NewWindow event occurs on the "opener" WebView, the Activate event occurs after the NewWindow event, but on the newly opened WebView.

You can find sample code for handling this event in the TabbedBrowser sample application. When this event is raised, the TabbedBrowser sample application handles this event and creates a new tab to display the new page.