NSKeyValueObserving

The NSKeyValueObserving (KVO) informal protocol defines a mechanism that allows objects to be notified of changes to the specified properties of other objects.

Overview

You can observe any object properties including simple attributes, to-one relationships, and to-many relationships. Observers of to-many relationships are informed of the type of change made — as well as which objects are involved in the change.

NSObject provides an implementation of the NSKeyValueObserving protocol that provides an automatic observing capability for all objects. You can further refine notifications by disabling automatic observer notifications and implementing manual notifications using the methods in this protocol.

Symbols

Change Notification

func observeValue(forKeyPath: String?, of: Any?, change: [NSKeyValueChangeKey : Any]?, context: UnsafeMutableRawPointer?)

Informs the observing object when the value at the specified key path relative to the observed object has changed.

Registering for Observation

func addObserver(NSObject, forKeyPath: String, options: NSKeyValueObservingOptions = [], context: UnsafeMutableRawPointer?)

Registers the observer object to receive KVO notifications for the key path relative to the object receiving this message.

func removeObserver(NSObject, forKeyPath: String)

Stops the observer object from receiving change notifications for the property specified by the key path relative to the object receiving this message.

func removeObserver(NSObject, forKeyPath: String, context: UnsafeMutableRawPointer?)

Stops the observer object from receiving change notifications for the property specified by the key path relative to the object receiving this message, given the context.

Notifying Observers of Changes

func willChangeValue(forKey: String)

Informs the observed object that the value of a given property is about to change.

func didChangeValue(forKey: String)

Informs the observed object that the value of a given property has changed.

func willChange(NSKeyValueChange, valuesAt: IndexSet, forKey: String)

Informs the observed object that the specified change is about to be executed at given indexes for a specified ordered to-many relationship.

func didChange(NSKeyValueChange, valuesAt: IndexSet, forKey: String)

Informs the observed object that the specified change has occurred on the indexes for a specified ordered to-many relationship.

func willChangeValue(forKey: String, withSetMutation: NSKeyValueSetMutationKind, using: Set<AnyHashable>)

Informs the observed object that the specified change is about to be made to a specified unordered to-many relationship.

func didChangeValue(forKey: String, withSetMutation: NSKeyValueSetMutationKind, using: Set<AnyHashable>)

Informs the observed object that the specified change was made to a specified unordered to-many relationship.

Observing Customization

class func automaticallyNotifiesObservers(forKey: String)

Returns a Boolean value that indicates whether the observed object supports automatic key-value observation for the given key.

class func keyPathsForValuesAffectingValue(forKey: String)

Returns a set of key paths for properties whose values affect the value of the specified key.

var observationInfo: UnsafeMutableRawPointer?

Returns a pointer that identifies information about all of the observers that are registered with the observed object.

Constants

NSKeyValueChange

These constants are returned as the value for a NSKeyValueChangeKindKey key in the change dictionary passed to observeValue(forKeyPath:of:change:context:) indicating the type of change made:

NSKeyValueObservingOptions

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 observeValue(forKeyPath:of:change:context:). You can pass 0 if you require no change dictionary values.

Change Dictionary Keys

These constants are used as keys in the change dictionary passed to observeValue(forKeyPath:of:change:context:).

NSKeyValueSetMutationKind

These constants are specified as the parameter to the methods willChangeValue(forKey:withSetMutation:using:) and didChangeValue(forKey:withSetMutation:using:). Their semantics correspond exactly to the NSMutableSet class methods union(_:), minus(_:), intersect(_:), and the instance method setSet(_:).