Protocol: NSKeyValueObserving

Overview

The NSKeyValueObserving (KVO) informal protocol defines a mechanism that allows objects to be notified of changes to the specified properties of other objects.Returns a Boolean value that indicates whether the receiver supports automatic key-value observation for the given key.Returns a set of key paths for properties whose values affect the value of the specified key.Registers anObserver to receive KVO notifications for the specified key-path relative to the receiver.Invoked to inform the receiver that the specified change has occurred on the indexes for a specified ordered to-many relationship.Invoked to inform the receiver that the value of a given property has changed.Invoked to inform the receiver that the specified change was made to a specified unordered to-many relationship.Returns a pointer that identifies information about all of the observers that are registered with the receiver.This message is sent to the receiver when the value at the specified key path relative to the given object has changed.Stops a given object from receiving change notifications for the property specified by a given key-path relative to the receiver.Stops a given object from receiving change notifications for the property specified by a given key-path relative to the receiver and a context.Sets the observation info for the receiver. Invoked to inform the receiver that the specified change is about to be executed at given indexes for a specified ordered to-many relationship.Invoked to inform the receiver that the value of a given property is about to change.Invoked to inform the receiver that the specified change is about to be made to a specified unordered to-many relationship.These constants are returned as the value for a NSKeyValueChangeKindKey key in the change dictionary passed to observeValueForKeyPath:ofObject:change:context: indicating the type of change made:These constants are passed to addObserver:forKeyPath:options:context: and determine the values that are returned as part of the change dictionary passed to an observeValueForKeyPath:ofObject:change:context:. You can pass 0 if you require no change dictionary values.These constants are used as keys in the change dictionary passed to observeValueForKeyPath:ofObject:change:context:.These constants are specified as the parameter to the methods willChangeValueForKey:withSetMutation:usingObjects: and didChangeValueForKey:withSetMutation:usingObjects:. Their semantics correspond exactly to the NSMutableSet class methods unionSet:, minusSet:, intersectSet:, and setSet: method, respectively.

Class Method Summary (collapse)

Instance Method Summary (collapse)

Class Method Details

+ (Boolean) automaticallyNotifiesObserversForKey(key)

Returns a Boolean value that indicates whether the receiver supports automatic key-value observation for the given key. The default implementation returns YES.

Returns:

  • (Boolean) —

    YES if the key-value observing machinery should automatically invoke willChangeValueForKey:/didChangeValueForKey: and willChange:valuesAtIndexes:forKey:/didChange:valuesAtIndexes:forKey: whenever instances of the class receive key-value coding messages for the key, or mutating key-value-coding-compliant methods for the key are invoked; otherwise NO.

+ (NSSet) keyPathsForValuesAffectingValueForKey(key)

Returns a set of key paths for properties whose values affect the value of the specified key. When an observer for the key is registered with an instance of the receiving class, key-value observing itself automatically observes all of the key paths for the same instance, and sends change notifications for the key to the observer when the value for any of those key paths changes.The default implementation of this method searches the receiving class for a method whose name matches the pattern +keyPathsForValuesAffecting, and returns the result of invoking that method if it is found. Any such method must return an NSSet. If no such method is found, an NSSet that is computed from information provided by previous invocations of the now-deprecated setKeys:triggerChangeNotificationsForDependentKey: method is returned, for backward binary compatibility.You can override this method when the getter method of one of your properties computes a value to return using the values of other properties, including those that are located by key paths. Your override should typically invoke super and return a set that includes any members in the set that result from doing that (so as not to interfere with overrides of this method in superclasses).Note: You must not override this method when you add a computed property to an existing class using a category, overriding methods in categories is unsupported. In that case, implement a matching +keyPathsForValuesAffecting to take advantage of this mechanism.

Parameters:

  • key (String) —

    The key whose value is affected by the key paths.

Returns:

Instance Method Details

- (Object) addObserver(anObserver, forKeyPath:keyPath, options:options, context:context)

Registers anObserver to receive KVO notifications for the specified key-path relative to the receiver. Neither the receiver, nor anObserver, are retained.

Parameters:

  • anObserver (NSObject) —

    The object to register for KVO notifications. The observer must implement the key-value observing method observeValueForKeyPath:ofObject:change:context:.

  • keyPath (String) —

    The key path, relative to the receiver, of the property to observe. This value must not be nil.

  • options (NSKeyValueObservingOptions) —

    A combination of the NSKeyValueObservingOptions values that specifies what is included in observation notifications. For possible values, see “NSKeyValueObservingOptions.”

  • context (Object) —

    Arbitrary data that is passed to anObserver in observeValueForKeyPath:ofObject:change:context:.

Returns:

- (Object) didChange(change, valuesAtIndexes:indexes, forKey:key)

Invoked to inform the receiver that the specified change has occurred on the indexes for a specified ordered to-many relationship. You should invoke this method when implementing key-value-observing compliance manually.

Parameters:

  • change (NSKeyValueChange) —

    The type of change that was made.

  • indexes (NSIndexSet) —

    The indexes of the to-many relationship that were affected by the change.

  • key (String) —

    The name of a property that is an ordered to-many relationship.

Returns:

