Popup Popup Popup Class

Displays content on top of existing content, within the bounds of the application window.

Syntax

Declaration

public sealed class Popuppublic sealed class PopupPublic NotInheritable Class Popup
<Popup .../>

Inheritance Hierarchy

Inherited Members

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

Do not use a Popup if a Flyout, MenuFlyout, ToolTip or MessageDialog is more appropriate.

Popup is a general purpose container for hosting UIElement s on top of existing content. You typically use a Popup to temporarily display content that accomplishes a particular task. The Popup does not have a default visual template. Instead, you must set the content yourself by specifying a single Child element as content. You can define the Popup content inline, but it's common to define the content as a UserControl, and then set the UserControl as the Child of the Popup.

You position the Popup by setting the HorizontalOffset and VerticalOffset properties. The Popup is offset relative to its immediate parent container. A Popup is not modal, so input to the screen behind it is not blocked.

To show a Popup, set its IsOpen property to true. To hide the Popup, set IsOpen to false. You can set IsLightDismissEnabled to make the Popup hide automatically when a user taps anywhere away from it.

The Popup can host input controls. When hosting input controls like TextBox, the touch keyboard might slide into view when the user touches the input control. If the Popup 's parent container is already in the visual tree, the Popup automatically repositions itself when the touch keyboard is in view. Otherwise, the Popup is not repositioned and the touch keyboard can cover it. This can happen if you create the Popup in code and set IsOpen to true without adding the Popup as a child of an element in the visual tree.

For more code examples that show the Popup control, see the XAML Popup sample.

Examples

This example shows a simple Popup with content defined inline.

<Grid x:Name="Output" HorizontalAlignment="Left" VerticalAlignment="Top" Grid.Row="1">
    <StackPanel>
        <Button Content="Show Popup (using Offset)" Click="ShowPopupOffsetClicked"/>
    </StackPanel>
    <Popup VerticalOffset="10" HorizontalOffset="200" x:Name="StandardPopup">
        <Border BorderBrush="{StaticResource ApplicationForegroundThemeBrush}" 
                Background="{StaticResource ApplicationPageBackgroundThemeBrush}"
                BorderThickness="2" Width="200" Height="200">
            <StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
                <TextBlock Text="Simple Popup" FontSize="24.667" HorizontalAlignment="Center"/>
                <Button Content="Close" Click="ClosePopupClicked" HorizontalAlignment="Center"/>
            </StackPanel>
        </Border>
    </Popup>
</Grid>
// Handles the Click event on the Button inside the Popup control and 
// closes the Popup. 
private void ClosePopupClicked(object sender, RoutedEventArgs e)
{
    // if the Popup is open, then close it 
    if (StandardPopup.IsOpen) { StandardPopup.IsOpen = false; }
}

// Handles the Click event on the Button on the page and opens the Popup. 
private void ShowPopupOffsetClicked(object sender, RoutedEventArgs e)
{
    // open the Popup if it isn't open already 
    if (!StandardPopup.IsOpen) { StandardPopup.IsOpen = true; }
}

This example shows a Popup that has a UserControl set as its Child element. The UserControl defines the content of the Popup.

<Popup x:Name="ParentedPopup" HorizontalOffset="200" VerticalOffset="200">
    <local:PopupInputContent/>
</Popup>
<UserControl
    x:Class="XAMLPopup.PopupInputContent"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:PopupExample"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DesignHeight="300"
    d:DesignWidth="400">
    <Grid>
        <StackPanel>
            <TextBlock Text="Type some input" FontSize="24.667"/>
            <TextBox Width="300" Height="55"/>
            <Button Content="Save" Click="SimulateSaveClicked"/>
        </StackPanel>
    </Grid>
</UserControl>
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Controls.Primitives;

namespace XAMLPopup
{
    public sealed partial class PopupInputContent : UserControl
    {
        public PopupInputContent()
        {
            this.InitializeComponent();
        }

        // Handles the Click event of the 'Save' button simulating a save and close 
        private void SimulateSaveClicked(object sender, RoutedEventArgs e)
        {
            // in this example we assume the parent of the UserControl is a Popup 
            Popup p = this.Parent as Popup;

            // close the Popup
            if (p != null) { p.IsOpen = false; }  
        } 
    }
}

Constructors summary

Initializes a new instance of the Popup class.

Properties summary

Gets or sets the content to be hosted in the popup.

Gets the identifier for the Child dependency property.

