| -api-id | -api-type |
|---|---|
T:Windows.UI.Xaml.Controls.Control |
winrt 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.
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 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.
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 Control templates.
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 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.
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.
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 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.
Each OnEvent method represents a prewired event handler for the corresponding UIElement event. Practical controls that derive from Control can override the OnEvent 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 OnEvent 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 OnEvent overrides that mark the event Handled. Once you've provided an initial OnEvent override for a control, then any controls that you further derive from your own control class would also inherit the OnEvent 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 OnEvent method logic, but they need to use the handledEventsToo parameter for the UIElement.AddHandler method. For more info, see UIElement.AddHandler 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 method, with an empty definition. Within the base Control constructor, event wiring for all the relevant input events includes the OnEvent 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 OnEvent 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 OnEvent 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 OnEvent definitions in a particular control class can affect you as the consumer of the control even if you haven't overridden any OnEvent methods yourself. This is because the existing OnEvent definitions may have provided handling for an event that sets a Handled property value to true 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 OnEvent 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.
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 Control.FontSize value is implicitly inherited by ContentPresenter.FontSize based on the context within the template's definition, so the text within the Button will be presented using the Control.FontSize you set.
Control is the host service class for several XAML attached properties.
In order to support XAML processor access to the attached properties, and also to expose equivalent get and set operations to code, each XAML attached property has a pair of Get and Set accessor methods. Another way to get or set the value in code is to use the dependency property system, calling either GetValue or SetValue and passing the identifier field as the dependency property identifier.
| Attached property | Description |
|---|---|
| IsTemplateFocusTarget | Gets or sets a value that indicates whether this element is the part of a control template that has the focus visual. |
| IsTemplateKeyTipTarget | Gets or sets a value that indicates whether this element is the part of a control template where the KeyTip is placed. |
| Windows version | SDK version | Value added |
|---|---|---|
| 1607 | 14393 | ElementSoundMode |
| 1607 | 14393 | FocusDisengaged |
| 1607 | 14393 | FocusEngaged |
| 1607 | 14393 | IsFocusEngaged |
| 1607 | 14393 | IsFocusEngagementEnabled |
| 1607 | 14393 | RemoveFocusEngagement |
| 1607 | 14393 | RequiresPointer |
| 1607 | 14393 | XYFocusDown |
| 1607 | 14393 | XYFocusLeft |
| 1607 | 14393 | XYFocusRight |
| 1607 | 14393 | XYFocusUp |
| 1703 | 15063 | DefaultStyleResourceUri |
| 1703 | 15063 | GetIsTemplateKeyTipTarget |
| 1703 | 15063 | SetIsTemplateKeyTipTarget |
| 1709 | 16299 | OnCharacterReceived |
| 1709 | 16299 | OnPreviewKeyDown |
| 1709 | 16299 | OnPreviewKeyUp |
| 1809 | 17763 | BackgroundSizing |
| 1809 | 17763 | CornerRadius |
FrameworkElement, Controls by function, Control templates, Styling controls, Storyboarded animations for visual states, Focus visuals sample (Windows 10), Gamepad-style navigation (XAML) sample