- (Object) didChangeValueForKey(key)

Invoked to inform the receiver that the value of a given property has changed. You should invoke this method when implementing key-value observer compliance manually.

Parameters:

  • key (String) —

    The name of the property that changed.

Returns:

- (Object) didChangeValueForKey(key, withSetMutation:mutationKind, usingObjects:objects)

Invoked to inform the receiver that the specified change was made to a specified unordered to-many relationship. You invoke this method when implementing key-value observer compliance manually.

Parameters:

  • key (String) —

    The name of a property that is an unordered to-many relationship

  • mutationKind (NSKeyValueSetMutationKind) —

    The type of change that was made.

  • objects (NSSet) —

    The objects that were involved in the change (see “NSKeyValueSetMutationKind”).

Returns:

- (Object) observationInfo

Returns a pointer that identifies information about all of the observers that are registered with the receiver. The default implementation of this method retrieves the information from a global dictionary keyed by the receiver’s pointers. For improved performance, this method and setObservationInfo: can be overridden to store the opaque data pointer in an instance variable. Overrides of this method must not attempt to send Objective-C messages to the stored data, including retain and release.

Returns:

  • (Object) —

    A pointer that identifies information about all of the observers that are registered with the receiver, the options that were used at registration-time, and so on.

- (Object) observeValueForKeyPath(keyPath, ofObject:object, change:change, context:context)

This message is sent to the receiver when the value at the specified key path relative to the given object has changed. The receiver must be registered as an observer for the specified keyPath and object.

Parameters:

  • keyPath (String) —

    The key path, relative to object, to the value that has changed.

  • object (Object) —

    The source object of the key path keyPath.

  • change (Hash) —

    A dictionary that describes the changes that have been made to the value of the property at the key path keyPath relative to object. Entries are described in “Keys used by the change dictionary.”

  • context (Object) —

    The value that was provided when the receiver was registered to receive key-value observation notifications.

Returns:

- (Object) removeObserver(observerforKeyPath, :keyPathcontext, :context)

Stops a given object from receiving change notifications for the property specified by a given key-path relative to the receiver and a context. Examining the value in context you are able to determine precisely which addObserver:forKeyPath:options:context: invocation was used to create the observation relationship. When the same observer is registered for the same key-path multiple times, but with different context pointers, an application can determine specifically which object to stop observing.

Parameters:

  • observer (NSObject) —

    The object to remove as an observer.

  • keyPath (String) —

    A key-path, relative to the receiver, for which anObserver is registered to receive KVO change notifications.

  • context (Object) —

    Arbitrary data that more specifically identifies the observer to be removed.

Returns:

- (Object) removeObserver(anObserver, forKeyPath:keyPath)

Stops a given object from receiving change notifications for the property specified by a given key-path relative to the receiver.

Parameters:

  • anObserver (NSObject) —

    The object to remove as an observer.

  • keyPath (String) —

    A key-path, relative to the receiver, for which anObserver is registered to receive KVO change notifications.

Returns:

- (Object) setObservationInfo(observationInfo)

Sets the observation info for the receiver. The observationInfo is a pointer that identifies information about all of the observers that are registered with the receiver. The default implementation of this method stores observationInfo in a global dictionary keyed by the receiver’s pointers.For improved performance, this method and observationInfo can be overridden to store the opaque data pointer in an instance variable. Classes that override this method must not attempt to send Objective-C messages to observationInfo, including retain and release.

Parameters:

  • observationInfo (Object) —

    The observation info for the receiver.

Returns:

- (Object) willChange(change, valuesAtIndexes:indexes, forKey:key)

Invoked to inform the receiver that the specified change is about to be executed at given indexes for a specified ordered to-many relationship. You should invoke this method when implementing key-value-observing compliance manually. Important: After the values have been changed, a corresponding didChange:valuesAtIndexes:forKey: must be invoked with the same parameters.

Parameters:

  • change (NSKeyValueChange) —

    The type of change that is about to be made.

  • indexes (NSIndexSet) —

    The indexes of the to-many relationship that will be affected by the change.

  • key (String) —

    The name of a property that is an ordered to-many relationship.

Returns:

- (Object) willChangeValueForKey(key)

Invoked to inform the receiver that the value of a given property is about to change. You should invoke this method when implementing key-value observer compliance manually.The change type of this method is NSKeyValueChangeSetting.Important: After the values have been changed, a corresponding didChangeValueForKey: must be invoked with the same parameter.

Parameters:

  • key (String) —

    The name of the property that will change.

Returns:

- (Object) willChangeValueForKey(key, withSetMutation:mutationKind, usingObjects:objects)

Invoked to inform the receiver that the specified change is about to be made to a specified unordered to-many relationship. You invoke this method when implementing key-value observer compliance manually.Important: After the values have been changed, a corresponding didChangeValueForKey:withSetMutation:usingObjects: must be invoked with the same parameters.

Parameters:

  • key (String) —

    The name of a property that is an unordered to-many relationship

  • mutationKind (NSKeyValueSetMutationKind) —

    The type of change that will be made.

  • objects (NSSet) —

    The objects that are involved in the change (see “NSKeyValueSetMutationKind”).

Returns: