Skip to end of metadata
Go to start of metadata

Remarks

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.

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.

XAML
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:
XAML
C#

UXButton implements ICommandSource interface which exposes Command, CommandParameter 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.

XAML

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.

In addition to command button, you can also use UXButton as a toggle button, group button, or a navigation button. To learn more about UXButton features, see UXButton Overview.

Working with NavigateUri Property and TargetName Property

UXButton implements INavigationSource interface, which exposes NavigateUri and TargetName property. Therefore, UXButton can be used to facilitate navigation between pages in a valid navigation host such as UXFrame. To learn more about the navigation host and related features, see Navigation Overview.

The following example shows how to use NavigateUri property to navigate the pages in the project by using UXNavigationButton. The UXNavigationButton is a specialized button control derives from UXButton, featuring more sophisticated navigation visual state and features.

XAML

The result looks like the following figure.

For a more complete walkthrough that shows how to define the UXFrame and use UXNavigationButton to navigate to the pages in the frame, see Walkthrough: Create Simple Website Navigation Using Frame, Navigation Button and Hyperlink.

If your page contains multiple UXFrame instances, you can set the UXNavigationButton to navigate the page on a particular frame by setting the TargetName property of the button to the name of the target frame.
Beside local pages, you can also use UXButton to navigate to external URIs such as a web page. Certain safe protocols are supported as well, including http, https, and mailto.

If you navigate to an external web page, you can also set the target where the page will be displayed. You set the TargetName property to one of the following values:

  • _blank
  • _self (default)
  • _parent
  • _top

Although UXButton implements the core navigation functionality, it is recommended to use UXNavigationButton to perform page navigation as it is designed with more sophisticated visual states and built-in features to track the navigation process. The following example shows how to use UXNavigationButton to navigate to external URIs.

XAML

Definition

Summary

The following table summarizes the members exposed in this class.

Public Constructors

UXButton Constructor()Initializes a new instance of UXButton class.
UXButton Constructor(string)Initializes a new UXButton instance with specified text.

Public Properties

ContentEffectSpecifies the pixel shader effect applied to the content element of the button.
DialogResultSpecifies identifiers to indicate the return value of a dialog box when this button is clicked.
DisplayModeSpecifies the mode of the content presentation.
GlassBackgroundRepresents the brush used to draw the glass element of the button.
GlassMarginGets or sets a value that determines the margin of the glass element.
IconGets or sets the icon that appears in the button.
ImageHeightSpecifies the height applied to the icon element.
ImageWidthSpecifies the width applied to the icon element.
InnerBorderVisibilitySpecifies whether the inner border should be visible.
InnerCornerRadiusInner corner radius.
NavigateUriGets or sets the URI to navigate when this button is clicked.
RootElementGets the root element.
StylishLabelGets the stylish label.
TargetNameGets or sets the name of a target window or frame that will display the content specified by the NavigationUri property.
TextImageRelationSpecifies the position of the text and image relative to each other on a control.

Protected Properties

ProductProduct Info.

Fields

ContentEffectPropertyIdentifies the ContentEffect dependency property.
DialogResultPropertyIdentifies the DialogResult dependency property.
DisplayModePropertyIdentifies the DisplayMode dependency property.
GlassBackgroundPropertyIdentifies the GlassBackground dependency property.
GlassMarginPropertyIdentifies the GlassMargin dependency property
IconPropertyIdentifies the Icon dependency property.
ImageHeightPropertyIdentifies the ImageHeight dependency property.
ImageWidthPropertyIdentifies the ImageWidth dependency property.
InnerBorderVisibilityPropertyIdentifies the InnerBorderVisibility dependency property.
InnerCornerRadiusPropertyIdentifies the InnerCornerRadius dependency property.
NavigateUriPropertyIdentifies the NavigationUri dependency property.
TargetNamePropertyIdentifies the TargetName dependency property.
TextImageRelationPropertyIdentifies the TextImageRelation dependency property.

Public Methods

InitializeTemplates()Initializes control templates.
OnApplyTemplate()Builds the visual tree for the UXButton when a new template is applied.
UpdateVisualState(bool)Updates the visual state of this control.

Protected Methods

ButtonBase_OnClick()Calls the original OnClick implementation of ButtonBase.
ChangeVisualState(bool)Change visual state.
DisplayModeChanged()Called when the DisplayMode property is changed.
OnClick()Called before the Click event occurs.
OnCornerRadiusChanged(CornerRadius)Called when the value of CornerRadius property changes.
OnInitializeCommandDefault(ICommand)Called when the Command is initialized.
OnLostKeyboardFocus(KeyboardFocusChangedEventArgs)Inheritors should override this method to handle custom logic for LostKeyboardFocus event.
TryNavigateCore()Called when the button is about to perform navigation based on specified URI.

