Quickstart: Adding a TimePicker (XAML)

  • Article

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Learn how to use a TimePicker to let users pick a time value in your app using touch, mouse, or keyboard input.

Prerequisites

  • Windows 8.1 or Windows Phone 8.1
  • Microsoft Visual Studio 2013
  • We assume that you can add controls to a basic Windows Runtime app using C++, C#, or Visual Basic. For instructions on adding a control, see Quickstart: Adding controls and handling events.

When to use a time picker

The time picker gives you a standardized way to let users pick a time by using touch, mouse, or keyboard input. You can use the TimePicker control in its default form with a minimal amount of Extensible Application Markup Language (XAML) or other code, or you can customize it in a variety of ways. The TimePicker can use a 12-hour or 24-hour clock.

To let the user pick a date value, use a DatePicker control. See Quickstart: Adding a DatePicker.

For more info, see Guidelines for TimePickers.

Adding a TimePicker

To add a TimePicker in XAML

  1. Add a TimePicker control to a parent container.

  2. To assign a label to the time picker, set the Header property to a string value.

  3. To assign a name to the time picker, set the x:Name attribute to a string value.

    To refer to a control in code, it must have a name. Otherwise, a name is not required.

This example shows how to create a simple TimePicker with a header.

<TimePicker x:Name="arrivalTimePicker" Header="Arrival Time"/>

This TimePicker looks like this.

Using the time value

You can read the Time property in your code, or bind it to a System.TimeSpan (C#/VB) or Windows::Foundation::TimeSpan (C++) data object.

You typically read the Time property value when the user clicks a submit button on a form or takes some other action to indicate that data entry is complete. The TimePicker has a TimeChanged event. However, because the user sets the time in 3 different selectors, this event might occur several times before the user is done setting the time. If you use the TimePickerValueChangedEventArgs to get the date value in a TimeChanged event handler, you shouldn't assume that the time entry is final.

To use the time value

  1. Bind the Time property to a System.TimeSpan (C#/VB) or Windows::Foundation::TimeSpan (C++) data object.

    - or -

  2. Set the x:Name attribute on the TimePicker to access it by name from your code.

  3. Read the Time property.

This example shows how to read the Time property of a TimePicker named arrivalTimePicker. When the user clicks a submit button, the code in the button click handler verifies that the selected time is between 8AM and 5PM. The user is then notified whether the selected time is okay or needs to be corrected.

<StackPanel Orientation="Horizontal" Height="60">
    <TimePicker x:Name="arrivalTimePicker" Header="Arrival Time"/>
    <Button Content="Submit" Click="SubmitButton_Click" 
            Margin="5,0,0,-2" VerticalAlignment="Bottom"/>
    <TextBlock x:Name="Control1Output"/>
</StackPanel>

private void SubmitButton_Click(object sender, RoutedEventArgs e)
{
    if (VerifyTimeIsAvailable(arrivalTimePicker.Time) == true)
    {
        Control2Output.Text = string.Format("Thank you. Your appointment is set for {0}.",
                                             arrivalTimePicker.Time.ToString());

        // In a real app, you'd probably set a value on your data object, like this:
        //_reservation.ArrivalTime = arrivalTimePicker.Time; 
    }
    else
    {
        Control2Output.Text = "Sorry, we're only open from 8AM to 5PM.";
    }
}

private bool VerifyTimeIsAvailable(TimeSpan time)
{
    // Set open (8AM) and close (5PM) times.
    TimeSpan openTime = new TimeSpan(8, 0, 0);
    TimeSpan closeTime = new TimeSpan(17, 0, 0);
    
    if (time >= openTime && time < closeTime)
    {
        return true; // Open
    }

    return false; // Closed
}

Initializing the time value

By default, the TimePicker initializes to the current time. You can set the Time property to a different default time if you need to. You typically put this code wherever you have your other page initialization code, such as in the page's OnNavigatedTo method override, or in the time picker's Loaded event.

Here, the OnNavigatedTo method override is used. The Time property is set to default to 8 AM.

<TimePicker x:Name="arrivalTimePicker" Header="Arrival Time"/>

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    // Set the default time to 8 AM
    arrivalTimePicker.Time = new TimeSpan(8, 0, 0);
}

You can also set the Time value as an attribute in XAML. This is probably easiest if you're already declaring the TimePicker object in XAML and aren't using bindings for the Time value. Use a string in the form Hh:Mm where Hh is hours and can be between 0 and 23 and Mm is minutes and can be between 0 and 59. A "0" can be the initial character in either Hh or Mm and is typically included for clarity of any values 0 thru 9. For example, "9:5" and "09:05" are both valid and represent the same time, but "09:05" is easier to read in markup.

Here, the Time property is set in XAML.

<TimePicker x:Name="arrivalTimePicker" Header="Arrival Time" Time="08:00"/>

Setting the minute increment

By default, the minute selector shows the values 0-59 in 1-minute increments. You can change the time increments shown in the minute picker to values that make sense for your app. For example, in an appointment scheduling app, you can set 15 minute increments so users can select time slots only at 00, 15, 30, and 45 minutes past the hour.

To set the minute increment

  • Set the MinuteIncrement property to an integer from 0-59 that indicates the increments shown in the minute picker.

You can set the increment in the minute selector to a value that makes sense for your app. Here, the minute increment is 15 minutes.

<TimePicker x:Name="arrivalTimePicker" Header="Arrival Time" MinuteIncrement="15"/>

The TimePicker looks like this when the minute selector is opened.

Using a 24-hour clock

By default, the TimePicker shows time using a 12-hour clock and an AM/PM selector. You can change the time picker to use a 24-hour clock format. When you use the 24-hour clock, the AM/PM selector is automatically hidden. The 12- and 24-hour clocksare defined by the ClockIdentifiers class.

To specify a 12-hour or 24-hour clock

  1. To specify a 12-hour clock in XAML, set the ClockIdentifier property to the string value, "12HourClock".

    <TimePicker ClockIdentifier="12HourClock"/>

  2. To specify a 12-hour clock in code, set the ClockIdentifier property to the string value returned by the ClockIdentifiers.TwelveHour property.

    TimePicker timePicker1 = new TimePicker();
timePicker1.ClockIdentifier = Windows.Globalization.ClockIdentifiers.TwelveHour;

  3. To specify a 24-hour clock in XAML, set the ClockIdentifier property to the string value, "24HourClock".

    <TimePicker ClockIdentifier="24HourClock"/>

  4. To specify a 24-hour clock in code, set the ClockIdentifier property to the string value returned by the ClockIdentifiers.TwentyFourHour property.

    TimePicker timePicker1 = new TimePicker();
timePicker1.ClockIdentifier = Windows.Globalization.ClockIdentifiers.TwentyFourHour;

A TimePicker with a 24-hour clock looks like this. The AM/PM selector is automatically hidden.

Samples

To learn more about the TimePicker control, download the XAML DatePicker and TimePicker controls sample.

Summary and next steps

You learned how to use a TimePicker control to let users set a time value in your app.

Learn how to use a DatePicker control to let users pick a date value in the Quickstart: Adding a DatePicker tutorial.