source: gs3-extensions/seaweed-debug/trunk/src/MVC.js@ 25160

/*
 * file: MVC.js
 *
 * @BEGINLICENSE
 * Copyright 2010 Brook Novak  (email : [email protected]) 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 * @ENDLICENSE
 */
bootstrap.provides("MVC");

/**
 * Extends the given instance into a model (wrt MVC).
 * 
 * @param {Object} subject The subject containing model data to be observed.
 */
function _model(subject) {
    
    // The list of registered observers for this subject
    var observers = [],
        observersToRemove; // Zeroed/undef when not firing event, array when model is firing event.
    
    $extend(subject, {

        /**
         * 
         * Notifies all observers that a specific event occured.
         * 
         * @param {String} event   The event name to fire (excluding the "on" prefix).
         *                         For example, "KeyDown" would invoke "onKeyDown" in all observers
         *                         
         * @param {Object} details Optional custom details data
         */
        fireEvent: function(event){
            
            if (observers.length > 0) {
                
                // Construct additional arguments array
                var i, 
                    observer,
                    remObservers,
                    args = Array.prototype.slice.call(arguments);
                    
                args.shift();
                
                // Flag this model as firing
                observersToRemove = [];
                
                // Fire events on each observer
                for (i in observers) {
                    observer = observers[i];
                    
                    // If the observer has declared a listener function for this event invoke it
                    if (typeof observer.ref["on" + event] == "function")
                        observer.ref["on" + event].apply(observer.context, args);
                }
                
                // Reset flag
                remObservers = observersToRemove;
                observersToRemove = 0;
                
                // If Observers when trying to remove themself during an event fire
                // then safely remove them now.        
                for (i in remObservers) {
                    this.removeObserver(remObservers[i]);
                }

            }
        },
        
        /**
         * Adds an observer for receiving event notifications.
         * If the observer already exists in the observer set it will not be added twice.
         * 
         * @param {Object} observer         An observer to add to the set.
         * 
         * @param {Object} context          (Optional) The context at which the events should be invoked in.
         *                                  Will default to the observer object.
         *                                  
         * @param {Boolean} notifiedFirst   (Optional) True to be the first observer to be notified in the current list.
         *                                  Otherwise it will be added to the end of the list
         */
        addObserver: function(observer, context, notifiedFirst){
            
            // Ensure that observer array is a set
            if (observerIndex(observer) != -1)
                return;
                
            // Create observer instance
            observer = {
                ref : observer,
                context : context || observer
            };
            
            // Add to list depending on requested order
            if (notifiedFirst) observers.unshift(observer);
            else observers.push(observer);
            
        },
        
        /**
         * Removes an observer from the subjects observer list.
         * 
         * @param {Object} observer An observer to remove from the set
         */
        removeObserver: function(observer) {
            
            // Avoid removing observers while in a firing-event state since some browsers
            // may miss firing an event on a observer if the observer list is sliced while iterating the list
            if (observersToRemove) 
                observersToRemove.push(observer); // Will be removed after firing of events finished
                
            else {
                var index = observerIndex(observer);
                if (index >= 0) observers.splice(index, 1);
            }
        }
    });
    
    /**
     * @param {Object} observerRef The observer reference to check
     * 
     * @return {Number} The index in the observers array at which observerRef exists.
     *                  -1 if not found.
     */
    function observerIndex(observerRef) {
        for (var i = 0; i < observers.length; i++) {
            if (observers[i].ref == observerRef)
                return i;
        }
        return -1;
    }
    
}
    
/**
 * Exposure of model internal
 * @see _model
 */  
de.model = _model;