/*
 * Types
 * Visit http://createjs.com/ for documentation, updates and examples.
 *
 *
 * Copyright (c) 2012 gskinner.com, inc.
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following
 * conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 */

/**
 * @module PreloadJS
 */

(function () {

	"use strict";

	/**
	 * A PreloadJS plugin provides a way to inject functionality into PreloadJS to load file types that are unsupported,
	 * or in a way that PreloadJS does not.
	 *
	 * <strong>Note that this class is mainly for documentation purposes, and is not a real plugin.</strong>
	 *
	 * Plugins are registered based on file extension, or supported preload types, which are defined as constants on
	 * the {{#crossLink "LoadQueue"}}{{/crossLink}} class. Available load types are:
	 * <ul>
	 *     <li>binary ({{#crossLink "LoadQueue/BINARY:property"}}{{/crossLink}})</li>
	 *     <li>css ({{#crossLink "LoadQueue/CSS:property"}}{{/crossLink}})</li>
	 *     <li>image ({{#crossLink "LoadQueue/IMAGE:property"}}{{/crossLink}})</li>
	 *     <li>javascript ({{#crossLink "LoadQueue/JAVASCRIPT:property"}}{{/crossLink}})</li>
	 *     <li>json ({{#crossLink "LoadQueue/JSON:property"}}{{/crossLink}})</li>
	 *     <li>jsonp ({{#crossLink "LoadQueue/JSONP:property"}}{{/crossLink}})</li>
	 *     <li>manifest ({{#crossLink "LoadQueue/MANIFEST:property"}}{{/crossLink}})</li>
	 *     <li>sound ({{#crossLink "LoadQueue/SOUND:property"}}{{/crossLink}})</li>
	 *     <li>spriteSheet ({{#crossLink "LoadQueue/SPRITESHEET:property"}}{{/crossLink}})</li>
	 *     <li>svg ({{#crossLink "LoadQueue/SVG:property"}}{{/crossLink}})</li>
	 *     <li>text ({{#crossLink "LoadQueue/TEXT:property"}}{{/crossLink}})</li>
	 *     <li>xml ({{#crossLink "LoadQueue/XML:property"}}{{/crossLink}})</li>
	 * </ul>
	 *
	 * A plugin defines what types or extensions it handles via a {{#crossLink "SamplePlugin/getPreloadHandlers"}}{{/crossLink}}
	 * method, which is called when a plugin is first registered.
	 *
	 * To register a plugin with PreloadJS, simply install it into a LoadQueue before files begin to load using the
	 * {{#crossLink "LoadQueue/installPlugin"}}{{/crossLink}} method:
	 *
	 *      var queue = new createjs.LoadQueue();
	 *      queue.installPlugin(createjs.SamplePlugin);
	 *      queue.loadFile("test.jpg");
	 *
	 * The {{#crossLink "SamplePlugin/getPreloadHandlers"}}{{/crossLink}} method can also return a `callback`
	 * property, which is a function that will be invoked before each file is loaded. Check out the {{#crossLink "SamplePlugin/preloadHandler"}}{{/crossLink}}
	 * for more information on how the callback works. For example, the SoundJS plugin allows PreloadJS to manage a
	 * download that uses the Flash Player.
	 *
	 * @class SamplePlugin
	 * @static
	 */
	var SamplePlugin = function () {
	};
	var s = SamplePlugin;

	/**
	 * When a plugin is installed, this method will be called to let PreloadJS know when to invoke the plugin.
	 *
	 * PreloadJS expects this method to return an object containing:
	 * <ul>
	 *     <li><strong>callback:</strong> The function to call on the plugin class right before an item is loaded. Check
	 *     out the {{#crossLink "SamplePlugin/preloadHandler"}}{{/crossLink}} method for more information. The callback
	 *     is automatically called in the scope of the plugin.</li>
	 *     <li><strong>types:</strong> An array of recognized PreloadJS load types to handle. Supported load types are
	 *     "binary","image", "javascript", "json", "jsonp", "sound", "svg", "text", and "xml".</li>
	 *     <li><strong>extensions:</strong> An array of strings containing file extensions to handle, such as "jpg",
	 *     "mp3", etc. This only fires if an applicable type handler is not found by the plugin.</li>
	 * </ul>
	 *
	 * Note that currently, PreloadJS only supports a single handler for each extension or file type.
	 *
	 * <h4>Example</h4>
	 *
	 *      // Check out the SamplePlugin source for a more complete example.
	 *      SamplePlugin.getPreloadHandlers = function() {
	 *          return {
	 *              callback: SamplePlugin.preloadHandler,
	 *              extensions: ["jpg", "jpeg", "png", "gif"]
	 *          }
	 *      }
	 *
	 * If a plugin provides both "type" and "extension" handlers, the type handler will take priority, and will only
	 * fire once per file. For example if you have a handler for type=sound, and for extension=mp3, the callback will
	 * fire when it matches the type.
	 *
	 * @method getPreloadHandlers
	 * @return {Object} An object defining a callback, type handlers, and extension handlers (see description)
	 */
	s.getPreloadHandlers = function () {
		return {
			callback: s.preloadHandler, // Proxy the method to maintain scope
			types: ["image"],
			extensions: ["jpg", "jpeg", "png", "gif"]
		}
	};

	/**
	 * This is a sample method to show how to handle the callback specified in the {{#crossLink "LoadQueue/getPreloadHandlers"}}{{/crossLink}}.
	 * Right before a file is loaded, if a plugin for the file type or extension is found, then the callback for that
	 * plugin will be invoked. This gives the plugin an opportunity to modify the load item, or even cancel the load.
	 * The return value of the callback determines how PreloadJS will handle the file:
	 * <ul>
	 *     <li><strong>false:</strong> Skip the item. This allows plugins to determine if a file should be loaded or
	 *     not. For example,the plugin could determine if a file type is supported at all on the current system, and
	 *     skip those that do not.</li>
	 *     <li><strong>true:</strong> Continue normally. The plugin will not affect the load.</li>
	 *     <li><strong>AbstractLoader instance:</strong> Used as the loader for the content. This is new in 0.6.0.</li>
	 * </ul>
	 *
	 * Since the {{#crossLink "LoadItem"}}{{/crossLink}} is passed by reference, a plugin can modify as needed, even
	 * appending additional data to it. Note that if the {{#crossLink "LoadItem/src:property"}}{{/crossLink}} is
	 * modified, PreloadJS will automatically update the {{#crossLink "LoadItem/ext:property"}}{{/crossLink}} property.
	 *
	 * <h4>Example</h4>
	 *
	 *      // Cancel a load
	 *      SamplePlugin.preloadHandler = function(loadItem, queue) {
     *          if (loadItem.id.indexOf("thumb") { return false; } // Don't load items like "image-thumb.png"
     *          return true;
     *      }
	 *
	 *      // Specify a completeHandler
	 *      SamplePlugin.preloadHandler = function(loadItem, queue) {
	 *          item.completeHandler = SamplePlugin.fileLoadHandler;
	 *      }
	 *
	 *      // Check out the SamplePlugin source to see another example.
	 *
	 * <em>Note: In 0.4.2 and earlier, instead of a {{#crossLink "LoadItem"}}{{/crossLink}}, arguments were passed in,
	 * and a modified object was returned to PreloadJS. This has been changed to passing a reference to the LoadItem,
	 * which can be directly modified.</em>
	 *
	 * @method preloadHandler
	 * @param {LoadItem|Object} loadItem The item that PreloadJS is going to load. This item is passes by reference,
	 * so it can be directly modified.
	 * @param {LoadQueue} queue The {{#crossLink "LoadQueue"}}{{/crossLink}} instance that is preloading the item.
	 * @return {Boolean|AbstractLoader} How PreloadJS should handle the load. See the main description for more info.
	 */
	s.preloadHandler = function (loadItem, queue) {
		var options = {};

		// Tell PreloadJS to skip this file
		if (options.stopDownload) { return false; }

		// Tell PreloadJS to continue normally
		if (options.doNothing) { return true; }

		// Modify the LoadItem
		loadItem.id = "newId";
		loadItem.completeHandler = createjs.proxy(s.fileCompleteHandler, s);

		// Return a new loader. This is an advanced usage, similar to what SoundJS does.
		var loader = new createjs.ImageLoader(loadItem);
		loader.on("complete", createjs.proxy(s.fileCompleteHandler, s));

		return loader;
	};

	/**
	 * This is a sample method to show a `completeHandler`, which is optionally specified by the return object in the
	 * {{#crossLink "SamplePlugin/preloadHandler"}}{{/crossLink}}. This sample provides a `completeHandler` to the
	 * {{#crossLink "LoadItem"}}{{/crossLink}}. This method is called after the item has completely loaded, but before
	 * the {{#crossLink "LoadQueue/fileload:event"}}{{/crossLink}} event is dispatched from the {{#crossLink "LoadQueue"}}{{/crossLink}}.
	 *
	 * The provided sample also listens for the {{#crossLink "AbstractLoader/complete:event"}}{{/crossLink}}
	 * event on the loader it returns to show a different usage.
	 *
	 * @method fileLoadHandler
	 * @param event {Event} A {{#crossLink "LoadQueue/fileload:event"}}{{/crossLink}} event.
	 */
	s.fileLoadHandler = function (event) {
		// Do something with the result.
	};

	createjs.SamplePlugin = SamplePlugin;

}());