NSNotificationCenter Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
NSNotification.h
Related sample code

Overview

An NSNotificationCenter object (or simply, notification center) provides a mechanism for broadcasting information within a program. An NSNotificationCenter object is essentially a notification dispatch table.

Objects register with a notification center to receive notifications (NSNotification objects) using the addObserver:selector:name:object: or addObserverForName:object:queue:usingBlock: methods. Each invocation of this method specifies a set of notifications. Therefore, objects may register as observers of different notification sets by calling these methods several times.

Each running Cocoa program has a default notification center. You typically don’t create your own. An NSNotificationCenter object can deliver notifications only within a single program. If you want to post a notification to other processes or receive notifications from other processes, use an instance of NSDistributedNotificationCenter.

Tasks

Getting the Notification Center

Managing Notification Observers

Posting Notifications

Class Methods

defaultCenter

Returns the process’s default notification center.

+ (id)defaultCenter
Return Value

The current process’s default notification center, which is used for system notifications.

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

Instance Methods

addObserver:selector:name:object:

Adds an entry to the receiver’s dispatch table with an observer, a notification selector and optional criteria: notification name and sender.

- (void)addObserver:(id)notificationObserver selector:(SEL)notificationSelector name:(NSString *)notificationName object:(id)notificationSender
Parameters
notificationObserver

Object registering as an observer. This value must not be nil.

notificationSelector

Selector that specifies the message the receiver sends notificationObserver to notify it of the notification posting. The method specified by notificationSelector must have one and only one argument (an instance of NSNotification).

notificationName

The name of the notification for which to register the observer; that is, only notifications with this name are delivered to the observer.

If you pass nil, the notification center doesn’t use a notification’s name to decide whether to deliver it to the observer.

notificationSender

The object whose notifications the observer wants to receive; that is, only notifications sent by this sender are delivered to the observer.

If you pass nil, the notification center doesn’t use a notification’s sender to decide whether to deliver it to the observer.

Discussion

Be sure to invoke removeObserver: or removeObserver:name:object: before notificationObserver or any object specified in addObserver:selector:name:object: is deallocated.

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

addObserverForName:object:queue:usingBlock:

Adds an entry to the receiver’s dispatch table with a notification queue and a block to add to the queue, and optional criteria: notification name and sender.

- (id)addObserverForName:(NSString *)name object:(id)obj queue:(NSOperationQueue *)queue usingBlock:(void (^)(NSNotification *))block
Parameters
name

The name of the notification for which to register the observer; that is, only notifications with this name are used to add the block to the operation queue.

If you pass nil, the notification center doesn’t use a notification’s name to decide whether to add the block to the operation queue.

obj

The object whose notifications you want to add the block to the operation queue.

If you pass nil, the notification center doesn’t use a notification’s sender to decide whether to add the block to the operation queue.

queue

The operation queue to which block should be added.

If you pass nil, the block is run synchronously on the posting thread.

block

The block to be executed when the notification is received.

The block is copied by the notification center and (the copy) held until the observer registration is removed.

The block takes one argument:

notification

The notification.

Return Value

An opaque object to act as the observer.

Discussion

If a given notification triggers more than one observer block, the blocks may all be executed concurrently with respect to one another (but on their given queue or on the current thread).

The following example shows how you can register to receive locale change notifications.

NSNotificationCenter *center = [NSNotificationCenter defaultCenter];
NSOperationQueue *mainQueue = [NSOperationQueue mainQueue];
self.localeChangeObserver = [center addObserverForName:NSCurrentLocaleDidChangeNotification object:nil
    queue:mainQueue usingBlock:^(NSNotification *note) {
 
        NSLog(@"The user's locale changed to: %@", [[NSLocale currentLocale] localeIdentifier]);
    }];

To unregister observations, you pass the object returned by this method to removeObserver:. You must invoke removeObserver: or removeObserver:name:object: before any object specified by addObserverForName:object:queue:usingBlock: is deallocated.

NSNotificationCenter *center = [NSNotificationCenter defaultCenter];
[center removeObserver:self.localeChangeObserver];
Availability
  • Available in iOS 4.0 and later.
Declared In
NSNotification.h

postNotification:

Posts a given notification to the receiver.

- (void)postNotification:(NSNotification *)notification
Parameters
notification

The notification to post. This value must not be nil.

Discussion

You can create a notification with the NSNotification class method notificationWithName:object: or notificationWithName:object:userInfo:. An exception is raised if notification is nil.

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

postNotificationName:object:

Creates a notification with a given name and sender and posts it to the receiver.

- (void)postNotificationName:(NSString *)notificationName object:(id)notificationSender
Parameters
notificationName

The name of the notification.

notificationSender

The object posting the notification.

Discussion

This method invokes postNotificationName:object:userInfo: with a userInfo argument of nil.

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

postNotificationName:object:userInfo:

Creates a notification with a given name, sender, and information and posts it to the receiver.

- (void)postNotificationName:(NSString *)notificationName object:(id)notificationSender userInfo:(NSDictionary *)userInfo
Parameters
notificationName

The name of the notification.

notificationSender

The object posting the notification.

userInfo

Information about the the notification. May be nil.

Discussion

This method is the preferred method for posting notifications.

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

removeObserver:

Removes all the entries specifying a given observer from the receiver’s dispatch table.

- (void)removeObserver:(id)notificationObserver
Parameters
notificationObserver

The observer to remove. Must not be nil.

Discussion

Be sure to invoke this method (or removeObserver:name:object:) before notificationObserver or any object specified in addObserver:selector:name:object: is deallocated.

The following example illustrates how to unregister someObserver for all notifications for which it had previously registered:

[[NSNotificationCenter defaultCenter] removeObserver:someObserver];
Availability
  • Available in iOS 2.0 and later.
Declared In
NSNotification.h

removeObserver:name:object:

Removes matching entries from the receiver’s dispatch table.

- (void)removeObserver:(id)notificationObserver name:(NSString *)notificationName object:(id)notificationSender
Parameters
notificationObserver

Observer to remove from the dispatch table. Specify an observer to remove only entries for this observer. Must not be nil, or message will have no effect.

notificationName

Name of the notification to remove from dispatch table. Specify a notification name to remove only entries that specify this notification name. When nil, the receiver does not use notification names as criteria for removal.

notificationSender

Sender to remove from the dispatch table. Specify a notification sender to remove only entries that specify this sender. When nil, the receiver does not use notification senders as criteria for removal.

Discussion

Be sure to invoke this method (or removeObserver:) before the observer object or any object specified in addObserver:selector:name:object: is deallocated.

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