You are on page 1of 13

UIDatePicker Class Reference

Contents

UIDatePicker Class Reference 3


Overview 3 Tasks 4 Managing the Date and Calendar 4 Configuring the Date Picker Mode 4 Configuring Temporal Attributes 4 Properties 4 calendar 5 countDownDuration 5 date 6 datePickerMode 6 maximumDate 7 minimumDate 7 minuteInterval 7 timeZone 8 Instance Methods 8 setDate:animated: 8 Constants 9 Date Picker Mode 9

Deprecated UIDatePicker Methods 11


Deprecated in iOS 5.0 11 locale 11

Document Revision History 12

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

UIDatePicker Class Reference

Inherits from Conforms to

UIControl : UIView : UIResponder : NSObject NSCoding NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) NSObject (NSObject)

Framework Availability Declared in Related sample code

/System/Library/Frameworks/UIKit.framework Available in iOS 2.0 and later. UIDatePicker.h CoreDataBooks DateCell SimpleUndo

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 theyre counted down.
UIDatePicker does not inherit from UIPickerView, but it manages a custom picker-view object as a subview.

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

UIDatePicker Class Reference Tasks

Tasks
Managing the Date and Calendar
calendar (page 5)

property

The calendar to use for the date picker.


date (page 6)

property

The 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. property

timeZone (page 8)

The time zone reflected in the date displayed by the date picker.
locale (page 11)

property Deprecated in iOS 5.0

The locale used by the date picker.

Configuring the Date Picker Mode


datePickerMode (page 6)

property

The mode of the date picker.

Configuring Temporal Attributes


maximumDate (page 7)

property

The maximum date that a date picker can show.


minimumDate (page 7)

property

The minimum date that a date picker can show.


minuteInterval (page 7)

property

The interval at which the date picker should display minutes.


countDownDuration (page 5)

property

The seconds from which the countdown timer counts down.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

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

UIDatePicker Class Reference 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 users 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
@property locale (page 11) @property timeZone (page 8)

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 (page 10), 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

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

UIDatePicker Class Reference Properties

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 (page 10); 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: (page 8) method. Availability Available in iOS 2.0 and later. See Also
setDate:animated:

(page 8)

Related Sample Code CoreDataBooks SimpleUndo

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 (page 10). See Date Picker Mode (page 9) for a list of mode constants. Availability Available in iOS 2.0 and later. Declared in
UIDatePicker.h

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

UIDatePicker Class Reference Properties

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 (page 7) 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 (page 10)). 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 (page 7) 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 (page 10)). Availability Available in iOS 2.0 and later. Declared in
UIDatePicker.h

minuteInterval
The interval at which the date picker should display minutes.

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

UIDatePicker Class Reference Instance Methods

@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 pickers calendar. Availability Available in iOS 2.0 and later. See Also
@property calendar (page 5) @property locale (page 11)

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

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

UIDatePicker Class Reference Constants

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
@property date (page 6)

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.

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

UIDatePicker Class Reference Constants

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 (page 6) property.

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

10

Deprecated UIDatePicker Methods

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

Discussion The 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 pickers 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. Deprecated in iOS 5.0. See Also
@property calendar (page 5) @property timeZone (page 8)

Declared in
UIDatePicker.h

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

11

Document Revision History

This table describes the changes to UIDatePicker Class Reference .

Date 2010-11-29

Notes Corrected the description for the calendar (page 5) property.

2008-05-01

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

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

12

Apple Inc. 2010 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. The Apple logo is a trademark of Apple Inc. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, iPhone, and Objective-C are trademarks of Apple Inc., registered in the United States and other countries. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.