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
- Since:
- SproutCore 1.0
Field Summary
- Fields borrowed from SC.Object:
- concatenatedProperties, isDestroyed, isObject, nextProperty, object, property, target, toInvalidate
- Fields borrowed from SC.Observable:
- isObservable
Instance Methods
- init()
- loadImage(url, target, method, isBackgroundFlag)
- loadNextImage()
- releaseImage(url, target, method)
- reloadImage(url)
Field Detail
activeRequestsThe 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
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.
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.
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.
- Parameters:
- url String
- target Object
- method String|Function
- Returns:
- SC.imageQueue
- receiver
- Parameters:
- url