com.smartgwt.client.docs

Interface SCSpriteConfig

All Superinterfaces:

SCImgURL, URI, URL

public interface SCSpriteConfig
extends SCImgURL

Using Sprites

Image sprites are a technique to minimize server http requests when displaying media to a user. Given a series of small images (icons, say), instead of having a separate image file be loaded for each icon, the server can provide a single large composite image to the client, and the client can use CSS to display sections of this larger image to the user.
See also the "spriting" discussion in the skinning overview documentation.

The Smart GWT framework supports the SCSpriteConfig format for sprited images.

Note that SCSpriteConfig is just a special class of image URL, and as such any component attribute of type SCImgURL may be set to a sprite configuration.

SCSpriteConfigs have the following format:
"sprite:<image URL>;offset:<Left>,<Top>;size:<Width>,<Height>;cssClass:<className>"

This format allows developers to specify the image source and the native size and offset of the sprite within the image.

The media to load will be retrieved from the specified image URL. Standard SCImgURL directory prefixes such as "[SKIN]" can be included in this URL.

Developers may also specify an image data URL - for example "sprite:data:image/jpeg;base64,<data>;offset:-120,0;size:20,20;".

An explicit URL is not required. Developers may instead specify a css class which can include an explicit background-image attribute.

The offset: property specifies the left and top coordinate to apply to the composite image element such that the desired sprite is visible. The size: property indicates the size of the sprite in pixels.
For example, a sprite configuration of "sprite:composite.png;offset:0,-20;size:20,20;" would load the image file "composite.png", and display a 20 pixel square from it. The origin of the larger image would be offset vertically by -20px, so the sprite actually visible to the user would have its y-origin at 20px within the larger image.
As with the image URL, explicit size and offset are not required - a developer may use css properties (width, height and background-offset) from the specified class to specify the specific sprite to display.

The cssClass: denotes the css class to apply to the rendered element displaying the sprite. This is optional - a sprite can be specified with an image URL and explicit sizing and offset coordinates, in which case no css class is actually required.
(Of course for a valid sprite, it is expected that the image URL and size are specified either explicitly in the string, or within the css class definition. If the offset is omitted, it will be assumed to be zero on both axes).

Sprites will scale automatically. If a spriteConfig is used to provide an image for an icon and some other property is used to configure the drawn size of the icon in question (Button.iconSize,for example), the sprite image will be scaled to render at the appropriate size.

Sprited image configuration and "stateful" images

Many image URLs in Smart GWT are "stateful", meaning that variants of the image should be displayed to the user depending on the current state of the widget. (For example a custom button icon may be displayed on roll over, or a selection checkbox icon in a treeGrid may appear disabled for unselectable nodes).

There are a couple of approaches to display stateful versions of sprited images.

Wherever SCStatefulImgConfig objects are supported, a developer may include spriteConfig strings as entries for specific states.
For example, the following SCStatefulImgConfig definition would display different sprites from "compositeImg.png" for base and "Over" states:
{ _base:"sprite:compositeImg.png;offset:-100,-100;size:20,20",
Over:"sprite:compositeImg.png;offset:-100,-120;size:20,20" }

Alternatively, if a property that behaves as the base URL for a stateful image (such as Button.icon) is set to a sprite configuration string, the framework will use the state name as a suffix to apply to the source URL or the css class specified in the sprite.
As with standard stateful images, if a URL was specified for the sprite, the stateful suffix will be applied with a preceding "_" character.
So if the state "Over" was applied to a sprite configuration of "sprite:compositeImg.png;offset:100,100;size:20,20", the generated HTML would attempt to load an image from the URL "compositeImg_Over.png" (and display a sprite from that image with the specified size/offset).
If a class name was specified in the sprite, the stateful suffix would be appended with no leading underscore, similar to how state suffixes are applied to the baseStyle of a StatefulCanvas.
For example a sprite config of "sprite:cssClass:buttonIcon" would display styling from "buttonIconOver" when the "Over" state was applied.

SVG sprites

If you have a collection of SVG graphics, you can combine them into a single <svg> container, and then use the sprite: mechanism to access them as SVG symbols, which can be reused and re-colored at runtime without server traffic.

See the SVG Symbols overview for more information.