Control Control Control Class

Represents the base class for UI elements that use a ControlTemplate to define their appearance. Parent class for ContentControl, UserControl, ItemsControl and several practical controls.

Syntax

Declaration

public class Controlpublic class ControlPublic Class Control

Inheritance Hierarchy

Inherited Members

Inherited properties

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

Inherited events

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited methods

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

The Control class is the base class for many of the controls you add to an app and its UI. The Control class defines very little behavior; you can add an actual Control element to XAML for UI but you typically add something that inherits from Control directly or indirectly, such as a Button or ListBox. For a list of controls you can use, see Controls by function.

The Template property, which uses the type ControlTemplate, specifies the visual appearance of a control. If you want to change the appearance of a control but retain its functionality, you should consider creating a new ControlTemplate instead of defining a new Control -based class. For more info, see Quickstart: Control templates.

Control is the parent of UserControl. UserControl is the intended base class for lightweight controls that don't need visual states. Although the UserControl technically inherits the Template property, you cannot apply a template to a UserControl.

Implicit styles for controls

Each practical control that's defined for XAML has a default style that contains its default control template. Controls can have an implicit style, meaning that the Style property isn't set explicitly. Once that implicit style is available, almost all other properties of a control can be set with Setter elements in that Style. The Style can initialize the control separately from the rest of the control logic, and can set values that aren't the code-based defaults for each property.

The implicit style exists as a keyed resource that's part of the Windows Runtime, stored internally as a binary representation of XAML. You can get a copy of either a particular control's style or of the full set of styles to look at how the styles and control templates are defined.

The association between a particular control type and the key/name of the implicit style it uses by default is established by the value of the DefaultStyleKey property. The DefaultStyleKey property is protected, so only someone that subclasses a control class can change the value. If you're just creating a control instance, for example declaring controls in a XAML UI, then the default style is the implicit style that's based on the control's type. For more info, see Remarks in DefaultStyleKey. You don't need to change the DefaultStyleKey value to use a different style, you just need to define your own XAML Style that has the same TargetType that matches the implicit style lookup and exists as a XAML resource. For more info, see Quickstart: Control templates.

The visual state model

The visual state model is a technique where you modify just a few of the properties defined in a control's template. You change property values in order to provide visual feedback to the user that indicates what the control is doing and hints at further UI interactions that are possible. The controls are modified by applying zero-duration or short-duration storyboarded animations to some of the properties in the template. You also can define short-duration animations that apply for the transitions between states.

The visual states themselves are defined as part of the control template. Each visual state has a name, so that the control logic can invoke the GoToState(Control, String, Boolean) method that loads up each visual state when it's needed for a particular logic state. Visual states are declared within visual state groups, so that visual states that are exclusive to each other can ensure that only one such state is active at a time. As soon as another visual state from the same group is loaded, the animations for the previous state stop being applied, but animations in another group might still be running and applying their changes and visual behavior. For example, a control might have a visual indicator for keyboard focus and a visual indicator for pointer-over. Because these are UI modes that can be adjusted independently of each other and can happen at the same time, they're each defined in a different visual state group.

Because it's defined in XAML as part of the control template, you can change the visual state behavior for any XAML control that you use in your UI. However, the logic is still based on the control expecting to find certain visual state groups and named visual states within. So you have to be very careful that you're providing the correctly named and structured visual states that are showing all aspects of a control's behavior to the user. For more info, see Storyboarded animations for visual states. Visual states are also briefly introduced in Quickstart: Control templates.

Default visual states for controls sometimes use the library animations. You should try to preserve the library animations when you replace control templates or visual states because these animations are an important part of the control's look and feel in the UI. For more info, see Animations overview.

Controls and focus

The Control class defines several API that influence the keyboard focus behavior for a UI: the Focus(FocusState) method, the FocusState property, and the IsEnabled and IsTabStop properties. Enabling keyboard focus is an important part of assuring that a UI is accessible, because each focusable element becomes part of the tab order for the UI. Only UI elements that are interactive are typically enabled to receive keyboard focus. For example, a TextBox is interactive because the user can type text, whereas a TextBlock is not interactive because the text is read-only. Most of the classes that derive from Control are legitimately interactive and so it makes sense that they can be focused and should be in the tab order.

