API Documentation for: 0.4.1
Show:

LoadQueue Class

Extends AbstractLoader
Defined in: LoadQueue:107
Module: PreloadJS

The LoadQueue class is the main API for preloading content. LoadQueue is a load manager, which can preload either a single file, or queue of files.

Creating a Queue
To use LoadQueue, create a LoadQueue instance. If you want to force tag loading where possible, set the useXHR argument to false.

 var queue = new createjs.LoadQueue(true);

Listening for Events
Add any listeners you want to the queue. Since PreloadJS 0.3.0, the EventDispatcher lets you add as many listeners as you want for events. You can subscribe to the following events:

  • complete: fired when a queue completes loading all files
  • error: fired when the queue encounters an error with any file.
  • progress: Progress for the entire queue has changed.
  • fileload: A single file has completed loading.
  • fileprogress: Progress for a single file has changes. Note that only files loaded with XHR (or possibly by plugins) will fire progress events other than 0 or 100%.

 queue.on("fileload", handleFileLoad, this);
 queue.on("complete", handleComplete, this);

Adding files and manifests
Add files you want to load using loadFile or add multiple files at a time using a list or a manifest definition using loadManifest. Files are appended to the end of the active queue, so you can use these methods as many times as you like, whenever you like.

 queue.loadFile("filePath/file.jpg");
 queue.loadFile({id:"image", src:"filePath/file.jpg"});
 queue.loadManifest(["filePath/file.jpg", {id:"image", src:"filePath/file.jpg"}];

If you pass false as the loadNow parameter, the queue will not kick of the load of the files, but it will not stop if it has already been started. Call the load method to begin a paused queue. Note that a paused queue will automatically resume when new files are added to it with a loadNow argument of true.

 queue.load();

File Types
The file type of a manifest item is auto-determined by the file extension. The pattern matching in PreloadJS should handle the majority of standard file and url formats, and works with common file extensions. If you have either a non-standard file extension, or are serving the file using a proxy script, then you can pass in a type property with any manifest item.

 queue.loadFile({src:"path/to/myFile.mp3x", type:createjs.LoadQueue.SOUND});

 // Note that PreloadJS will not read a file extension from the query string
 queue.loadFile({src:"http://server.com/proxy?file=image.jpg"}, type:createjs.LoadQueue.IMAGE});

Supported types are defined on the LoadQueue class, and include:

Handling Results
When a file is finished downloading, a fileload event is dispatched. In an example above, there is an event listener snippet for fileload. Loaded files are usually a resolved object that can be used immediately, including:

  • Image: An <img /> tag
  • Audio: An <audio /> tag
  • JavaScript: A <script /> tag
  • CSS: A <link /> tag
  • XML: An XML DOM node
  • SVG: An <object /> tag
  • JSON: A formatted JavaScript Object
  • Text: Raw text
  • Binary: The binary loaded result
 function handleFileLoad(event) {
     var item = event.item; // A reference to the item that was passed in to the LoadQueue
     var type = item.type;

     // Add any images to the page body.
     if (type == createjs.LoadQueue.IMAGE) {
         document.body.appendChild(event.result);
     }
 }

At any time after the file has been loaded (usually after the queue has completed), any result can be looked up via its "id" using getResult. If no id was provided, then the "src" or file path can be used instead, including the path defined by a manifest, but not including a base path defined on the LoadQueue. It is recommended to always pass an id.

 var image = queue.getResult("image");
 document.body.appendChild(image);

Raw loaded content can be accessed using the rawResult property of the fileload event, or can be looked up using getResult, passing true as the 2nd argument. This is only applicable for content that has been parsed for the browser, specifically: JavaScript, CSS, XML, SVG, and JSON objects, or anything loaded with XHR.

 var image = queue.getResult("image", true); // load the binary image data loaded with XHR.

Plugins
LoadQueue has a simple plugin architecture to help process and preload content. For example, to preload audio, make sure to install the SoundJS Sound class, which will help load HTML audio, Flash audio, and WebAudio files. This should be installed before loading any audio files.

 queue.installPlugin(createjs.Sound);

Known Browser Issues

  • Browsers without audio support can not load audio files.
  • Safari on Mac OS X can only play HTML audio if QuickTime is installed
  • HTML Audio tags will only download until their canPlayThrough event is fired. Browsers other than Chrome will continue to download in the background.
  • When loading scripts using tags, they are automatically added to the document.
  • Scripts loaded via XHR may not be properly inspectable with browser tools.
  • IE6 and IE7 (and some other browsers) may not be able to load XML, Text, or JSON, since they require XHR to work.
  • Content loaded via tags will not show progress, and will continue to download in the background when canceled, although no events will be dispatched.

Constructor

LoadQueue

(
  • [useXHR=true]
  • [basePath=""]
  • [crossOrigin=""]
)

Defined in LoadQueue:107