Gets or sets the collection of Transition style elements that apply to child content of a Popup.

Identifies the ChildTransitions dependency property.

Gets or sets the distance between the left side of the application window and the left side of the popup.

Gets the identifier for the HorizontalOffset dependency property.

Gets or sets a value that determines how the Popup can be dismissed.

Identifies the IsLightDismissEnabled dependency property.

Gets or sets whether the popup is currently displayed on the screen.

Gets the identifier for the IsOpen dependency property.

Gets or sets a value that specifies whether the area outside of a light-dismiss UI is darkened.

Identifies the LightDismissOverlayMode dependency property.

Gets or sets the distance between the top of the application window and the top of the popup.

Gets the identifier for the VerticalOffset dependency property.

Events summary

Fires when the IsOpen property is set to false.

Fires when the IsOpen property is set to true.

Constructors

  • Popup()
    Popup()
    Popup()
    Popup()

    Initializes a new instance of the Popup class.

    public Popup()public Popup()Public Function Popup() As

Properties

  • Child
    Child
    Child
    Child

    Gets or sets the content to be hosted in the popup.

    public UIElement Child { get; set; }public UIElement Child { get; set; }Public ReadWrite Property Child As UIElement
    <Popup ...>
      singleChild
    </Popup>
    

    Property Value

  • ChildProperty
    ChildProperty
    ChildProperty
    ChildProperty

    Gets the identifier for the Child dependency property.

    public static DependencyProperty ChildProperty { get; }public static DependencyProperty ChildProperty { get; }Public Static ReadOnly Property ChildProperty As DependencyProperty

    Property Value

  • ChildTransitions
    ChildTransitions
    ChildTransitions
    ChildTransitions

    Gets or sets the collection of Transition style elements that apply to child content of a Popup.

    public TransitionCollection ChildTransitions { get; set; }public TransitionCollection ChildTransitions { get; set; }Public ReadWrite Property ChildTransitions As TransitionCollection
    <Popup>
      <Popup.ChildTransitions>
        <TransitionCollection>
          oneOrMoreTransitions
        </TransitionCollection>
      </Popup.ChildTransitions>
    </Popup>
    

    Property Value

    Remarks

    Important

    The XAML syntax for all properties that use a TransitionCollection value is unusual in that you must declare an explicit TransitionCollection object element as the value, and then provide object elements as child elements of TransitionCollection for each of the transition animations you want to use. For most other XAML collection properties you could omit the collection object element because it can be implicit, but properties that use TransitionCollection don't support the implicit collection usage. For more info on implicit collections and XAML, see XAML syntax guide.

    Transition animations play a particular role in UI design of your app. The basic idea is that when there is a change or transition, the animation draws the attention of the user to the change.

    It's not common to set the value of the ChildTransitions property directly on a Popup that is a direct element of app UI. It's more common to have a transitions collection be a part of a visual state, template or style. In this case you use mechanisms such as Setter of a Style to specify the ChildTransitions property. Styles are typically stored as a XAML resource.

  • ChildTransitionsProperty
    ChildTransitionsProperty
    ChildTransitionsProperty
    ChildTransitionsProperty

    Identifies the ChildTransitions dependency property.

    public static DependencyProperty ChildTransitionsProperty { get; }public static DependencyProperty ChildTransitionsProperty { get; }Public Static ReadOnly Property ChildTransitionsProperty As DependencyProperty

    Property Value

  • HorizontalOffset
    HorizontalOffset
    HorizontalOffset
    HorizontalOffset

    Gets or sets the distance between the left side of the application window and the left side of the popup.

    public double HorizontalOffset { get; set; }public double HorizontalOffset { get; set; }Public ReadWrite Property HorizontalOffset As double
    <Popup HorizontalOffset="double"/>
    

    Property Value

    • double
      double
      double

      A measurement in pixels.

  • HorizontalOffsetProperty
    HorizontalOffsetProperty
    HorizontalOffsetProperty
    HorizontalOffsetProperty

    Gets the identifier for the HorizontalOffset dependency property.

    public static DependencyProperty HorizontalOffsetProperty { get; }public static DependencyProperty HorizontalOffsetProperty { get; }Public Static ReadOnly Property HorizontalOffsetProperty As DependencyProperty

    Property Value

  • IsLightDismissEnabled
    IsLightDismissEnabled
    IsLightDismissEnabled
    IsLightDismissEnabled

    Gets or sets a value that determines how the Popup can be dismissed.

    public bool IsLightDismissEnabled { get; set; }public bool IsLightDismissEnabled { get; set; }Public ReadWrite Property IsLightDismissEnabled As bool
    <Popup IsLightDismissEnabled="bool" />
    

    Property Value

    • bool
      bool
      bool

      true if light dismiss is enabled for this control; otherwise, false.

    Remarks

    Light dismiss is when the user taps on any area other than the popup.

  • IsLightDismissEnabledProperty
    IsLightDismissEnabledProperty
    IsLightDismissEnabledProperty
    IsLightDismissEnabledProperty

    Identifies the IsLightDismissEnabled dependency property.

    public static DependencyProperty IsLightDismissEnabledProperty { get; }public static DependencyProperty IsLightDismissEnabledProperty { get; }Public Static ReadOnly Property IsLightDismissEnabledProperty As DependencyProperty

    Property Value

  • IsOpen
    IsOpen
    IsOpen
    IsOpen

    Gets or sets whether the popup is currently displayed on the screen.

    public bool IsOpen { get; set; }public bool IsOpen { get; set; }Public ReadWrite Property IsOpen As bool
    <Popup IsOpen="bool" />
    

    Property Value

    • bool
      bool
      bool

      true if the popup is currently displayed; otherwise, false. The default is false.

  • IsOpenProperty
    IsOpenProperty
    IsOpenProperty
    IsOpenProperty

    Gets the identifier for the IsOpen dependency property.

    public static DependencyProperty IsOpenProperty { get; }public static DependencyProperty IsOpenProperty { get; }Public Static ReadOnly Property IsOpenProperty As DependencyProperty

    Property Value

  • LightDismissOverlayMode
    LightDismissOverlayMode
    LightDismissOverlayMode
    LightDismissOverlayMode

    Gets or sets a value that specifies whether the area outside of a light-dismiss UI is darkened.

    public LightDismissOverlayMode LightDismissOverlayMode { get; set; }public LightDismissOverlayMode LightDismissOverlayMode { get; set; }Public ReadWrite Property LightDismissOverlayMode As LightDismissOverlayMode

    Property Value

    Remarks

    Transient UI, such as a Popup, closes when you click or tap outside of it. This is called light-dismiss. "Overlay" refers to the area outside of a light-dismiss UI.

    By default, the "overlay" is darkened on the Xbox, and not darkened on other devices families. You can set LightDismissOverlayModeProperty to On to make your app darken the "overlay" area on all device families, or set it to Off to not darken the "overlay" area on all device families.

  • LightDismissOverlayModeProperty
    LightDismissOverlayModeProperty
    LightDismissOverlayModeProperty
    LightDismissOverlayModeProperty

    Identifies the LightDismissOverlayMode dependency property.

    public static DependencyProperty LightDismissOverlayModeProperty { get; }public static DependencyProperty LightDismissOverlayModeProperty { get; }Public Static ReadOnly Property LightDismissOverlayModeProperty As DependencyProperty

    Property Value

  • VerticalOffset
    VerticalOffset
    VerticalOffset
    VerticalOffset

    Gets or sets the distance between the top of the application window and the top of the popup.

    public double VerticalOffset { get; set; }public double VerticalOffset { get; set; }Public ReadWrite Property VerticalOffset As double
    <Popup VerticalOffset="double"/>
    

    Property Value

    • double
      double
      double

      A measurement in pixels.

  • VerticalOffsetProperty
    VerticalOffsetProperty
    VerticalOffsetProperty
    VerticalOffsetProperty

    Gets the identifier for the VerticalOffset dependency property.

    public static DependencyProperty VerticalOffsetProperty { get; }public static DependencyProperty VerticalOffsetProperty { get; }Public Static ReadOnly Property VerticalOffsetProperty As DependencyProperty

    Property Value

Events

  • Closed
    Closed
    Closed
    Closed

    Fires when the IsOpen property is set to false.

    public event EventHandler Closedpublic event EventHandler ClosedPublic Event Closed
    <Popup Closed="eventhandler"/>
    
  • Opened
    Opened
    Opened
    Opened

    Fires when the IsOpen property is set to true.

    public event EventHandler Openedpublic event EventHandler OpenedPublic Event Opened
    <Popup Opened="eventhandler"/>
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.UI.Xaml.Markup.ContentPropertyAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.ActivatableAttribute

Details

Assembly

Windows.UI.Xaml.Controls.Primitives.dll