Class

UIDatePicker

A UIDatePicker object is a control used for the inputting of date and time values. You can use a date picker to allow a user to enter either a point in time (calendar date, time value or both) or a time interval (for example for a timer). The date picker reports interactions to its associated target object.

Overview

To add a date picker to your interface:

  • Set the date picker mode at creation time.

  • Supply additional configuration options such as minimum and maximum dates if required.

  • Connect an action method to the date picker.

  • Set up Auto Layout rules to govern the position of the date picker in your interface.

You use a date picker only for handling the selection of times and dates. If you want to handle the selection of arbitrary items from a list, use a UIPickerView object.

Configuring a Date Picker

The configuration of a date picker is determined by the datePickerMode property, whose value you can set programmatically or in Interface Builder. For modes that include date or time values, you can also configure the locale, calendar, and time zone information as appropriate. The date picker uses that information when formatting date and time values for the current user, and defaults to the device’s locale, calendar and time zone. The date property represents the currently selected date in the form of an NSDate object, which is calendar and time zone agnostic.

To limit the range of dates that the user can select, assign values to the minimumDate and maximumDate properties. You can also use the minuteInterval property to allow only specific time increments.

Setting the datePickerMode property to countDownTimer allows the user to choose a duration in hours and minutes. When in this mode, the countDownDuration property represents the displayed duration, measured in seconds as an TimeInterval. Note that even though you set this property in seconds, the date picker can only show values in minutes.

Figure 1 shows a date picker configured with the datePickerMode property set to countDownTimer and the minuteInterval property set to 5. The value of countDownDuration is currently 4500.

Figure 1

Date picker displaying a duration.

Responding to User Interaction

Date pickers use the Target-Action design pattern to notify your app when the user changes the selected date. To be notified when the date picker’s value changes, register your action method with the valueChanged event. At runtime the date picker calls your methods in response to the user selecting a date or time.

You connect a date picker to your action method using the addTarget(_:action:for:) method or by creating a connection in Interface Builder. The signature of an action method takes one of three forms, which are listed in Listing 1. Choose the form that provides the information that you need to respond to the value change in the date picker.

Listing 1

Action methods for date pickers

@IBAction func doSomething()
@IBAction func doSomething(sender: UIDatePicker)
@IBAction func doSomething(sender: UIDatePicker, forEvent event: UIEvent)

Debugging Date Pickers

When debugging issues with date pickers, watch for these common pitfalls:

  • The minimum date must be earlier than the maximum date. Check the bounds of your minimumDate and maximumDate properties. If the maximum date is less than the minimum date, both properties are ignored, and the date picker allows the selection of any date value. The minimum and maximum dates are ignored in the countdown-timer mode (countDownTimer).

  • The minute interval must be a divisor of 60. Check that the minuteInterval value can be evenly divided into 60; otherwise, the default value is used (1).

Interface Builder Attributes

Table 1 lists the core attributes that you configure for date pickers in Attributes Inspector within Interface Builder.

Table 1

Core attributes

Attribute

Description

Mode

The date picker mode. Determines whether the date picker should display a time, a date, a time and date or a countdown interval. Access this value at runtime with the datePickerMode property.

Locale

The locale associated with the date picker. This property allows you to override the system default with a specific locale. You can access this attribute programmatically with the locale property.

Interval

The granularity of the minutes spinner, if it is shown in the current mode. The default value is 1, and the maximum value is 30. The value you choose must be a divisor of 60 (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30). Access this value at runtime with the minuteInterval property.

Table 2 lists the attributes that control the display of date and time in a date picker.

Table 2

Time attributes

Attribute

Description

Date

The initial date that the date picker will display. Defaults to the current date, but you can set a custom value. This attribute is equivalent to setting the date property programmatically.

Constraints

The range of selectable dates displayed by the date picker. To use a dynamic range, configure the minimumDate and maximumDate properties programmatically. The date picker ignores these options when the Mode attribute is set to Count Down Timer.

Timer

The initial value of the date picker when used in countdown timer mode. The value is measured in seconds, but the display is in minutes.

For information about the date picker’s inherited Interface Builder attributes, see UIControl and UIView.

Appearance

The appearance of UIDatePicker is not customizable.

You should integrate date pickers in your layout using Auto Layout. Although date pickers can be resized, they should be used at their intrinsic content size.

Internationalization

Date pickers handle their own internationalization; the only thing you need to do is specify the appropriate locale. You can choose a specific locale for your date picker to appear in by setting the Locale (locale) field in Attributes Inspector. This changes the language that the date picker uses for display, but also the format of the date and time (for example, certain locales present days before month names, or prefer a 24-hour clock over a 12-hour clock). The width of the date picker automatically accommodates for the length of the localization. To use the system language, leave this property set to default.

For more information, see Internationalization and Localization Guide.

Accessibility

Date pickers are accessible by default. Each time component in the date picker is its own accessibility element and has the Adjustable (UIAccessibilityTraitAdjustable) trait.

The accessibility value, traits, and hint for each picker wheel are spoken back to the user when VoiceOver is enabled on a device. VoiceOver speaks this information when a user taps on a picker wheel. For example, when a user taps the hours column on the Add Alarm page (Clock > Alarm > Add), VoiceOver speaks the following:

"2 o'clock. Picker item. Adjustable. Swipe up or down with one finger to adjust the value.”

For further information about making iOS controls accessible, see the Accessibility Programming Guide for iOS.

Symbols

Managing the Date and Calendar

var calendar: Calendar!

The calendar to use for the date picker.

var date: Date

The date displayed by the date picker.

var locale: Locale?

The locale used by the date picker.

func setDate(Date, animated: Bool)

Sets the date to display in the date picker, with an option to animate the setting.

var timeZone: TimeZone?

The time zone reflected in the date displayed by the date picker.

Configuring the Date Picker Mode

var datePickerMode: UIDatePickerMode

The mode of the date picker.

Configuring Temporal Attributes

var maximumDate: Date?

The maximum date that a date picker can show.

var minimumDate: Date?

The minimum date that a date picker can show.

var minuteInterval: Int

The interval at which the date picker should display minutes.

var countDownDuration: TimeInterval

The value displayed by the date picker when the mode property is set to countDownTimer.

Constants

UIDatePickerMode

The mode displayed by the date picker.

Relationships

Inherits From

Conforms To