Parameters:

  • [useXHR=true] Boolean optional

    Determines whether the preload instance will favor loading with XHR (XML HTTP Requests), or HTML tags. When this is false, the queue will use tag loading when possible, and fall back on XHR when necessary.

  • [basePath=""] String optional

    A path that will be prepended on to the source parameter of all items in the queue before they are loaded. Sources beginning with a protocol such as http:// or a relative path such as ../ will not receive a base path.

  • [crossOrigin=""] String | Boolean optional

    An optional flag to support images loaded from a CORS-enabled server. To use it, set this value to true, which will default the crossOrigin property on images to "Anonymous". Any string value will be passed through, but only "" and "Anonymous" are recommended.

Item Index

Methods

_addItem

(
  • value
  • [path]
  • [basePath]
)
private

Defined in _addItem:1190

Add an item to the queue. Items are formatted into a usable object containing all the properties necessary to load the content. The load queue is populated with the loader instance that handles preloading, and not the load item that was passed in by the user. To look up the load item by id or src, use the LoadQueue.getItem method.

Parameters:

  • value String | Object

    The item to add to the queue.

  • [path] String optional

    An optional path prepended to the src. The path will only be prepended if the src is relative, and does not start with a protocol such as http://, or a path like ../. If the LoadQueue was provided a _basePath, then it will optionally be prepended after.

  • [basePath] String optional

    DeprecatedAn optional basePath passed into a loadManifest or loadFile call. This parameter will be removed in a future tagged version.

_checkScriptLoadOrder

() private

Ensure the scripts load and dispatch in the correct order. When using XHR, scripts are stored in an array in the order they were added, but with a "null" value. When they are completed, the value is set to the load item, and then when they are processed and dispatched, the value is set to true. This method simply iterates the array, and ensures that any loaded items that are not preceded by a null value are dispatched.

_createLoader

(
  • item
)
AbstractLoader private

Defined in _createLoader:1355

Create a loader for a load item.

Parameters:

  • item Object

    A formatted load item that can be used to generate a loader.

Returns:

AbstractLoader:

A loader that can be used to load content.

_createLoadItem

(
  • value
  • [path]
  • [basePath]
)
Object private

Create a refined load item, which contains all the required properties (src, type, extension, tag). The type of item is determined by browser support, requirements based on the file type, and developer settings. For example, XHR is only used for file types that support it in new browsers.

Before the item is returned, any plugins registered to handle the type or extension will be fired, which may alter the load item.

Parameters:

  • value String | Object | HTMLAudioElement | HTMLImageElement

    The item that needs to be preloaded.

  • [path] String optional

    A path to prepend to the item's source. Sources beginning with http:// or similar will not receive a path. Since PreloadJS 0.4.1, the src will be modified to include the path and _basePath when it is added.

  • [basePath] String optional

    Deprectated A base path to prepend to the items source in addition to the path argument.

Returns:

Object:

The loader instance that will be used.

_createTag

(
  • type
)
HTMLImageElement | HTMLAudioElement | HTMLScriptElement | HTMLLinkElement | Object private

Defined in _createTag:1635

Create an HTML tag. This is in LoadQueue instead of TagLoader because no matter how we load the data, we may need to return it in a tag.

Parameters:

  • type String

    The item type. Items are passed in by the developer, or deteremined by the extension.

Returns:

HTMLImageElement | HTMLAudioElement | HTMLScriptElement | HTMLLinkElement | Object:

The tag that is created. Note that tags are not appended to the HTML body.

_dispatchEvent

(
  • eventObj
  • eventPhase
)
protected

Parameters:

_disposeItem

(
  • item
)
private

Defined in _disposeItem:1620

Clean out item results, to free them from memory. Mainly, the loaded item and results are cleared from internal hashes.

Parameters:

  • item Object

    The item that was passed in for preloading.

_formatQueryString

(
  • data
  • [query]
)
private

Formats an object into a query string for either a POST or GET request.

Parameters:

  • data Object

    The data to convert to a query string.

  • [query] Array optional

    Existing name/value pairs to append on to this query.

_handleFileComplete

(
  • event
)
private

An item has finished loading. We can assume that it is totally loaded, has been parsed for immediate use, and is available as the "result" property on the load item. The raw text result for a parsed item (such as JSON, XML, CSS, JavaScript, etc) is available as the "rawResult" event, and can also be looked up using getResult.

Parameters:

  • event Object

    The event object from the loader.

_handleFileError

(
  • event
)
private

The callback that is fired when a loader encounters an error. The queue will continue loading unless stopOnError is set to true.

Parameters:

  • event Object

    The error event, containing relevant error information.

_handleProgress

(
  • event
)
private

An item has dispatched progress. Propagate that progress, and update the LoadQueue overall progress.

Parameters:

  • event Object

    The progress event from the item.

_isCanceled

() Boolean protected

Determine if the load has been canceled. This is important to ensure that method calls or asynchronous events do not cause issues after the queue has been cleaned up.

Returns:

Boolean:

If the loader has been canceled.

_isCrossDomain

(
  • item
)
Boolean private

Parameters:

  • item Object

    A load item with a src property

Returns:

Boolean:

If the load item is loading from a different domain than the current location.

_isLocal

(
  • item
)
Boolean private

Inherited from AbstractLoader: _isLocal:405

Parameters:

  • item Object

    A load item with a src property

Returns:

Boolean:

If the load item is loading from the "file:" protocol. Assume that the host must be local as well.

_loadItem

(
  • loader
)
private

Defined in _loadItem:1441

Begin loading an item. Events are not added to the loaders until the load starts.

Parameters:

  • loader AbstractLoader

    The loader instance to start. Currently, this will be an XHRLoader or TagLoader.

_loadNext

() private

Defined in _loadNext:1393

Load the next item in the queue. If the queue is empty (all items have been loaded), then the complete event is processed. The queue will "fill up" any empty slots, up to the max connection specified using LoadQueue.setMaxConnections method. The only exception is scripts that are loaded using tags, which have to be loaded one at a time to maintain load order.

_parsePath

(
  • path
)
Array protected

Inherited from AbstractLoader: _parsePath:321

Parse a file URI using the AbstractLoader/PATH_PATTERN RegExp pattern.

Parameters:

  • path String

    The file path to parse.

Returns:

Array:

The matched path contents. Please see the PATH_PATTERN property for details on the return value. This will return null if it does not match.

_parseURI

(
  • path
)
Array protected

Inherited from AbstractLoader: _parseURI:308

Parse a file URI using the FILE_PATTERN RegExp pattern.

Parameters:

  • path String

    The file path to parse.

Returns:

Array:

The matched file contents. Please see the FILE_PATTERN property for details on the return value. This will return null if it does not match.

_processFinishedLoad

(
  • item
  • loader
)
protected

Parameters:

_removeLoadItem

(
  • loader
)
private

A load item is completed or was canceled, and needs to be removed from the LoadQueue.

Parameters:

_sendComplete

() protected

Dispatch a complete event. Please see the complete event for details on the event payload.

_sendError

(
  • event
)
protected

Inherited from AbstractLoader: _sendError:279

Dispatch an error event. Please see the error event for details on the event payload.

Parameters:

  • event Object

    The event object containing specific error properties.

_sendFileComplete

(
  • item
  • loader
)
protected

Dispatch a fileload event. Please see the fileload event for details on the event payload.

Parameters:

_sendFileProgress

(
  • item
  • progress
)
protected

Dispatch a fileprogress event (and onFileProgress callback). Please see the LoadQueue.fileprogress event for details on the event payload.

Parameters:

  • item Object

    The item that is being loaded.

  • progress Number

    The amount the item has been loaded (between 0 and 1).

_sendFileStart

(
  • item
)
protected

Defined in _sendFileStart:1772

Dispatch a filestart event immediately before a file starts to load. Please see the filestart event for details on the event payload.

Parameters:

  • item Object

    The item that is being loaded.

_sendLoadStart

() protected

Dispatch a loadstart event. Please see the loadstart event for details on the event payload.

_sendProgress

(
  • value
)
protected

Dispatch a progress event. Please see the progress event for details on the event payload.

Parameters:

  • value Number | Object

    The progress of the loaded item, or an object containing loaded and total properties.

_updateProgress

() private

Overall progress has changed, so determine the new progress amount and dispatch it. This changes any time an item dispatches progress or completes. Note that since we don't know the actual filesize of items before they are loaded, and even then we can only get the size of items loaded with XHR. In this case, we define a "slot" for each item (1 item in 10 would get 10%), and then append loaded progress on top of the already-loaded items.

For example, if 5/10 items have loaded, and item 6 is 20% loaded, the total progress would be:

  • 5/10 of the items in the queue (50%)
  • plus 20% of item 6's slot (2%)
  • equals 52%

addEventListener

(
  • type
  • listener
  • [useCapture]
)
Function | Object

Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.

Example

 displayObject.addEventListener("click", handleClick);
 function handleClick(event) {
    // Click happened.
 }

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function | Object:

Returns the listener for chaining or assignment.

buildPath

(
  • src
  • [data]
)
String

Inherited from AbstractLoader: buildPath:355

Available since 0.3.1

A utility method that builds a file path using a source and a data object, and formats it into a new path. All of the loaders in PreloadJS use this method to compile paths when loading.

Parameters:

  • src String

    The source path to add values to.

  • [data] Object optional

    Object used to append values to this request as a query string. Existing parameters on the path will be preserved.

Returns:

String:

A formatted string that contains the path and the supplied parameters.

close

()

Inherited from AbstractLoader: close:221

Close the active queue. Closing a queue completely empties the queue, and prevents any remaining items from starting to download. Note that currently any active loads will remain open, and events may be processed.

To stop and restart a queue, use the setPaused method instead.

dispatchEvent

(
  • eventObj
  • [target]
)
Boolean

Dispatches the specified event to all listeners.

Example

 // Use a string event
 this.dispatchEvent("complete");

 // Use an Event instance
 var event = new createjs.Event("progress");
 this.dispatchEvent(event);

