Based on the flexible UXSpinner control, UXDomainUpDown provides an easy data input with up down spin buttons to cycle through the items. With various available properties, such as InvalidInputAction, IsCyclic, IsEditable, and ErrorMessage, UXDomainUpDown gives you full control over the input behaviors.

Using UXDomainUpDown

UXDomainUpDown control displays a single value that is selected from an Object collection by clicking the up or down buttons of the control. Users can also enter text in the control, unless the IsEditable property is set to false (the string typed in must match an item in the collection to be accepted). You can also can get the current item, index and value using CurrentItem, CurrentIndex and Value property.

The following code shows how to create a simple UXDomainUpDown control.

<Grid>
    <Intersoft:UXDomainUpDown Width="150" >
            <Systems:String>School</Systems:String>
            <Systems:String>University</Systems:String>
            <Systems:String>Work</Systems:String>
            <Systems:String>Mall</Systems:String>
            <Systems:String>Home</Systems:String>
        </Intersoft:UXDomainUpDown>
</Grid>

Data Binding

UXDomainUpDown derives from ItemsControl therefore you can bind a collection of data to UXDomainUpDown. To learn more about data binding, see Data Binding Overview. To bind the data, you can either use ItemTemplate or the member path properties such as:

• ValueMemberPath
• ValueMemberBinding

When ValueMemberPath and ValueMemberBinding is set, the editing mode will used this for the value. You can also customize the display mode using item template.

The following code shows you how to customize the display using item template and MVVM pattern.

public class Book : ModelBase
{
    private string _title;
    private string _image;

    public String Title
    {
        get { return this._title; }
        set
        {
            if (this._title != value)
            {
                this._title = value;
                OnPropertyChanged("Title");
            }
        }
    }
    public String Image
    {
        get { return this._image; }
        set
        {
            if (this._image != value)
            {
                this._image = value;
                OnPropertyChanged("Image");
            }
        }
    }
}

public partial class MainPage : Page
{
    public MyTests()
    {
        InitializeComponent();
        ObservableCollection<Book> datas = new ObservableCollection<Book>();
        datas.Add(new Book() { Title = "American Cooking", Image = "/TestingMySpinner;component/Images/Books/American_cooking_1.jpg" });
        datas.Add(new Book() { Title = "Anthologies", Image = "/TestingMySpinner;component/Images/Books/Anthologies_1.jpg" });
        datas.Add(new Book() { Title = "Application and Software", Image = "/TestingMySpinner;component/Images/Books/Application_and_Software_1.jpg" });
        datas.Add(new Book() { Title = "Baking", Image = "/TestingMySpinner;component/Images/Books/Baking_1.jpg" });
        datas.Add(new Book() { Title = "Computer hardware", Image = "/TestingMySpinner;component/Images/Books/Computer_hardware_1.jpg" });
        domain.ItemsSource = datas;
    }
}

public class RentalBookViewModel : ViewModelBase
{
    private ObservableCollection<Book> _books;

    public ObservableCollection<Book> Books
    {
        get { return this._books; }
        set
        {
            if (this._books != value)
            {
                this._books = value;
                OnPropertyChanged("Books");
            }
        }
    }

    public RentalBookViewModel()
    {
        Books = new ObservableCollection<Book>();
        Books.Add(new Book() { Title = "American Cooking", Image = "/MVVMTesting;component/Images/Books/American_cooking_1.jpg" });
        Books.Add(new Book() { Title = "Anthologies", Image = "/MVVMTesting;component/Images/Books/Anthologies_1.jpg" });
        Books.Add(new Book() { Title = "Application and Software", Image = "/MVVMTesting;component/Images/Books/Application_and_Software_1.jpg" });
        Books.Add(new Book() { Title = "Baking", Image = "/MVVMTesting;component/Images/Books/Baking_1.jpg" });
        Books.Add(new Book() { Title = "Computer hardware", Image = "/MVVMTesting;component/Images/Books/Computer_hardware_1.jpg" });
    }
}

<Intersoft:UXPage.Resources>
    <ViewModel:RentalBookViewModel x:Key="RentalBookViewModel" />
</Intersoft:UXPage.Resources>

<Grid x:Name="LayoutRoot" DataContext="{StaticResource RentalBookViewModel}">
    <Intersoft:UXDomainUpDown x:Name="domain" Height="100" Width="100" ItemsSource="{Binding Books}" ValueMemberPath="Title">
        <Intersoft:UXDomainUpDown.ItemTemplate>
            <DataTemplate>
                <Grid>
                    <Image Source="{Binding Image}" />
                </Grid>
            </DataTemplate>
        </Intersoft:UXDomainUpDown.ItemTemplate>
    </Intersoft:UXDomainUpDown>
