Class: SC.imageQueue

Extends SC.Object.

The image queue can be used to control the order of loading images.

Images queues are necessary because browsers impose strict limits on the number of concurrent connections that can be open at any one time to any one host. By controlling the order and timing of your loads using this image queue, you can improve the percieved performance of your application by ensuring the images you need most load first.

Note that if you use the SC.ImageView class, it will use this image queue for you automatically.

Loading Images

When you need to display an image, simply call the loadImage() method with the URL of the image, along with a target/method callback. The signature of your callback should be:

imageDidLoad: function(imageUrl, imageOrError) {

The "imageOrError" parameter will contain either an image object or an error object if the image could not be loaded for some reason. If you receive an error object, it will be one of SC.IMAGE_ABORTED_ERROR or SC.IMAGE_FAILED_ERROR.

You can also optionally specify that the image should be loaded in the background. Background images are loaded with a lower priority than foreground images.

Aborting Image Loads

If you request an image load but then no longer require the image for some reason, you should notify the imageQueue by calling the releaseImage() method. Pass the URL, target and method that you included in your original loadImage() request.

If you have requested an image before, you should always call releaseImage() when you are finished with it, even if the image has already loaded. This will allow the imageQueue to properly manage its own internal resources.

This method may remove the image from the queue of images that need or load or it may abort an image load in progress to make room for other images. If the image is already loaded, this method will have no effect.

Reloading an Image

If you have already loaded an image, the imageQueue will avoid loading the image again. However, if you need to force the imageQueue to reload the image for some reason, you can do so by calling reloadImage(), passing the URL.

This will cause the image queue to attempt to load the image again the next time you call loadImage on it.

Defined in: image_queue.js

SproutCore 1.0

Field Summary

Instance Methods

Field Detail

The number of currently active requests on the queue.

The maximum number of images that can load from a single hostname at any one time. For most browsers 4 is a reasonable number, though you may tweak this on a browser-by-browser basis.

Instance Method Detail

loadImage(url, target, method, isBackgroundFlag)

Loads an image from the server, calling your target/method when complete.

You should always pass at least a URL and optionally a target/method. If you do not pass the target/method, the image will be loaded in background priority. Usually, however, you will want to pass a callback to be notified when the image has loaded. Your callback should have a signature like:

imageDidLoad: function(imageUrl, imageOrError) { .. }

If you do pass a target/method you can optionally also choose to load the image either in the foreground or in the background. The imageQueue prioritizes foreground images over background images. This does not impact how many images load at one time.

url String
target Object
method String|Function
isBackgroundFlag Boolean

Initiates a load of the next image in the image queue. Normally you will not need to call this method yourself as it will be initiated automatically when the queue becomes active.

releaseImage(url, target, method)

Invoke this method when you are finished with an image URL. If you passed a target/method, you should also pass it here to remove it from the list of callbacks.

url String
target Object
method String|Function
Forces the image to reload the next time you try to load it.
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)