Parameters:

  • eventObj Object | String | Event

    An object with a "type" property, or a string type. While a generic object will work, it is recommended to use a CreateJS Event instance. If a string is used, dispatchEvent will construct an Event instance with the specified type.

  • [target] Object optional

    The object to use as the target property of the event object. This will default to the dispatching object. This parameter is deprecated and will be removed.

Returns:

Boolean:

Returns the value of eventObj.defaultPrevented.

getItem

(
  • value
)
Object

Defined in getItem:1112

Look up a load item using either the "id" or "src" that was specified when loading it. Note that if no "id" was supplied with the load item, the ID will be the "src", including a path property defined by a manifest. The basePath will not be part of the ID.

Parameters:

  • value String

    The id or src of the load item.

Returns:

Object:

The load item that was initially requested using loadFile or loadManifest. This object is also returned via the fileload event as the item parameter.

getResult

(
  • value
  • [rawResult=false]
)
Object

Defined in getResult:1126

Look up a loaded result using either the "id" or "src" that was specified when loading it. Note that if no "id" was supplied with the load item, the ID will be the "src", including a path property defined by a manifest. The basePath will not be part of the ID.

Parameters:

  • value String

    The id or src of the load item.

  • [rawResult=false] Boolean optional

    Return a raw result instead of a formatted result. This applies to content loaded via XHR such as scripts, XML, CSS, and Images. If there is no raw result, the formatted result will be returned instead.

Returns:

Object:

A result object containing the content that was loaded, such as:

  • An image tag (<image />) for images
  • A script tag for JavaScript (<script />). Note that scripts are automatically added to the HTML DOM.
  • A style tag for CSS (<style /> or <link >)
  • Raw text for TEXT
  • A formatted JavaScript object defined by JSON
  • An XML document
  • A binary arraybuffer loaded by XHR
  • An audio tag (<audio >) for HTML audio. Note that it is recommended to use SoundJS APIs to play loaded audio. Specifically, audio loaded by Flash and WebAudio will return a loader object using this method which can not be used to play audio back.
This object is also returned via the fileload event as the 'item` parameter. Note that if a raw result is requested, but not found, the result will be returned instead.

hasEventListener

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean:

Returns true if there is at least one listener for the specified event.

init

() private

Inherited from AbstractLoader: init:202

Initialize the loader. This is called by the constructor.

initialize

() protected

Initialization method.

installPlugin

(
  • plugin
)

Defined in installPlugin:889

Register a plugin. Plugins can map to load types (sound, image, etc), or specific extensions (png, mp3, etc). Currently, only one plugin can exist per type/extension.

When a plugin is installed, a getPreloadHandlers() method will be called on it. For more information on this method, check out the getPreloadHandlers method in the SamplePlugin class.

Before a file is loaded, a matching plugin has an opportunity to modify the load. If a callback is returned from the getPreloadHandlers method, it will be invoked first, and its result may cancel or modify the item. The callback method can also return a completeHandler to be fired when the file is loaded, or a tag object, which will manage the actual download. For more information on these methods, check out the preloadHandler and fileLoadHandler methods on the SamplePlugin.

Parameters:

  • plugin Function

    The plugin class to install.

isBinary

(
  • type
)
Boolean private

Defined in isBinary:845

Determine if a specific type should be loaded as a binary file. Currently, only images and items marked specifically as "binary" are loaded as binary. Note that audio is not a binary type, as we can not play back using an audio tag if it is loaded as binary. Plugins can change the item type to binary to ensure they get a binary result to work with. Binary files are loaded using XHR2.

Parameters:

Returns:

Boolean:

If the specified type is binary.

isText

(
  • type
)
Boolean private

Defined in isText:866

Determine if a specific type is a text based asset, and should be loaded as UTF-8.

Parameters:

Returns:

Boolean:

If the specified type is text.

load

()

Inherited from AbstractLoader: load:209

Begin loading the queued items. This method can be called when a LoadQueue is set up but not started immediately.

Example:

 var queue = new createjs.LoadQueue();
 queue.addEventListener("complete", handleComplete);
 queue.loadManifest(fileArray, false); // Note the 2nd argument that tells the queue not to start loading yet
 queue.load();

loadFile

(
  • file
  • [loadNow=true]
  • [basePath]
)

Defined in loadFile:946

Load a single file. To add multiple files at once, use the loadManifest method.

Files are always appended to the current queue, so this method can be used multiple times to add files. To clear the queue first, use the close method.

