Button class
[This documentation is preliminary and is subject to change.]
Applies to: Metro style apps only
Represents a templated button control that interprets a Click user interaction.
Inheritance
Syntax
<Button .../> -or- <Button> singleObject </Button> -or- <Button ...>stringContent</Button>
XAML Values
- singleObject
-
A single object element that declares the content. This is often a container, such as a Panel derived class, so that content can be composited.
- stringContent
-
A string that is displayed as content, using the presenter settings in the default template ContentPresenter.
Attributes
- MarshalingBehaviorAttribute(Agile)
- ThreadingAttribute(Both)
- VersionAttribute(NTDDI_WIN8)
- WebHostHiddenAttribute()
Members
The Button class has these types of members:
Constructors
The Button class has these constructors.
| Constructor | Description |
|---|---|
| Button | Initializes a new instance of the Button class. |
Events
The Button class has these events.
| Event | Description |
|---|---|
| Click | Occurs when a button control is clicked. (Inherited from ButtonBase) |
| DoubleTapped | Occurs when an otherwise unhandled DoubleTap interaction occurs over the hit test area of this element. (Inherited from UIElement) |
| DragEnter | Occurs when the input system reports an underlying drag event with this element as the target. (Inherited from UIElement) |
| DragLeave | Occurs when the input system reports an underlying drag event with this element as the origin. (Inherited from UIElement) |
| DragOver | Occurs when the input system reports an underlying drag event with this element as the potential drop target. (Inherited from UIElement) |
| Drop | Occurs when the input system reports an underlying drop event with this element as the drop target. (Inherited from UIElement) |
| GotFocus | Occurs when a UIElement receives focus. (Inherited from UIElement) |
| Holding | Occurs when an otherwise unhandled Hold interaction occurs over the hit test area of this element. (Inherited from UIElement) |
| IsEnabledChanged | Occurs when the IsEnabled property changes. (Inherited from Control) |
| KeyDown | Occurs when a keyboard key is pressed while the UIElement has focus. (Inherited from UIElement) |
| KeyUp | Occurs when a keyboard key is released while the UIElement has focus. (Inherited from UIElement) |
| LayoutUpdated | Occurs when the layout of the visual tree changes. (Inherited from FrameworkElement) |
| Loaded | Occurs when a FrameworkElement has been constructed and added to the object tree. (Inherited from FrameworkElement) |
| LostFocus | Occurs when a UIElement loses focus. (Inherited from UIElement) |
| ManipulationCompleted | Occurs when a manipulation on the UIElement is complete. (Inherited from UIElement) |
| ManipulationDelta | Occurs when the input device changes position during a manipulation. (Inherited from UIElement) |
| ManipulationInertiaStarting | Occurs when the input device loses contact with the UIElement object during a manipulation and inertia begins. (Inherited from UIElement) |
| ManipulationStarted | Occurs when an input device begins a manipulation on the UIElement. (Inherited from UIElement) |
| ManipulationStarting | Occurs when the manipulation processor is first created. (Inherited from UIElement) |
| PointerCanceled | Occurs when a pointer that made contact abnormally loses contact. (Inherited from UIElement) |
| PointerCaptureLost | Occurs when pointer capture previously held by this element moves to another element or elsewhere. (Inherited from UIElement) |
| PointerEntered | Occurs when a pointer enters the hit test area of this element. (Inherited from UIElement) |
| PointerExited | Occurs when a pointer leaves the hit test area of this element. (Inherited from UIElement) |
| PointerMoved | Occurs when a pointer moves while the pointer remains within the hit test area of this element. (Inherited from UIElement) |
| PointerPressed | Occurs when the pointer device initiates a Press action within this element. (Inherited from UIElement) |
| PointerReleased | Occurs when the pointer device that previously initiated a Press action is released, while within this element. (Inherited from UIElement) |
| PointerWheelChanged | Occurs when the delta value of a pointer wheel changes. (Inherited from UIElement) |
| RightTapped | Occurs when a right-tap input stimulus happens while the pointer is over the element. (Inherited from UIElement) |
| SizeChanged | Occurs when either the ActualHeight or the ActualWidth property changes value on a FrameworkElement. (Inherited from FrameworkElement) |
| Tapped | Occurs when an otherwise unhandled Tap interaction occurs over the hit test area of this element. (Inherited from UIElement) |
| Unloaded | Occurs when this object is no longer connected to the main object tree. (Inherited from FrameworkElement) |
Methods
The Button class has these methods. It also inherits methods from the Object class.
| Method | Description |
|---|---|
| AddHandler | 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 for a routed event case that had already been marked as handled by another element along the event route. (Inherited from UIElement) |
| ApplyTemplate | Loads the relevant control template so that its parts can be referenced. (Inherited from Control) |
| Arrange | 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. (Inherited from UIElement) |
| ArrangeOverride | Provides the behavior for the Arrange pass of layout. Classes can override this method to define their own Arrange pass behavior. (Inherited from FrameworkElement) |
| CapturePointer | Sets pointer capture to a UIElement. (Inherited from UIElement) |
| ClearValue | Clears the local value of a dependency property. (Inherited from DependencyObject) |
| FindName | Retrieves an object that has the specified identifier name. (Inherited from FrameworkElement) |
| FindSubElementsForTouchTargeting | Enables a UIElement subclass to expose child elements that assist with resolving touch targeting. (Inherited from UIElement) |
| Focus | Attempts to set the focus on the control. (Inherited from Control) |
| GetAnimationBaseValue | Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject) |
| GetTemplateChild | Retrieves the named element in the instantiated ControlTemplate visual tree. (Inherited from Control) |
| GetValue | Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject) |
| InvalidateArrange | Invalidates the arrange state (layout) for a UIElement. After the invalidation, the UIElement will have its layout updated, which will occur asynchronously. (Inherited from UIElement) |
| InvalidateMeasure | Invalidates the measurement state (layout) for a UIElement. (Inherited from UIElement) |
| Measure | 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. (Inherited from UIElement) |
| MeasureOverride | Provides the behavior for the Measure pass of the layout cycle. Classes can override this method to define their own Measure pass behavior. (Inherited from FrameworkElement) |
| OnApplyTemplate | 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. (Inherited from FrameworkElement) |
| OnContentChanged | Invoked when the value of the Content property changes. (Inherited from ContentControl) |
| OnContentTemplateChanged | Invoked when the value of the ContentTemplate property changes. (Inherited from ContentControl) |
| OnContentTemplateSelectorChanged | Invoked when the value of the ContentTemplateSelector property changes. (Inherited from ContentControl) |
| OnCreateAutomationPeer | When implemented in a derived class, returns class-specific AutomationPeer implementations for the UI Automation infrastructure. (Inherited from UIElement) |
| OnDisconnectVisualChildren | Override this method to implement how layout and logic should behave when items are removed from a class-specific content or children property. (Inherited from UIElement) |
| OnDoubleTapped | Called before the DoubleTapped event occurs. (Inherited from Control) |
| OnDragEnter | Called before the DragEnter event occurs. (Inherited from Control) |
| OnDragLeave | Called before the DragLeave event occurs. (Inherited from Control) |
| OnDragOver | Called before the DragOver event occurs. (Inherited from Control) |
| OnDrop | Called before the Drop event occurs. (Inherited from Control) |
| OnGotFocus | Called before the GotFocus event occurs. (Inherited from Control) |
| OnHolding | Called before the Holding event occurs. (Inherited from Control) |
| OnKeyDown | Called before the KeyDown event occurs. (Inherited from Control) |
| OnKeyUp | Called before the KeyUp event occurs. (Inherited from Control) |
| OnLostFocus | Called before the LostFocus event occurs. (Inherited from Control) |
| OnManipulationCompleted | Called before the ManipulationCompleted event occurs. (Inherited from Control) |
| OnManipulationDelta | Called before the ManipulationDelta event occurs. (Inherited from Control) |
| OnManipulationInertiaStarting | Called before the ManipulationInertiaStarting event occurs. (Inherited from Control) |
| OnManipulationStarted | Called before the ManipulationStarted event occurs. (Inherited from Control) |
| OnManipulationStarting | Called before the ManipulationStarting event occurs. (Inherited from Control) |
| OnPointerCanceled | Called before the PointerCanceled event occurs. (Inherited from Control) |
| OnPointerCaptureLost | Called before the PointerCaptureLost event occurs. (Inherited from Control) |
| OnPointerEntered | Called before the PointerEntered event occurs. (Inherited from Control) |
| OnPointerExited | Called before the PointerExited event occurs. (Inherited from Control) |
| OnPointerMoved | Called before the PointerMoved event occurs. (Inherited from Control) |
| OnPointerPressed | Called before the PointerPressed event occurs. (Inherited from Control) |
| OnPointerReleased | Called before the PointerReleased event occurs. (Inherited from Control) |
| OnPointerWheelChanged | Called before the PointerWheelChanged event occurs. (Inherited from Control) |
| OnRightTapped | Called before the RightTapped event occurs. (Inherited from Control) |
| OnTapped | Called before the Tapped event occurs. (Inherited from Control) |
| ReadLocalValue | Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject) |
| ReleasePointerCapture | Releases pointer captures for capture of one specific pointer by this UIElement. (Inherited from UIElement) |
| ReleasePointerCaptures | Releases all pointer captures held by this element. (Inherited from UIElement) |
| RemoveHandler | Removes the specified routed event handler from this UIElement. Typically the handler in question was added by AddHandler. (Inherited from UIElement) |
| SetBinding | Attaches a binding to a FrameworkElement, using the provided binding object. (Inherited from FrameworkElement) |
| SetValue | Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject) |
| TransformToVisual | Returns a transform object that can be used to transform coordinates from the UIElement to the specified object. (Inherited from UIElement) |
| UpdateLayout | Ensures that all positions of child objects of a UIElement are properly updated for layout. (Inherited from UIElement) |
Properties
The Button class has these properties.
| Property | Access type | Description |
|---|---|---|
| Read-only | Gets the rendered height of a FrameworkElement. (Inherited from FrameworkElement) | |
| Read-only | Gets the rendered width of a FrameworkElement. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets a value that determines whether this UIElement can be a drop target for purposes of drag-and-drop operations. (Inherited from UIElement) | |
| Read/write | Gets or sets a brush that provides the background of the control. (Inherited from Control) | |
| Read-only | Gets a Uniform Resource Identifier (URI) that represents the base Uniform Resource Identifier (URI) for an XAML-constructed object at XAML load time. This property is useful for Uniform Resource Identifier (URI) resolution at run time. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets a brush that describes the border background of a control. (Inherited from Control) | |
| Read/write | Gets or sets the border thickness of a control. (Inherited from Control) | |
| Read/write | Gets or sets a value that indicates that rendered content should be cached when possible. (Inherited from UIElement) | |
| Read/write | Gets or sets the uniform spacing between characters, in units of 1/1000 of an em. (Inherited from Control) | |
| Read/write | Gets or sets when the Click event occurs, in terms of device behavior. (Inherited from ButtonBase) | |
| Read-only | Identifies the ClickMode dependency property (Inherited from ButtonBase) | |
| Read/write | Gets or sets the RectangleGeometry used to define the outline of the contents of a UIElement. (Inherited from UIElement) | |
| Read/write | Gets or sets the command to invoke when this button is pressed. (Inherited from ButtonBase) | |
| Read/write | Gets or sets the parameter to pass to the Command property. (Inherited from ButtonBase) | |
| Read-only | Identifier for the CommandParameter dependency property. (Inherited from ButtonBase) | |
| Read-only | Identifier for the Command dependency property. (Inherited from ButtonBase) | |
| Read/write | Gets or sets the value of the ContentControl dependency property. (Inherited from ContentControl) | |
| Read/write | Gets or sets the data template that is used to display the content of the ContentControl. (Inherited from ContentControl) | |
| Read/write | Gets or sets a selection object that changes the DataTemplate to apply for content, based on processing information about the content item or its container at run time. (Inherited from ContentControl) | |
| Read/write | Gets or sets the collection of Transition style elements that apply to the content of a ContentControl. (Inherited from ContentControl) | |
| Read/write | Gets or sets the data context for a FrameworkElement when it participates in data binding. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the key that references the default style for the control. (Inherited from Control) | |
| Read-only | Gets the size that this UIElement computed during the measure pass of the layout process. (Inherited from UIElement) | |
| Read-only | Gets the CoreDispatcher that this object is associated with. (Inherited from DependencyObject) | |
| Read/write | Gets or sets the direction in which text and other UI elements flow within any parent element that controls their layout. (Inherited from FrameworkElement) | |
| Read-only | Gets a value that specifies whether this control has focus, and the mode by which focus was obtained. (Inherited from Control) | |
| Read/write | Gets or sets the font used to display text in the control. (Inherited from Control) | |
| Read/write | Gets or sets the size of the text in this control. (Inherited from Control) | |
| Read/write | Gets or sets the degree to which a font is condensed or expanded on the screen. (Inherited from Control) | |
| Read/write | Gets or sets the style in which the text is rendered. (Inherited from Control) | |
| Read/write | Gets or sets the thickness of the specified font. (Inherited from Control) | |
| Read/write | Gets or sets a brush that describes the foreground color. (Inherited from Control) | |
| Read/write | Gets or sets the suggested height of a FrameworkElement. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the horizontal alignment characteristics that are applied to a FrameworkElement when it is composed in a layout parent, such as a panel or items control. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the horizontal alignment of the control's content. (Inherited from Control) | |
| Read/write | Gets or sets a value that determines whether the DoubleTapped event can originate from that element. (Inherited from UIElement) | |
| Read/write | Gets or sets a value indicating whether the user can interact with the control. (Inherited from Control) | |
| Read/write | Gets or sets whether the contained area of this UIElement can return true values for hit testing. (Inherited from UIElement) | |
| Read/write | Gets or sets a value that determines whether the Holding event can originate from that element. (Inherited from UIElement) | |
| Read-only | Gets a value indicating whether a device pointer is located over this button control. (Inherited from ButtonBase) | |
| Read-only | Identifies the IsPointerOver dependency property. (Inherited from ButtonBase) | |
| Read-only | Gets a value that indicates whether a ButtonBase is currently in a pressed state. (Inherited from ButtonBase) | |
| Read-only | Identifies the IsPressed dependency property. (Inherited from ButtonBase) | |
| Read/write | Gets or sets a value that determines whether the RightTapped event can originate from that element. (Inherited from UIElement) | |
| Read/write | Gets or sets a value that indicates whether a control is included in tab navigation. (Inherited from Control) | |
| Read/write | Gets or sets a value that determines whether the Tapped event can originate from that element. (Inherited from UIElement) | |
| Read/write | Gets or sets localization/globalization language information that applies to a FrameworkElement. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the ManipulationModes value used for UIElement behavior and interaction with gestures. (Inherited from UIElement) | |
| Read/write | Gets or sets the outer margin of a FrameworkElement. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the maximum height constraint of a FrameworkElement. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the maximum width constraint of a FrameworkElement. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the minimum height constraint of a FrameworkElement. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the minimum width constraint of a FrameworkElement. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the identifying name of the object. When a XAML processor creates the object tree from XAML markup, run-time code can refer to the XAML-declared object by this name. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the degree of the object's opacity. (Inherited from UIElement) | |
| Read/write | Gets or sets the padding inside a control. (Inherited from Control) | |
| Read-only | Gets the parent object of this FrameworkElement in the object tree. (Inherited from FrameworkElement) | |
| Read-only | Gets the set of all captured pointers, represented as Pointer values. (Inherited from UIElement) | |
| Read/write | Gets or sets the perspective projection (3-D effect) to apply when rendering this element. (Inherited from UIElement) | |
| Read-only | Gets the final render size of a UIElement. (Inherited from UIElement) | |
| Read/write | Gets or sets transform information that affects the rendering position of a UIElement. (Inherited from UIElement) | |
| Read/write | Gets or sets the origin point of any possible render transform declared by RenderTransform, relative to the bounds of the UIElement. (Inherited from UIElement) | |
| Read/write | Gets the locally defined resource dictionary. In XAML, you can establish resource items as child object elements of a frameworkElement.Resources property element, through XAML implicit collection syntax. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets an instance Style that is applied for this object during rendering. (Inherited from FrameworkElement) | |
| Read/write | 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. (Inherited from Control) | |
| Read/write | Gets or sets a value that modifies how tabbing and TabIndex work for this control. (Inherited from Control) | |
| Read/write | Gets or sets an arbitrary object value that can be used to store custom information about this object. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets a control template. (Inherited from Control) | |
| Read/write | Gets or sets the collection of Transition style elements that apply to a UIElement. (Inherited from UIElement) | |
| Read-only | Gets the collection of triggers for animations that are defined for a FrameworkElement. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets a value that determines whether rendering for the object and its visual subtree should use rounding behavior that aligns rendering to whole pixels. (Inherited from UIElement) | |
| Read/write | Gets or sets the vertical alignment characteristics that are applied to a FrameworkElement when it is composed in a parent object such as a panel or items control. (Inherited from FrameworkElement) | |
| Read/write | Gets or sets the vertical alignment of the control's content. (Inherited from Control) | |
| Read/write | Gets or sets the visibility of a UIElement. A UIElement that is not visible is not rendered and does not communicate its desired size to layout. (Inherited from UIElement) | |
| Read/write | Gets or sets the width of a FrameworkElement. (Inherited from FrameworkElement) |
Examples
The following example shows three buttons that respond to clicks in three different ways based on their ClickMode property value.
-
Hover - When the mouse pointer hovers over the first button, the foreground color of the button changes.
-
Press - When the left mouse button is pressed over the second button, the foreground color of the button changes.
-
Release - When the mouse button is pressed and released when over the third button, the button resets the foreground color of the other two buttons to their original color.
<StackPanel x:Name="LayoutRoot" Margin="10"> <Button x:Name="btn1" Content="Hover to Click" Click="OnClick1" ClickMode="Hover" Margin="5" Width="150" HorizontalAlignment="Left" Foreground="Green"/> <TextBlock x:Name="text1" Margin="5,8,0,0" /> <Button x:Name="btn2" Content="Press to Click" Click="OnClick2" ClickMode="Press" Margin="5,5,5,5" Width="150" HorizontalAlignment="Left" Foreground="Blue"/> <TextBlock x:Name="text2" Margin="5,8,0,0" /> <Button x:Name="btn3" Content="Reset" Click="OnClick3" ClickMode="Release" Margin="5,5,5,5" Width="150" HorizontalAlignment="Left"/> <TextBlock x:Name="text3" Margin="5,8,0,0" /> </StackPanel>
void OnClick1(object sender, RoutedEventArgs e) { btn1.Foreground = new SolidColorBrush(Colors.Blue); text1.Text = "Click event occurs on Hover."; text2.Text = ""; text3.Text = ""; } void OnClick2(object sender, RoutedEventArgs e) { btn2.Foreground = new SolidColorBrush(Colors.Green); text1.Text = ""; text2.Text = "Click event occurs on Press."; text3.Text = ""; } void OnClick3(object sender, RoutedEventArgs e) { btn1.Foreground = new SolidColorBrush(Colors.Green); btn2.Foreground = new SolidColorBrush(Colors.Blue); text1.Text = ""; text2.Text = ""; text3.Text = "Click event occurs on Release."; }
Requirements
|
Minimum supported client | Windows 8 Release Preview |
|---|---|
|
Minimum supported server | Windows Server 2012 |
|
Namespace |
|
|
Metadata |
|
See also
Build date: 5/22/2012