KVO Design

Key-Value Observing (KVO) is a mechanism that references the value of a property by using the character string which refers to the property as a key in order to access the property of an object. It also observes changes of the property value that corresponds to a key.

Inherit from the KVO class

To inherit from the KVO class, specify the prototype of a class when declaring the class, as shown in the code below.

var MyClass = function() {
    // class initialization codes
};

MyClass.prototype = new naver.maps.KVO();
MyClass.prototype.constructor = MyClass;

MyClass.prototype.myMethod = function() {
    // implementation
};

Declare MyClass as above, and the instance of MyClass is an object that inherits from the KVO class.

var myKVO = new naver.maps.KVO();
var myClass = new MyClass();

myClass instanceof MyClass;         // true
myClass instanceof naver.maps.KVO;  // true

myKVO instanceof naver.maps.KVO;    // true
myKVO instanceof MyClass;           // false

How to use Key-Value

A class inheriting from the KVO class can set or get values corresponding to keys, with the set and get methods.

var MyClass = function() {
    this.set('zoom', 10);
};

MyClass.prototype = new naver.maps.KVO();
MyClass.prototype.constructor = MyClass;

MyClass.prototype.getZoom = function() {
    return this.get('zoom');
};

Bind Key-Value

An instance of a class inheriting from the KVO class can synchronize values with the corresponding keys, by using the bindTo method.

The following code example sets the value of a property by using zoom as a key, and binds the zoom property between two instances of a class inheriting from the KVO class. By binding the zoom property of the myModel object, the myView object can access and change the property. State changes of the zoom property apply to both objects.

var myModel = new naver.maps.KVO();
myModel.set('zoom', 11);

var myView = new naver.maps.KVO();

myView.bindKVO = function() {
    this.bindTo('zoom', myModel);
};

myView.bindKVO();

myView.get('zoom');         // 11

myModel.set('zoom', 21);
myModel.get('zoom');        // 21

myView.get('zoom');         // 21

When binding a property, you can specify the name of the property for synchronization. The following code example specifies the zoom property as a key named myZoom to bind it.

myView.bindKVO = function() {
    this.bindTo('myZoom', myModel, 'zoom');
};

myView.bindKVO();

myView.get('zoom');           // undefined
myView.get('myZoom');         // 11

myModel.set('zoom', 21);

myView.get('myZoom');         // 21

If the third argument, targetKey, of the bindTo method is omitted, it binds to the property of the first argument in the list of properties of an object to bind.

When binding multiple properties, you can use an array as a key. The following code example binds the zoom, center, centerPoint, and scale properties of the myModel object at once.

var myModel = new naver.maps.KVO();
myModel.set('zoom', 11);
myModel.set('center', new naver.maps.LatLng(38, 127));
myModel.set('centerPoint', new naver.maps.Point(128, 128));
myModel.set('scale', 1);

var myView = new naver.maps.KVO();

myView.bindKVO = function() {
    this.bindTo([
            'zoom',
            'center',
            'centerPoint',
            'scale'
        ], myModel);
};

myView.bindKVO();

Detect KVO state changes

KVO provides a notification of state changes of a property by using the {key}_changed naming rule. The objects binding the property can detect the time when the state of the property changes. So, it is useful if there are things you need to perform when the state of a specific property changes.

For more information, refer to KVO State Change Notifications.

The NAVER Maps API v3 supports the following two ways to detect state changes of a property. The first is to use the methods complying with the {key}_changed naming rule. The following code example displays a system warning window when the zoom property of the myModel object is changed.

myView.zoom_changed = function(zoom) {
    alert('The zoom value is changed to '+ zoom +'!');
};

myModel.set('zoom', 14);

The second is to listen to the event complying with the {key}_changed naming rule. The following code example uses an event listener to implement the same thing.

var listener = naver.maps.Event.addListener(myView, 'zoom_changed', function(zoom) {
    alert('The zoom value is changed to '+ zoom +'!');
});

myModel.set('zoom', 14);

If you use the addListener method of Event to listen to a KVO event, you can use the removeListener method to cancel the listening.

var listener = naver.maps.Event.addListener(myView, 'zoom_changed', function(zoom) {
    alert('The zoom value is changed to '+ zoom +'!');
});

naver.maps.Event.removeListener(listener);

myModel.set('zoom', 14); // not notified