NSNotification 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

NSNotification objects encapsulate information so that it can be broadcast to other objects by an NSNotificationCenter object. An NSNotification object (referred to as a notification) contains a name, an object, and an optional dictionary. The name is a tag identifying the notification. The object is any object that the poster of the notification wants to send to observers of that notification (typically, it is the object that posted the notification). The dictionary stores other related objects, if any. NSNotification objects are immutable objects.

You can create a notification object with the class methods notificationWithName:object: or notificationWithName:object:userInfo:. However, you don’t usually create your own notifications directly. The NSNotificationCenter methods postNotificationName:object: and postNotificationName:object:userInfo: allow you to conveniently post a notification without creating it first.

NSCopying Protocol

The NSNotification class adopts the NSCopying protocol, making it possible to treat notifications as context-independent values that can be copied and reused. You can store a notification for later use or use the distributed objects system to send a notification to another process. The NSCopying protocol essentially allows clients to deal with notifications as first class values that can be copied by collections. You can put notifications in an array and send the copy message to that array, which recursively copies every item.

Creating Subclasses

You can subclass NSNotification to contain information in addition to the notification name, object, and dictionary. This extra data must be agreed upon between notifiers and observers.

NSNotification is a class cluster with no instance variables. As such, you must subclass NSNotification and override the primitive methods name, object, and userInfo. You can choose any designated initializer you like, but be sure that your initializer does not call NSNotification’s implementation of init (via [super init]). NSNotification is not meant to be instantiated directly, and its init method raises an exception.

Adopted Protocols

NSCoding
NSCopying

Tasks

Creating Notifications

Getting Notification Information

Class Methods

notificationWithName:object:

Returns a new notification object with a specified name and object.

+ (instancetype)notificationWithName:(NSString *)aName object:(id)anObject
Parameters
aName

The name for the new notification. May not be nil.

anObject

The object for the new notification.

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

notificationWithName:object:userInfo:

Returns a notification object with a specified name, object, and user information.

+ (instancetype)notificationWithName:(NSString *)aName object:(id)anObject userInfo:(NSDictionary *)userInfo
Parameters
aName

The name for the new notification. May not be nil.

anObject

The object for the new notification.

userInfo

The user information dictionary for the new notification. May be nil.

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

Instance Methods

initWithName:object:userInfo:

Initializes a notification with a specified name, object, and user information.

- (instancetype)initWithName:(NSString *)aName object:(id)object userInfo:(NSDictionary *)userInfo
Parameters
aName

The name for the new notification. May not be nil.

object

The object for the new notification.

userInfo

The user information dictionary for the new notification. May be nil.

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

name

Returns the name of the notification.

- (NSString *)name
Return Value

The name of the notification. Typically you use this method to find out what kind of notification you are dealing with when you receive a notification.

Special Considerations

Notification names can be any string. To avoid name collisions, you might want to use a prefix that’s specific to your application.

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

object

Returns the object associated with the notification.

- (id)object
Return Value

The object associated with the notification. This is often the object that posted this notification. It may be nil.

Typically you use this method to find out what object a notification applies to when you receive a notification.

Discussion

For example, suppose you’ve registered an object to receive the message handlePortDeath: when the “PortInvalid” notification is posted to the notification center and that handlePortDeath: needs to access the object monitoring the port that is now invalid. handlePortDeath: can retrieve that object as shown here:

- (void)handlePortDeath:(NSNotification *)notification
{
    ...
    [self reclaimResourcesForPort:[notification object]];
    ...
}
Availability
  • Available in iOS 2.0 and later.
Declared In
NSNotification.h

userInfo

Returns the user information dictionary associated with the receiver.

- (NSDictionary *)userInfo
Return Value

Returns the user information dictionary associated with the receiver. May be nil.

The user information dictionary stores any additional objects that objects receiving the notification might use.

Discussion

For example, in the Application Kit, NSControl objects post the NSControlTextDidChangeNotification whenever the field editor (an NSText object) changes text inside the NSControl. This notification provides the NSControl object as the notification's associated object. In order to provide access to the field editor, the NSControl object posting the notification adds the field editor to the notification's user information dictionary. Objects receiving the notification can access the field editor and the NSControl object posting the notification as follows:

- (void)controlTextDidBeginEditing:(NSNotification *)notification
{
    NSText *fieldEditor = [[notification userInfo]
        objectForKey:@"NSFieldEditor"];               // the field editor
    NSControl *postingObject = [notification object]; // the object that posted the notification
    ...
}
Availability
  • Available in iOS 2.0 and later.
Declared In
NSNotification.h