UIDatePicker Class Reference

Inherits from
UIControl : UIView : UIResponder : NSObject
Conforms to
NSCoding
NSCoding (UIView)
UIAppearance (UIView)
UIAppearanceContainer (UIView)
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UIDatePicker.h
Related sample code

Overview

The UIDatePicker class implements an object that uses multiple rotating wheels to allow users to select dates and times. iPhone examples of a date picker are the Timer and Alarm (Set Alarm) panes of the Clock application. You may also use a date picker as a countdown timer.

When properly configured, a UIDatePicker object sends an action message when a user finishes rotating one of the wheels to change the date or time; the associated control event is UIControlEventValueChanged. A UIDatePicker object presents the countdown timer but does not implement it; the application must set up an NSTimer object and update the seconds as they’re counted down.

UIDatePicker does not inherit from UIPickerView, but it manages a custom picker-view object as a subview.

Tasks

Managing the Date and Calendar

Configuring the Date Picker Mode

Configuring Temporal Attributes

Properties

calendar

The calendar to use for the date picker.

@property(nonatomic, copy) NSCalendar *calendar
Discussion

The default value of this property corresponds to the user’s current calendar as configured in Settings. This is equivalent to the value returned by calling the NSCalendar class method currentCalendar. Setting calendar to nil is equivalent to setting it to its default value.

Calendars specify the details of cultural systems used for reckoning time; they identify the beginning, length, and divisions of a year.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIDatePicker.h

countDownDuration

The seconds from which the countdown timer counts down.

@property(nonatomic) NSTimeInterval countDownDuration
Discussion

The NSTimeInterval value of this property indicates the seconds from which the date picker in countdown-timer mode counts down. If the mode of the date picker is not UIDatePickerModeCountDownTimer, this value is ignored. The default value is 0.0 and the maximum value is 23:59 (86,399 seconds).

Availability
  • Available in iOS 2.0 and later.
Declared In
UIDatePicker.h

date

The date displayed by the date picker.

@property(nonatomic, retain) NSDate *date
Discussion

The default is the date when the UIDatePicker object is created. The date is ignored in the mode UIDatePickerModeCountDownTimer; for that mode, the date picker starts at 0:00. Setting this property does not animate the date picker by spinning the wheels to the new date and time; to do that you must use the setDate:animated: method.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIDatePicker.h

datePickerMode

The mode of the date picker.

@property(nonatomic) UIDatePickerMode datePickerMode
Discussion

The value of this property indicates the mode of a date picker. It determines whether the date picker allows selection of a date, a time, both date and time, or a countdown time. The default mode is UIDatePickerModeDateAndTime. See “Date Picker Mode” for a list of mode constants.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIDatePicker.h

locale

The locale used by the date picker.

@property(nonatomic, retain) NSLocale *locale
Discussion

The default value is the current locale as returned by the currentLocale property of NSLocale, or the locale used by the date picker’s calendar. Locales encapsulate information about facets of a language or culture, such as the way dates are formatted.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIDatePicker.h

maximumDate

The maximum date that a date picker can show.

@property(nonatomic, retain) NSDate *maximumDate
Discussion

The property is an NSDate object or nil (the default), which means no maximum date. This property, along with the minimumDate property, lets you specify a valid date range. If the minimum date value is greater than the maximum date value, both properties are ignored. The minimum and maximum dates are also ignored in the countdown-timer mode (UIDatePickerModeCountDownTimer).

Availability
  • Available in iOS 2.0 and later.
Declared In
UIDatePicker.h

minimumDate

The minimum date that a date picker can show.

@property(nonatomic, retain) NSDate *minimumDate
Discussion

The property is an NSDate object or nil (the default), which means no minimum date. This property, along with the maximumDate property, lets you specify a valid date range. If the minimum date value is greater than the maximum date value, both properties are ignored. The minimum and maximum dates are also ignored in the countdown-timer mode (UIDatePickerModeCountDownTimer).

Availability
  • Available in iOS 2.0 and later.
Declared In
UIDatePicker.h

minuteInterval

The interval at which the date picker should display minutes.

@property(nonatomic) NSInteger minuteInterval
Discussion

You can use this property to set the interval displayed by the minutes wheel (for example, 15 minutes). The interval value must be evenly divided into 60; if it is not, the default value is used. The default and minimum values are 1; the maximum value is 30.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIDatePicker.h

timeZone

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

@property(nonatomic, retain) NSTimeZone *timeZone
Discussion

The default value is nil. which tells the date picker to use the current time zone as returned by localTimeZone (NSTimeZone) or the time zone used by the date picker’s calendar.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIDatePicker.h

Instance Methods

setDate:animated:

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

- (void)setDate:(NSDate *)date animated:(BOOL)animated
Parameters
date

An NSDate object representing the new date to display in the date picker.

animated

YES to animate the setting of the new date, otherwise NO. The animation rotates the wheels until the new date and time is shown under the highlight rectangle.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIDatePicker.h

Constants

Date Picker Mode

The mode of the date picker. 

typedef enum {
   UIDatePickerModeTime,
   UIDatePickerModeDate,
   UIDatePickerModeDateAndTime,
   UIDatePickerModeCountDownTimer
} UIDatePickerMode;
Constants
UIDatePickerModeTime

The date picker displays hours, minutes, and (optionally) an AM/PM designation. The exact items shown and their order depend upon the locale set. An example of this mode is [ 6 | 53 | PM ].

Available in iOS 2.0 and later.

Declared in UIDatePicker.h.

UIDatePickerModeDate

The date picker displays months, days of the month, and years. The exact order of these items depends on the locale setting. An example of this mode is [ November | 15 | 2007 ].

Available in iOS 2.0 and later.

Declared in UIDatePicker.h.

UIDatePickerModeDateAndTime

The date picker displays dates (as unified day of the week, month, and day of the month values) plus hours, minutes, and (optionally) an AM/PM designation. The exact order and format of these items depends on the locale set. An example of this mode is [ Wed Nov 15 | 6 | 53 | PM ].

Available in iOS 2.0 and later.

Declared in UIDatePicker.h.

UIDatePickerModeCountDownTimer

The date picker displays hour and minute values, for example [ 1 | 53 ]. The application must set a timer to fire at the proper interval and set the date picker as the seconds tick down.

Available in iOS 2.0 and later.

Declared in UIDatePicker.h.

Discussion

The mode determines whether dates, times, or both dates and times are displayed. You can also use it to specify the appearance of a countdown timer. You can set and retrieve the mode value through the datePickerMode property.



© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-11-29)

Did this document help you? Yes It's good, but... Not helpful...