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 |
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
Class Methods
notificationWithName:object:
Returns a new notification object with a specified name and object.
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
-
– postNotificationName:object:(NSNotificationCenter)
Declared In
NSNotification.hnotificationWithName:object:userInfo:
Returns a notification object with a specified name, object, and user information.
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.
See Also
-
+ notificationWithName:object: -
– postNotificationName:object:userInfo:(NSNotificationCenter)
Declared In
NSNotification.hInstance Methods
name
Returns the name of the notification.
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.hobject
Returns the object associated with the notification.
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.huserInfo
Returns the user information dictionary associated with the receiver.
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© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-04-02)