public interface SCSpriteConfig extends SCImgURL
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.
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.
sprite:
mechanism to access them. The <svg>
container can be defined externally in a .svg file or inline in your HTML, but it must
conform to the following 3 rules:
<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" style="position: absolute; width: 0; height: 0; overflow: hidden;" > <defs> <symbol id="icon-play" viewBox="0 0 32 32"> <path d="M6 4l20 12-20 12z"></path> </symbol> ... </defs> </svg>
An <svg> container structured in this way will not be rendered in the browser, but the
<symbol>s it defines are made available as a set of templates which
can be re-used later in src
strings. The format of src
strings
differs slightly according to where your <svg> container is defined. If it's defined
inline in the HTML, only the fragment-id is required - for example
src: "sprite:usesvg:#icon-play"If it's defined in a separate file, you must also specify which file:
src: "sprite:usesvg:path/to/fileName.svg#icon-play"When the external file-name is specified in this way, there is no need for the developer to explicitly load the file.
Note that this mechanism is not explicitly supported in any version of Internet Explorer, since that browser has never had full SVG support.
At its most basic, individual graphics elements in a <symbol> which do not specify styles inline can be easily modified. If all child elements are unstyled (ie, the symbol is single-color, even if it has multiple child graphics), the image-color can be changed as a whole by applying external CSS. If some child elements have inlined styles, they will not be modified by such external CSS - this means that certain parts of a <symbol> can be of a fixed-color, via inlined styles, while other parts can be left unstyled and can be customized via external CSS later, to highlight only those unstyled parts.
Another way to apply two colors at once is to have parts of your <symbol> use the
special currentColor
CSS value, like fill=currentColor
. This
value is always equal to the current/inherited CSS color
and can be
referenced by graphics elements. If your CSS class sets fill
and
color
to different values, graphics elements that use currentColor
will assume the color
value.
As noted above, it's also possible to fully re-style more complex, multi-color SVG - but this involves ensuring that all styling is externalized and backed by CSS; these details are highly dependent on the graphics and as such are the responsibility of the graphics designer or generator tool.
svgIcon
style that you can use or modify for this purpose, or you can create
your own custom styles:
// filled icons, no outline .icon { fill: grey; stroke: none; } .iconOver { fill: green; stroke: none; } .iconDown { fill: lightgreen; stroke: none; } .iconDisabled { fill: lightgrey; stroke: none; } // outline icons, no fill .iconOutline { stroke: grey; stroke-width: 1px; fill: none; } .iconOutlineOver { stroke: green; stroke-width: 1px; fill: none; } .iconOutlineDown { stroke: lightgreen; stroke-width: 1px; fill: none; } .iconOutlineDisabled { stroke: lightgrey; stroke-width: 1px; fill: none; }This class can then be applied to a stateful widget via its
baseStyle
or similar, by including it directly in src
strings, or as separate per-state
URLs in an SCStatefulImgConfig
object.
isc.Img.create({ // show stateful styles showRollOver: true, showDown: true // use baseStyle for statefulness src: "sprite:usesvg:fileName.svg#icon-id;", baseStyle: "icon" // or, use cssClass in config-strings for statefulness src: "sprite:usesvg:fileName.svg#icon-id;cssClass:icon;" // or, use a specific cssClass for each state, in an SCStatefulImgConfig block src: { _base: "sprite:usesvg:fileName.svg#icon-id;cssClass:icon;", Over: "sprite:usesvg:fileName.svg#icon-id;cssClass:iconOver;", Down: "sprite:usesvg:fileName.svg#icon-id;cssClass:iconDown;", Disabled: "sprite:usesvg:fileName.svg#icon-id;cssClass:iconDisabled;" } })
Developers can also override fill
, stroke
and
stroke-width
on a per usage basis, by specifying them directly in sprite-config
src
strings
// apply settings in the sprite-config string - this modifies the style
// attribute, and will override presentation attributes on svg symbol elements
isc.Img.create({
src: {
_base: "sprite:usesvg:fileName.svg#icon-id;fill:grey;",
Over: "sprite:usesvg:fileName.svg#icon-id;fill:green;",
Down: "sprite:usesvg:fileName.svg#icon-id;fill:lightgreen;",
Disabled: "sprite:usesvg:fileName.svg#icon-id;fill:lightgrey;"
}
})
Some UI elements also provide default colors for SVG graphics - for example, an unstyled
SVG used as the icon in a MenuItem will show skin-appropriate stateful colors automatically.
MenuItem.icon
is not itself a stateful attribute, but its
colors will be inherited
from the menu's stateful icon-field
if not
specified.
isc.Menu.create({ items: [ { title: "Option 1", icon: "sprite:usesvg:fileName.svg#icon-id" } ] })