gistfile1.js

/**
 @name glow.events
 @namespace
 @description Listening, creating & firing events
*/

/**
 @name glow.events.addListeners
 @function
 @param {Object[]} attachTo   Array of objects to add listeners to
 @param {String}   name       Name of the event to listen for
 @param {Function} callback   Function to call when the event fires.
	The callback is passed a single event object. The type of this
	object depends on the event (see documentation for the event
	you're listening to).
 @param {Object}   [thisVal]  Value of 'this' within the callback.
	By default, this is the object being listened to.

 @description Convenience method to add listeners to many objects at once.
	If you're wanting to add a listener to a single object, use its
	'on' method.
*/

/**
 @name glow.events.fire
 @function
 @param {Object[]} items      Array of objects to add listeners to
 @param {String}   eventName  Name of the event to fire
 @param {glow.events.Event|Object} [Event]  Event object to pass into listeners.
	You can provide a simple object of key / value pairs which will
	be added as properties of a glow.events.Event instance.

 @description Convenience method to fire events on multiple items at once.
	If you're wanting to fire events on a single object, use its
	'on' method.
*/

/**
 @name glow.events.removeAllListeners
 @function
 @param {Object[]} items  Items to remove events from

 @description Removes all listeners attached to a given object.
	This removes not only listeners you added, but listeners others
	added too. For this reason it should only be used as part of a cleanup
	operation on objects that are about to be destroyed.
	
	Glow will call this by default on its own classes like NodeList and
	widgets.
*/

/* =glow.events.Target= */

	/**
	 @name glow.events.Target (or glow.events.Despatcher ?)
	 @class
	 @description An object that can have event listeners and fire events.
		This is a base class for objects that can fire events. You can
		extend this class to make your own objects have 'on' and 'fire'
		methods.
	 
	 @example
		// Ball is our constructor
		function Ball() {
			// ...
		}
		
		// make Ball inherit from Target
		glow.lang.extend(Ball, glow.events.Target, {
			// additional methods for Ball here, eg:
			bowl: function() {
				// ...
			}
		});
		
		// now instances of Ball can receive event listeners
		var myBall = new Ball();
		myBall.on('bounce', function() {
			alert('BOING!');
		});
		
		// and events can be fired from Ball instances
		myBall.fire('bounce');
	*/
	
	/**
	 @name glow.events.Target.extend
	 @function
	 @param {Object} obj  Object to add methods to
	 
	 @description Convenience method to add Target instance methods onto an object.
		If you want to add events to a class, extend glow.events.Target instead.
		
	 @example
		// myApplication is a singleton
		var myApplication = {};
		
		glow.events.Target.extend(myApplication);
		
		// now myApplication can fire events...
		myApplication.fire('load');
		
		// and other objects can listen for those events
		myApplication.on('load', function(e) {
			alert('App loaded');
		});
	*/
	
	/**
	 @name glow.events.Target#on
	 @function
	 @param {String}   eventName  Name of the event to listen for
	 @param {Function} callback   Function to call when the event fires.
		The callback is passed a single event object. The type of this
		object depends on the event (see documentation for the event
		you're listening to).
	 @param {Object}   [thisVal]  Value of 'this' within the callback.
		By default, this is the object being listened to.
	 
	 @description Listen for an event
	 
	 @returns this
	 
	 @example
		myObj.on('show', function() {
			// do stuff
		});
	*/
	
	/**
	 @name glow.events.Target#removeListener
	 @function
	 @param {String}   eventName  Name of the event to listen for
	 @param {Function} callback   Callback to detach
	 
	 @description Remove an event listener
	 
	 @returns this
	 
	 @example
		function showListener() {
			// ...
		}
		
		// add listener
		myObj.on('show', showListener);
		
		// remove listener
		myObj.removeListener('show', showListener);
		
	 @example
		// note the following WILL NOT WORK
		
		// add listener
		myObj.on('show', function() {
			alert('hi');
		});
		
		// remove listener
		myObj.removeListener('show', function() {
			alert('hi');
		});
		
		// this is because both callbacks are different function instances
		// YUI do it more like this:
		
		// add listener
		var listenerHandle = myObj.on('show', function() {
			alert('hi');
		});
		
		// remove listener
		listenerHandle.remove();
		
		// the problem here is we lose chaining
	*/
	
	/**
	 @name glow.events.Target#fire
	 @function
	 @param {String} eventName  Name of the event to fire
	 @param {glow.events.Event|Object} [Event]  Event object to pass into listeners.
		You can provide a simple object of key / value pairs which will
		be added as properties of a glow.events.Event instance.
	 
	 @description Fire an event
	 
	 @returns glow.events.Event
	 
	 @example
		myObj.fire('show');
		
	 @example
		// adding properties to the event object
		myBall.fire('bounce', {
			velocity: 30
		});
	
	 @example
		// BallBounceEvent extends glow.events.Event but has extra methods
		myBall.fire( 'bounce', new BallBounceEvent(myBall) );
	*/
	
/* =glow.events.Event= */

	/**
	 @name glow.events.Event
	 @class
	 @param {Object} [properties] Properties to add to the Event instance.
		Each key-value pair in the object will be added to the Event as
		properties
	
	 @description Describes an event that occurred
		You don't need to create instances of this class if you're simply
		listening to events. One will be provided as the first argument
		in your callback.
	
	 @example
		// creating a simple event object
		var event = new glow.events.Event({
			velocity: 50,
			direction: 180
		});
		
		// 'velocity' and 'direction' are simple made-up properties
		// you may want to add to your event object
		
	 @example
		// inheriting from glow.events.Event to make a more
		// specialised event object
		
		function RocketEvent() {
			// ...
		}
		
		// inherit from glow.events.Event
		glow.lang.extend(RocketEvent, glow.events.Event, {
			getVector: function() {
				return // ...
			}
		});
		
		// firing the event
		rocketInstance.fire( 'landingGearDown', new RocketEvent() );
		
		// how a user would listen to the event
		rocketInstance.on('landingGearDown', function(rocketEvent) {
			var vector = rocketEvent.getVector();
		});
	*/
	
	/**
	 @name glow.events.Event#attachedTo
	 @type {Object}
	 @description The object the listener was attached to.
		If null, this value will be populated by {@link glow.events.Target#fire}
	*/
	
	/**
	 @name glow.events.Event#source
	 @type {Object}
	 @description The object the event originated from.
		This will be different from {@link glow.events.Event#attachedTo} for
		events that bubble.
		
		If null, this value will be populated by {@link glow.events.Target#fire}
	*/
	
	/**
	 @name glow.events.Event#preventDefault
	 @function
	 @description Prevent the default action of the event.
		Eg, if the click event on a link is cancelled, the link
		is not followed.
		
		Returning false from an event listener has the same effect
		as calling this function.
		
		For custom events, it's down to whatever fired the event
		to decide what to do in this case. See {@link glow.events.Event#defaultPrevented defaultPrevented}
		
	 @example
		myLinks.on('click', function(event) {
			event.preventDefault();
		});
		
		// same as...
		
		myLinks.on('click', function(event) {
			return false;
		});
	*/
	
	/**
	 @name glow.events.Event#defaultPrevented
	 @function
	 @description Has the default been prevented for this event?
		This should be used by whatever fires the event to determine if it should
		carry out of the default action.
	 
	 @returns {Boolean} Returns true if {@link glow.events.Event#preventDefault preventDefault} has been called for this event.
	 
	 @example
		// fire the 'show' event
		// read if the default action has been prevented
		if ( overlayInstance.fire('show').defaultPrevented() == false ) {
			// go ahead and show
		}
	*/