Events

VisualStateChangedOccurs when the visual state of this control has changed.

Public Constructors

public UXButton()

Initializes a new instance of UXButton class.

public UXButton(string text)

Initializes a new UXButton instance with specified text.

Parameters

textThe text that represents the button's content.

 

Public Properties

public Effect ContentEffect { get; set; }

Specifies the pixel shader effect applied to the content element of the button.

public DialogResult DialogResult { get; set; }

Specifies identifiers to indicate the return value of a dialog box when this button is clicked.

public ContentType DisplayMode { get; set; }

Specifies the mode of the content presentation.

public Brush GlassBackground { get; set; }

Represents the brush used to draw the glass element of the button.

public Thickness GlassMargin { get; set; }

Gets or sets a value that determines the margin of the glass element.

public ImageSource Icon { get; set; }

Gets or sets the icon that appears in the button.

public double ImageHeight { get; set; }

Specifies the height applied to the icon element.

public double ImageWidth { get; set; }

Specifies the width applied to the icon element.

public Visibility InnerBorderVisibility { get; set; }

Specifies whether the inner border should be visible.

public CornerRadius InnerCornerRadius { get; set; }

Inner corner radius.

public Uri NavigateUri { get; set; }

Gets or sets the URI to navigate when this button is clicked.

public Grid RootElement { get; }

Gets the root element.

public StylishLabel StylishLabel { get; }

Gets the stylish label.

public string TargetName { get; set; }

Gets or sets the name of a target window or frame that will display the content specified by the NavigationUri property.

public TextImageRelation TextImageRelation { get; set; }

Specifies the position of the text and image relative to each other on a control.

Protected Properties

protected ProductInfo Product { get; }

Product Info.

Fields

public static readonly DependencyProperty ContentEffectProperty

Identifies the ContentEffect dependency property.

public static readonly DependencyProperty DialogResultProperty

Identifies the DialogResult dependency property.

public static readonly DependencyProperty DisplayModeProperty

Identifies the DisplayMode dependency property.

public static readonly DependencyProperty GlassBackgroundProperty

Identifies the GlassBackground dependency property.

public static readonly DependencyProperty GlassMarginProperty

Identifies the GlassMargin dependency property

public static readonly DependencyProperty IconProperty

Identifies the Icon dependency property.

public static readonly DependencyProperty ImageHeightProperty

Identifies the ImageHeight dependency property.

public static readonly DependencyProperty ImageWidthProperty

Identifies the ImageWidth dependency property.

public static readonly DependencyProperty InnerBorderVisibilityProperty

Identifies the InnerBorderVisibility dependency property.

public static readonly DependencyProperty InnerCornerRadiusProperty

Identifies the InnerCornerRadius dependency property.

public static readonly DependencyProperty NavigateUriProperty

Identifies the NavigationUri dependency property.

public static readonly DependencyProperty TargetNameProperty

Identifies the TargetName dependency property.

public static readonly DependencyProperty TextImageRelationProperty

Identifies the TextImageRelation dependency property.

Public Methods

public void InitializeTemplates()

Initializes control templates.

public void OnApplyTemplate()

Builds the visual tree for the UXButton when a new template is applied.

public void UpdateVisualState(bool useTransition)

Updates the visual state of this control.

Parameters

useTransition 

 

Protected Methods

protected void ButtonBase_OnClick()

Calls the original OnClick implementation of ButtonBase.

protected void ChangeVisualState(bool useTransitions)

Change visual state.

Parameters

useTransitionsUse transition.

 

protected void DisplayModeChanged()

Called when the DisplayMode property is changed.

protected void OnClick()

Called before the Click event occurs.

protected void OnCornerRadiusChanged(CornerRadius newRadius)

Called when the value of CornerRadius property changes.

Parameters

newRadiusThe new corner radius.

 

protected void OnInitializeCommandDefault(ICommand command)

Called when the Command is initialized.

Parameters

commandThe command to be initialized.

 

protected void OnLostKeyboardFocus(KeyboardFocusChangedEventArgs e)

Inheritors should override this method to handle custom logic for LostKeyboardFocus event.

Parameters

eKeyboardFocusChangedEventArgs object.

 

protected bool TryNavigateCore()

Called when the button is about to perform navigation based on specified URI.

Return Types

True if the navigation succeed.

 

Events

public event EventHandler<VisualStateChangedEventArgs> VisualStateChanged

Occurs when the visual state of this control has changed.

  • No labels