Share via

  • Article

HtmlPage.PopupWindow Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Opens a pop-up window.

Namespace:  System.Windows.Browser
Assembly:  System.Windows.Browser (in System.Windows.Browser.dll)

Syntax

'Declaration
<SecuritySafeCriticalAttribute> _
Public Shared Function PopupWindow ( _
    navigateToUri As Uri, _
    target As String, _
    options As HtmlPopupWindowOptions _
) As HtmlWindow

[SecuritySafeCriticalAttribute]
public static HtmlWindow PopupWindow(
    Uri navigateToUri,
    string target,
    HtmlPopupWindowOptions options
)

Parameters

  • navigateToUri
    Type: System.Uri
    Specifies the Uniform Resource Identifier (URI) for the pop-up window.
  • target
    Type: System.String
    Specifies the window that will be opened. (For more information, see the Remarks section.)

Return Value

Type: System.Windows.Browser.HtmlWindow
A handle to the new window; or nulla null reference (Nothing in Visual Basic) (see the Remarks section).

Exceptions

Exception Condition
ArgumentException

navigateToUri specifies a protocol other than http or https, such as file://, or a random URI moniker.
ArgumentNullException

navigateToUri is set to nulla null reference (Nothing in Visual Basic).

Remarks

This method is intended as a simple way for site authors to host cross-domain advertising content that needs to pop up a window when the user clicks the content. Therefore, this method provides a constrained way to trigger pop-up windows while bypassing the browser's pop-up blockers. This method is also available for developers who are running Silverlight-based applications from the same domain and who want to reliably create pop-up windows without triggering pop-up blockers.

Constraints

This method temporarily turns off the browser's pop-up blockers. Therefore, additional constraints exist for this method to run:

  • The AllowHtmlPopupWindow property must be set to true on the Silverlight plug-in.

  • The call to PopupWindow must be triggered by a user-initiated click on a visible area of the hosting Silverlight plug-in.

  • PopupWindow can be called only once per interactive user event. This prevents the display of multiple pop-ups during the course of a single click on the Silverlight plug-inl.

Call the IsPopupWindowAllowed property to determine whether the above constraints are met.

Behaviors and Return Values

This method returns an HtmlWindow handle to the new window if the following requirements are met:

  • The EnableHtmlAccess property is set to true.

  • IsPopupWindowAllowed returns true.

  • The browser's security settings do not block the underlying JavaScript window.open call.

The method returns nulla null reference (Nothing in Visual Basic) if any of the previous requirements are not met.

The Pop-up Window Target

The target of the window navigation differs depending on whether the Silverlight-based application has been granted HTML access (either through the EnableHtmlAccess property or the IsEnabled property). Empty strings and nulla null reference (Nothing in Visual Basic) are allowable values for the target parameter.

  • If EnableHtmlAccess is set to true, both nulla null reference (Nothing in Visual Basic) and non- null values of target are passed to the browser.

  • If EnableHtmlAccess is set to false, "_blank" is used as the target of the new window.

Customizing the Target Window

You can customize the target window by optionally supplying a HtmlPopupWindowOptions reference in the options parameter. If nulla null reference (Nothing in Visual Basic) is passed for options, the internal call to the JavaScript window.open function will not supply any value for the window features, and the new window's settings will be set to the browser defaults.

If you specify options, the following additional constraints on the window size are imposed:

  • To prevent displaying a pop-up window that overlays the entirety of a user's desktop window, this method internally decreases the pop-up's height to 250 pixels less than the available screen height, and the pop-up's width to 200 pixels less than the available screen width of the user's desktop. In Internet Explorer, the available screen height and width can be found by using the Document Object Model (DOM) navigator.screen.availHeight and navigator.screen.availWidth properties.

  • To prevent displaying a pop-up window that appears off-screen, the method internally reduces the pop-up's top coordinate to 100 pixels less than the maximum top coordinate of the screen, and the pop-up's left coordinate to 100 pixels less than the maximum left coordinate of the screen. Therefore, if the top and left values are both set to off-screen coordinates, this method internally changes the coordinates of the new window so that it is displayed in the lower-right corner of the screen with width and height set to 100 pixels each.

Also, the browser has minimum height and width values that prevent the display of arbitrarily small windows.

Browser Considerations

In Internet Explorer, the browser's pop-up blocker must be configured to Medium or lower.

In Firefox (Windows and Macintosh), pop-up windows are available with the default Firefox security settings.

In Safari, pop-up windows are not available.

Version Information

Silverlight

Supported in: 5, 4, 3

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.