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.

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 FrameworkElement.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 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 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.

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 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 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 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.

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 method, with an empty definition. Within the base Control 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 and OnKeyDown. 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 set Handled to true and that prevented PointerPressed from propagating to your instance and app code. For OnKeyDown, 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 method with handledEventsToo. For more info see AddHandler 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.

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.

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.

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.

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.

ClipPropertyClipPropertyClipPropertyClipProperty

CompositeModeCompositeModeCompositeModeCompositeMode

Gets or sets a property that declares alternate composition and blending modes for the element in its parent layout and window. This is relevant for elements that are involved in a mixed XAML / Microsoft DirectX UI.

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:

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:

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.

Remarks

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.

FlowDirectionFlowDirectionFlowDirectionFlowDirection

Gets or sets the direction in which text and other UI elements flow within any parent element that controls their layout. This property can be set to either LeftToRight or RightToLeft. Setting FlowDirection to RightToLeft on any element sets the alignment to the right, the reading order to right-to-left and the layout of the control to flow from right to left.

A value of the enumeration. A value of Unfocused indicates that the control does not have focus.

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 and then gets the value of FocusState from the sender. If FocusState is Keyboard, then a different named visual state that includes a focus rectangle is loaded, by calling GoToState. 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.

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 Programmatic, the keyboard focus visual is shown even if the prior method of input was pointer. In Windows 8.1, when you call Focus (FocusState.Programmatic), the prior FocusState, either Pointer or Keyboard, 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.Programmatic), the FocusState property will have a value of either Pointer or Keyboard.

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 Programmatic 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.

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 brush that paints the foreground of the control. The default value is a SolidColorBrush with color of Black.

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.

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 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.

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.

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.

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

Additional features and requirements

Device family

Windows 10 Anniversary Edition (introduced v10.0.14393.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v3)

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.

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.

IsTabStopIsTabStopIsTabStopIsTabStop

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

public : Platform::Boolean IsTabStop { get; set; }

bool IsTabStop(); void IsTabStop(bool istabstop);

public bool IsTabStop { get; set; }

Public ReadWrite Property IsTabStop As bool

<control IsTabStop="bool"/>

Value

boolbool

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 method, Focus 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.

The amount of space between the content of a Control and its Margin or Border. The default is a Thickness with values of 0 on all four sides.

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.

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.

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.

The template that defines the appearance of the Control. The ControlTemplate must have exactly one root element as its content.

Examples

This example shows a more complete control template defined as a Style and Setter with Setter.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.

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 Control.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.

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.

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.

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.

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.

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.

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.

Methods

Adds a routed event handler for a specified routed event, adding the handler to the handler collection on the current element. Specify handledEventsToo as true to have the provided handler be invoked even if the event is handled elsewhere.

ApplyTemplate()ApplyTemplate()ApplyTemplate()ApplyTemplate()

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

public : Platform::Boolean ApplyTemplate()

bool ApplyTemplate() const;

public bool ApplyTemplate()

Public Function ApplyTemplate() As bool

Returns

boolbool

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.

Arrange(Rect)Arrange(Rect)Arrange(Rect)Arrange(Rect)

Positions child objects and determines a size for a UIElement. Parent objects that implement custom layout for their child elements should call this method from their layout override implementations to form a recursive layout update.

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 Unfocused 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.Programmatic as the parameter to indicate the control obtained focus through a deliberate call to the Focus method. For example, if clicking an "Edit" button causes focus to be set on a TextBox, use the Programmatic focus state.

Pass FocusState.Pointer if you’re setting focus as the direct result of a pointer interaction. Pass FocusState.Keyboard 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 Keyboard focus state when you call Focus in your key press handler.

Note

In Windows 8, when FocusState is Programmatic, the keyboard focus visual is shown even if the prior method of input was pointer. In Windows 8.1, when you call Focus (FocusState.Programmatic), the prior FocusState, either Pointer or Keyboard, 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.Programmatic), the FocusState property will have a value of either Pointer or Keyboard.

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 Programmatic and the keyboard focus visual is shown.

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 Control.IsTemplateKeyTipTarget attached property.

InvalidateMeasureInvalidateMeasureInvalidateMeasureInvalidateMeasure

Measure(Size)Measure(Size)Measure(Size)Measure(Size)

Updates the DesiredSize of a UIElement. Typically, objects that implement custom layout for their layout children call this method from their own MeasureOverride implementations to form a recursive layout update.

OnApplyTemplateOnApplyTemplateOnApplyTemplateOnApplyTemplate

Invoked whenever application code or internal processes (such as a rebuilding layout pass) call ApplyTemplate. In simplest terms, this means the method is called just before a UI element displays in your app. Override this method to influence the default post-template logic of a class.

Remarks

As it's implemented directly on Control, OnKeyDown 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.

Remarks

As it's implemented directly on Control, OnKeyUp 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.

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.

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.

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.

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.

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.

Remarks

As it's implemented directly on Control, OnPointerPressed 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 happens to be an On* event that several Windows Runtime XAML controls have provided overrides for. For example, ButtonBase has overridden OnPointerPressed 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 UIElement.PointerPressed on a button, but you probably shouldn't be handling it anyways for most scenarios. Just use Click instead.

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.

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 RightTappedRoutedEventArgs.GetPosition 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.

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

public : void RemoveFocusEngagement()

void RemoveFocusEngagement() const;

public void RemoveFocusEngagement()

Public Function RemoveFocusEngagement() As void

Additional features and requirements

Device family

Windows 10 Anniversary Edition (introduced v10.0.14393.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v3)

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.

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.

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 Control.IsTemplateKeyTipTarget attached property.

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.

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.

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.

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.

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.

PointerPressedPointerPressedPointerPressedPointerPressed

PointerReleasedPointerReleasedPointerReleasedPointerReleased

Occurs when the pointer device that previously initiated a Press action is released, while within this element. Note that the end of a Press action is not guaranteed to fire a PointerReleased event; other events may fire instead. For more info, see Remarks.