public interface SCSpriteConfig extends SCImgURL
skinning overview documentation.
The Smart GWT
framework supports the
SCSpriteConfig format for sprited images.
spriteConfigs have the following format:
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.
An explicit URL is not required - developers may instead specify a css class which can include an explicit
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
For example, a sprite configuration of
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
As with the image URL, explicit size and offset are not required - a developer may use css properties (
background-offset) from the specified class to specify the
specific sprite to display.
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.
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:
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
"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
would display styling from
"buttonIconOver" when the "Over" state was applied.