com.smartgwt.client.docs

Interface SCSpriteConfig

All Superinterfaces:

SCImgURL, URI, URL

public interface SCSpriteConfig
extends SCImgURL

Special SCImgURL format for specifying sprited image configuration.

See also the "spriting" discussion in the skinning overview documentation.

In order to generate HTML to render a properly scaled image sprite from a composite image file, this format allows developers to specify the image source, native size and offset of the sprite within the image, and the desired drawn size for the image.
spriteConfigs have the following format:

   "sprite:<image URL>;offset:<Left>,<Top>;size:<Width>,<Height>;cssClass:<className>"
  

Where supported, the sprite: prefix is used to identify a specified SCImgURL as a sprited 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.
An explicit URL is not required - developers may also specify a css class which includes an explicit background-image attribute.
The size: and offset: properties should specify the pixel size and position of the sprite within the composite image. Again these are not required and can be specified directly in the css class using width and height and background-offset properties.
The cssClass: denotes the css class to apply to the sprite. This is also 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).

Sprited image configuration and "stateful" images
Many image URLs in Smart GWT are "stateful", meaning that the actual URL used to fetch an image will vary according to the component's state (eg, "Disabled"), generally, by adding a suffix to the image URL.
Component image attributes which support "stateful" suffixes are not guaranteed to always support having their value set to a SCSpriteConfig string, as special handling is required both to ensure the stateful suffix is incorporated into the generated HTML correctly and that logic to update the images state at runtime handles this HTML being present in the DOM rather than a simple <img...> element.
Where these are supported they will be documented as such. The handling in these cases is as follows:

• if the configuration includes an explicit image URL, stateful suffixes are combined and appended using "_" characters as described in Img.src
• if the configuration inclues a cssClass, the stateful suffixes will be combined and appended to the class name (with no "_" characters), as with standard StatefulCanvas.baseStyle stateful suffixes