In order to be focusable, each of these must be true:

  • Visibility is Visible
  • IsEnabled is true
  • IsTabStop is true
  • The control must be instantiated with its template loaded (Loaded fired, control connected to app's root visual) If you want a control to not be focusable, you can set IsTabStop to false. However, if the reason you don't want the control to have focus is because it's not interactive in your UI, you might want to set IsEnabled to false to make the lack of interaction obvious to everyone. Many controls have predefined visual states that are invoked for IsEnabled =false, such as "graying out" text in labels.

Focus changes can fire GotFocus or LostFocus events. Although the "FocusedElement" value (exposed via GetFocusedElement method) is updated immediately, the change notifications of GotFocus or LostFocus occur asynchronously. This asynchronous focusing design is intended to avoid flickering on visual state transitions when control logic reacts to focus change too quickly.

The Focus(FocusState) method enables bringing keyboard focus to a control programmatically. Be judicious when calling this method, it can be intrusive to move the keyboard focus when the user doesn't expect it. The main scenarios for Focus(FocusState) are either setting the very first keyboard focus point when an entire page of UI is loaded, or setting focus to a specific part of a control once the parent control container has received top-level focus (like focusing the textbox in a combobox). For more info, see Focus(FocusState). FocusState tracks whether focus is programmatic or user-driven, which makes a difference for visual states, notably the visual focus indicator for keyboard focus that all controls should have.

On* event handler overrides

Each On* method represents a prewired event handler for the corresponding UIElement event. Practical controls that derive from Control can override the On* method and use this to provide control-specific handling and behavior for that input event. The most common scenario is to use the event handler to mark the event as Handled in the event data. The control code has first chance to handle this event, before any event handlers that are wired on a control instance are invoked. When the event data is marked Handled, then other handlers like those on the control instance won't be called. Also, the event won't bubble.

As it's implemented directly on Control, the On* method has an empty implementation. But each ancestor in a control's hierarchy may have provided an implementation. You won't be able to see this implementation because it's internal native code. In some cases a control will already have existing On* overrides that mark the event Handled. Once you've provided an initial On* override for a control, then any controls that you further derive from your own control class would also inherit the On* overrides you define. Any instances you use have that behavior too.

Note

App code can still handle events that may have been marked Handled by a control's On* method logic, but they need to use the handledEventsToo parameter for the AddHandler(RoutedEvent, Object, Boolean) method. For more info, see AddHandler(RoutedEvent, Object, Boolean) or Events and routed events overview.

The Control class defines several protected virtual methods that are each associated with a framework-level input event. These methods are intended to provide a pre-wired event handler for input events such that a control can enforce that certain input behaviors are used by that control and all instances of it. For example, there's a PointerPressed event defined by UIElement. Control defines the OnPointerPressed(PointerRoutedEventArgs) method, with an empty definition. Within the base @Windows.UI.Xaml.Controls.Control.#ctor constructor, event wiring for all the relevant input events includes the On* method as a listener/handler, which initially does nothing. But all it takes now for you as the control author to change the behavior for an input event is to give a new override definition for an On* method (also, make sure your constructor calls base). That behavior gets inherited to all instances or subclasses, unless another subclasser overrides it again. Because the On* events are first in sequence, before any UI definition XAML, they can adjust the event data and potentially change the conditions that other listeners see about the event.

The existing On* definitions in a particular control class can affect you as the consumer of the control even if you haven't overridden any On* methods yourself. This is because the existing On* definitions may have provided handling for an event that sets a Handled property value to false in some event's event data. That will prevent your instance-based event handling from even seeing the event, and will prevent your handler from being invoked. What's happening here is that there's an intentional control design that is enforcing that certain events shouldn't matter to the control, either because they're low-level events that clash with control logic or because the control has replacement logic. A prominent example of this is the ButtonBase class. The ButtonBase class has two behaviors that it enforces through a native override of OnPointerPressed(PointerRoutedEventArgs) and OnKeyDown(KeyRoutedEventArgs). It's doing this because it's combining various input modes at a low level and reporting them instead as the control-specific Click event. In the case of a PointerPressed event handler, if you tried to handle this on a Button instance, your handler doesn't get invoked. That's because the native OnPointerPressed(PointerRoutedEventArgs) set Handled to true and that prevented PointerPressed from propagating to your instance and app code. For OnKeyDown(KeyRoutedEventArgs), the logic was just looking for certain keys (Ctrl and Enter) so an instance handler can still invoke as long as it isn't also looking for those keys.

Note

There's actually a way to get around native handling of On* methods for input, for some of the input events. To do this you need to wire your handlers using the AddHandler(RoutedEvent, Object, Boolean) method with handledEventsToo. For more info see AddHandler(RoutedEvent, Object, Boolean) or Events and routed events overview.

Text properties that inherit to text element parts

Control defines several properties that are relevant to presentation of text. These are:

Obviously, not every control is intended to display text within it. For example, setting FontFamily on an AppBarSeparator is legal but has absolutely no effect. The reason that Control defines these properties at the base class level is to make it easy for control templates to use {TemplateBinding} markup extension to apply top-level text properties to one or more text element parts that exist within the template. For example, if you look at the control template for a DatePicker, you'll see that the root is a container and more deeply within that container are several ComboBox parts that actually take the text input. Each of these uses statements like FontWeight="{TemplateBinding FontWeight}" to have the top-level FontWeight as set on a DatePicker be used by various parts within.

Text properties on Control also inherit implicitly for a control that has a ContentPresenter within it that displays text. For example, if you set FontSize on a Button, there's no explicit {TemplateBinding} markup extension in its template or ContentPresenter part that controls what the template does with a top-level FontSize value. But the FontSize value is implicitly inherited by FontSize based on the context within the template's definition, so the text within the Button will be presented using the FontSize you set.

Control derived classes

Control is the parent class for these immediately derived control classes. Some of these are practical controls. Others are intermediate base classes for various controls that share characteristics.

Constructors summary

Provides base class initialization behavior for Control derived classes.

Properties summary

Gets or sets a brush that provides the background of the control.

Identifies the Background dependency property.

Gets or sets a brush that describes the border fill of a control.

Identifies the BorderBrush dependency property.

Gets or sets the border thickness of a control.

Identifies the BorderThickness dependency property.

Gets or sets the uniform spacing between characters, in units of 1/1000 of an em.

Identifies the CharacterSpacing dependency property.

Gets or sets the key that references the default style for the control. Authors of custom controls use this property to change the default for the style that their control uses.

Identifies the DefaultStyleKey dependency property.

Prerelease. Gets or sets the path to the resource file that contains the default style for the control.

Prerelease. Identifies the DefaultStyleResourceUri dependency property.

Get or sets a value that specifies a control's preference for whether sounds are played.

Identifies the ElementSoundMode dependency property.

Gets a value that specifies whether this control has focus, and the mode by which focus was obtained.

Identifies the FocusState dependency property.

Gets or sets the font used to display text in the control.

Identifies the FontFamily dependency property.

Gets or sets the size of the text in this control.

Identifies the FontSize dependency property.

Gets or sets the degree to which a font is condensed or expanded on the screen.

Identifies the FontStretch dependency property.

Gets or sets the style in which the text is rendered.

Identifies the FontStyle dependency property.

Gets or sets the thickness of the specified font.

Identifies the FontWeight dependency property.

Gets or sets a brush that describes the foreground color.

Identifies the Foreground dependency property.

Gets or sets the horizontal alignment of the control's content.

Identifies the HorizontalContentAlignment dependency property.

Gets or sets a value indicating whether the user can interact with the control.

Identifies the IsEnabled dependency property.

Get or sets a value that indicates whether focus is constrained within the control boundaries (for game pad/remote interaction).

Identifies the IsFocusEngaged dependency property.

Get or sets a value that indicates whether focus can be constrained within the control boundaries (for game pad/remote interaction).

Identifies the IsFocusEngagementEnabled dependency property.

Gets or sets a value that indicates whether a control is included in tab navigation.

Identifies the IsTabStop dependency property.

Identifies the IsTemplateFocusTargetProperty XAML attached property.

Prerelease. Identifies the IsTemplateKeyTipTargetProperty XAML attached property.

Gets or sets whether automatic text enlargement, to reflect the system text size setting, is enabled.

Identifies the IsTextScaleFactorEnabled dependency property.

Gets or sets the padding inside a control.

Identifies the Padding dependency property.

Gets or sets whether a UI element supports mouse mode, which emulates pointer interaction experiences with non-pointer input devices such as an Xbox gamepad or remote control.

Identifies the RequiresPointer dependency property.

Gets or sets a value that determines the order in which elements receive focus when the user navigates through controls by pressing the Tab key.

Identifies the TabIndex dependency property.

Gets or sets a value that modifies how tabbing and TabIndex work for this control.

Identifies the TabNavigation dependency property.

Gets or sets a control template. The control template defines the visual appearance of a control in UI, and is defined in XAML markup.

Identifies the Template dependency property.

Gets or sets a value that indicates whether the control uses focus visuals that are drawn by the system or those defined in the control template.

Identifies the UseSystemFocusVisuals dependency property.

Gets or sets the vertical alignment of the control's content.

Identifies the VerticalContentAlignment dependency property.

Gets or sets the object that gets focus when a user presses the Directional Pad (D-pad) down.

Identifies the XYFocusDown dependency property.

Gets or sets the object that gets focus when a user presses the Directional Pad (D-pad) left.

Identifies the XYFocusLeft dependency property.

Gets or sets the object that gets focus when a user presses the Directional Pad (D-pad) right.

Identifies the XYFocusRight dependency property.

Gets or sets the object that gets focus when a user presses the Directional Pad (D-pad) up.

Identifies the XYFocusUp dependency property.

Methods summary

Loads the relevant control template so that its parts can be referenced.

Attempts to set the focus on the control.

Gets the value of the IsTemplateFocusTargetProperty XAML attached property for the target element.

Prerelease. Gets the value of the IsTemplateKeyTipTargetProperty XAML attached property for the target element.

Retrieves the named element in the instantiated ControlTemplate visual tree.

Called before the DoubleTapped event occurs.

Called before the DragEnter event occurs.

Called before the DragLeave event occurs.

Called before the DragOver event occurs.

Called before the Drop event occurs.

Called before the GotFocus event occurs.

Called before the Holding event occurs.

Called before the KeyDown event occurs.

Called before the KeyUp event occurs.

Called before the LostFocus event occurs.

Called before the ManipulationCompleted event occurs.

Called before the ManipulationDelta event occurs.

Called before the ManipulationInertiaStarting event occurs.

Called before the ManipulationStarted event occurs.

Called before the ManipulationStarting event occurs.

Called before the PointerCanceled event occurs.

Called before the PointerCaptureLost event occurs.

Called before the PointerEntered event occurs.

Called before the PointerExited event occurs.

Called before the PointerMoved event occurs.

Called before the PointerPressed event occurs.

Called before the PointerReleased event occurs.

Called before the PointerWheelChanged event occurs.

Called before the RightTapped event occurs.

Called before the Tapped event occurs.

Releases focus from the control boundaries for a control that has focus engagement (for game pad/remote interaction).

Sets the value of the IsTemplateFocusTargetProperty XAML attached property for a target element.

Prerelease. Sets the value of the IsTemplateKeyTipTargetProperty XAML attached property for a target element.

Events summary

Occurs when focus is released from the control boundaries (for game pad/remote interaction).

Occurs when focus is constrained within the control boundaries (for game pad/remote interaction).

Occurs when the IsEnabled property changes.

Constructors

  • Control()
    Control()
    Control()
    Control()

    Provides base class initialization behavior for Control derived classes.

    protected Control()protected New()Protected Sub New()protected Control()

Properties

  • Background
    Background
    Background
    Background

    Gets or sets a brush that provides the background of the control.

    public Brush Background { get; set; }public Brush Background { get; set; }Public ReadWrite Property Background As Brushpublic Brush Background { get; set; }
    <control Background="{StaticResource resourceName}"/>
    
    

    Property Value

    • The brush that provides the background of the control. The default is null, (a null brush) which is evaluated as Transparent for rendering.

    Remarks

    Each control might apply this property differently based on its visual template. This property only affects a control whose template uses the Background property as an input for the template's UI properties. On other controls, this property has no effect. Typically, a control uses a {TemplateBinding} markup extension to bind its Background value to the Background of a Panel that is the root element of the control template; for example, to Grid.Background. For more info about visual templates and control templating, see Styling controls or the reference page for the Template property.

    Starting in Windows 10, version 1607 (Windows Software Development Kit (SDK) version 10.0.14393.0), generic.xaml includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. In apps that target this software development kit (SDK) or later, modifying these resources is preferred to setting properties such as Background, Foreground, and BorderBrush. For more info, see the Light-weight styling section of the Styling controls article.

  • BackgroundProperty
    BackgroundProperty
    BackgroundProperty
    BackgroundProperty

    Identifies the Background dependency property.

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

    Property Value

  • BorderBrush
    BorderBrush
    BorderBrush
    BorderBrush

    Gets or sets a brush that describes the border fill of a control.

    public Brush BorderBrush { get; set; }public Brush BorderBrush { get; set; }Public ReadWrite Property BorderBrush As Brushpublic Brush BorderBrush { get; set; }
    <control Background="{StaticResource resourceName}"/>
    
    

    Property Value

    • The brush that is used to fill the control's border. The default is null, (a null brush) which is evaluated as Transparent for rendering.

    Remarks

    Each control might apply this property differently based on its visual template. This property only affects a control whose template uses the BorderBrush property as an input for the template's UI properties. On other controls, this property has no effect. Typically, if it wants to display a border, a control uses a {TemplateBinding} markup extension to bind its BorderBrush value to the BorderBrush of a Border that is the root element of the control template. For more info about visual templates and control templating, see Styling controls or the reference page for the Template property.

    Starting in Windows 10, version 1607 (Windows Software Development Kit (SDK) version 10.0.14393.0), generic.xaml includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. In apps that target this software development kit (SDK) or later, modifying these resources is preferred to setting properties such as Background, Foreground, and BorderBrush. For more info, see the Light-weight styling section of the Styling controls article.

    The BorderThickness value must be greater than 0 in order to see the BorderBrush value take effect.

  • BorderBrushProperty
    BorderBrushProperty
    BorderBrushProperty
    BorderBrushProperty

    Identifies the BorderBrush dependency property.

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

    Property Value

  • BorderThickness
    BorderThickness
    BorderThickness
    BorderThickness

    Gets or sets the border thickness of a control.

    public Thickness BorderThickness { get; set; }public Thickness BorderThickness { get; set; }Public ReadWrite Property BorderThickness As Thicknesspublic Thickness BorderThickness { get; set; }
    <control BorderThickness="uniform"/>
    - or -
    <control BorderThickness="left&right,top&bottom"/>
    - or -
    <control BorderThickness="left,top,right,bottom"/>
    

    Property Value

    Remarks

    Each control might apply this property differently based on its visual template. This property only affects a control whose template uses the BorderThickness property as a parameter. On other controls, this property has no effect. For more info about visual templates, see the Template property.

  • BorderThicknessProperty
    BorderThicknessProperty
    BorderThicknessProperty
    BorderThicknessProperty

    Identifies the BorderThickness dependency property.

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

    Property Value

  • CharacterSpacing
    CharacterSpacing
    CharacterSpacing
    CharacterSpacing

    Gets or sets the uniform spacing between characters, in units of 1/1000 of an em.

    public int CharacterSpacing { get; set; }public int CharacterSpacing { get; set; }Public ReadWrite Property CharacterSpacing As intpublic int CharacterSpacing { get; set; }
    <control CharacterSpacing="int"/>
    

    Property Value

    • int
      int
      int

      The uniform spacing between characters, in units of 1/1000 of an em. The default is 0. Positive values increase tracking and loosen character spacing. Negative values decrease tracking and tighten the character spacing.

  • CharacterSpacingProperty
    CharacterSpacingProperty
    CharacterSpacingProperty
    CharacterSpacingProperty

    Identifies the CharacterSpacing dependency property.

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

    Property Value

  • DefaultStyleKey
    DefaultStyleKey
    DefaultStyleKey
    DefaultStyleKey

    Gets or sets the key that references the default style for the control. Authors of custom controls use this property to change the default for the style that their control uses.

    protected object DefaultStyleKey { get; set; }protected object DefaultStyleKey { get; set; }Protected ReadWrite Property DefaultStyleKey As objectprotected object DefaultStyleKey { get; set; }

    Property Value

    • object
      object
      object

      The key that references the default style for the control. To work correctly as part of theme style lookup, this value is expected to be a System.Type value.

      Note

      Visual C++ component extensions (C++/CX) uses a string that is the qualified name of the type. But this relies on generated code that produces a TypeName once accessed by a XAML compiler; see Remarks.

    Remarks

    DefaultStyleKey is one of the very few protected properties in the Windows Runtime API. It's intended only for use by control authors, who will be subclassing some existing control class and therefore have the necessary access to set this property. For many custom control scenarios where you'll be setting DefaultStyleKey, you'll also be overriding OnApplyTemplate().

    The return type of DefaultStyleKey is loosely typed as Object in the syntax, but the XAML style system will expect the value to provide a type reference:

    • For a control that has its logic written in C#, the value of DefaultStyleKey should be an instance of System.Type. Typically you set this value in the default constructor:```csharp public CustomControl1() {

      this.DefaultStyleKey = typeof(CustomControl1);

    }

    
    
    
    
    + For a control that has its logic written in Microsoft Visual Basic, the value of @Windows.UI.Xaml.Controls.Control.DefaultStyleKey should be an instance of [System.Type](https://msdn.microsoft.com/library/system.type.aspx). Typically you set this value in the default constructor:```vbnet
    Public Sub New()
    
        Me.DefaultStyleKey = GetType(CustomControl1)
    
    End Sub
    
    • For a control that has its logic written in Visual C++ component extensions (C++/CX), the value of DefaultStyleKey should be a namespace-qualified string that is the name of the custom control class. Typically you set this value in the default constructor:```vbnet CustomControl1::CustomControl1() //public: in the header {

      DefaultStyleKey = "App1.CustomControl1";

    } ```

    Note

    Ultimately the string alone isn't enough to support a Visual C++ component extensions (C++/CX) type reference. If you use the Add / New Item / Templated Control options in Solution Explorer, the templates and support for Visual C++ component extensions (C++/CX) and XAML generates classes that give IXamlMetadataProvider info. The XAML compiler can access this code when the XAML is loaded, and uses it to validate and create types and members and join the partial classes. As far as what you define in your own app code, the string is all you need. But if you're curious you can have a look at the XamlTypeInfo.g.h and XamlTypeInfo.g.cpp files that are generated.

    Control authors could choose to not provide a value for DefaultStyleKey, but that's uncommon. The result would be that the default style is the one as defined by the base class. In some cases (like for ContentControl ) the value is null. Even if you choose to not redefine the value, make sure that the original default style is useful for rendering your control.

    When a XAML control is loaded, the rendering process starts, and the system is looking for the correct template to apply, what's being loaded is the XAML default style for the control, including its template. Included in the Windows Runtime is an internal copy of all the default styles for all the XAML controls that the Windows Runtime defines. The type reference in DefaultStyleKey tells the system which named XAML resource to load as this style. In XAML form, the styles really are keyed by type even though there's no mechanism in Windows Runtime XAML that defines a type reference explicitly. But for any TargetType value, which is the attribute that holds the key for lookup, it's implicitly assumed to represent a type reference in the form of a string. For example, DefaultStyleKey from a Button is a System.Type instance where the Name is "Button", FullName is "Windows.UI.Xaml.Controls.Button". The system uses this info to know to load the Style from the internal resources that has TargetType="Button".

    Custom controls usually aren't in the default XAML namespace. Instead, they're in a XAML namespace that has a using: statement to reference the app's code namespace. By default, projects create a prefix "local:" that maps this namespace for you. You could also map other XAML namespaces to refer to additional code namespaces for controls or other code that your app defines.

    The "local:" prefix (or some other namespace that maps to your app's code and namespaces) should precede the name of your custom control, when it's in XAML as the TargetType value. This is also already done for you by the starting templates; when you add a new control, you'll see a generic.xaml file that contains just one style. That style will have TargetType value that is a string starting with "local:" and completed by the name you chose for your custom control class. To match previous examples that set DefaultStyleKey in a CustomControl1 definition, you'd see an element for <Style TargetType="local:CustomControl1"> defined in the starting generic.xaml, and that style defines the control template as well as setting other properties.

    Note

    The "local:" prefix is isolated to the XAML where it's defined and used. XAML namespaces and the prefixes only have meaning within XAML and are self-contained to each XAML file. DefaultStyleKey values in code don't include the prefixes.

  • DefaultStyleKeyProperty
    DefaultStyleKeyProperty
    DefaultStyleKeyProperty
    DefaultStyleKeyProperty

    Identifies the DefaultStyleKey dependency property.

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

    Property Value

  • DefaultStyleResourceUri
    DefaultStyleResourceUri
    DefaultStyleResourceUri
    DefaultStyleResourceUri

    Prerelease. Gets or sets the path to the resource file that contains the default style for the control.

    public Uri DefaultStyleResourceUri { get; set; }public Uri DefaultStyleResourceUri { get; set; }Public ReadWrite Property DefaultStyleResourceUri As Uripublic Uri DefaultStyleResourceUri { get; set; }

    Property Value

    • The path to the resource file that contains the default style for the control.

  • DefaultStyleResourceUriProperty
    DefaultStyleResourceUriProperty
    DefaultStyleResourceUriProperty
    DefaultStyleResourceUriProperty

    Prerelease. Identifies the DefaultStyleResourceUri dependency property.

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

    Property Value

  • ElementSoundMode
    ElementSoundMode
    ElementSoundMode
    ElementSoundMode

    Get or sets a value that specifies a control's preference for whether sounds are played.

    public ElementSoundMode ElementSoundMode { get; set; }public ElementSoundMode ElementSoundMode { get; set; }Public ReadWrite Property ElementSoundMode As ElementSoundModepublic ElementSoundMode ElementSoundMode { get; set; }
    <control ElementSoundMode="elementSoundModeMemberName"/>
    

    Property Value

    Remarks

    Set the ElementSoundMode property to override the global ElementSoundPlayer setting for a specific control.

    For more info about using this property, see Sound in UWP apps.

    Version compatibility

    The ElementSoundMode property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

     private void MainPage_Loaded(object sender, RoutedEventArgs e)
     {
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.Control", "ElementSoundMode"))
        {
            button1.ElementSoundMode = ElementSoundMode.Off;
        }
    }
    
  • ElementSoundModeProperty
    ElementSoundModeProperty
    ElementSoundModeProperty
    ElementSoundModeProperty

    Identifies the ElementSoundMode dependency property.

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

    Property Value

  • FocusState
    FocusState
    FocusState
    FocusState

    Gets a value that specifies whether this control has focus, and the mode by which focus was obtained.

    public FocusState FocusState { get; }public FocusState FocusState { get; }Public ReadOnly Property FocusState As FocusStatepublic FocusState FocusState { get; }

    Property Value

    Remarks

    This property supports controls that use different visual styles depending on whether the control was focused by the keyboard or by other means. Some controls use visual states that show a visible focus indicator if the control was focused by a keyboard action, but do not show the indicator if the control was focused by a pointer action. The internal logic of such a control implements OnGotFocus(RoutedEventArgs) and then gets the value of FocusState from the sender. If FocusState is FocusState, then a different named visual state that includes a focus rectangle is loaded, by calling GoToState(Control, String, Boolean). Typically, focus-related visual states are grouped together in the default control template XAML. Custom controls that want to use different focus visuals depending on the means of focus can implement this same logic themselves. See OnGotFocus(RoutedEventArgs).

    Another way to use this property is to use FocusManager to determine which element in the overall UI has focus, and then call FocusState on that element to get information on how that control received focus.

    Note

    In Windows 8, when FocusState is FocusState, the keyboard focus visual is shown even if the prior method of input was pointer. In Windows 8.1, when you call Focus(FocusState) (FocusState.Programmatic), the prior FocusState, either FocusState or FocusState, is retained so that the correct focus visual is shown. This means that if you check the value of the FocusState property after you call Focus(FocusState) (FocusState.Programmatic), the FocusState property will have a value of either FocusState or FocusState.

    In an app that’s compiled for Windows 8, but run in Windows 8.1, the Windows 8 behavior is retained. The FocusState property value is FocusState and the keyboard focus visual is shown.

    Note

    Classes that inherit from ItemsControl, such as ListBox and AutoSuggestBox, do not propagate the FocusState property. They will always return Unfocused. Access the correct value through RoutedEventArgs.OriginalSource.

  • FocusStateProperty
    FocusStateProperty
    FocusStateProperty
    FocusStateProperty

    Identifies the FocusState dependency property.

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

    Property Value

  • FontFamily
    FontFamily
    FontFamily
    FontFamily

    Gets or sets the font used to display text in the control.

    public FontFamily FontFamily { get; set; }public FontFamily FontFamily { get; set; }Public ReadWrite Property FontFamily As FontFamilypublic FontFamily FontFamily { get; set; }
    <control FontFamily="fontFamilyValue"/>
    

    Property Value

  • FontFamilyProperty
    FontFamilyProperty
    FontFamilyProperty
    FontFamilyProperty

    Identifies the FontFamily dependency property.

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

    Property Value

  • FontSize
    FontSize
    FontSize
    FontSize

    Gets or sets the size of the text in this control.

    public double FontSize { get; set; }public double FontSize { get; set; }Public ReadWrite Property FontSize As doublepublic double FontSize { get; set; }
    <control FontSize="double"/>
    

    Property Value

    • double
      double
      double

      The size of the text in the Control, in pixels.

    Remarks

    The unit measure for FontSize is pixels, measuring the line height of the characters in the font. The apparent size of text in the UI can vary based on the current scaling. If you want to use different FontSize values for different scalings, you can do this using the resources system.

    The default value of FontSize is 11.

  • FontSizeProperty
    FontSizeProperty
    FontSizeProperty
    FontSizeProperty

    Identifies the FontSize dependency property.

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

    Property Value

  • FontStretch
    FontStretch
    FontStretch
    FontStretch

    Gets or sets the degree to which a font is condensed or expanded on the screen.

    public FontStretch FontStretch { get; set; }public FontStretch FontStretch { get; set; }Public ReadWrite Property FontStretch As FontStretchpublic FontStretch FontStretch { get; set; }
    <control FontStretch="fontStretchMemberName"/>
    

    Property Value

  • FontStretchProperty
    FontStretchProperty
    FontStretchProperty
    FontStretchProperty

    Identifies the FontStretch dependency property.

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

    Property Value

  • FontStyle
    FontStyle
    FontStyle
    FontStyle

    Gets or sets the style in which the text is rendered.

    public FontStyle FontStyle { get; set; }public FontStyle FontStyle { get; set; }Public ReadWrite Property FontStyle As FontStylepublic FontStyle FontStyle { get; set; }
    <control FontStyle="fontStyleMemberName" />
    

    Property Value

  • FontStyleProperty
    FontStyleProperty
    FontStyleProperty
    FontStyleProperty

    Identifies the FontStyle dependency property.

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

    Property Value

  • FontWeight
    FontWeight
    FontWeight
    FontWeight

    Gets or sets the thickness of the specified font.

    public FontWeight FontWeight { get; set; }public FontWeight FontWeight { get; set; }Public ReadWrite Property FontWeight As FontWeightpublic FontWeight FontWeight { get; set; }
    <control FontWeight="fontWeightMemberName"/>
    

    Property Value

  • FontWeightProperty
    FontWeightProperty
    FontWeightProperty
    FontWeightProperty

    Identifies the FontWeight dependency property.

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

    Property Value

  • Foreground
    Foreground
    Foreground
    Foreground

    Gets or sets a brush that describes the foreground color.

    public Brush Foreground { get; set; }public Brush Foreground { get; set; }Public ReadWrite Property Foreground As Brushpublic Brush Foreground { get; set; }
    <control Foreground="{StaticResource resourceName}"/>
    
    

    Property Value

    Remarks

    Each control might apply this property differently based on its visual template. This property only affects a control whose template uses the Foreground property as a parameter. On other controls, this property has no effect. Typically, a ContentControl derived control uses a {TemplateBinding} markup extension to bind its Foreground value to the Foreground of a ContentPresenter within the control template. The same color/brush might also be used for values of other decorative elements in the template (glyphs, icons, control surfaces) or to composite part properties such as the individual ComboBox elements of the TimePicker control. For more info about visual templates and control templating, see Styling controls or the reference page for the Template property.

    Starting in Windows 10, version 1607 (Windows Software Development Kit (SDK) version 10.0.14393.0), generic.xaml includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. In apps that target this software development kit (SDK) or later, modifying these resources is preferred to setting properties such as Background, Foreground, and BorderBrush. For more info, see the Light-weight styling section of the Styling controls article.

  • ForegroundProperty
    ForegroundProperty
    ForegroundProperty
    ForegroundProperty

    Identifies the Foreground dependency property.

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

    Property Value

  • HorizontalContentAlignment
    HorizontalContentAlignment
    HorizontalContentAlignment
    HorizontalContentAlignment

    Gets or sets the horizontal alignment of the control's content.

    public HorizontalAlignment HorizontalContentAlignment { get; set; }public HorizontalAlignment HorizontalContentAlignment { get; set; }Public ReadWrite Property HorizontalContentAlignment As HorizontalAlignmentpublic HorizontalAlignment HorizontalContentAlignment { get; set; }
    <control HorizontalContentAlignment="horizontalAlignmentMemberName"/>
    

    Property Value

    Remarks

    Each control might apply this property differently based on the Style setters for the control's implicit style, and its visual template. Also, the apparent "default value" of each individual control used in UI can be different. For example, a Button control starts with the value Center.

    A value for the HorizontalContentAlignment property only affects layout behavior for a control when its template uses the HorizontalContentAlignment property as the source of a HorizontalAlignment value for presenters or content areas within. On other controls, setting HorizontalContentAlignment has no effect. For more info about visual templates for controls, see the reference for Template.

  • HorizontalContentAlignmentProperty
    HorizontalContentAlignmentProperty
    HorizontalContentAlignmentProperty
    HorizontalContentAlignmentProperty

    Identifies the HorizontalContentAlignment dependency property.

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

    Property Value

  • IsEnabled
    IsEnabled
    IsEnabled
    IsEnabled

    Gets or sets a value indicating whether the user can interact with the control.

    public bool IsEnabled { get; set; }public bool IsEnabled { get; set; }Public ReadWrite Property IsEnabled As boolpublic bool IsEnabled { get; set; }
    <control IsEnabled="bool"/>
    

    Property Value

    • bool
      bool
      bool

      true if the user can interact with the control; otherwise, false.

    Remarks

    Many controls have predefined visual states that are invoked for IsEnabled =false, such as "graying out" text in labels.

    Whenever IsEnabled changes, that fires the IsEnabledChanged event. Controls might handle this event in order to change the visual states. The event has DependencyPropertyChangedEventArgs data, so you can determine the old and new values without having to use your own flags.

    A control inherits the IsEnabled property from its parent control. For example, if a control that contains a button has IsEnabled set to false, the button's IsEnabled property is also false. When the parent's property changes, that fires IsEnabledChanged for each control where the value changes because of the value inheriting.

    How the control logic behaves when disabled is potentially different for each control. However, these behaviors will result in all controls when IsEnabled =false:

    • The control can't receive keyboard focus or be focused programmatically.
    • The control does not appear in a tab sequence (any value for TabIndex is ignored).
    • A disabled control is still visible to hit testing. It can't handle any input events on itself. However, a disabled control can still source the input events, and input routed events can bubble to a parent where they can be handled.
  • IsEnabledProperty
    IsEnabledProperty
    IsEnabledProperty
    IsEnabledProperty

    Identifies the IsEnabled dependency property.

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

    Property Value

  • IsFocusEngaged
    IsFocusEngaged
    IsFocusEngaged
    IsFocusEngaged

    Get or sets a value that indicates whether focus is constrained within the control boundaries (for game pad/remote interaction).

    public bool IsFocusEngaged { get; set; }public bool IsFocusEngaged { get; set; }Public ReadWrite Property IsFocusEngaged As boolpublic bool IsFocusEngaged { get; set; }
    <control IsFocusEngaged="bool"/>
    

    Property Value

    • bool
      bool
      bool

      true if focus is constrained within the control boundaries; otherwise, false.

    Remarks

    IsFocusEngagementEnabled must be true and the control must have focus before you set the IsFocusEngaged property to true. Otherwise, a runtime exception will occur.

    Focus engagement makes it easier to use a game pad or remote control to interact with an app. Setting focus engagement does not affect keyboard or other input devices.

    When the IsFocusEngagementEnabled property is set to true, it marks the control as requiring focus engagement. This means that the user must press the A/Select button to "engage" the control and interact with it. When they are finished, they can press the B/Back button to disengage the control and navigate away from it.

    For more info about this property, see the Focus engagement section of the Designing for Xbox and TV article.

    Version compatibility

    The IsFocusEngaged property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

    
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.Control", "IsFocusEngaged"))
    {
        slider1.IsFocusEngaged = true;
    }
    
  • IsFocusEngagedProperty
    IsFocusEngagedProperty
    IsFocusEngagedProperty
    IsFocusEngagedProperty

    Identifies the IsFocusEngaged dependency property.

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

    Property Value

  • IsFocusEngagementEnabled
    IsFocusEngagementEnabled
    IsFocusEngagementEnabled
    IsFocusEngagementEnabled

    Get or sets a value that indicates whether focus can be constrained within the control boundaries (for game pad/remote interaction).

    public bool IsFocusEngagementEnabled { get; set; }public bool IsFocusEngagementEnabled { get; set; }Public ReadWrite Property IsFocusEngagementEnabled As boolpublic bool IsFocusEngagementEnabled { get; set; }
    <control IsFocusEngagementEnabled="bool"/>
    

    Property Value

    • bool
      bool
      bool

      true if focus can be constrained within the control boundaries; otherwise, false.

    Remarks

    Focus engagement makes it easier to use a game pad or remote control to interact with an app. Setting focus engagement does not affect keyboard or other input devices.

    When the IsFocusEngagementEnabled property is set to true, it marks the control as requiring focus engagement. This means that the user must press the A/Select button to "engage" the control and interact with it. When they are finished, they can press the B/Back button to disengage the control and navigate away from it.

    For more info about this property, see the Focus engagement section of the Designing for Xbox and TV article.

    Version compatibility

    The IsFocusEngagementEnabled property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

    
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.Control", "IsFocusEngagementEnabled"))
    {
        slider1.IsFocusEngagementEnabled = true;
    }
    
  • IsFocusEngagementEnabledProperty
    IsFocusEngagementEnabledProperty
    IsFocusEngagementEnabledProperty
    IsFocusEngagementEnabledProperty

    Identifies the IsFocusEngagementEnabled dependency property.

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

    Property Value

  • IsTabStop
    IsTabStop
    IsTabStop
    IsTabStop

    Gets or sets a value that indicates whether a control is included in tab navigation.

    public bool IsTabStop { get; set; }public bool IsTabStop { get; set; }Public ReadWrite Property IsTabStop As boolpublic bool IsTabStop { get; set; }
    <control IsTabStop="bool"/>
    

    Property Value

    • bool
      bool
      bool

      true if the control is included in tab navigation; otherwise, false. The default is true.

    Remarks

    Controlling the tab sequence with a combination of IsTabStop and TabIndex rather than using the default tab sequence is sometimes necessary in order to tune the keyboard accessibility of your UI. For more info, see Keyboard accessibility.

    If IsTabStop is false, the control is excluded from tab navigation. In addition, if IsTabStop is false, the control cannot receive input focus. (If you try to set focus programmatically, by calling the Focus(FocusState) method, Focus(FocusState) returns false).

    If the reason you don't want the control to be a tab stop is because it's not interactive in your UI, you might want to set IsEnabled to false to make the lack of interaction more obvious. Many controls have predefined visual states that are invoked for IsEnabled =false, such as "graying out" text in labels.

  • IsTabStopProperty
    IsTabStopProperty
    IsTabStopProperty
    IsTabStopProperty

    Identifies the IsTabStop dependency property.

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

    Property Value

  • IsTemplateFocusTargetProperty
    IsTemplateFocusTargetProperty
    IsTemplateFocusTargetProperty
    IsTemplateFocusTargetProperty

    Identifies the IsTemplateFocusTargetProperty XAML attached property.

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

    Property Value

  • IsTemplateKeyTipTargetProperty
    IsTemplateKeyTipTargetProperty
    IsTemplateKeyTipTargetProperty
    IsTemplateKeyTipTargetProperty

    Prerelease. Identifies the IsTemplateKeyTipTargetProperty XAML attached property.

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

    Property Value

  • IsTextScaleFactorEnabled
    IsTextScaleFactorEnabled
    IsTextScaleFactorEnabled
    IsTextScaleFactorEnabled

    Gets or sets whether automatic text enlargement, to reflect the system text size setting, is enabled.

    public bool IsTextScaleFactorEnabled { get; set; }public bool IsTextScaleFactorEnabled { get; set; }Public ReadWrite Property IsTextScaleFactorEnabled As boolpublic bool IsTextScaleFactorEnabled { get; set; }
    <control IsTextScaleFactorEnabled="bool"/>
    

    Property Value

    • bool
      bool
      bool

      true if automatic text enlargement is enabled; otherwise, false.

  • IsTextScaleFactorEnabledProperty
    IsTextScaleFactorEnabledProperty
    IsTextScaleFactorEnabledProperty
    IsTextScaleFactorEnabledProperty

    Identifies the IsTextScaleFactorEnabled dependency property.

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

    Property Value

  • Padding
    Padding
    Padding
    Padding

    Gets or sets the padding inside a control.

    public Thickness Padding { get; set; }public Thickness Padding { get; set; }Public ReadWrite Property Padding As Thicknesspublic Thickness Padding { get; set; }
    <control Padding="uniform"/>
    - or -
    <control Padding="left&right,top&bottom"/>
    - or -
    <control Padding="left,top,right,bottom"/>
    

    Property Value

    Remarks

    Each control might apply this property differently based on its visual template. This property only affects a control whose template uses the Padding property as a parameter. On other controls, this property has no effect. For more info about control templates, see the Template property.

    A related property is Margin (a property of FrameworkElement ). For many controls, margin and padding would typically blend together with the division between them not being apparent in the rendering. For such controls it's typical to specify a Margin or a Padding, but not both. For more info about the relationship between margin and padding, see Alignment, margin, and padding or Define layouts with XAML.

  • PaddingProperty
    PaddingProperty
    PaddingProperty
    PaddingProperty

    Identifies the Padding dependency property.

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

    Property Value

  • RequiresPointer
    RequiresPointer
    RequiresPointer
    RequiresPointer

    Gets or sets whether a UI element supports mouse mode, which emulates pointer interaction experiences with non-pointer input devices such as an Xbox gamepad or remote control.

    public RequiresPointer RequiresPointer { get; set; }public RequiresPointer RequiresPointer { get; set; }Public ReadWrite Property RequiresPointer As RequiresPointerpublic RequiresPointer RequiresPointer { get; set; }
    <control RequiresPointer="requiresPointerMemberName"/>
    

    Property Value

    Remarks

    For non-pointer input devices, focus is moved between controls through a variety of methods, such as the Tab and arrow keys on a keyboard, the directional pad (D-pad) on a remote, or thumb sticks on an Xbox controller. For some user experiences, such as maps and drawing surfaces, it is not possible or practical to use XY focus navigation. RequiresPointer enables an app to provide a more pointer-like interaction experience through a cursor that can be moved freely using the Xbox input devices.

    RequiresPointer is supported only on the Xbox device family, and only when using a game pad or remote control. The property is ignored otherwise.

    RequiresPointerMode sets mouse mode at the application level.

    For more info, see the Mouse mode section of Designing for Xbox and TV.

    Version compatibility

    The RequiresPointer property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

    
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.Control", "RequiresPointer"))
    {
        mapControl1.RequiresPointer = RequiresPointer.WhenEngaged;
    }
    
  • RequiresPointerProperty
    RequiresPointerProperty
    RequiresPointerProperty
    RequiresPointerProperty

    Identifies the RequiresPointer dependency property.

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

    Property Value

  • TabIndex
    TabIndex
    TabIndex
    TabIndex

    Gets or sets a value that determines the order in which elements receive focus when the user navigates through controls by pressing the Tab key.

    public int TabIndex { get; set; }public int TabIndex { get; set; }Public ReadWrite Property TabIndex As intpublic int TabIndex { get; set; }
    <control TabIndex="int/>
    

    Property Value

    • int
      int
      int

      A value that determines the order of logical navigation for a device. The default value is MaxValue.

  • TabIndexProperty
    TabIndexProperty
    TabIndexProperty
    TabIndexProperty

    Identifies the TabIndex dependency property.

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

    Property Value

  • TabNavigation
    TabNavigation
    TabNavigation
    TabNavigation

    Gets or sets a value that modifies how tabbing and TabIndex work for this control.

    public KeyboardNavigationMode TabNavigation { get; set; }public KeyboardNavigationMode TabNavigation { get; set; }Public ReadWrite Property TabNavigation As KeyboardNavigationModepublic KeyboardNavigationMode TabNavigation { get; set; }
    <control TabNavigation="keyboardNavigationModeMemberName"/>
    

    Property Value

  • TabNavigationProperty
    TabNavigationProperty
    TabNavigationProperty
    TabNavigationProperty

    Identifies the TabNavigation dependency property.

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

    Property Value

  • Template
    Template
    Template
    Template

    Gets or sets a control template. The control template defines the visual appearance of a control in UI, and is defined in XAML markup.

    public ControlTemplate Template { get; set; }public ControlTemplate Template { get; set; }Public ReadWrite Property Template As ControlTemplatepublic ControlTemplate Template { get; set; }
    <control Template="{StaticResource templateResourceKey}"/>
    

    Property Value

    Remarks

    The second XAML syntax shown above is a Setter syntax as part of a Style. This is how a Template value for a Control is defined in almost all cases.

    TargetType is a required attribute on all ControlTemplate elements used as a Template value. The value should match the TargetType property for the Style that contains the Setter for Template, if you are using a style-setter syntax.

    The ControlTemplate specifies the appearance of a Control; if a Control does not have a ControlTemplate, the Control will have no visible presence in your app. The control author defines the default control template, and the app author can re-template the ControlTemplate XAML to redefine the visual tree of the control.

    Control templates are typically set in Extensible Application Markup Language (XAML) as part of a control-specific implicit style. In this case, a Property value in the Setter is set as the string "Template", and the Value value is set as a property element, which contains a ControlTemplate object element. For example, this is the Style that defines a Template value for a ScrollViewer. This is an example of an implicit style, where the Style can be in a ResourceDictionary but doesn't need an x:Key attribute.

    
    <ResourceDictionary>
      <Style TargetType="ScrollViewer">
      ...
        <Setter Property="Template">
          <Setter.Value>
            <ControlTemplate TargetType="ScrollViewer">
              <!--visual root of template for a ScrollViewer-->
            </ControlTemplate>
          </Setter.Value>
        </Setter>
      </Style>
      ...
    </ResourceDictionary>
    

    Styles and templates

    You can use a Setter in a Style to apply values to any dependency property. But it's the Setter for the Template property of a Control -derived class that constitutes the majority of the XAML markup in a typical Style. When a Style is used to define a control template, the TargetType of the Style element and the TargetType of the ControlTemplate element for its Template setter should always use the same value. The Template setter defines the basic templated UI definition for a control where that template is applied. It also contains the visual states for a control, and other state-based UI definitions such as default theme transitions. For a complex control such as ListBox, the default template Style and the ControlTemplate within can have hundreds of lines of XAML. For more info on the role of Template in control templating scenarios, see Quickstart: Control templates.

    Implicit styles

    You can define styles such that a Style is used implicitly by all objects of the same TargetType, without requiring each instance of such an object to specifically reference the Style as a Style value. When a <Style> resource is declared in a ResourceDictionary without an x:Key attribute, the x:Key value uses the value of the TargetType property. If you set the style implicitly, the style is applied only to the types that match the TargetType exactly and not to elements derived from the TargetType value. For example, if you create a style implicitly for all the ToggleButton controls in your application, and your application has ToggleButton and CheckBox controls (CheckBox derives from ToggleButton ), the "ToggleButton" implicit style is applied only to the ToggleButton controls.

    Examples

    This example shows a more complete control template defined as a Style and Setter with Property value of "Template". This is a named style for a RadioButton control. It includes the template elements that are normally part of a functional control template, such as a VisualStateManager.VisualStateGroups attached property element attached to the root element of the template, and x:Name attribute values assigned to each of the prominent control parts.

    
        <Style x:Key="TextRadioButtonStyle" TargetType="RadioButton"> 
            <Setter Property="MinWidth" Value="0"/> 
            <Setter Property="MinHeight" Value="0"/> 
            <Setter Property="Template"> 
                <Setter.Value> 
                    <ControlTemplate TargetType="RadioButton"> 
                        <Grid Background="Transparent"> 
                            <TextBlock 
                                x:Name="Text" 
                                Text="{TemplateBinding Content}" 
                                Margin="3,-7,3,10" 
                                TextWrapping="NoWrap" 
                                Style="{StaticResource SubheaderTextStyle}"/> 
                            <Rectangle 
                                x:Name="FocusVisualWhite" 
                                IsHitTestVisible="False" 
                                Stroke="{StaticResource FocusVisualWhiteStrokeThemeBrush}" 
                                StrokeEndLineCap="Square" 
                                StrokeDashArray="1,1" 
                                Opacity="0" 
                                StrokeDashOffset="1.5"/> 
                            <Rectangle 
                                x:Name="FocusVisualBlack" 
                                IsHitTestVisible="False" 
                                Stroke="{StaticResource FocusVisualBlackStrokeThemeBrush}" 
                                StrokeEndLineCap="Square" 
                                StrokeDashArray="1,1" 
                                Opacity="0" 
                                StrokeDashOffset="0.5"/> 
    
                            <VisualStateManager.VisualStateGroups> 
                                <VisualStateGroup x:Name="CommonStates"> 
                                    <VisualState x:Name="Normal"/> 
                                    <VisualState x:Name="PointerOver"> 
                                        <Storyboard> 
                                            <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Text" Storyboard.TargetProperty="Foreground"> 
                                                <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource ApplicationPointerOverForegroundThemeBrush}"/> 
                                            </ObjectAnimationUsingKeyFrames> 
                                        </Storyboard> 
                                    </VisualState> 
                                    <VisualState x:Name="Pressed"> 
    
                                        <Storyboard> 
                                            <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Text" Storyboard.TargetProperty="Foreground"> 
                                                <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource ApplicationPressedForegroundThemeBrush}"/> 
                                            </ObjectAnimationUsingKeyFrames> 
                                        </Storyboard> 
                                    </VisualState> 
                                    <VisualState x:Name="Disabled"> 
                                        <Storyboard> 
                                            <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Text" Storyboard.TargetProperty="Foreground"> 
                                                <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource ButtonDisabledForegroundThemeBrush}"/> 
                                            </ObjectAnimationUsingKeyFrames> 
                                        </Storyboard> 
                                    </VisualState> 
                                </VisualStateGroup> 
                                <VisualStateGroup x:Name="FocusStates"> 
                                    <VisualState x:Name="Focused"> 
                                        <Storyboard> 
                                            <DoubleAnimation Duration="0" To="1" Storyboard.TargetName="FocusVisualWhite" Storyboard.TargetProperty="Opacity"/> 
                                            <DoubleAnimation Duration="0" To="1" Storyboard.TargetName="FocusVisualBlack" Storyboard.TargetProperty="Opacity"/> 
                                        </Storyboard> 
                                    </VisualState> 
                                    <VisualState x:Name="Unfocused"/> 
                                </VisualStateGroup> 
                                <VisualStateGroup x:Name="CheckStates"> 
                                    <VisualState x:Name="Checked"/> 
                                    <VisualState x:Name="Unchecked"> 
                                        <Storyboard> 
                                            <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Text" Storyboard.TargetProperty="Foreground"> 
                                                <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource ApplicationSecondaryForegroundThemeBrush}"/> 
                                            </ObjectAnimationUsingKeyFrames> 
                                        </Storyboard> 
                                    </VisualState> 
                                    <VisualState x:Name="Indeterminate"/> 
                                </VisualStateGroup> 
                            </VisualStateManager.VisualStateGroups> 
                        </Grid> 
                    </ControlTemplate> 
                </Setter.Value> 
            </Setter> 
        </Style> 
    
  • TemplateProperty
    TemplateProperty
    TemplateProperty
    TemplateProperty

    Identifies the Template dependency property.

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

    Property Value

  • UseSystemFocusVisuals
    UseSystemFocusVisuals
    UseSystemFocusVisuals
    UseSystemFocusVisuals

    Gets or sets a value that indicates whether the control uses focus visuals that are drawn by the system or those defined in the control template.

    public bool UseSystemFocusVisuals { get; set; }public bool UseSystemFocusVisuals { get; set; }Public ReadWrite Property UseSystemFocusVisuals As boolpublic bool UseSystemFocusVisuals { get; set; }

    Property Value

    • bool
      bool
      bool

      true if the control uses focus visuals drawn by the system; false if the control uses focus visuals defined in the ControlTemplate. The default is false; see Remarks.

    Remarks

    This property is false by default so that a custom ControlTemplate that defines its own focus visuals works as expected. However, all XAML framework controls set this property to true in their ControlTemplate and use system drawn focus visuals.

    To define custom focus visuals for a control, you need to provide a custom ControlTemplate. In the ControlTemplate, do the following:

    Examples

    This example shows a ControlTemplate that defines custom focus visuals for a Button.

    Some elements of the control template aren't shown to make the relevant parts more clear. To see the full control template for Button, see Button styles and templates.

    <Style TargetType="Button">
    
    <!-- Set UseSystemFocusVisuals to false. -->
        <Setter Property="UseSystemFocusVisuals" Value="False"/> 
         ...
    
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="Button">
                    <Grid>
                        <VisualStateManager.VisualStateGroups>
                            <VisualStateGroup x:Name="CommonStates">
                                <VisualState x:Name="Normal"/>
                                <VisualState x:Name="PointerOver">
                                 ...
    
                                </VisualState>
                            </VisualStateGroup>
    
    <!-- Add VisualStateGroup for FocusStates. -->
                            <VisualStateGroup x:Name="FocusStates">
                                <VisualState x:Name="Focused">
                                    <Storyboard>
                                        <DoubleAnimation Storyboard.TargetName="FocusVisualWhite"
                                                         Storyboard.TargetProperty="Opacity"
                                                         To="1"
                                                         Duration="0"/>
                                        <DoubleAnimation Storyboard.TargetName="FocusVisualBlack"
                                                         Storyboard.TargetProperty="Opacity"
                                                         To="1"
                                                         Duration="0"/>
                                    </Storyboard>
                                </VisualState>
                                <VisualState x:Name="Unfocused"/>
                                <VisualState x:Name="PointerFocused"/>
                            </VisualStateGroup>
    
                        </VisualStateManager.VisualStateGroups>
                        <Border x:Name="Border"
                                Background="{TemplateBinding Background}"
                                BorderBrush="{TemplateBinding BorderBrush}"
                                BorderThickness="{TemplateBinding BorderThickness}"
                                Margin="3">
                            <ContentPresenter x:Name="ContentPresenter"
                                              Content="{TemplateBinding Content}"
                                              ContentTransitions="{TemplateBinding ContentTransitions}"
                                              ContentTemplate="{TemplateBinding ContentTemplate}"
                                              Margin="{TemplateBinding Padding}"
                                              HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
                                              VerticalAlignment="{TemplateBinding VerticalContentAlignment}" 
                                              AutomationProperties.AccessibilityView="Raw"/>
                        </Border>
    
    <!-- Add elements for focus visuals. -->
                        <Rectangle x:Name="FocusVisualWhite"
                                   IsHitTestVisible="False"
                                   Stroke="{ThemeResource FocusVisualWhiteStrokeThemeBrush}"
                                   StrokeEndLineCap="Square"
                                   StrokeDashArray="1,1"
                                   Opacity="0"
                                   StrokeDashOffset="1.5"/>
                        <Rectangle x:Name="FocusVisualBlack"
                                   IsHitTestVisible="False"
                                   Stroke="{ThemeResource FocusVisualBlackStrokeThemeBrush}"
                                   StrokeEndLineCap="Square"
                                   StrokeDashArray="1,1"
                                   Opacity="0"
                                   StrokeDashOffset="0.5"/>
                    </Grid>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
    
  • UseSystemFocusVisualsProperty
    UseSystemFocusVisualsProperty
    UseSystemFocusVisualsProperty
    UseSystemFocusVisualsProperty

    Identifies the UseSystemFocusVisuals dependency property.

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

    Property Value

  • VerticalContentAlignment
    VerticalContentAlignment
    VerticalContentAlignment
    VerticalContentAlignment

    Gets or sets the vertical alignment of the control's content.

    public VerticalAlignment VerticalContentAlignment { get; set; }public VerticalAlignment VerticalContentAlignment { get; set; }Public ReadWrite Property VerticalContentAlignment As VerticalAlignmentpublic VerticalAlignment VerticalContentAlignment { get; set; }
    <control VerticalContentAlignment="verticalAlignmentValue"/>
    

    Property Value

    Remarks

    Each control might apply this property differently based on the Style setters for the control's implicit style, and its visual template. Also, the apparent "default value" of each individual control used in UI can be different. For example, a Button control starts with the value Center.

    A value for the VerticalContentAlignment property only affects layout behavior for a control when its template uses the VerticalContentAlignment property as the source of a VerticalAlignment value for presenters or content areas within. On other controls, setting VerticalContentAlignment has no effect. For more info about visual templates for controls, see the reference for Template.

  • VerticalContentAlignmentProperty
    VerticalContentAlignmentProperty
    VerticalContentAlignmentProperty
    VerticalContentAlignmentProperty

    Identifies the VerticalContentAlignment dependency property.

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

    Property Value

  • XYFocusDown
    XYFocusDown
    XYFocusDown
    XYFocusDown

    Gets or sets the object that gets focus when a user presses the Directional Pad (D-pad) down.

    public DependencyObject XYFocusDown { get; set; }public DependencyObject XYFocusDown { get; set; }Public ReadWrite Property XYFocusDown As DependencyObjectpublic DependencyObject XYFocusDown { get; set; }
    <control XYFocusDown="{x:Bind dependencyObjectValue}"/>
    

    Property Value

    Remarks

    XYFocusDown is supported only on the Xbox device family, and only when using a game pad or remote control. The property is ignored otherwise.

    For more info about this property, see the XY focus navigation and interaction section of the Designing for Xbox and TV article.

    XYFocusDown="{x:Bind commandBar2}"

    Version compatibility

    The XYFocusDown property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

    
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.Control", "XYFocusDown"))
    {
        button1.XYFocusDown = button2;
    }
    
  • XYFocusDownProperty
    XYFocusDownProperty
    XYFocusDownProperty
    XYFocusDownProperty

    Identifies the XYFocusDown dependency property.

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

    Property Value

  • XYFocusLeft
    XYFocusLeft
    XYFocusLeft
    XYFocusLeft

    Gets or sets the object that gets focus when a user presses the Directional Pad (D-pad) left.

    public DependencyObject XYFocusLeft { get; set; }public DependencyObject XYFocusLeft { get; set; }Public ReadWrite Property XYFocusLeft As DependencyObjectpublic DependencyObject XYFocusLeft { get; set; }
    <control XYFocusLeft="{x:Bind dependencyObjectValue}"/>
    

    Property Value

    Remarks

    XYFocusLeft is supported only on the Xbox device family, and only when using a game pad or remote control. The property is ignored otherwise.

    For more info about this property, see the XY focus navigation and interaction section of the Designing for Xbox and TV article.

    Version compatibility

    The XYFocusLeft property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

    
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.Control", "XYFocusLeft"))
    {
        button1.XYFocusLeft = button2;
    }
    
  • XYFocusLeftProperty
    XYFocusLeftProperty
    XYFocusLeftProperty
    XYFocusLeftProperty

    Identifies the XYFocusLeft dependency property.

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

    Property Value

  • XYFocusRight
    XYFocusRight
    XYFocusRight
    XYFocusRight

    Gets or sets the object that gets focus when a user presses the Directional Pad (D-pad) right.

    public DependencyObject XYFocusRight { get; set; }public DependencyObject XYFocusRight { get; set; }Public ReadWrite Property XYFocusRight As DependencyObjectpublic DependencyObject XYFocusRight { get; set; }
    <control XYFocusRight="{x:Bind dependencyObjectValue}"/>
    

    Property Value

    Remarks

    XYFocusRight is supported only on the Xbox device family, and only when using a game pad or remote control. The property is ignored otherwise.

    For more info about this property, see the XY focus navigation and interaction section of the Designing for Xbox and TV article.

    Version compatibility

    The XYFocusRight property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

    
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.Control", "XYFocusRight"))
    {
        button1.XYFocusRight = button2;
    }
    
  • XYFocusRightProperty
    XYFocusRightProperty
    XYFocusRightProperty
    XYFocusRightProperty

    Identifies the XYFocusRight dependency property.

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

    Property Value

  • XYFocusUp
    XYFocusUp
    XYFocusUp
    XYFocusUp

    Gets or sets the object that gets focus when a user presses the Directional Pad (D-pad) up.

    public DependencyObject XYFocusUp { get; set; }public DependencyObject XYFocusUp { get; set; }Public ReadWrite Property XYFocusUp As DependencyObjectpublic DependencyObject XYFocusUp { get; set; }
    <control XYFocusUp="{x:Bind dependencyObjectValue}"/>
    

    Property Value

    Remarks

    XYFocusUp is supported only on the Xbox device family, and only when using a game pad or remote control. The property is ignored otherwise.

    For more info about this property, see the XY focus navigation and interaction section of the Designing for Xbox and TV article.

    Version compatibility

    The XYFocusUp property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

    
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.Control", "XYFocusUp"))
    {
        button1.XYFocusUp = button2;
    }
    
  • XYFocusUpProperty
    XYFocusUpProperty
    XYFocusUpProperty
    XYFocusUpProperty

    Identifies the XYFocusUp dependency property.

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

    Property Value

