Class: SC.Observable

Key-Value-Observing (KVO) simply allows one object to observe changes to a
property on another object. It is one of the fundamental ways that models,
controllers and views communicate with each other in a SproutCore
application. Any object that has this module applied to it can be used in
KVO-operations.

This module is applied automatically to all objects that inherit from
SC.Object, which includes most objects bundled with the SproutCore
framework. You will not generally apply this module to classes yourself,
but you will use the features provided by this module frequently, so it is
important to understand how to use it.

Enabling Key Value Observing

With KVO, you can write functions that will be called automatically whenever
a property on a particular object changes. You can use this feature to
reduce the amount of "glue code" that you often write to tie the various
parts of your application together.

To use KVO, just use the KVO-aware methods get() and set() to access
properties instead of accessing properties directly. Instead of writing:

Although this is the most common way to add an observer, this capability is
actually built into the SC.Object class on top of two methods defined in
this mixin called addObserver() and removeObserver(). You can use these two
methods to add and remove observers yourself if you need to do so at run
time.

To add an observer for a property, just call:

object.addObserver('propertyKey', targetObject, targetAction);

This will call the 'targetAction' method on the targetObject to be called
whenever the value of the propertyKey changes.

Observer Parameters

An observer function typically does not need to accept any parameters,
however you can accept certain arguments when writing generic observers.
An observer function can have the following arguments:

propertyObserver(target, key, value, revision);

target - This is the object whose value changed. Usually this.

key - The key of the value that changed

value - this property is no longer used. It will always be null

revision - this is the revision of the target object

Implementing Manual Change Notifications

Sometimes you may want to control the rate at which notifications for
a property are delivered, for example by checking first to make sure
that the value has changed.

To do this, you need to implement a computed property for the property
you want to change and override automaticallyNotifiesObserversFor().

The example below will only notify if the "balance" property value actually
changes:

Implementation Details

Internally, SproutCore keeps track of observable information by adding a
number of properties to the object adopting the observable. All of these
properties begin with "_kvo_" to separate them from the rest of your object.

Field Detail

Instance Method Detail

addObserver(key, target, method, context)

Adds an observer on a property.

This is the core method used to register an observer for a property.

Once you call this method, anytime the key's value is set, your observer
will be notified. Note that the observers are triggered anytime the
value is set, regardless of whether it has actually changed. Your
observer should be prepared to handle that.

You can also pass an optional context parameter to this method. The
context will be passed to your observer method whenever it is triggered.
Note that if you add the same target/method pair on a key multiple times
with different context parameters, your observer will only be called once
with the last context you passed.

Observer Methods

Observer methods you pass should generally have the following signature if
you do not pass a "context" parameter:

fooDidChange: function (sender, key, value, rev);

The sender is the object that changed. The key is the property that
changes. The value property is currently reserved and unused. The rev
is the last property revision of the object when it changed, which you can
use to detect if the key value has really changed or not.

If you pass a "context" parameter, the context will be passed before the
revision like so:

fooDidChange: function (sender, key, value, context, rev);

Usually you will not need the value, context or revision parameters at
the end. In this case, it is common to write observer methods that take
only a sender and key value as parameters or, if you aren't interested in
any of these values, to write an observer that has no parameters at all.

Allows you to inspect a property for changes. Whenever the named property
changes, a log will be printed to the console. This (along with removeProbe)
are convenience methods meant for debugging purposes.

Sometimes when you make a major update to your object, it is cheaper to
simply notify all observers that their property might have changed than
to figure out specifically which properties actually did change.

In those cases, you can simply call this method to notify all property
observers immediately. Note that this ignores property groups.

You can use this method to group property changes so that notifications
will not be sent until the changes are finished. If you plan to make a
large number of changes to an object at one time, you should call this
method at the beginning of the changes to suspend change notifications.
When you are done making changes, call endPropertyChanges() to allow
notification to resume.

didChangeFor is a very important method which allows you to tell whether
a property or properties have changed.

The key to using didChangeFor is to pass a unique string as the first argument,
which signals, "Has anything changed since the last time this was called with
this unique key?" The string can be anything you want, as long as it's unique
and stays the same from call to call.

After the key argument, you can pass as many property arguments as you like;
didChangeFor will only return true if any of those properties have changed
since the last call.

For example, in your view's update method, you might want to gate DOM changes
(generally a slow operation) on whether the root values have changed. You might
ask the following:

Each call will correctly return whether the property has changed since the last
time displayDidChange was called with that key. The following sequence of calls
will return the following values:

