Package com.smartgwt.client.docs

# Interface StatefulImages

public interface StatefulImages

### Stateful Images

Images displayed in `stateful components` may display different media depending on the current state of the component. See the `Img.src` attribute or `Button.icon` attribute for examples of such "stateful images".

In general the media to load for each state may be specified in two ways:

### Base URL combined with state suffixes

If the property in question is set to a standard `image URL`, this value will be treated as a default, or base URL. When a new `state` is applied, this filename will be combined with the state name to form a combined URL. This in turn changes the media that gets loaded and updates the image to reflect the new state.
Note that if the property was defined as a sprite configuration string a css style may be defined instead of, or in addition to a src URL. See the `sprite configuration documentation` for a discussion of how sprites can be used for stateful images.

The following table lists out the standard set of combined URLs that may be generated. Subclasses may support additional state-derived media of course. Note that the src URL will be split such that the extension is always applied to the end of the combined string. For example in the following table, if `src` was set to `"blank.gif"`, the Selected+Focused URL would be `"blank_Selected_Focused.gif"`.

URL for Img source | Description
`src+extension` | Default URL
`src+"_Selected"+extension` | Applied when `StatefulCanvas.selected` is set to true
`src+"_Focused"+extension` | Applied when the component has keyboard focus, if `StatefulCanvas.showFocused` is true, and `StatefulCanvas.showFocusedAsOver` is not true.
`src+"_Over"+extension` | Applied when the user rolls over the component if `StatefulCanvas.showRollOver` is set to true
`src+"_Down"+extension` | Applied when the user presses the mouse button over over the component if `StatefulCanvas.showDown` is set to true
`src+"_Disabled"+extension` | Applied to `Canvas.disabled` component if `StatefulCanvas.showDisabled` is true.
Combined states
`src+"_Selected_Focused"+extension` | Combined Selected and focused state
`src+"_Selected_Over"+extension` | Combined Selected and rollOver state
`src+"_Focused_Over"+extension` | Combined Focused and rollOver state
`src+"_Selected_Focused_Over"+extension` | Combined Selected, Focused and rollOver state
`src+"_Selected_Down"+extension` | Combined Selected and mouse-down state
`src+"_Focused_Down"+extension` | Combined Focused and mouse-down state
`src+"_Selected_Focused_Down"+extension` | Combined Selected, Focused and mouse-down state
`src+"_Selected_Disabled"+extension` | Combined Selected and Disabled state

### Explicit stateful image configuration

The `SCStatefulImgConfig` object allows developers to specify a set of explicit image URLs, one for each state to be displayed, rather than relying on an automatically generated combined URL. This pattern is useful for cases where the filename of the stateful versions of the image doesn't match up with the auto-generated format.