Methods

  • ApplyTemplate()
    ApplyTemplate()
    ApplyTemplate()
    ApplyTemplate()

    Loads the relevant control template so that its parts can be referenced.

    public bool ApplyTemplate()public bool ApplyTemplate()Public Function ApplyTemplate() As boolpublic bool ApplyTemplate()

    Returns

    • bool
      bool
      bool

      A value that indicates whether the visual tree was rebuilt by this call. True if the tree was rebuilt; false if the previous visual tree was retained.

  • Focus(FocusState)
    Focus(FocusState)
    Focus(FocusState)
    Focus(FocusState)

    Attempts to set the focus on the control.

    public bool Focus(FocusState value)public bool Focus(FocusState value)Public Function Focus(value As FocusState) As boolpublic bool Focus(FocusState value)

    Parameters

    Returns

    • bool
      bool
      bool

      true if focus was set to the control, or focus was already on the control. false if the control is not focusable.

    Remarks

    You can't remove focus from a control by calling this method with FocusState as the parameter. This value is not allowed and causes an exception. To remove focus from a control, set focus to a different control.

    You typically pass FocusState as the parameter to indicate the control obtained focus through a deliberate call to the Focus(FocusState) method. For example, if clicking an "Edit" button causes focus to be set on a TextBox, use the FocusState focus state.

    Pass FocusState if you’re setting focus as the direct result of a pointer interaction. Pass FocusState as the parameter if you’re setting focus as a result of a keyboard interaction, like a tab sequence or key press. For example, if you’re implementing an ItemsControl and handle key presses to let the user move focus between items in the control, use the FocusState focus state when you call Focus(FocusState) in your key press handler.

    Note

    In Windows 8, when FocusState is FocusState, the keyboard focus visual is shown even if the prior method of input was pointer. In Windows 8.1, when you call Focus(FocusState) (FocusState.Programmatic), the prior FocusState, either FocusState or FocusState, is retained so that the correct focus visual is shown. This means that if you check the value of the FocusState property after you call Focus(FocusState) (FocusState.Programmatic), the FocusState property will have a value of either FocusState or FocusState.

    In an app that’s compiled for Windows 8, but run in Windows 8.1, the Windows 8 behavior is retained. The FocusState property value is FocusState and the keyboard focus visual is shown.

  • GetIsTemplateFocusTarget(FrameworkElement)
    GetIsTemplateFocusTarget(FrameworkElement)
    GetIsTemplateFocusTarget(FrameworkElement)
    GetIsTemplateFocusTarget(FrameworkElement)

    Gets the value of the IsTemplateFocusTargetProperty XAML attached property for the target element.

    public static bool GetIsTemplateFocusTarget(FrameworkElement element)public static bool GetIsTemplateFocusTarget(FrameworkElement element)Public Static Function GetIsTemplateFocusTarget(element As FrameworkElement) As boolpublic static bool GetIsTemplateFocusTarget(FrameworkElement element)

    Parameters

    Returns

    Remarks

    This method is a utility method for the property system, and isn't used in most app scenarios. In most cases you set the IsTemplateFocusTargetProperty XAML attached property in XAML and won't need this method. For more info, see the IsTemplateFocusTargetProperty attached property.

  • GetIsTemplateKeyTipTarget(DependencyObject)
    GetIsTemplateKeyTipTarget(DependencyObject)
    GetIsTemplateKeyTipTarget(DependencyObject)
    GetIsTemplateKeyTipTarget(DependencyObject)

    Prerelease. Gets the value of the IsTemplateKeyTipTargetProperty XAML attached property for the target element.

    public static bool GetIsTemplateKeyTipTarget(DependencyObject element)public static bool GetIsTemplateKeyTipTarget(DependencyObject element)Public Static Function GetIsTemplateKeyTipTarget(element As DependencyObject) As boolpublic static bool GetIsTemplateKeyTipTarget(DependencyObject element)

    Parameters

    Returns

    Remarks

    This method is a utility method for the property system, and isn't used in most app scenarios. In most cases you set the Control.IsTemplateKeytipTarget XAML attached property in XAML and won't need this method. For more info, see the IsTemplateKeyTipTargetProperty attached property.

  • GetTemplateChild(String)
    GetTemplateChild(String)
    GetTemplateChild(String)
    GetTemplateChild(String)

    Retrieves the named element in the instantiated ControlTemplate visual tree.

    protected DependencyObject GetTemplateChild(String childName)protected DependencyObject GetTemplateChild(String childName)Protected Function GetTemplateChild(childName As String) As DependencyObjectprotected DependencyObject GetTemplateChild(String childName)

    Parameters

    • childName
      System.String
      System.String
      System.String

      The name of the element to find.

    Returns

    Remarks

    You call GetTemplateChild(String) to get references to objects in a controls Template after it's instantiated. The ControlTemplate is instantiated in the OnApplyTemplate() method. You can use the GetTemplateChild(String) method inside your OnApplyTemplate() override and keep a reference to the objects you need.

  • OnDoubleTapped(DoubleTappedRoutedEventArgs)
    OnDoubleTapped(DoubleTappedRoutedEventArgs)
    OnDoubleTapped(DoubleTappedRoutedEventArgs)
    OnDoubleTapped(DoubleTappedRoutedEventArgs)

    Called before the DoubleTapped event occurs.

    protected virtual void OnDoubleTapped(DoubleTappedRoutedEventArgs e)protected virtual void OnDoubleTapped(DoubleTappedRoutedEventArgs e)Protected Overridable Function OnDoubleTapped(e As DoubleTappedRoutedEventArgs) As voidprotected virtual void OnDoubleTapped(DoubleTappedRoutedEventArgs e)

    Parameters

  • OnDragEnter(DragEventArgs)
    OnDragEnter(DragEventArgs)
    OnDragEnter(DragEventArgs)
    OnDragEnter(DragEventArgs)

    Called before the DragEnter event occurs.

    protected virtual void OnDragEnter(DragEventArgs e)protected virtual void OnDragEnter(DragEventArgs e)Protected Overridable Function OnDragEnter(e As DragEventArgs) As voidprotected virtual void OnDragEnter(DragEventArgs e)

    Parameters

  • OnDragLeave(DragEventArgs)
    OnDragLeave(DragEventArgs)
    OnDragLeave(DragEventArgs)
    OnDragLeave(DragEventArgs)

    Called before the DragLeave event occurs.

    protected virtual void OnDragLeave(DragEventArgs e)protected virtual void OnDragLeave(DragEventArgs e)Protected Overridable Function OnDragLeave(e As DragEventArgs) As voidprotected virtual void OnDragLeave(DragEventArgs e)

    Parameters

  • OnDragOver(DragEventArgs)
    OnDragOver(DragEventArgs)
    OnDragOver(DragEventArgs)
    OnDragOver(DragEventArgs)

    Called before the DragOver event occurs.

    protected virtual void OnDragOver(DragEventArgs e)protected virtual void OnDragOver(DragEventArgs e)Protected Overridable Function OnDragOver(e As DragEventArgs) As voidprotected virtual void OnDragOver(DragEventArgs e)

    Parameters

  • OnDrop(DragEventArgs)
    OnDrop(DragEventArgs)
    OnDrop(DragEventArgs)
    OnDrop(DragEventArgs)

    Called before the Drop event occurs.

    protected virtual void OnDrop(DragEventArgs e)protected virtual void OnDrop(DragEventArgs e)Protected Overridable Function OnDrop(e As DragEventArgs) As voidprotected virtual void OnDrop(DragEventArgs e)

    Parameters

  • OnGotFocus(RoutedEventArgs)
    OnGotFocus(RoutedEventArgs)
    OnGotFocus(RoutedEventArgs)
    OnGotFocus(RoutedEventArgs)

    Called before the GotFocus event occurs.

    protected virtual void OnGotFocus(RoutedEventArgs e)protected virtual void OnGotFocus(RoutedEventArgs e)Protected Overridable Function OnGotFocus(e As RoutedEventArgs) As voidprotected virtual void OnGotFocus(RoutedEventArgs e)

    Parameters

  • OnHolding(HoldingRoutedEventArgs)
    OnHolding(HoldingRoutedEventArgs)
    OnHolding(HoldingRoutedEventArgs)
    OnHolding(HoldingRoutedEventArgs)

    Called before the Holding event occurs.

    protected virtual void OnHolding(HoldingRoutedEventArgs e)protected virtual void OnHolding(HoldingRoutedEventArgs e)Protected Overridable Function OnHolding(e As HoldingRoutedEventArgs) As voidprotected virtual void OnHolding(HoldingRoutedEventArgs e)

    Parameters

  • OnKeyDown(KeyRoutedEventArgs)
    OnKeyDown(KeyRoutedEventArgs)
    OnKeyDown(KeyRoutedEventArgs)
    OnKeyDown(KeyRoutedEventArgs)

    Called before the KeyDown event occurs.

    protected virtual void OnKeyDown(KeyRoutedEventArgs e)protected virtual void OnKeyDown(KeyRoutedEventArgs e)Protected Overridable Function OnKeyDown(e As KeyRoutedEventArgs) As voidprotected virtual void OnKeyDown(KeyRoutedEventArgs e)

    Parameters

    Remarks

    As it's implemented directly on Control, OnKeyDown(KeyRoutedEventArgs) has an empty implementation. But each ancestor in a control's hierarchy may have provided an implementation. You won't be able to see this implementation because it's internal native code. In some cases a control will already have existing On* overrides that mark the event Handled. For key events, controls are usually only handling for certain keys, by checking values in KeyRoutedEventArgs. For example, ButtonBase detects the Space key as a way to fire Click. Control code or your code probably shouldn't be suppressing all key events, because it's a common pattern to let key events bubble to the root visual so that they can be shortcuts or accelerators for app interaction. For more info see Keyboard interactions.

  • OnKeyUp(KeyRoutedEventArgs)
    OnKeyUp(KeyRoutedEventArgs)
    OnKeyUp(KeyRoutedEventArgs)
    OnKeyUp(KeyRoutedEventArgs)

    Called before the KeyUp event occurs.

    protected virtual void OnKeyUp(KeyRoutedEventArgs e)protected virtual void OnKeyUp(KeyRoutedEventArgs e)Protected Overridable Function OnKeyUp(e As KeyRoutedEventArgs) As voidprotected virtual void OnKeyUp(KeyRoutedEventArgs e)

    Parameters

    Remarks

    As it's implemented directly on Control, OnKeyUp(KeyRoutedEventArgs) has an empty implementation. But each ancestor in a control's hierarchy may have provided an implementation. You won't be able to see this implementation because it's internal native code. In some cases a control will already have existing On* overrides that mark the event Handled. For key events, controls are usually only handling for certain keys, by checking values in KeyRoutedEventArgs. For example, ButtonBase detects the Space key as a way to fire Click. Control code or your code probably shouldn't be suppressing all key events, because it's a common pattern to let key events bubble to the root visual so that they can be shortcuts or accelerators for app interaction. For more info see Keyboard interactions.

  • OnLostFocus(RoutedEventArgs)
    OnLostFocus(RoutedEventArgs)
    OnLostFocus(RoutedEventArgs)
    OnLostFocus(RoutedEventArgs)

    Called before the LostFocus event occurs.

    protected virtual void OnLostFocus(RoutedEventArgs e)protected virtual void OnLostFocus(RoutedEventArgs e)Protected Overridable Function OnLostFocus(e As RoutedEventArgs) As voidprotected virtual void OnLostFocus(RoutedEventArgs e)

    Parameters

  • OnManipulationCompleted(ManipulationCompletedRoutedEventArgs)
    OnManipulationCompleted(ManipulationCompletedRoutedEventArgs)
    OnManipulationCompleted(ManipulationCompletedRoutedEventArgs)
    OnManipulationCompleted(ManipulationCompletedRoutedEventArgs)

    Called before the ManipulationCompleted event occurs.

    protected virtual void OnManipulationCompleted(ManipulationCompletedRoutedEventArgs e)protected virtual void OnManipulationCompleted(ManipulationCompletedRoutedEventArgs e)Protected Overridable Function OnManipulationCompleted(e As ManipulationCompletedRoutedEventArgs) As voidprotected virtual void OnManipulationCompleted(ManipulationCompletedRoutedEventArgs e)

    Parameters

    Remarks

    Windows 8 behavior

    Windows 8 doesn't fire ManipulationCompleted in cases where the inertial phase has started (and ManipulationInertiaStarting has fired) but the user has tapped on the item before it's finished scrolling, which cancels the inertial phase visually. The issue is fixed starting with Windows 8.1; ManipulationCompleted is fired as soon as the tap action cancels the inertial phase.

    Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

  • OnManipulationDelta(ManipulationDeltaRoutedEventArgs)
    OnManipulationDelta(ManipulationDeltaRoutedEventArgs)
    OnManipulationDelta(ManipulationDeltaRoutedEventArgs)
    OnManipulationDelta(ManipulationDeltaRoutedEventArgs)

    Called before the ManipulationDelta event occurs.

    protected virtual void OnManipulationDelta(ManipulationDeltaRoutedEventArgs e)protected virtual void OnManipulationDelta(ManipulationDeltaRoutedEventArgs e)Protected Overridable Function OnManipulationDelta(e As ManipulationDeltaRoutedEventArgs) As voidprotected virtual void OnManipulationDelta(ManipulationDeltaRoutedEventArgs e)

    Parameters

  • OnManipulationInertiaStarting(ManipulationInertiaStartingRoutedEventArgs)
    OnManipulationInertiaStarting(ManipulationInertiaStartingRoutedEventArgs)
    OnManipulationInertiaStarting(ManipulationInertiaStartingRoutedEventArgs)
    OnManipulationInertiaStarting(ManipulationInertiaStartingRoutedEventArgs)

    Called before the ManipulationInertiaStarting event occurs.

    protected virtual void OnManipulationInertiaStarting(ManipulationInertiaStartingRoutedEventArgs e)protected virtual void OnManipulationInertiaStarting(ManipulationInertiaStartingRoutedEventArgs e)Protected Overridable Function OnManipulationInertiaStarting(e As ManipulationInertiaStartingRoutedEventArgs) As voidprotected virtual void OnManipulationInertiaStarting(ManipulationInertiaStartingRoutedEventArgs e)

    Parameters

    Remarks

    Windows 8 behavior

    Windows 8 doesn't fire ManipulationCompleted in cases where the inertial phase has started (and ManipulationInertiaStarting has fired) but the user has tapped on the item before it's finished scrolling, which cancels the inertial phase visually. The issue is fixed starting with Windows 8.1; ManipulationCompleted is fired as soon as the tap action cancels the inertial phase.

    Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

  • OnManipulationStarted(ManipulationStartedRoutedEventArgs)
    OnManipulationStarted(ManipulationStartedRoutedEventArgs)
    OnManipulationStarted(ManipulationStartedRoutedEventArgs)
    OnManipulationStarted(ManipulationStartedRoutedEventArgs)

    Called before the ManipulationStarted event occurs.

    protected virtual void OnManipulationStarted(ManipulationStartedRoutedEventArgs e)protected virtual void OnManipulationStarted(ManipulationStartedRoutedEventArgs e)Protected Overridable Function OnManipulationStarted(e As ManipulationStartedRoutedEventArgs) As voidprotected virtual void OnManipulationStarted(ManipulationStartedRoutedEventArgs e)

    Parameters

  • OnManipulationStarting(ManipulationStartingRoutedEventArgs)
    OnManipulationStarting(ManipulationStartingRoutedEventArgs)
    OnManipulationStarting(ManipulationStartingRoutedEventArgs)
    OnManipulationStarting(ManipulationStartingRoutedEventArgs)

    Called before the ManipulationStarting event occurs.

    protected virtual void OnManipulationStarting(ManipulationStartingRoutedEventArgs e)protected virtual void OnManipulationStarting(ManipulationStartingRoutedEventArgs e)Protected Overridable Function OnManipulationStarting(e As ManipulationStartingRoutedEventArgs) As voidprotected virtual void OnManipulationStarting(ManipulationStartingRoutedEventArgs e)

    Parameters

    Remarks

    Windows 8 behavior

    Windows 8 had an issue with firing this event if multiple gestures happened in a short period of time. For example, Windows 8 might only fire ManipulationStarting for the first gesture and not the second. The issue is fixed starting with Windows 8.1; multiple starting gestures processed by the input system each fire a distinct ManipulationStarting event.

    Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

  • OnPointerCanceled(PointerRoutedEventArgs)
    OnPointerCanceled(PointerRoutedEventArgs)
    OnPointerCanceled(PointerRoutedEventArgs)
    OnPointerCanceled(PointerRoutedEventArgs)

    Called before the PointerCanceled event occurs.

    protected virtual void OnPointerCanceled(PointerRoutedEventArgs e)protected virtual void OnPointerCanceled(PointerRoutedEventArgs e)Protected Overridable Function OnPointerCanceled(e As PointerRoutedEventArgs) As voidprotected virtual void OnPointerCanceled(PointerRoutedEventArgs e)

    Parameters

  • OnPointerCaptureLost(PointerRoutedEventArgs)
    OnPointerCaptureLost(PointerRoutedEventArgs)
    OnPointerCaptureLost(PointerRoutedEventArgs)
    OnPointerCaptureLost(PointerRoutedEventArgs)

    Called before the PointerCaptureLost event occurs.

    protected virtual void OnPointerCaptureLost(PointerRoutedEventArgs e)protected virtual void OnPointerCaptureLost(PointerRoutedEventArgs e)Protected Overridable Function OnPointerCaptureLost(e As PointerRoutedEventArgs) As voidprotected virtual void OnPointerCaptureLost(PointerRoutedEventArgs e)

    Parameters

  • OnPointerEntered(PointerRoutedEventArgs)
    OnPointerEntered(PointerRoutedEventArgs)
    OnPointerEntered(PointerRoutedEventArgs)
    OnPointerEntered(PointerRoutedEventArgs)

    Called before the PointerEntered event occurs.

    protected virtual void OnPointerEntered(PointerRoutedEventArgs e)protected virtual void OnPointerEntered(PointerRoutedEventArgs e)Protected Overridable Function OnPointerEntered(e As PointerRoutedEventArgs) As voidprotected virtual void OnPointerEntered(PointerRoutedEventArgs e)

    Parameters

    Remarks

    Windows 8 behavior

    For Windows 8, generally the PointerEntered event won't fire if the onscreen cursor (or stylus or touchpoint) did not actually move. For example, PointerEntered doesn't fire if the mouse and its onscreen cursor remains stationary, and an object with a PointerEntered handler has its position translated or otherwise adjusted to move underneath the onscreen cursor. Or, PointerEntered doesn't fire if an element like a popup or flyout disappears and the pointer is now over a new element (but pointer hasn't moved yet). Related to this is the PointerExited behavior. For example, if a popup is dismissed programmatically, it won't fire PointerExited if the pointer didn't move as the cause of dismissing it. You would still get a PointerEntered event if the pointer moves while over the newly revealed element, but that's up to the user whether that will happen, and it happens at the time of movement, not the moment of dismissal. In short, trying to use the last element that fired PointerEntered for pointer state determination in the app UI isn't comprehensive in Windows 8, and there are many scenarios where PointerEntered and PointerExited won't pair up. This impacts the visual states for controls that use PointerEntered and PointerExited as triggers also.

    Starting with Windows 8.1, PointerExited is fired for any case where the pointer had at one time fired a PointerEntered event, but some UI state change happens where the pointer is no longer within that element. This includes cases where the whole element disappears. And if the pointer is now over a different element because a previous element disappeared, that element fires PointerEntered, even if the pointer never moves. Elements that set their Visibility to Collapsed programmatically is one way that elements might disappear from UI, and the Windows 8.1 behavior accounts for this and will fire PointerExited for the **Collapsed ** element and PointerEntered for the newly revealed element.

    If you migrate your app code from Windows 8 to Windows 8.1 you may want to account for this behavior change, because it results in PointerExited and PointerEntered being fired in cases where they wouldn't have fired before.

    Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

  • OnPointerExited(PointerRoutedEventArgs)
    OnPointerExited(PointerRoutedEventArgs)
    OnPointerExited(PointerRoutedEventArgs)
    OnPointerExited(PointerRoutedEventArgs)

    Called before the PointerExited event occurs.

    protected virtual void OnPointerExited(PointerRoutedEventArgs e)protected virtual void OnPointerExited(PointerRoutedEventArgs e)Protected Overridable Function OnPointerExited(e As PointerRoutedEventArgs) As voidprotected virtual void OnPointerExited(PointerRoutedEventArgs e)

    Parameters

    Remarks

    Windows 8 behavior

    For Windows 8, generally the PointerEntered event won't fire if the onscreen cursor (or stylus or touchpoint) did not actually move. For example, PointerEntered doesn't fire if the mouse and its onscreen cursor remains stationary, and an object with a PointerEntered handler has its position translated or otherwise adjusted to move underneath the onscreen cursor. Or, PointerEntered doesn't fire if an element like a popup or flyout disappears and the pointer is now over a new element (but pointer hasn't moved yet). Related to this is the PointerExited behavior. For example, if a popup is dismissed programmatically, it won't fire PointerExited if the pointer didn't move as the cause of dismissing it. You would still get a PointerEntered event if the pointer moves while over the newly revealed element, but that's up to the user whether that will happen, and it happens at the time of movement, not the moment of dismissal. In short, trying to use the last element that fired PointerEntered for pointer state determination in the app UI isn't comprehensive in Windows 8, and there are many scenarios where PointerEntered and PointerExited won't pair up. This impacts the visual states for controls that use PointerEntered and PointerExited as triggers also.

    Starting with Windows 8.1, PointerExited is fired for any case where the pointer had at one time fired a PointerEntered event, but some UI state change happens where the pointer is no longer within that element. This includes cases where the whole element disappears. And if the pointer is now over a different element because a previous element disappeared, that element fires PointerEntered, even if the pointer never moves. Elements that set their Visibility to Collapsed programmatically is one way that elements might disappear from UI, and the Windows 8.1 behavior accounts for this and will fire PointerExited for the **Collapsed ** element and PointerEntered for the newly revealed element.

    If you migrate your app code from Windows 8 to Windows 8.1 you may want to account for this behavior change, because it results in PointerExited and PointerEntered being fired in cases where they wouldn't have fired before.

    Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

  • OnPointerMoved(PointerRoutedEventArgs)
    OnPointerMoved(PointerRoutedEventArgs)
    OnPointerMoved(PointerRoutedEventArgs)
    OnPointerMoved(PointerRoutedEventArgs)

    Called before the PointerMoved event occurs.

    protected virtual void OnPointerMoved(PointerRoutedEventArgs e)protected virtual void OnPointerMoved(PointerRoutedEventArgs e)Protected Overridable Function OnPointerMoved(e As PointerRoutedEventArgs) As voidprotected virtual void OnPointerMoved(PointerRoutedEventArgs e)

    Parameters

  • OnPointerPressed(PointerRoutedEventArgs)
    OnPointerPressed(PointerRoutedEventArgs)
    OnPointerPressed(PointerRoutedEventArgs)
    OnPointerPressed(PointerRoutedEventArgs)

    Called before the PointerPressed event occurs.

    protected virtual void OnPointerPressed(PointerRoutedEventArgs e)protected virtual void OnPointerPressed(PointerRoutedEventArgs e)Protected Overridable Function OnPointerPressed(e As PointerRoutedEventArgs) As voidprotected virtual void OnPointerPressed(PointerRoutedEventArgs e)

    Parameters

    Remarks

    As it's implemented directly on Control, OnPointerPressed(PointerRoutedEventArgs) has an empty implementation. But each ancestor in a control's hierarchy may have provided an implementation. You won't be able to see this implementation because it's internal native code. In some cases a control will already have existing On* overrides that mark the event Handled. OnPointerPressed(PointerRoutedEventArgs) happens to be an On* event that several Windows Runtime XAML controls have provided overrides for. For example, ButtonBase has overridden OnPointerPressed(PointerRoutedEventArgs) to mark the event Handled. What all buttons do instead is to then raise the Click event that represents a higher-level event behavior for that control. That means you won't easily be able to handle PointerPressed on a button, but you probably shouldn't be handling it anyways for most scenarios. Just use Click instead.

  • OnPointerReleased(PointerRoutedEventArgs)
    OnPointerReleased(PointerRoutedEventArgs)
    OnPointerReleased(PointerRoutedEventArgs)
    OnPointerReleased(PointerRoutedEventArgs)

    Called before the PointerReleased event occurs.

    protected virtual void OnPointerReleased(PointerRoutedEventArgs e)protected virtual void OnPointerReleased(PointerRoutedEventArgs e)Protected Overridable Function OnPointerReleased(e As PointerRoutedEventArgs) As voidprotected virtual void OnPointerReleased(PointerRoutedEventArgs e)

    Parameters

  • OnPointerWheelChanged(PointerRoutedEventArgs)
    OnPointerWheelChanged(PointerRoutedEventArgs)
    OnPointerWheelChanged(PointerRoutedEventArgs)
    OnPointerWheelChanged(PointerRoutedEventArgs)

    Called before the PointerWheelChanged event occurs.

    protected virtual void OnPointerWheelChanged(PointerRoutedEventArgs e)protected virtual void OnPointerWheelChanged(PointerRoutedEventArgs e)Protected Overridable Function OnPointerWheelChanged(e As PointerRoutedEventArgs) As voidprotected virtual void OnPointerWheelChanged(PointerRoutedEventArgs e)

    Parameters

    Remarks

    Windows 8 behavior

    For Windows 8, track pad device gestures that were input-handled by a ScrollViewer control part were interpreted as mouse wheel input, and thus would fire a PointerWheelChanged event. Starting with Windows 8.1, ScrollViewer uses an underlying manipulation logic that interprets track pad gestures as actions that the ScrollViewer responds to, and thus the gesture is considered handled by the control and the PointerWheelChanged event is not fired anymore.

    If you migrate your app code from Windows 8 to Windows 8.1 you may want to account for this behavior change, because it results in PointerWheelChanged being fired in fewer cases. Also, the behavior that's now built-in to ScrollViewer may be duplicating what your handler would have done.

    Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

  • OnRightTapped(RightTappedRoutedEventArgs)
    OnRightTapped(RightTappedRoutedEventArgs)
    OnRightTapped(RightTappedRoutedEventArgs)
    OnRightTapped(RightTappedRoutedEventArgs)

    Called before the RightTapped event occurs.

    protected virtual void OnRightTapped(RightTappedRoutedEventArgs e)protected virtual void OnRightTapped(RightTappedRoutedEventArgs e)Protected Overridable Function OnRightTapped(e As RightTappedRoutedEventArgs) As voidprotected virtual void OnRightTapped(RightTappedRoutedEventArgs e)

    Parameters

    Remarks

    Windows 8 behavior

    Windows 8 had an issue with the data for the RightTapped event, where the X and Y values for the point you'd get from GetPosition(UIElement) were reversed (X was really Y; Y was really X). This issue has been fixed starting with Windows 8.1. But if you're retargeting a Windows 8 app for Windows 8.1, you might have had code that worked around this issue by swapping the X and Y back. If so, remove that code when you retarget because the issue is now fixed.

    Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

    Also, Windows 8 didn't include default key handling for Shift+F10 that would fire this event and then display context menus. Shift+F10 is typically a secondary key combination for the VK_APP virtual key value (the Properties key), and thus Shift+F10 might be expected to fire RightTapped too. This issue has been fixed starting with Windows 8.1; Shift+F10 now fires RightTapped. You can see this change as default event handling on some controls that have default context menus for text, such as TextBox, or when invoking custom menus and flyouts.

    Apps that were compiled for Windows 8 but running on Windows 8.1 do not use this Windows 8 behavior, they use the corrected Windows 8.1 behavior.

  • OnTapped(TappedRoutedEventArgs)
    OnTapped(TappedRoutedEventArgs)
    OnTapped(TappedRoutedEventArgs)
    OnTapped(TappedRoutedEventArgs)

    Called before the Tapped event occurs.

    protected virtual void OnTapped(TappedRoutedEventArgs e)protected virtual void OnTapped(TappedRoutedEventArgs e)Protected Overridable Function OnTapped(e As TappedRoutedEventArgs) As voidprotected virtual void OnTapped(TappedRoutedEventArgs e)

    Parameters

  • RemoveFocusEngagement()
    RemoveFocusEngagement()
    RemoveFocusEngagement()
    RemoveFocusEngagement()

    Releases focus from the control boundaries for a control that has focus engagement (for game pad/remote interaction).

    public void RemoveFocusEngagement()public void RemoveFocusEngagement()Public Function RemoveFocusEngagement() As voidpublic void RemoveFocusEngagement()

    Remarks

    Focus engagement makes it easier to use a game pad or remote control to interact with an app. Setting focus engagement does not affect keyboard or other input devices.

    When the IsFocusEngagementEnabled property is set to true, it marks the control as requiring focus engagement. This means that the user must press the A/Select button to "engage" the control and interact with it. When they are finished, they can press the B/Back button to disengage the control and navigate away from it. You can call RemoveFocusEngagement() to programmatically disengage a control.

    For more info, see the Focus engagement section of the Designing for Xbox and TV article.

    Version compatibility

    The RemoveFocusEngagement() method is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not call this method without first performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this method before you use it.

    if (ApiInformation.IsMethodPresent("Windows.UI.Xaml.Controls.Control", "RemoveFocusEngagement"))
    {
        control1.RemoveFocusEngagement();
    }
    
  • SetIsTemplateFocusTarget(FrameworkElement, Boolean)
    SetIsTemplateFocusTarget(FrameworkElement, Boolean)
    SetIsTemplateFocusTarget(FrameworkElement, Boolean)
    SetIsTemplateFocusTarget(FrameworkElement, Boolean)

    Sets the value of the IsTemplateFocusTargetProperty XAML attached property for a target element.

    public static void SetIsTemplateFocusTarget(FrameworkElement element, Boolean value)public static void SetIsTemplateFocusTarget(FrameworkElement element, Boolean value)Public Static Function SetIsTemplateFocusTarget(element As FrameworkElement, value As Boolean) As voidpublic static void SetIsTemplateFocusTarget(FrameworkElement element, Boolean value)

    Parameters

    Remarks

    This method is a utility method for the property system, and isn't used in most app scenarios. In most cases you set the IsTemplateFocusTargetProperty XAML attached property in XAML and won't need this method. For more info, see the IsTemplateFocusTargetProperty attached property.

  • SetIsTemplateKeyTipTarget(DependencyObject, Boolean)
    SetIsTemplateKeyTipTarget(DependencyObject, Boolean)
    SetIsTemplateKeyTipTarget(DependencyObject, Boolean)
    SetIsTemplateKeyTipTarget(DependencyObject, Boolean)

    Prerelease. Sets the value of the IsTemplateKeyTipTargetProperty XAML attached property for a target element.

    public static void SetIsTemplateKeyTipTarget(DependencyObject element, Boolean value)public static void SetIsTemplateKeyTipTarget(DependencyObject element, Boolean value)Public Static Function SetIsTemplateKeyTipTarget(element As DependencyObject, value As Boolean) As voidpublic static void SetIsTemplateKeyTipTarget(DependencyObject element, Boolean value)

    Parameters

    Remarks

    This method is a utility method for the property system, and isn't used in most app scenarios. In most cases you set the Control.IsTemplateFocusTarget XAML attached property in XAML and won't need this method. For more info, see the IsTemplateKeyTipTargetProperty attached property.

