UILocalNotification Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Declared in
UILocalNotification.h

Overview

Instances of UILocalNotification represent notifications that an application can schedule for presentation to its users at specific dates and times. The operating system is responsible for delivering the notification at the proper time; the application does not have to be running for this to happen. Although local notifications are similar to remote notifications in that they are used for displaying alerts, playing sounds, and badging application icons, they are composed and delivered locally and do not require connection with remote servers.

Local notifications are primarily intended for applications with timer-based behaviors and simple calendar or to-do list applications. Applications that run in the allowed period in the background may also present a local notification, scheduled or immediate, to inform the user of an incoming message, chat, or update. An application can have only a limited number of scheduled notifications; the system keeps the soonest-firing 64 notifications (with automatically rescheduled notifications counting as a single notification) and discards the rest

When you create a local notification, you must specify when the system should deliver the notification. You can qualify this “fire date” (fireDate) with a time zone so that the fire date is adjusted when time-zone changes occur. You can also specify a repeat interval (daily, weekly, monthly, and so on). The substance of the notification can be an alert message or an application-icon badge number; you can also request that sound be played when alert messages are displayed. Local notifications can include custom data stored in a dictionary. Because UILocalNotification adopts the NSCopying protocol, you can copy existing local notifications and modify them to suit.

Once you have created an instance of UILocalNotification, you schedule it using one of two methods of the UIApplication class: scheduleLocalNotification: or presentLocalNotificationNow:. The former method use the fire date to schedule delivery; the latter method presents the notification immediately, regardless of the value of fireDate. You can cancel specific or all local notifications by calling cancelLocalNotification: or cancelAllLocalNotifications, respectively.

When the system delivers a local notification, several things can happen, depending on the application state and the type of notification. If the application is not frontmost and visible, the system displays the alert message, badges the application, and plays a sound—whatever is specified in the notification. If the notification is an alert and the user taps the action button (or, if the device is locked, drags open the action slider), the application is launched. In the application:didFinishLaunchingWithOptions: method the application delegate can obtain the UILocalNotification object from the passed-in options dictionary by using the UIApplicationLaunchOptionsLocalNotificationKey key. The delegate can inspect the properties of the notification and, if the notification includes custom data in its userInfo dictionary, it can access that data and process it accordingly. On the other hand, if the local notification only badges the application icon, and the user in response launches the application, the application:didFinishLaunchingWithOptions: method is invoked, but no UILocalNotification object is included in the options dictionary.

If the application is foremost and visible when the system delivers the notification, no alert is shown, no icon is badged, and no sound is played. However, the application:didReceiveLocalNotification: is called if the application delegate implements it. The UILocalNotification instance is passed into this method, and the delegate can check its properties or access any custom data from the userInfo dictionary.

An application is responsible for managing the badge number displayed on its icon. For example, if a text-messaging application processes all incoming messages after receiving a local notification, it should remove the icon badge by setting the applicationIconBadgeNumber property of the UIApplication object to 0.

Tasks

Scheduling a Local Notification

Composing the Alert

Configuring Other Parts of the Notification

Properties

alertAction

The title of the action button or slider.

@property(nonatomic, copy) NSString *alertAction
Discussion

Assign a string or, preferably, a localized-string key (using NSLocalizedString) as the value. The alert action is the title of the right button of the alert or the value of the unlock slider, where the value replaces “unlock” in “slide to unlock”. If you specify nil, and alertBody is non-nil, “View” (localized to the preferred language) is used as the default value.

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

alertBody

The message displayed in the notification alert.

@property(nonatomic, copy) NSString *alertBody
Discussion

Assign a string or, preferably, a localized-string key (using NSLocalizedString) as the value of the message. If the value of this property is non-nil, an alert is displayed. The default value is nil (no alert). Printf style escapes are stripped; to include a percent symbol (%) in the message, use two percent symbols (%%).

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

alertLaunchImage

Identifies the image used as the launch image when the user taps (or slides) the action button (or slider).

@property(nonatomic,copy) NSString *alertLaunchImage
Discussion

The string is a filename of an image file in the application bundle. This image is a launching image specified for a given notification; when the user taps the action button (for example, “View”) or moves the action slider, the image is used in place of the default launching image. If the value of this property is nil (the default), the system either uses the previous snapshot, uses the image identified by the UILaunchImageFile key in the application’s Info.plist file, or falls back to Default.png.

The value of this key has the exact same semantics as UILaunchImageFile. For more about this key, see the Information Property List Key Reference.

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

applicationIconBadgeNumber

The number to display as the application’s icon badge.

@property(nonatomic) NSInteger applicationIconBadgeNumber
Discussion

The default value is 0, which means that no badge is displayed.

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

fireDate

The date and time when the system should deliver the notification.

@property(nonatomic, copy) NSDate *fireDate
Discussion

The fire date is interpreted according to the value specified for timeZone. If the specified value is nil or is a date in the past, the notification is delivered immediately.

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

hasAction

A Boolean value that controls whether the notification shows or hides the alert action.

@property(nonatomic) BOOL hasAction
Discussion

Assign NO to this property to hide the alert button or slider. (This effect requires alertBody to be non-nil.) The default value is YES.

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

repeatCalendar

The calendar the system should refer to when it reschedules a repeating notification.

@property(nonatomic, copy) NSCalendar *repeatCalendar
Discussion

The default value is nil, which indicates that the current user calendar is used. (The current user calendar is returned by the currentCalendar class method of NSCalendar.)

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

repeatInterval

The calendar interval at which to reschedule the notification.

@property(nonatomic) NSCalendarUnit repeatInterval
Discussion

If you assign an calendar unit such as weekly (NSWeekCalendarUnit) or yearly (NSYearCalendarUnit), the system reschedules the notification for delivery at the specified interval. The default value is 0, which means don't repeat.

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

soundName

The name of the file containing the sound to play when an alert is displayed.

@property(nonatomic, copy) NSString *soundName
Discussion

For this property, specify the filename (including extension) of a sound resource in the application’s main bundle or UILocalNotificationDefaultSoundName to request the default system sound. When the system displays an alert for a local notification or badges an application icon, it plays this sound. The default value is nil (no sound). Sounds that last longer than 30 seconds are not supported. If you specify a file with a sound that plays over 30 seconds, the default sound is played instead.

For information on valid sound resources, see “Scheduling, Registering, and Handling Notifications” in Local and Push Notification Programming Guide.

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

timeZone

The time zone of the notification’s fire date.

@property(nonatomic, copy) NSTimeZone *timeZone
Discussion

The date specified in fireDate is interpreted according to the value of this property. If you specify nil (the default), the fire date is interpreted as an absolute GMT time, which is suitable for cases such as countdown timers. If you assign a valid NSTimeZone object to this property, the fire date is interpreted as a wall-clock time that is automatically adjusted when there are changes in time zones; an example suitable for this case is an an alarm clock.

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

userInfo

A dictionary for passing custom information to the notified application.

@property(nonatomic, copy) NSDictionary *userInfo
Discussion

You may add arbitrary key-value pairs to this dictionary. However, the keys and values must be valid property-list types; if any are not, an exception is raised.

Availability
  • Available in iOS 4.0 and later.
Declared In
UILocalNotification.h

Constants

Notification Sound

The default system sound for local notifications.

UIKIT_EXTERN NSString *const UILocalNotificationDefaultSoundName;
Constants
UILocalNotificationDefaultSoundName

Identifies the default system sound to play when a notification alert is displayed. You assign this value to the soundName property.

Available in iOS 4.0 and later.

Declared in UILocalNotification.h.