UIDatePicker Class

UIDatePicker Class Reference

Contents

UIDatePicker Class Reference 3Overview 3Tasks 4

Managing the Date and Calendar 4Configuring the Date Picker Mode 4Configuring Temporal Attributes 4

Properties 4calendar 5countDownDuration 5date 6datePickerMode 6maximumDate 7minimumDate 7minuteInterval 7timeZone 8

Instance Methods 8setDate:animated: 8

Constants 9Date Picker Mode 9

Deprecated UIDatePicker Methods 11Deprecated in iOS 5.0 11

locale 11

Document Revision History 12

2010-11-29 | © 2010 Apple Inc. All Rights Reserved.

2

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 CoreDataBooks

DateCell

SimpleUndo

OverviewThe UIDatePicker class implements an object that uses multiple rotating wheels to allow users to selectdates and times. iPhone examples of a date picker are the Timer and Alarm (Set Alarm) panes of the Clockapplication. 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 rotatingone 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 setup 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.


3

UIDatePicker Class Reference

Tasks

Managing the Date and Calendar

calendar (page 5) propertyThe calendar to use for the date picker.

date (page 6) propertyThe date displayed by the date picker.

– setDate:animated: (page 8)Sets the date to display in the date picker, with an option to animate the setting.

timeZone (page 8) propertyThe time zone reflected in the date displayed by the date picker.

locale (page 11) property Deprecated in iOS 5.0The locale used by the date picker.

Configuring the Date Picker Mode

datePickerMode (page 6) propertyThe mode of the date picker.

Configuring Temporal Attributes

maximumDate (page 7) propertyThe maximum date that a date picker can show.

minimumDate (page 7) propertyThe minimum date that a date picker can show.

minuteInterval (page 7) propertyThe interval at which the date picker should display minutes.

countDownDuration (page 5) propertyThe seconds from which the countdown timer counts down.

PropertiesFor more about Objective-C properties, see “Properties” in The Objective-C Programming Language .

UIDatePicker Class ReferenceTasks


4

calendar

The calendar to use for the date picker.

@property(nonatomic, copy) NSCalendar *calendar

DiscussionThe default value of this property corresponds to the user’s current calendar as configured in Settings. This isequivalent to the value returned by calling the NSCalendar class method currentCalendar. Settingcalendar 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.

AvailabilityAvailable in iOS 2.0 and later.

See Also @property locale (page 11)

@property timeZone (page 8)

Declared inUIDatePicker.h

countDownDuration

The seconds from which the countdown timer counts down.

@property(nonatomic) NSTimeInterval countDownDuration

DiscussionThe NSTimeInterval value of this property indicates the seconds from which the date picker incountdown-timer mode counts down. If the mode of the date picker is notUIDatePickerModeCountDownTimer (page 10), this value is ignored. The default value is 0.0 and the maximumvalue is 23:59 (86,399 seconds).



UIDatePicker Class ReferenceProperties


5

date

The date displayed by the date picker.

@property(nonatomic, retain) NSDate *date

DiscussionThe default is the date when the UIDatePicker object is created. The date is ignored in the modeUIDatePickerModeCountDownTimer (page 10); for that mode, the date picker starts at 0:00. Setting this propertydoes not animate the date picker by spinning the wheels to the new date and time; to do that you must usethe setDate:animated: (page 8) method.


See Also– setDate:animated: (page 8)

Related Sample CodeCoreDataBooksSimpleUndo


datePickerMode

The mode of the date picker.

@property(nonatomic) UIDatePickerMode datePickerMode

DiscussionThe value of this property indicates the mode of a date picker. It determines whether the date picker allowsselection of a date, a time, both date and time, or a countdown time. The default mode isUIDatePickerModeDateAndTime (page 10). See “Date Picker Mode” (page 9) for a list of mode constants.





6

maximumDate

The maximum date that a date picker can show.

@property(nonatomic, retain) NSDate *maximumDate

DiscussionThe property is an NSDate object or nil (the default), which means no maximum date. This property, alongwith the minimumDate (page 7) property, lets you specify a valid date range. If the minimum date value isgreater than the maximum date value, both properties are ignored. The minimum and maximum dates arealso ignored in the countdown-timer mode (UIDatePickerModeCountDownTimer (page 10)).



minimumDate

The minimum date that a date picker can show.

@property(nonatomic, retain) NSDate *minimumDate

DiscussionThe property is an NSDate object or nil (the default), which means no minimum date. This property, alongwith the maximumDate (page 7) property, lets you specify a valid date range. If the minimum date value isgreater than the maximum date value, both properties are ignored. The minimum and maximum dates arealso ignored in the countdown-timer mode (UIDatePickerModeCountDownTimer (page 10)).



minuteInterval

The interval at which the date picker should display minutes.



7

@property(nonatomic) NSInteger minuteInterval

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



timeZone

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

@property(nonatomic, retain) NSTimeZone *timeZone

DiscussionThe 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.


See Also @property calendar (page 5)

@property locale (page 11)


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

UIDatePicker Class ReferenceInstance Methods


8

Parametersdate

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 thenew date and time is shown under the highlight rectangle.


See Also @property date (page 6)


Constants

Date Picker Mode

The mode of the date picker.

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

ConstantsUIDatePickerModeTime

The date picker displays hours, minutes, and (optionally) an AM/PM designation. The exact items shownand 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 dependson the locale setting. An example of this mode is [ November | 15 | 2007 ].



UIDatePicker Class ReferenceConstants


9

UIDatePickerModeDateAndTime

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



UIDatePickerModeCountDownTimer

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



DiscussionThe mode determines whether dates, times, or both dates and times are displayed. You can also use it tospecify the appearance of a countdown timer. You can set and retrieve the mode value through thedatePickerMode (page 6) property.

UIDatePicker Class ReferenceConstants


10

A method identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in iOS 5.0

locale

The locale used by the date picker. (Deprecated in iOS 5.0.)

@property(nonatomic, retain) NSLocale *locale

DiscussionThe default value is nil. which tells the date picker to use the current locale as returned by currentLocale(NSLocale) or the locale used by the date picker’s calendar. Locales encapsulate information about facets ofa language or culture, such as the way dates are formatted.


Deprecated in iOS 5.0.

See Also @property calendar (page 5)

@property timeZone (page 8)



11

Deprecated UIDatePicker Methods

This table describes the changes to UIDatePicker Class Reference .

NotesDate

Corrected the description for the calendar (page 5) property.2010-11-29

New document that describes the class for implementing a control thatallows users to select dates and times.

2008-05-01


12

Document Revision History

Apple Inc.© 2010 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApple’s copyright notice.

The Apple logo is a trademark of Apple Inc.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, iPhone, and Objective-Care trademarks of Apple Inc., registered in theUnited States and other countries.

IOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE.ASARESULT, THISDOCUMENT ISPROVIDED“AS IS,” AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and youmay also have otherrights which vary from state to state.

Documents

UIDatePicker Class