</Grid>

The following code shows how to set the value using ValueMemberPath.

<Grid>
    <Intersoft:UXDomainUpDown x:Name="domain" Height="100" Width="170" ValueMemberPath="Title" >
        <Intersoft:UXDomainUpDown.ItemTemplate>
            <DataTemplate>
                <Grid>
                    <Image Source="{Binding Image}" />
                </Grid>
            </DataTemplate>
        </Intersoft:UXDomainUpDown.ItemTemplate>
    </Intersoft:UXDomainUpDown>
</Grid>

The following code shows how to set the value using ValueMemberBinding.

<Grid>
    <Intersoft:UXDomainUpDown x:Name="domain" Height="100" Width="170" ValueMemberBinding="{Binding Title}" >
        <Intersoft:UXDomainUpDown.ItemTemplate>
            <DataTemplate>
                <Grid>
                    <Image Source="{Binding Image}" />
                </Grid>
            </DataTemplate>
        </Intersoft:UXDomainUpDown.ItemTemplate>
    </Intersoft:UXDomainUpDown>
</Grid>

Customizing the Spin Behavior

You can do a spin either using keyboard up and down key, or clicking on the spinner button. By default, when it reaches the first or end of the item, the up or down button will be automatically disabled. You can change that behavior by setting the IsCyclic property to true. In such case, it will cycle the selected item, if the item reaches the first or the end of item, it will start again from the beginning or the end from the item collection.

Editing Behavior

The editing mode can be activated by setting IsEditable property to True. You can enter the editing mode by just clicking into the control, or press enter when the control is in display mode. In edit mode, you can input any values you desire. The input text will be processed when the control loses its focus, or enter key is pressed.

UXDomainUpDown requires an exact match between the input value and the item in the collection. In the case that inpu value doesn't match any items in the collection, an invalid action will occur. You can cancel the editing mode by presssing Escape key.

By default, the InvalidInputAction property for this control is set to TextBoxCannotLostFocus. You can set the InvalidInputAction property to UseFallbackItem. When this value is set, the control will fall back the item to the default value in the case of invalid input value. You set the default fallback item through the FallBackItem property.

The following illustration shows the control with TextBoxCannotLostFocus mode.

Notice that there is an error message displayed, you also can change the error message in the ErrorMessage property.

The following illustration shows the control with UseFallbackItem mode.

Understanding UXDomainUpDown Commands

UXDomainUpDown is built around the commanding semantics which allows the value changing interaction to be executed through declarative definition in the XAML markup. The commanding semantics is also an ideal approach for MVVM pattern development.

UXDomainUpDown already includes several predefined commands to change the selected value that you can use in your application.

• Increase

  Gets a command that increases the item index of the UXDomainUpDown.

  Increase command will be invoked when you perform the following action:

  • Press the spin up button.
  • Press the up keyboard key.
• Decrease

  Gets a command that decreases the item index of the UXDomainUpDown.

  Decrease command will be invoked when you perform the following action:

  • Press the spin down button.
  • Press the down keyboard key.

Although these commands are already registered in the elements of UXDomainUpDown, you can still register these commands to other UIElement outside UXDomainUpDown scope. For example, you can have a UXButton to perform Decrease command. For more information on how to register UXDomainUpDown commands to other type of UIElement, see How-to: Register UXDomainUpDown Command to UXButton.

Customizing UXDomainUpDown Appearance

The default spinner button is always set to the right of the control. To change the alignment of the spinner button, you set the SpinnerAlignment property to the Left. In case that the spinner button is not desired, you can set the SpinnerVisibility property to Collapsed. Although the spinner buttons are not shown, you can still perform the increment and decrement by pressing the Up or Down arrow key.

The following code shows how to change the spinner alignment in UXDomainUpDown.

<Grid>
    <UXDomainUpDown SpinnerAlignment="Left" Width="150">
        <Systems:String>School</Systems:String>
        <Systems:String>University</Systems:String>
        <Systems:String>Work</Systems:String>
        <Systems:String>Mall</Systems:String>
        <Systems:String>Home</Systems:String>
    </Intersoft:UXDomainUpDown>
</Grid>

The following code shows how to change the spinner visibility in UXDomainUpDown.

<Grid>
    <Intersoft:UXDomainUpDown SpinnerVisibility="Collapsed" Width="150">
        <Systems:String>School</Systems:String>
        <Systems:String>University</Systems:String>
        <Systems:String>Work</Systems:String>
        <Systems:String>Mall</Systems:String>
        <Systems:String>Home</Systems:String>
    </Intersoft:UXDomainUpDown>
</Grid>

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 how to customize the template and visual states, see Styles and Template Overview.