NSKey​Value​Observing

The NSKey​Value​Observing (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 NSKey​Value​Observing 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 observe​Value(for​Key​Path:​ String?, of:​ Any?, change:​ [NSKey​Value​Change​Key :​ Any]?, context:​ Unsafe​Mutable​Raw​Pointer?)

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

Registering for Observation

func add​Observer(NSObject, for​Key​Path:​ String, options:​ NSKey​Value​Observing​Options = [], context:​ Unsafe​Mutable​Raw​Pointer?)

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

func remove​Observer(NSObject, for​Key​Path:​ 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 remove​Observer(NSObject, for​Key​Path:​ String, context:​ Unsafe​Mutable​Raw​Pointer?)

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 will​Change​Value(for​Key:​ String)

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

func did​Change​Value(for​Key:​ String)

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

func will​Change(NSKey​Value​Change, values​At:​ Index​Set, for​Key:​ 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 did​Change(NSKey​Value​Change, values​At:​ Index​Set, for​Key:​ String)

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

func will​Change​Value(for​Key:​ String, with​Set​Mutation:​ NSKey​Value​Set​Mutation​Kind, using:​ Set<Any​Hashable>)

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

func did​Change​Value(for​Key:​ String, with​Set​Mutation:​ NSKey​Value​Set​Mutation​Kind, using:​ Set<Any​Hashable>)

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

Observing Customization

class func automatically​Notifies​Observers(for​Key:​ String)

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

class func key​Paths​For​Values​Affecting​Value(for​Key:​ String)

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

var observation​Info:​ Unsafe​Mutable​Raw​Pointer?

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

Constants

NSKey​Value​Change

These constants are returned as the value for a NSKey​Value​Change​Kind​Key key in the change dictionary passed to observe​Value(for​Key​Path:​of:​change:​context:​) indicating the type of change made:

NSKey​Value​Observing​Options

These constants are passed to add​Observer(_:​for​Key​Path:​options:​context:​) and determine the values that are returned as part of the change dictionary passed to an observe​Value(for​Key​Path:​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 observe​Value(for​Key​Path:​of:​change:​context:​).

See Also