Parameters:

  • file Object | String

    The file object or path to load. A file can be either

    • A string path to a resource. Note that this kind of load item will be converted to an object (see below) in the background.
    • OR an object that contains:
      • src: The source of the file that is being loaded. This property is required. The source can either be a string (recommended), or an HTML tag.
      • type: The type of file that will be loaded (image, sound, json, etc). PreloadJS does auto-detection of types using the extension. Supported types are defined on LoadQueue, such as LoadQueue.IMAGE. It is recommended that a type is specified when a non-standard file URI (such as a php script) us used.
      • id: A string identifier which can be used to reference the loaded object.
      • callback: Optional, used for JSONP requests, to define what method to call when the JSONP is loaded.
      • data: An arbitrary data object, which is included with the loaded object
      • method: used to define if this request uses GET or POST when sending data to the server. The default value is "GET"
      • values: Optional object of name/value pairs to send to the server.
  • [loadNow=true] Boolean optional

    Kick off an immediate load (true) or wait for a load call (false). The default value is true. If the queue is paused using setPaused, and the value is true, the queue will resume automatically.

  • [basePath] String optional

    A base path that will be prepended to each file. The basePath argument overrides the path specified in the constructor. Note that if you load a manifest using a file of type MANIFEST, its files will NOT use the basePath parameter. The basePath parameter is deprecated. This parameter will be removed in a future version. Please either use the basePath parameter in the LoadQueue constructor, or a path property in a manifest definition.

loadManifest

(
  • manifest
  • [loadNow=true]
  • [basePath]
)

Defined in loadManifest:996

Load an array of files. To load a single file, use the loadFile method. The files in the manifest are requested in the same order, but may complete in a different order if the max connections are set above 1 using setMaxConnections. Scripts will load in the right order as long as LoadQueue/maintainScriptOrder is true (which is default).

Files are always appended to the current queue, so this method can be used multiple times to add files. To clear the queue first, use the close method.

Parameters:

  • manifest Array | String | Object

    An list of files to load. The loadManifest call supports four types of manifests:

    1. A string path, which points to a manifest file, which is a JSON file that contains a "manifest" property, which defines the list of files to load, and can optionally contain a "path" property, which will be prepended to each file in the list.
    2. An object which defines a "src", which is a JSON or JSONP file. A "callback" can be defined for JSONP file. The JSON/JSONP file should contain a "manifest" property, which defines the list of files to load, and can optionally contain a "path" property, which will be prepended to each file in the list.
    3. An object which contains a "manifest" property, which defines the list of files to load, and can optionally contain a "path" property, which will be prepended to each file in the list.
    4. An Array of files to load.

    Each "file" in a manifest can be either:

    • A string path to a resource (string). Note that this kind of load item will be converted to an object (see below) in the background.
    • OR an object that contains:
      • src: The source of the file that is being loaded. This property is required. The source can either be a string (recommended), or an HTML tag.
      • type: The type of file that will be loaded (image, sound, json, etc). PreloadJS does auto-detection of types using the extension. Supported types are defined on LoadQueue, such as LoadQueue.IMAGE. It is recommended that a type is specified when a non-standard file URI (such as a php script) us used.
      • id: A string identifier which can be used to reference the loaded object.
      • callback: Optional, used for JSONP requests, to define what method to call when the JSONP is loaded.
      • data: An arbitrary data object, which is included with the loaded object
      • method: used to define if this request uses GET or POST when sending data to the server. The default value is "GET"
      • values: Optional object of name/value pairs to send to the server.
  • [loadNow=true] Boolean optional

    Kick off an immediate load (true) or wait for a load call (false). The default value is true. If the queue is paused using setPaused and this value is true, the queue will resume automatically.

  • [basePath] String optional

    A base path that will be prepended to each file. The basePath argument overrides the path specified in the constructor. Note that if you load a manifest using a file of type MANIFEST, its files will NOT use the basePath parameter. The basePath parameter is deprecated. This parameter will be removed in a future version. Please either use the basePath parameter in the LoadQueue constructor, or a path property in a manifest definition.

off

(
  • type
  • listener
  • [useCapture]
)

Inherited from EventDispatcher: off:247

A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the .on method.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

on

(
  • type
  • listener
  • [scope]
  • [once=false]
  • [data]
  • [useCapture=false]
)
Function

Inherited from EventDispatcher: on:175

A shortcut method for using addEventListener that makes it easier to specify an execution scope, have a listener only run once, associate arbitrary data with the listener, and remove the listener.

This method works by creating an anonymous wrapper function and subscribing it with addEventListener. The created anonymous function is returned for use with .removeEventListener (or .off).

Example

    var listener = myBtn.on("click", handleClick, null, false, {count:3});
    function handleClick(evt, data) {
        data.count -= 1;
        console.log(this == myBtn); // true - scope defaults to the dispatcher
        if (data.count == 0) {
            alert("clicked 3 times!");
            myBtn.off("click", listener);
            // alternately: evt.remove();
        }
    }

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

  • [scope] Object optional

    The scope to execute the listener in. Defaults to the dispatcher/currentTarget for function listeners, and to the listener itself for object listeners (ie. using handleEvent).

  • [once=false] Boolean optional

    If true, the listener will remove itself after the first time it is triggered.

  • [data] optional

    Arbitrary data that will be included as the second parameter when the listener is called.

  • [useCapture=false] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function:

Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.

proxy

(
  • method
  • scope
)
deprecated private static

Defined in proxy:1785

Deprecated: In favour of the createjs.proxy method (see LoadQueue source).

REMOVED. Use createjs.proxy instead

Parameters:

  • method Function

    The function to call

  • scope Object

    The scope to call the method name on

remove

(
  • idsOrUrls
)

Defined in remove:734

Available since 0.3.0

Stops an item from being loaded, and removes it from the queue. If nothing is passed, all items are removed. This also removes internal references to loaded item(s).

Example

 queue.loadManifest([
     {src:"test.png", id:"png"},
     {src:"test.jpg", id:"jpg"},
     {src:"test.mp3", id:"mp3"}
 ]);
 queue.remove("png"); // Single item by ID
 queue.remove("png", "test.jpg"); // Items as arguments. Mixed id and src.
 queue.remove(["test.png", "jpg"]); // Items in an Array. Mixed id and src.

Parameters:

  • idsOrUrls String | Array multiple

    The id or ids to remove from this queue. You can pass an item, an array of items, or multiple items as arguments.

removeAll

()

Defined in removeAll:724

Available since 0.3.0

Stops all queued and loading items, and clears the queue. This also removes all internal references to loaded content, and allows the queue to be used again.

removeAllEventListeners

(
  • [type]
)

Removes all listeners for the specified type, or all listeners of all types.

Example

 // Remove all listeners
 displayObject.removeAllEventListeners();

 // Remove all click listeners
 displayObject.removeAllEventListeners("click");

Parameters:

  • [type] String optional

    The string type of the event. If omitted, all listeners for all types will be removed.

removeEventListener

(
  • type
  • listener
  • [useCapture]
)

Removes the specified event listener.

Important Note: that you must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.

Example

 displayObject.removeEventListener("click", handleClick);

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

reset

()

Defined in reset:822

Available since 0.3.0

Stops all open loads, destroys any loaded items, and resets the queue, so all items can be reloaded again by calling load. Items are not removed from the queue. To remove items use the remove or removeAll method.

setMaxConnections

(
  • value
)

Set the maximum number of concurrent connections. Note that browsers and servers may have a built-in maximum number of open connections, so any additional connections may remain in a pending state until the browser opens the connection. When loading scripts using tags, and when maintainScriptOrder is true, only one script is loaded at a time due to browser limitations.

Example

 var queue = new createjs.LoadQueue();
 queue.setMaxConnections(10); // Allow 10 concurrent loads

Parameters:

  • value Number

    The number of concurrent loads to allow. By default, only a single connection per LoadQueue is open at any time.

setPaused

(
  • value
)

Defined in setPaused:1162

Pause or resume the current load. Active loads will not be cancelled, but the next items in the queue will not be processed when active loads complete. LoadQueues are not paused by default.

Note that if new items are added to the queue using loadFile or loadManifest, a paused queue will be resumed, unless the loadNow argument is false.

Parameters:

  • value Boolean

    Whether the queue should be paused or not.

setUseXHR

(
  • value
)
Boolean

Defined in setUseXHR:707

Available since 0.3.0

Change the usXHR value. Note that if this is set to true, it may fail depending on the browser's capabilities. Additionally, some files require XHR in order to load, such as JSON (without JSONP), Text, and XML, so XHR will be used regardless of what is passed to this method.

Parameters:

  • value Boolean

    The new useXHR value to set.

Returns:

Boolean:

The new useXHR value. If XHR is not supported by the browser, this will return false, even if the provided value argument was true.

toString

() String

Inherited from EventDispatcher but overwritten in toString:418

Returns:

String:

a string representation of the instance.

