Skip to end of metadata
Go to start of metadata

UXButton is a rich, full-featured button control that supports routed command, navigation, and standards-compliance usability features such as default focus, visual transitions, keyboard support, and more.

On this page:

Using UXButton

UXButton is primarily used to represent a command in a user interface application. Typical example of commands that are commonly found in an application are Save, OK and Cancel button. UXButton is a fundamental UI control that generally consisted of a visual interface and a text that users can click to execute the command associated to the button. Alternatively, users can press Enter key or Spacebar key to execute the command when the button has focus.

You can use UXButton in a number of scenarios such as discussed in the following sections.

Command Button

The primary function of UXButton is a command button which represents an action that will be executed when the button is clicked.

The following example shows how to define a simple UXButton using XAML.

Handling Click Event

The simplest way to respond to a button click is by handling its Click event. You add the Click handler in the XAML and write the logic in code to respond the Click event such as shown in the following example:

Using Commanding

UXButton implements ICommandSource interface which exposes CommandCommandParameter and CommandTarget property. You can assign a command to a UXButton by setting its Command property to the target command existed in your application. With commanding, you can separate the actual logic of the command from the command definition, which is ideal for MVVM pattern application. To learn about MVVM pattern, see MVVM Pattern Overview.

The following example shows how to assign a Copy command to a UXButton.


For more information on how to implement routed command in your application, see How-to: Implement a RoutedCommand. For more information about the basics of commanding concept, see Commanding Overview.

Toggle Button

You can use UXButton as a toggle button by setting its IsToggleButton to true, such as shown in the following example.


The following figure shows the comparison between the normal and toggled state.

To obtain the current toggle state of the button, you get the boolean value from the IsChecked property. You set the IsChecked property to true to set the button to show as toggled initially.

UXButton raises IsCheckedChanged event when the value of IsChecked property is changed. The IsCheckedChanged is a bubbling routed event which can be handled from any nodes in the parent visual tree. To learn how to handle a routed event, see How to: Handle a Routed Event. To learn more about the routed event concept, see Routed Events Overview.

For more advanced toggle button that supports indeterminate state, see UXToggleButton.

Group Button

In addition to toggle button, UXButton can also be used to represent a selection across multiple buttons that associated to a value defined in GroupName. In this case, clicking a button will automatically uncheck the other buttons within the same group.

The following example shows how to setup the UXButton as group button.


In the above example, clicking on Options 3 button makes the button as checked and automatically set the IsChecked property of other buttons to false, such as illustrated in the following figure.

Navigation Button

UXButton implements INavigationSource interface, which means that you can use UXButton to perform navigation to pages through the exposed NavigateUri property.

The following example shows how to setup the UXButton to perform navigation to a UXPage in a navigation frame.


You can also create user-friendly URI to simplify the URI reference and enhance navigation experience. For more information about ClientUI navigation framework and its features, see Navigation Overview.


Exploring UXButton Features

ImageContent Model

UXButton uses content control architecture which allows you to put any arbitrary object to its ContentUXButton extends the content model with ImageContent presentation to provide an efficient way to display an image in addition to the content itself.

The following example shows how to setup the UXButton to use ImageContent presentation and specify an image to the content.


The result looks like the following figure.

You can also customize a variety of settings related to the ImageContent model such as TextImageRelation, ImageWidth and ImageHeight. To learn more about this content model, see Content Model Overview.

Default and Cancel Button

UXButton implements solid focus scope architecture that made several advanced features possible, such as setting a button as a default button, or as a cancel button. When a UXButton acts as a default button, pressing Enter key on any valid input controls within the same focus scope will automatically execute the Click event of the button. Similarly, when UXButton acts as a cancel button, pressing Escape key would respectively execute the Click event of the matched button. This design conforms to the user experience standards in user interface application design. To learn more about user experience features, see User Experiences Overview.

To set a UXButton as default button, set its IsDefault property to true. Likewise, set the IsCancel property of a UXButton to set it as cancel button.

The following example shows how to setup the UXButton as default and cancel button.


In addition, a default button would be animated when the logical focus is within the same focus scope. This allows users to become aware that pressing the Enter key on the current focus will execute the particular button. The animation can be disabled through the EnableFocusAnimation Property property.

Using DialogResult with UXDialogBox

UXButton implements an advanced feature called DialogResult, which automatically sets the dialog result value of a dialog box. This feature makes UI development easier by eliminating the needs to write extensive code.

The DialogResult works in conjunction with the Default and Cancel feature such as described in the previous section. For example, you may want to set the DialogResult of a UXButton to OK for default button, and set it to Cancel for a cancel button.

The following example shows how to use the DialogResult feature in the buttons defined within a UXDialogBox.


For more information about using dialog boxes, see Window and Dialog Boxes Overview

Built-in UX Implementation

UXButton features several user experience features out-of-the-box such as keyboard access key support, focus animation, and keyboard focus visual.

These features can be customized through the following properties:

To learn more about the behaviors and details of each UX implementation, see User Experiences Overview.


Customizing UXButton Appearance

You can easily customize the UXButton appearance through the following properties.

  • Background
  • BorderBrush
  • BorderThickness
  • CornerRadius
  • ContentEffect
  • GlassBackground
  • InnerBorderVisibility

If you would like to completely customize the control appearance or if you want to change the styles of each visual state, you can edit the template of the control and do the modification accordingly.

To learn more how to customize the template and visual states, see Styles and Template Overview.


Samples and Walkthroughs

For the list of ClientUI walkthroughs, see Walkthroughs and How-to Topics.

For the list of ClientUI samples available in local installation, see Locating the Samples in Local Installation.