Events

  • FocusDisengaged
    FocusDisengaged
    FocusDisengaged
    FocusDisengaged

    Occurs when focus is released from the control boundaries (for game pad/remote interaction).

    public event TypedEventHandler FocusDisengagedpublic event TypedEventHandler FocusDisengagedPublic Event FocusDisengagedpublic event TypedEventHandler FocusDisengaged
    <control FocusDisengaged="eventhandler"/>
    

    Remarks

    For event data, see FocusDisengagedEventArgs.

    Focus engagement makes it easier to use a game pad or remote control to interact with an app. Setting focus engagement does not affect keyboard or other input devices.

    When the IsFocusEngagementEnabled property is set to true, it marks the control as requiring focus engagement. This means that the user must press the A/Select button to "engage" the control and interact with it. When they are finished, they can press the B/Back button to disengage the control and navigate away from it.

    For more info, see the Focus engagement section of the Designing for Xbox and TV article.

    Version compatibility

    The FocusDisengaged event is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not connect this event without first performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this event before you use it.

    <Slider x:Name="slider1" Loaded="Slider_Loaded"/>
    
    private void Slider_Loaded(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsEventPresent("Windows.UI.Xaml.Controls.Control", "FocusDisengaged"))
        {
            slider1.FocusDisengaged += Slider1_FocusDisengaged;
        }
    }
    
  • FocusEngaged
    FocusEngaged
    FocusEngaged
    FocusEngaged

    Occurs when focus is constrained within the control boundaries (for game pad/remote interaction).

    public event TypedEventHandler FocusEngagedpublic event TypedEventHandler FocusEngagedPublic Event FocusEngagedpublic event TypedEventHandler FocusEngaged
    <control FocusEngaged="eventhandler"/>
    

    Remarks

    For event data, see FocusEngagedEventArgs.

    Focus engagement makes it easier to use a game pad or remote control to interact with an app. Setting focus engagement does not affect keyboard or other input devices.

    When the IsFocusEngagementEnabled property is set to true, it marks the control as requiring focus engagement. This means that the user must press the A/Select button to "engage" the control and interact with it. When they are finished, they can press the B/Back button to disengage the control and navigate away from it.

    For more info about this property, see the Focus engagement section of the Designing for Xbox and TV article.

    Version compatibility

    The FocusEngaged event is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not connect this event without first performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this event before you use it.

    <Slider x:Name="slider1" Loaded="Slider_Loaded"/>
    
    private void Slider_Loaded(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsEventPresent("Windows.UI.Xaml.Controls.Control", "FocusEngaged"))
        {
            slider1.FocusEngaged += Slider1_FocusEngaged;
        }
    }
    
  • IsEnabledChanged
    IsEnabledChanged
    IsEnabledChanged
    IsEnabledChanged

    Occurs when the IsEnabled property changes.

    public event DependencyPropertyChangedEventHandler IsEnabledChangedpublic event DependencyPropertyChangedEventHandler IsEnabledChangedPublic Event IsEnabledChangedpublic event DependencyPropertyChangedEventHandler IsEnabledChanged
    <control IsEnabledChanged="eventhandler"/>
    

    Remarks

    Whenever IsEnabled changes, that fires the IsEnabledChanged event. Controls might handle this event in order to change the visual states. The event has DependencyPropertyChangedEventArgs data, so you can determine the old and new values without having to use your own flags.

    A control inherits the IsEnabled property from its parent control. For example, if a control that contains a button has IsEnabled set to false, the button's IsEnabled property is also false. When the parent's property changes, that fires IsEnabledChanged for each control where the value changes because of the value inheriting.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll