gistfile1.js

/**
	@name glow.ElementList#clone
	@function
	@description Clones each node in the ElementList, along with data & event listeners
	
	@returns {glow.ElementList}
		Returns a new ElementList containing clones of all the nodes in
		the ElementList
	
	@example
		// get a copy of all heading elements
		var myClones = glow.get("h1, h2, h3, h4, h5, h6").clone();
*/

/**
	@name glow.ElementList#copy
	@function
	@description Copies each node in the ElementList, excluding data & event listeners
	
	@returns {glow.ElementList}
		Returns a new ElementList containing copies of all the nodes in
		the ElementList
	
	@example
		// get a copy of all heading elements
		var myCopies = glow.get("h1, h2, h3, h4, h5, h6").copy();
*/

/**
	@name glow.ElementList#each
	@function
	@description Calls a function for each item in the list.
	
	@param {Function} callback The function to run for each node.
		The function will be passed 2 arguments, the index of the current item,
		and the ElementList being itterated over.
		
		Inside the function 'this' refers to the HTMLElement.
		
		Returning false from this function stops subsequent itterations
	
	@returns {glow.ElementList}
	
	@example
		// add "link number: x" to each link, where x is the index of the link
		glow("a").each(function(i, elementList) {
			glow(this).append(' link number: ' + i);
		});
	@example
		// breaking out of an each loop
		glow("a").each(function(i, elementList) {
			// do stuff
			if ( glow(this).hasClass('whatever') ) {
				// we don't want to process any more links
				return false;
			}
		});
*/

/**
	@name glow.ElementList#filter
	@function
	@description Filter the ElementList
	 
	@param {Function|string} test Filter test
		If a string is provided, it is used in a call to {@link glow.ElementList#is ElementList#is}.
		
		The function will be passed 2 arguments, the index of the current item,
		and the ElementList being itterated over.
		
		Inside the function 'this' refers to the HTMLElement.
		Return true to keep the element, or false to remove it.
	 
	@returns {glow.ElementList} A new ElementList containing the filtered nodes
	 
	@example
		// return images with a width greater than 320
		glow("img").filter(function () {
			return glow(this).width() > 320;
		});
	
	@example
		// Get items that don't have an alt attribute
		myElementList.filter(':not([href])');
*/
/**
	@name glow.ElementList#next
	@function
	@description Gets the next sibling element for each node in the ElementList.
		If a filter is provided, the next item that matches the filter is returned, or
		none if no match is found.
	
	@param {Function|string} [filter] Filter test
		If a string is provided, it is used in a call to {@link glow.ElementList#is ElementList#is}.
	
		If a function is provided it will be passed 2 arguments, the index of the current item,
		and the ElementList being itterated over.
		
		Inside the function 'this' refers to the HTMLElement.
		
		Return true to keep the node, or false to remove it.
	
	@returns {glow.ElementList}
	
		A new ElementList containing the next sibling elements that match the (optional)
		filter.
	
	@example
		// gets the element following #myLink (if there is one)
		var next = glow.get("#myLink").next();
		
	@example
		// get the next sibling link element after #skipLink
		glow.get('#skipLink').next('a')
*/

/**
	@name glow.ElementList#on
	@function
	@description Listen for an event.
	   This will listen for a particular event on each dom node
	   in the ElementList.
	   
	   If you're listening to many children of a particular item,
	   you may get better performance from {@link glow.ElementList#delegate}.
	
	@param {String} eventName Name of the event to listen for.
	   This can be any regular DOM event ('click', 'mouseover' etc) or
	   a special event of ElementList.
	   
	@param {Function} callback Function to call when the event fires.
	   The callback is passed a single event object. The type of this
	   object is {@link glow.DomEvent} unless otherwise stated.
	   
	@param {Object} [thisVal] Value of 'this' within the callback.
	   By default, this is the dom node being listened to.
	
	@returns this
	
	@example
	   glow.get('#testLink').on('click', function(domEvent) {
		   // do stuff
		   
		   // if you want to cancel the default action (following the link)...
		   return false;
	   });
*/

/**
	@name glow.ElementList#detatch
	@function
	@description Detatch a listener from elements
	   This will detatch the listener from each dom node in the ElementList.
	
	@param {String} eventName Name of the event to detatch the listener from
	   
	@param {Function} callback Listener callback to detatch
	
	@returns this
	
	@example
		function clickListener(domEvent) {
			// ...
		}
		
		// adding listeners
		glow.get('a').on('click', clickListener);
		
		// removing listeners
		glow.get('a').detatch('click', clickListener);
*/

/**
	@name glow.ElementList#delegate
	@function
	@description Listen for an event occurring on child elements matching a selector.
		'delegate' will catch events which occur on matching items created after
		the listener was added. 
	
	@param {String} eventName Name of the event to listen for.
		This can be any regular DOM event ('click', 'mouseover' etc) or
		a special event of ElementList.
	
	@param {String} selector CSS selector of child elements to listen for events on
		For example, if you were wanting to hear events from links, this
		would be 'a'.
	
	@param {Function} callback Function to call when the event fires.
		The callback is passed a single event object. The type of this
		object is {@link glow.DomEvent} unless otherwise stated.
	
	@param {Object} [thisVal] Value of 'this' within the callback.
		By default, this is the dom node matched by 'selector'.
	
	@returns this
	
	@example
		// Using 'on' to catch clicks on links in a list
		glow.get('#nav a').on('click', function() {
			// do stuff
		});
		
		// The above adds a listener to each link, any links created later
		// will not have this listener, so we won't hear about them.
		
		// Using 'delegate' to catch clicks on links in a list
		glow.get('#nav').delegate('click', 'a', function() {
			// do stuff
		});
		
		// The above only adds one listener to #nav which tracks clicks
		// to any links within. This includes elements created after 'delegate'
		// was called.
	
	@example
		// Using delegate to change class names on table rows so :hover
		// behaviour can be emulated in IE6
		glow.get('#contactData').delegate('mouseover', 'tr', function() {
			glow.get(this).addClass('hover');
		});
		
		glow.get('#contactData').delegate('mouseout', 'tr', function() {
			glow.get(this).removeClass('hover');
		});
*/

/**
	@name glow.ElementList#detatchDelegate
	@function
	@description Detatch a delegated listener from elements
	   This will detatch the listener from each dom node in the ElementList.
	
	@param {String} eventName Name of the event to detatch the listener from
	
	@param {String} selector CSS selector of child elements the listener is listening to
	
	@param {Function} callback Listener callback to detatch
	
	@returns this
	
	@example
		function clickListener(domEvent) {
			// ...
		}
		
		// adding listeners
		glow.get('#nav').delegate('click', 'a', clickListener);
		
		// removing listeners
		glow.get('#nav').detatchDelegate('click', 'a', clickListener);
*/

/**
	@name glow.ElementList#fire
	@function
	@param {String} eventName Name of the event to fire
	@param {glow.events.Event} [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 on dom nodes within the ElementList
	   Note, this will only trigger event listeners to be called, it won't
	   for example, move the mouse or click a link on the page.
	
	@returns glow.events.Event
	
	@example
	   glow.get('#testLink').on('click', function() {
		   alert('Link clicked!');
	   });
	   
	   // The following causes 'Link clicked!' to be alerted, but doesn't
	   // cause the browser to follow the link
	   glow.get('#testLink').fire('click');
*/

/**
	@name glow.ElementList#event:mouseenter
	@event
	@description Fires when the mouse enters the element specifically, does not bubble
	
	@param {glow.events.DomEvent} event Event Object
*/

/**
	@name glow.ElementList#event:mouseleave
	@event
	@description Fires when the mouse leaves the element specifically, does not bubble
	
	@param {glow.events.DomEvent} event Event Object
*/

/**
	@name glow.ElementList#event:keydown
	@event
	@description Fires when the user presses a key
		Only fires if the element has focus, listen for this event on
		the document to catch all keydowns.
		
		keydown will only fire once, when the user presses the key.
		
		The order of events is keydown, char*, keyup. Char will only fire
		if the element that has focus can receive character input, and may
		fire many times if the user holds the key down.
	
	@param {glow.events.KeyboardEvent} event Event Object
*/

/**
	@name glow.ElementList#event:keyChar
	@event
	@description Fires when the user enters a character into an element using the keyboard
		
		The order of events is keydown, char*, keyup. Char will only fire
		if the element that has focus can receive character input, and may
		fire many times if the user holds the key down.
	
	@param {glow.events.KeyboardEvent} event Event Object
*/

/**
	@name glow.ElementList#event:keyup
	@event
	@description Fires when the user releases a key
		Only fires if the element has focus, listen for this event on
		the document to catch all keyups.
	
		The order of events is keydown, char*, keyup. Char will only fire
		if the element that has focus can receive character input, and may
		fire many times if the user holds the key down.
	
	@param {glow.events.KeyboardEvent} event Event Object
*/

/** 
	@name glow.events.DomEvent
	@constructor
	@extends glow.events.Event
	
	@param {Event} nativeEvent A native browser event read properties from
	
	@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 a DOM 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.
*/

/** 
	@name glow.events.DomEvent#altKey
	@type {boolean}
	@description Was the alt key pressed during the event?
		// Our current docs say this only works for key events, I'm not so sure
*/

/**
	@name glow.events.DomEvent#button
	@type {number}
	@description A number representing which button was pressed.
		0 for the left button, 1 for the middle button or 2 for the right button.
*/

/** 
	@name glow.events.DomEvent#ctrlKey
	@type {boolean}
	@description Was the ctrl key pressed during the event?
		// Our current docs say this only works for key events, I'm not so sure
*/

/** 
	@name glow.events.DomEvent#mouseLeft
	@type {number}
	@description The horizontal position of the mouse pointer in the page in pixels.
		// This is currently pageX, which doesn't make a lot of sense to me
		// Using "left" rather than "X" as other dom methods use left/top rather than x/y
*/

/** 
	@name glow.events.DomEvent#mouseTop
	@type {number}
	@description The vertical position of the mouse pointer in the page in pixels.
*/

/** 
	@name glow.events.DomEvent#related
	@type {HTMLElement}
	@description A related HTMLElement
		For mouseover / mouseenter events, this will refer to the previous element
		the mouse was over.
		
		For mouseout / mouseleave events, this will refer to the element the mouse
		is now over.
*/

/** 
	@name glow.events.DomEvent#shiftKey
	@type {boolean}
	@description Was the shift key pressed during the event?
		// Our current docs say this only works for key events, I'm not so sure
*/

/** 
	@name glow.events.DomEvent#source
	@type {HTMLElement}
	@description The element that the event originated from.
		For example, you could attach a listener to an <ol> element to listen for
		clicks. If the user clicked on an <li> the source property would be the
		<li> element, and {@link glow.DomEvent#attachedTo attachedTo} would be
		the <ol>.
*/

/** 
	@name glow.events.DomEvent#wheelData
	@type {number}
	@description The number of clicks the mouse wheel moved.
		Up values are positive, down values are negative.
*/

/** 
	@name glow.events.KeyboardEvent
	@constructor
	@extends glow.events.Event
	
	@param {Event} nativeEvent A native browser event read properties from
	
	@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 a keyboard 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.
*/

/** 
	@name glow.events.KeyboardEvent#key
	@type {number}
	@description A number representing the key pressed
		Constants for these numbers can be found in
		{@link glow.KeyboardEvent.keys}.
		
		This is only available for 'keyup' and 'keydown' events
		
	@example
		var keys = glow.events.KeyboardEvent.keys;
		switch (event.key) {
			case keys.ESC:
				// do stuff
				break;
			case keys.SHIFT:
				// do stuff
				break;
		}
*/

/** 
	@name glow.events.KeyboardEvent#keyChar
	@type {string}
	@description The string of the key pressed
		This is only available for 'char' events.
		
	@example
		// prevent non-numbers being entered
		return !isNaN( Number(event.keyChar) );
*/

/**
	@name glow.events.KeyboardEvent.keys
	@namespace
	@description Constants for keys.
		// I can't be arsed to write all these out, but it'll have properties like ESC, SHIFT, A, B, C etc etc
*/