this.set('displayValue', 'value1');

this.didChangeFor('updateOnDisplayValue', 'displayValue');

true;

this.didChangeFor('updateOnDisplayValue', 'displayValue');
false;

this.didChangeFor('otherMethodDisplayValue', 'displayValue');
true;

this.set('displayValue', 'value2');

this.didChangeFor('updateOnDisplayValue', 'displayValue');
true;

this.didChangeFor('updateOnDisplayValue', 'displayValue');
false;

this.didChangeFor('updateOnDisplayValue', 'displayValue');
false;

this.didChangeFor('otherMethodDisplayValue', 'displayValue');
false;

This method works by comparing property revision counts. Every time a
property changes, an internal counter is incremented. When didChangeFor is
invoked, the current revision count of the property is compared to the
revision count from the last time this method was called.

You can use this method to group property changes so that notifications
will not be sent until the changes are finished. If you plan to make a
large number of changes to an object at one time, you should call
beginPropertyChanges() at the beginning of the changes to suspend change
notifications. When you are done making changes, call this method to allow
notification to resume.

When you call get() on a computed property, the property function will be
called and the return value will be returned instead of the function
itself.

Unknown Properties

Likewise, if you try to call get() on a property whose values is
undefined, the unknownProperty() method will be called on the object.
If this method returns any value other than undefined, it will be returned
instead. This allows you to implement "virtual" properties that are
not defined upfront.

Returns YES if the object currently has observers registered for a
particular key. You can use this method to potentially defer performing
an expensive action until someone begins observing a particular property
on the object.

Optionally, you may pass a target and method to check for the
presence of a particular observer. You can use this to avoid creating
duplicate observers in situations where that's likely.

This method will register any observers and computed properties saved on
the object. Normally you do not need to call this method yourself. It
is invoked automatically just before property notifications are sent and
from the init() method of SC.Object. You may choose to call this
from your own initialization method if you are using SC.Observable in
a non-SC.Object-based object.

This method looks for several private variables, which you can setup,
to initialize:

_observers: this should contain an array of key names for observers
you need to configure.

_bindings: this should contain an array of key names that configure
bindings.

_properties: this should contain an array of key names for computed
properties.

Sometimes you need to notify observers that a property has changed value
without actually changing this value. In those cases, you can use this
method as a convenience instead of calling propertyWillChange() and
propertyDidChange().

Sometimes you need to change a value directly or indirectly without
actually calling get() or set() on it. In this case, you can use this
method and propertyWillChange() instead. Calling these two methods
together will notify all observers that the property has potentially
changed value.

Note that you must always call propertyWillChange and propertyDidChange as
a pair. If you do not, it may get the property change groups out of order
and cause notifications to be delivered more often than you would like.

Sometimes you need to change a value directly or indirectly without
actually calling get() or set() on it. In this case, you can use this
method and propertyDidChange() instead. Calling these two methods
together will notify all observers that the property has potentially
changed value.

Note that you must always call propertyWillChange and propertyDidChange as
a pair. If you do not, it may get the property change groups out of order
and cause notifications to be delivered more often than you would like.

Use this to indicate that one key changes if other keys it depends on
change. Pass the key that is dependent and additional keys it depends
upon. You can either pass the additional keys inline as arguments or
in a single array.

You generally do not call this method, but instead pass dependent keys to
your property() method when you declare a computed property.

You can call this method during your init to register the keys that should
trigger a change notification for your computed properties.

This method is generally very similar to calling object[key] = value or
object.key = value, except that it provides support for computed
properties, the unknownProperty() method and property observers.

Computed Properties

If you try to set a value on a key that has a computed property handler
defined (see the get() method for an example), then set() will call
that method, passing both the value and key instead of simply changing
the value itself. This is useful for those times when you need to
implement a property that is composed of one or more member
properties.

Unknown Properties

If you try to set a value on a key that is undefined in the target
object, then the unknownProperty() handler will be called instead. This
gives you an opportunity to implement complex "virtual" properties that
are not predefined on the object. If unknownProperty() returns
undefined, then set() will simply set the value on the object.

Property Observers

In addition to changing the property, set() will also register a
property change with the object. Unless you have placed this call
inside of a beginPropertyChanges() and endPropertyChanges(), any "local"
observers (i.e. observer methods declared on the same object), will be
called immediately. Any "remote" observers (i.e. observer methods
declared on another object) will be placed in a queue and called at a
later time in a coalesced manner.

Chaining

In addition to property changes, set() returns the value of the object
itself so you can do chaining like this: