Package com.smartgwt.client.docs

# Interface SCImgURL

All Superinterfaces:
  `URI`, `URL`

All Known Subinterfaces:
  `SCSpriteConfig`

public interface SCImgURL extends URL
For properties that refer to images by URL, such as `Img.src` and `Button.icon`, Smart GWT provides various capabilities to allow for simpler and more uniform settings, and to allow applications to be restructured more easily.

StockIcons

Smart GWT defines a list of known-icons which can be used by name in src-strings. For example, setting a button's `icon` property to "Edit" will show the current image mapped to the builtin StockIcon with that name. You can also modify the image currently assigned to the "Edit" icon by calling Media.updateIconMapping("Edit", "new src").

When using a StockIcon-name as a src, you may also include additional settings to extend the StockIcon if applicable. For example, a src of "Edit:size:24,24;" will take the "Edit" stockIcon's current src and, if that src represents a sprite-string, apply the additional size attributes and render the Edit icon at a larger size.

These features are especially useful in combination with `SVG Symbols` using runtime-styling, where colors can be easily modified on a per usage-basis, for example with "Edit:color:red;". the application image directory

When specifying URLs to image files via Smart GWT component properties such as `StretchImg.src`, any relative path is assumed to be relative to the "application image directory" (`appImgDir`). The application image directory can be set via `Page.setAppImgDir()`, and defaults to "images/", representing the typical practice of placing images in a subdirectory relative to the URL at which the application is accessed.

For applications that may be launched from multiple URLs, the `appImgDir` can be set to the correct relative path to the image directory by calling `Page.setAppImgDir()` before any Smart GWT components are created. This enables applications or components of an application to be launched from multiple locations, or to be relocated, without changing any image URLs supplied to Smart GWT components.

the "[SKIN]" URL prefix

The special prefix "[SKIN]" can be used to refer to images within the skin folder whenever image URLs are supplied to Smart GWT components.

The value of "[SKIN]" is the combination of:

- the "skin directory", established in `load_skin.js` via `Page.setSkinDir()`, plus..
- the setting for `skinImgDir` on the component where you set an image URL property

`skinImgDir` defaults to "images/", so creating an `Img` component with `Img.src` set to "[SKIN]myButton/button.gif" will expand to `Page.getSkinDir() + "/images/myButton/button.gif"`.

Some components that use a large number of images use `skinImgDir` to group them together and make it possible to relocate all the media for the component with a single setting. For example, the `TreeGrid` class sets `skinImgDir` to "images/TreeGrid/". This allows `TreeGrid.folderIcon` to be set to just "[SKIN]folder.gif" but refer to `Page.getSkinDir() + "/images/TreeGrid/folder.gif"`.

A custom subclass of TreeGrid can set `skinImgDir` to a different path, such as "/images/MyTreeGrid", to source all media from a different location.

TIPS:

- subcomponents do not automatically share the parent component's setting for skinImgDir. For example, the `Window.minimizeButton` has the default setting for "skinImgDir" ("images/"), so the `src` property used with this component is set to "[SKIN]/Window/minimize.png" (in the "Smart GWT" sample skin).
- for a particular image, the skinImgDir setting on the component may not be convenient. The prefix "[SKINIMG]" can be used to refer to `Page.getSkinDir() + "/images"` regardless of the setting for `skinImgDir`

Using a css class instead of an image URL

In some cases, instead of an explicit image URL, developers may wish to apply a named css class with a background-image to an image based component. This may be achieved by specifying your image URL in the format "style:<styleName>".

For example if your application loads the following css class:

      .starImg {
         width: 48px; height: 48px;
         background: url(/images/star.gif) 0 0;
      }

It may be displayed in an Img component by setting `Img.src` to `"style:startImg"`.

Sprited images

In addition to the `"style:..."` prefix for specifying a css class instead of a simple image URL, the prefix `"sprite:..."` may be used to specify properties required to extract an image from an image sprite.

For details on how this format may be used, see the `SCSpriteConfig` documentation.

Stateful image URLs

Many Smart GWT components support changing their appearance to reflect their current "state" ["Focused", "Disabled", etc]. As such they may display different image media to reflect their current state.
See the `Stateful Images overview` for details on how image states are managed in Smart GWT.

SVG Images

For more information about using stylable SVGs for spriting in a way that doesn't involve lots of file-loads or the flickering typically associated with modifying SVGs in-browser, see the `SVG Symbols Overview`.

If the URL represents an SVG image, you may specify `tag` as a query param to control whether it's rendered in an object or image tag, provided `Canvas.useImageForSVG` isn't set. If that query param is present and has any value other than `object`, then the SVG image will be rendered in an image tag. Otherwise, it will be rendered in an object tag. For example, an `SCImgURL` of "circle.svg?tag=image" will render in an image tag.

the special "blank" constant

If you don't have to show any image for any reason or you need to reset the area where an image is, you can call myImage.setSrc('blank') or set:

      Img myImage = new Img();
      myImage.setWidth(48);
      myImage.setHeight(48);
      myImage.setSrc("blank");

This will render an empty space, where the blank.gif image, that each skin has, will be used for this purpose.