willTrigger

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type on this object or any of its ancestors (parent, parent's parent, etc). A return value of true indicates that if a bubbling event of the specified type is dispatched from this object, it will trigger at least one listener.

This is similar to hasEventListener, but it searches the entire event flow for a listener, not just this object.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean:

Returns true if there is at least one listener for the specified event.

Properties

_basePath

String private

Defined in _basePath:413

Available since 0.3.1

A path that will be prepended on to the item's src. The _basePath property will only be used if an item's source is relative, and does not include a protocol such as http://, or a relative path such as ../.

_captureListeners

Object protected

_crossOrigin

String private

Defined in _crossOrigin:423

Available since 0.4.1

An optional flag to set on images that are loaded using PreloadJS, which enables CORS support. Images loaded cross-domain by servers that support CORS require the crossOrigin flag to be loaded and interacted with by a canvas. When loading locally, or with a server with no CORS support, this flag can cause other security issues, so it is recommended to only set it if you are sure the server supports it. Currently, supported values are "" and "Anonymous".

_currentLoads

Array private

Defined in _currentLoads:585

An array containing the currently downloading files.

_currentlyLoadingScript

Boolean private

Determines if there is currently a script loading. This helps ensure that only a single script loads at once when using a script tag to do preloading.

_extensionCallbacks

Null private

An object hash of callbacks that are fired for each file extension before the file is loaded, giving plugins the ability to override properties of the load. Please see the installPlugin method for more information.

_item

Object private

Inherited from AbstractLoader: _item:109

The item this loader represents. Note that this is null in a LoadQueue, but will be available on loaders such as XHRLoader and TagLoader.

_listeners

Object protected

_loadedRawResults

Object private

An object hash of un-parsed loaded items, indexed by the ID of the load item.

_loadedResults

Object private

Defined in _loadedResults:625

An object hash of loaded items, indexed by the ID of the load item.

_loadedScripts

Array private

Defined in _loadedScripts:670

A list of scripts that have been loaded. Items are added to this list as null when they are requested, contain the loaded item if it has completed, but not been dispatched to the user, and true once they are complete and have been dispatched.

_loadItemsById

Object private

Defined in _loadItemsById:609

An object hash of items that have finished downloading, indexed by item IDs.

_loadItemsBySrc

Object private

Defined in _loadItemsBySrc:617

An object hash of items that have finished downloading, indexed by item source.

_loadQueue

Array private

Defined in _loadQueue:593

An array containing the queued items that have not yet started downloading.

_loadQueueBackup

Array private

An array containing downloads that have not completed, so that the LoadQueue can be properly reset.

_loadStartWasDispatched

Boolean private

Determines if the loadStart event was dispatched already. This event is only fired one time, when the first file is requested.

Default: false

_maxConnections

Number private

Defined in _maxConnections:566

The number of maximum open connections that a loadQueue tries to maintain. Please see setMaxConnections for more information.

Default: 1

_numItems

Number private

Defined in _numItems:641

The number of items that have been requested. This helps manage an overall progress without knowing how large the files are before they are downloaded.

Default: 0

_numItemsLoaded

Number private

Defined in _numItemsLoaded:651

The number of items that have completed loaded. This helps manage an overall progress without knowing how large the files are before they are downloaded.

Default: 0

_scriptOrder

Array private

Defined in _scriptOrder:661

A list of scripts in the order they were requested. This helps ensure that scripts are "completed" in the right order.

_typeCallbacks

Object private

Defined in _typeCallbacks:536

An object hash of callbacks that are fired for each file type before the file is loaded, giving plugins the ability to override properties of the load. Please see the installPlugin method for more information.

BINARY

String static

Defined in BINARY:279

The preload type for generic binary types. Note that images are loaded as binary files when using XHR.

Default: binary

canceled

Boolean

Inherited from AbstractLoader: canceled:82

Determine if the loader was canceled. Canceled loads will not fire complete events. Note that LoadQueue queues should be closed using close instead of setting this property.

Default: false

CSS

String static

Defined in CSS:288

The preload type for css files. CSS files are loaded using a <link> when loaded with XHR, or a <style> tag when loaded with tags.

Default: css

IMAGE

String static

Defined in IMAGE:298

The preload type for image files, usually png, gif, or jpg/jpeg. Images are loaded into an <image> tag.

Default: image

JAVASCRIPT

String static

Defined in JAVASCRIPT:307

The preload type for javascript files, usually with the "js" file extension. JavaScript files are loaded into a <script> tag.

Since version 0.4.1+, due to how tag-loaded scripts work, all JavaScript files are automatically injected into the body of the document to maintain parity between XHR and tag-loaded scripts. In version 0.4.0 and earlier, only tag-loaded scripts are injected.

Default: javascript

JSON

String static

Defined in JSON:321

The preload type for json files, usually with the "json" file extension. JSON data is loaded and parsed into a JavaScript object. Note that if a callback is present on the load item, the file will be loaded with JSONP, no matter what the useXHR property is set to, and the JSON must contain a matching wrapper function.

Default: json

JSONP

String static

Defined in JSONP:333

The preload type for jsonp files, usually with the "json" file extension. JSON data is loaded and parsed into a JavaScript object. You are required to pass a callback parameter that matches the function wrapper in the JSON. Note that JSONP will always be used if there is a callback present, no matter what the useXHR property is set to.

Default: jsonp

loaded

Boolean

Inherited from AbstractLoader: loaded:73

If the loader has completed loading. This provides a quick check, but also ensures that the different approaches used for loading do not pile up resulting in more than one complete event.

Default: false

loadTimeout

Number static

Defined in loadTimeout:260

Available since 0.4.1

Time in milliseconds to assume a load has failed. An error event is dispatched if the timeout is reached before any data is received.

Default: 8000

maintainScriptOrder

Boolean

Ensure loaded scripts "complete" in the order they are specified. Loaded scripts are added to the document head once they are loaded. Note that scripts loaded via tags will load one-at-a-time when this property is true. load one at a time

Default: true

MANIFEST

String static

Defined in MANIFEST:345

Available since 0.4.1

The preload type for json-based manifest files, usually with the "json" file extension. The JSON data is loaded and parsed into a JavaScript object. PreloadJS will then look for a "manifest" property in the JSON, which is an Array of files to load, following the same format as the loadManifest method. If a "callback" is specified on the manifest object, then it will be loaded using JSONP instead, regardless of what the useXHR property is set to.

Default: manifest

next

LoadQueue

Defined in next:470

The next preload queue to process when this one is complete. If an error is thrown in the current queue, and stopOnError is true, the next queue will not be processed.

Default: null

onComplete

Function deprecated

Inherited from AbstractLoader: onComplete:176

Deprecated: Use addEventListener and the "complete" event.

REMOVED. Use addEventListener and the complete event.

onError

Function deprecated

Inherited from AbstractLoader: onError:183

Deprecated: Use addEventListener and the "error" event.

REMOVED. Use addEventListener and the error event.

onFileLoad

Function deprecated

Defined in onFileLoad:519

Deprecated: Use addEventListener and the "fileload" event.

REMOVED. Use addEventListener and the fileload event.

onFileProgress

Function deprecated

Defined in onFileProgress:526

Deprecated: Use addEventListener and the "fileprogress" event.

REMOVED. Use addEventListener and the fileprogress event.

onLoadStart

Function deprecated

Inherited from AbstractLoader: onLoadStart:169

Deprecated: Use addEventListener and the "loadstart" event.

REMOVED. Use addEventListener and the loadstart event.

onProgress

Function deprecated

Inherited from AbstractLoader: onProgress:162

Deprecated: Use addEventListener and the "progress" event.

REMOVED. Use addEventListener and the progress event.

progress

Number

Inherited from AbstractLoader: progress:92

The current load progress (percentage) for this item. This will be a number between 0 and 1.

Example

var queue = new createjs.LoadQueue();
queue.loadFile("largeImage.png");
queue.on("progress", function() {
    console.log("Progress:", queue.progress, event.progress);
});

Default: 0

SOUND

String static

Defined in SOUND:359

The preload type for sound files, usually mp3, ogg, or wav. When loading via tags, audio is loaded into an <audio> tag.

Default: sound

stopOnError

Boolean

Defined in stopOnError:452

Determines if the LoadQueue will stop processing the current queue when an error is encountered.

Default: false

SVG

String static

Defined in SVG:369

The preload type for SVG files.

Default: svg

TEXT

String static

Defined in TEXT:378

The preload type for text files, which is also the default file type if the type can not be determined. Text is loaded as raw text.

Default: text

useXHR

Boolean

Defined in useXHR:437

Use XMLHttpRequest (XHR) when possible. Note that LoadQueue will default to tag loading or XHR loading depending on the requirements for a media type. For example, HTML audio can not be loaded with XHR, and WebAudio can not be loaded with tags, so it will default the the correct type instead of using the user-defined type.

Note: This property is read-only. To change it, please use the setUseXHR method, or specify the useXHR argument in the LoadQueue constructor.

Default: true

XML

String static

Defined in XML:388

The preload type for xml files. XML is loaded into an XML document.

Default: xml

Events

complete

Inherited from AbstractLoader: complete:139

Available since 0.3.0

The event that is fired when the entire queue has been loaded.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

error

Inherited from AbstractLoader: error:147

Available since 0.3.0

The event that is fired when the loader encounters an error. If the error was encountered by a file, the event will contain the item that caused the error. There may be additional properties such as the error reason on event objects.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

  • [item] Object optional

    The item that was being loaded that caused the error. The item was specified in the loadFile or loadManifest call. If only a string path or tag was specified, the object will contain that value as a src property.

  • [error] String optional

    The error object or text.

fileload

Defined in fileload:480

Available since 0.3.0

This event is fired when an individual file has loaded, and been processed.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

  • item Object

    The file item which was specified in the loadFile or loadManifest call. If only a string path or tag was specified, the object will contain that value as a src property.

  • result Object

    The HTML tag or parsed result of the loaded item.

  • rawResult Object

    The unprocessed result, usually the raw text or binary data before it is converted to a usable object.

fileprogress

Defined in fileprogress:494

Available since 0.3.0

This event is fired when an an individual file progress changes.

Event Payload:

  • The Object

    object that dispatched the event.

  • type String

    The event type.

  • item Object

    The file item which was specified in the loadFile or loadManifest call. If only a string path or tag was specified, the object will contain that value as a src property.

  • loaded Number

    The number of bytes that have been loaded. Note that this may just be a percentage of 1.

  • total Number

    The total number of bytes. If it is unknown, the value is 1.

  • progress Number

    The amount that has been loaded between 0 and 1.

filestart

Defined in filestart:508

This event is fired when an individual file starts to load.

Event Payload:

  • The Object

    object that dispatched the event.

  • type String

    The event type.

  • item Object

    The file item which was specified in the loadFile or loadManifest call. If only a string path or tag was specified, the object will contain that value as a property.

loadstart

Inherited from AbstractLoader: loadstart:131

Available since 0.3.1

The event that is fired when a load starts.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

progress

Inherited from AbstractLoader: progress:119

Available since 0.3.0

The event that is fired when the overall progress changes.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

  • loaded Number

    The amount that has been loaded so far. Note that this is may just be a percentage of 1, since file sizes can not be determined before a load is kicked off, if at all.

  • total Number

    The total number of bytes. Note that this may just be 1.

  • progress Number

    The ratio that has been loaded between 0 and 1.