NotificationWindow Class

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

Represents a notification area that is displayed in the system area. Notifications can only be enabled for an out-of-browser application; browser-hosted applications cannot access this notification area.

Inheritance Hierarchy

System.Object
  System.Windows.DependencyObject
    System.Windows.NotificationWindow

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

Syntax

'Declaration
Public NotInheritable Class NotificationWindow _
    Inherits DependencyObject

public sealed class NotificationWindow : DependencyObject

The NotificationWindow type exposes the following members.

Constructors

	Name	Description
	NotificationWindow	Initializes a new instance of the NotificationWindow class.

Top

Properties

	Name	Description
	Content	Gets or sets the root of visual elements that define the visual look of the notification.
	Dispatcher	Gets the Dispatcher this object is associated with. (Inherited from DependencyObject.)
	Height	Gets or sets the height, in pixels, of this notification window. See Remarks.
	Visibility	Gets a value that determines whether this notification is currently being displayed.
	Width	Gets or sets the width, in pixels, of this notification window. See Remarks.

Top

Methods

	Name	Description
	CheckAccess	Determines whether the calling thread has access to this object. (Inherited from DependencyObject.)
	ClearValue	Clears the local value of a dependency property. (Inherited from DependencyObject.)
	Close	Immediately closes the notification window.
	Equals(Object)	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
	GetAnimationBaseValue	Returns any base value established for a Silverlight dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject.)
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	GetValue	Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	ReadLocalValue	Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject.)
	SetValue	Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject.)
	Show	Displays the notification window for the specified number of milliseconds before it times out.
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Events

	Name	Description
	Closed	Occurs when Close is called, or when the notification window times out and has finished its fadeout animation.

Top

Fields

	Name	Description
	ContentProperty	Identifies the Content dependency property.
	HeightProperty	Identifies the Height dependency property.
	WidthProperty	Identifies the Width dependency property.

Top

Remarks

A notification is a UI area that is displayed for a period of time and then closes automatically even if no user interaction occurs. Systems that implement notifications typically have them display in a fixed, particular area of the UI. An alternative colloquial term for notifications that is used by some programmers is toast.

Notifications are exclusively for use in an out-of-browser application scenario for Silverlight 4. The out-of-browser installation or startup experience indicate to a user that an application is now running in the context of the local client computer, rather than as a Web site with Silverlight content. For more information about out-of-browser installation or startup, see Out-of-Browser Support.

Similar to Popup, content of a notification window is not part of the primary Silverlight visual tree, it effectively is described by a separate visual tree that is rendered and added to the content area. For purposes of XAML namescope resolution, a notification window's objects exists in a separate XAML namescope.

Using Popup within a notification window is not supported.

You must set Height and Width on a notification window before Show is called and the notification displays. Attempting to set the height/width of a displayed notification throws an exception. You may want to check Visibility first to avoid the exception.

User Interaction with a Notification Window

Content within a notification cannot receive keyboard focus or process keyboard events. Conceptually, the content of a notification should be thought of as read-only. Typically, the user sees the notification but knows that it will eventually time out without requiring input.

Content within a notification can receive mouse or stylus input, and can process mouse events. You can handle these input events to bring the main application window into focus, by calling Window.Activate. This is for a scenario where the user has switched to another application and the application that owns the notification is not the topmost window.

The input events from a notification window are not considered to be user-initiated for purpose of certain Silverlight features that require explicit user initiation. Examples of features that require user initiation and thus cannot be invoked from notification window UI include: navigating from a HyperlinkButton; displaying SaveFileDialog or OpenFileDialog; accessing the system clipboard; changing to full-screen mode. Calling Window.Activate is essentially the only privileged action that can be initiated from an input event handler for notification window content.

Notification Positioning and Dimensions

When Show is called, the notification is positioned so that the lower-right corner of the notification content area is (-44,-44) pixels offset from the lower right of the workspace dimensions of the primary monitor. The Height and Width add to the window dimensions in the up and left directions, respectively, starting from the lower-right positioning point.

Multiple Notifications

NotificationWindow API does not directly support queue or render logic for multiple notifications. If your application calls Show again on a second notification window instance while the previous notification is still displayed, an exception is thrown from Show. You can potentially design your own queue logic so that you can handle multiple notifications by staggering the notifications. Or you could display a dedicated notification that states that multiple notifications want to display and then use an alternative UI for the multiple-notification case.

Although only one notification window is permitted per application, it is possible that multiple Silverlight out-of-browser applications are running simultaneously, and each shows a notification window. In this case, the notifications appear in the same place but can overlap, with the most recently shown notification on top.

Examples

The following example code illustrates the various aspects of creating and displaying a notification window.

This code illustrates creating a new NotificationWindow and setting properties as part of its containing page's initialization, then calling Show from a helper method.

• The reference to nwContent refers to a constructor call to a custom UserControl "page" that is defined in the same project as a Page build action. The UserControl defines the root of UI content that the notification displays.

• Note how the NotificationWindow Height and Width are based on the nwContentUserControl dimensions. This is a good technique for maintaining code-design separation, but make sure that the UI design does not exceed the 400-width, 100-height limits imposed by the NotificationWindow API.

• Note the check against IsRunningOutOfBrowser wrapping all NotificationWindow API calls.

• The NextNotify method is invoked one time for the initial application load, mainly for illustration. Otherwise, it would be invoked whenever application logic determines an additional notification should display.

• Note how NextNotify uses a simple technique to close the visible window before it tries to display again, in order to avoid exceptions from multiple notifications trying to show.

• This particular design keeps reusing the same NotificationWindow instance nw. This is appropriate because there can only be one NotificationWindow displayed at a time. An alternative technique is to create different NotificationWindow instances with different content, but to keep track of them in a list to make sure you do not show more than one at a time.

• Note the call to DataContext. This particular notification design uses a single Content definition by the nwContent UserControl, and that design incorporates two TextBlock areas with data-bound Text. By changing the data context prior to each Show call to point to new business objects, you have a lightweight technique for changing the text in each notification shown, which is based on the data binding feature of Silverlight.

public MainPage()
{
...
  if (App.Current.IsRunningOutOfBrowser) {
      nw = new NotificationWindow();
      nw.Content = nwContent;
      nw.Height = nwContent.Height;
      nw.Width = nwContent.Width;
      NextNotify();
  }
...
}

private void NextNotify()
{
    if (nw.Visible)
        nw.Close();
    nw.Content.DataContext = list[count];
    nw.Show(5000);
    App.Current.MainWindow.Activate();
}

Version Information

Silverlight

Supported in: 5, 4

Platforms

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

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

System.Windows Namespace

Application

Window

Other Resources

Out-of-Browser Support