Mac Developer Library

Developer

Foundation Framework Reference NSNotification Class Reference

Options
Deployment Target:

On This Page
Language:

NSNotification

Inherits From

Conforms To

Import Statement

Objective-C

@import Foundation;

Swift

import Foundation

Availability

Available in OS X v10.0 and later

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.

Object Comparison

The objects of a notification are compared using pointer equality for local notifications. Distributed notifications use strings as their objects, and those strings are compared using isEqual: because pointer equality doesn’t make sense across process boundaries.

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 [super init]. NSNotification is not meant to be instantiated directly, and its init method raises an exception.

Creating Notifications
  • init(name:object:) + notificationWithName:object:

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

    Declaration

    Swift

    convenience init(name aName: String, object anObject: AnyObject?)

    Objective-C

    + (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 OS X v10.0 and later.

    See Also

    postNotificationName:object: (NSNotificationCenter)

  • + notificationWithName:object:userInfo:

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

    Declaration

    Objective-C

    + (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 OS X v10.0 and later.

    See Also

    + notificationWithName:object:
    postNotificationName:object:userInfo: (NSNotificationCenter)

  • init(name:object:userInfo:) - initWithName:object:userInfo: Designated Initializer

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

    Declaration

    Swift

    init(name name: String, object object: AnyObject?, userInfo userInfo: [NSObject : AnyObject]?)

    Objective-C

    - (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 OS X v10.6 and later.

Getting Notification Information
  • name name Property

    The name of the notification. (read-only)

    Declaration

    Swift

    var name: String { get }

    Objective-C

    @property(readonly, copy) NSString *name

    Discussion

    Typically you use this property 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 OS X v10.0 and later.

  • object object Property

    The object associated with the notification. (read-only)

    Declaration

    Swift

    var object: AnyObject? { get }

    Objective-C

    @property(readonly, retain) id object

    Discussion

    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.

    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:

    1. - (void)handlePortDeath:(NSNotification *)notification
    2. {
    3. ...
    4. [self reclaimResourcesForPort:notification.object];
    5. ...
    6. }

    Availability

    Available in OS X v10.0 and later.

  • userInfo userInfo Property

    The user information dictionary associated with the receiver. (read-only)

    Declaration

    Swift

    var userInfo: [NSObject : AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSDictionary *userInfo

    Discussion

    May be nil.

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

    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:

    1. - (void)controlTextDidBeginEditing:(NSNotification *)notification
    2. {
    3. NSText *fieldEditor = [notification.userInfo
    4. objectForKey:@"NSFieldEditor"]; // the field editor
    5. NSControl *postingObject = notification.object; // the object that posted the notification
    6. ...
    7. }

    Availability

    Available in OS X v10.0 and later.

Copyright © 2015 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2014-07-05