public interface Skinning
setStyleName() or
setBackgroundColor(), or you can
skin all
components of the same class at once, by using Canvas.setDefaultProperties().
to change the defaults for the class.
skin_styles.css)
load_skin.js)
skin_styles.css
load_skin.js
images/
ListGrid/
sort_ascending.gif
...
Tab/
... other directories containing
component or shared media ...
Three of Smart GWT's most commonly used skins - Enterprise, EnterpriseBlue and Graphite - now have a "CSS3 mode" in which almost all images required by the skin are replaced with CSS3 settings that appear nearly identical to the image-based appearance. This results in a performance boost through both a simplified DOM and far few images being loaded.
By default CSS3 mode is automatically used in modern browsers such as Firefox, Chrome, Safari, IE 9 in standards mode, and IE 10+. Internet Explorer version 8 and earlier does not have sufficient CSS support to create a close match to the existing image-based skin, so CSS3 mode is not enabled by default. If CSS3 mode is manually enabled for IE when not automatically enabled, this will result in a degraded appearance that is similar across IE6, 7, and 8: rounded elements such as tabs will become square, and backgrounds will have lower quality if not disappear.
To override the default decision on whether to use CSS3 support, set the JavaScript global
variable isc_css3Mode before any of the Smart GWT libraries are loaded. For
example:
<script>isc_css3Mode = "on";</script>
Possible settings are:
For more control than the above settings provide, you can create a custom skin based on one
of the above 3 skins and modify load_skin.js - whether CSS3 mode is used is controlled by a
JavaScript variable useCSS3 defined in this file.
NOTE: we are working on improving IE9 support using the limited CSS3 features provided by this browser, but at the moment, the well-published workarounds for IE9's CSS3 bugs create other bugs of their own that are, as yet, unresolved.
In addition to having a CSS3 mode, the Enterprise, EnterpriseBlue, and Graphite skins also support spriting of user interface images. This typically results in reduced load times and eliminates noticeable delays in changes of component appearance while the browser downloads a required image. Because of these benefits, spriting is enabled by default in all browsers except for Internet Explorer 6.
When spriting is enabled, Smart GWT uses images which have several of the smaller images
combined into one. For example, the up and down arrow images of a SpinnerItem in
the normal, "Focused", and "Disabled" states are combined into one image. The file size of
the combined image is 60% smaller than the sum of the file sizes of the 6 constituent images,
and the browser does not have to make 6 separate HTTP requests.
If certain component metrics (such as the height of a component or padding) are changed,
then the Enterprise, EnterpriseBlue, and Graphite skins' image sprites might not work in the
customized skin. In this case, spriting can be disabled by setting the JavaScript global
variable isc_spriting to "off" before any of the Smart GWT libraries are loaded.
For example:
<script>isc_spriting = "off";</script>
Possible settings are:
To modify a skin, first create a copy of one of the skins that comes with the Smart GWT SDK, then modify the copy. Full instructions are provided in Chapter 9 of the QuickStart Guide.
Starting from the name of the component
Given a Smart GWT component that you want to skin, open its JavaDoc:
baseStyle
src
Starting from a running example
Specific browsers offer alternate approaches to quickly discover the images or style names being used for a part of a Smart GWT component's appearance:
Properties that refer to images by URL, such as src and icon, are
specially interpreted in Smart GWT to allow for simpler and more uniform image URLs,
and to allow applications to be restructured more easily.
Unlike the URL used with an HTML <IMG> element, the image URL passed to a Smart GWT component is not assumed to be relative to the current page. See SCImgURL for a full explanation of the default application image directory, and the meaning of the "[SKIN]" prefix.
Default image URLs for Smart GWT components are specified in load_skin.js via
JavaScript, using calls to Class.addProperties and
Class.changeDefaults. For example, the load_skin.js file
from the "Enterprise" skin includes the following code to establish the media used by
minimizeButton:
isc.Window.changeDefaults("minimizeButtonDefaults", {
src:"[SKIN]/Window/minimize.png"
});
NOTE: These are JavaScript APIs and hence do not appear in SmartGWT JavaDoc - you may want to refer to the SmartClient Reference available at Isomorphic.com for these specific APIs.
Many Smart GWT components must know some image sizes in advance, in order to allow those components to autosize to data or content.
For example, the ImgTabs used in TabSets are capable of automatically sizing
to a variable length title. To make this
possible, Smart GWT must know the
sizes of the images used as "endcaps" on each tab in advance.
Like image URLs, image sizes are specified in load_skin.js. The following code
sample establishes the default size of the "endcaps" for tabs, by setting a default value
for capSize:
isc.ImgTab.addProperties({
capSize:4
})
In Smart GWT, screen layout and sizing are controlled via JavaScript, and appearance via CSS and images.
CSS borders, margins and padding applied to Smart GWT components can be treated as purely visual properties with no effect on sizing or layout. Unlike HTML elements, a Smart GWT component will always have the exact size you specify via JavaScript, regardless of browser platform, browser compatibility mode, or borders, margins, or padding, all of which normally affect the final size of an HTML element.
For this reason, Smart GWT skinning requires only novice-level familiarity with CSS, as CSS is used principally for colors and fonts. See this discussion for further details on what properties should be set via CSS vs via JavaScript.
In most cases, using newer CSS features such as CSS3 prefix attribute selectors or CSS3
pseudo-classes in a skin will just work, provided the browser supports those CSS features.
However, in some cases, Smart GWT needs to be able to extract style information from
CSS style declarations. For this reason, only single class name selectors are officially
supported (e.g. .myButton, .myButtonDown) and @-rules are not supported.
Some components or areas within components, including buttons and the cells within a grid, are "stateful", meaning that they can be in one of a set of states each of which has a distinct visual appearance.
Stateful components switch the CSS styles or image URLs they are using as they transition
from state to state, appending state information as suffixes on the style names or URL.
See src and baseStyle for details and examples.
Smart GWT has built-in logic to manage a series of state transitions, such as:
showRollOver, allow you to control whether the
component will switch CSS style or image URL when the component transitions into a given state.
A StretchImg is Smart GWT component that renders out a
compound image composed of 3
image files: two fixed-size endcaps images and a stretchable center segment. Like stateful
components, the names of each image segment is appended to the image URL as a suffix. See
src for details.
Similar to a StretchImg, an EdgedCanvas provides an
image-based decorative edge
around and/or behind another component, with up to 9 segments (a 3x3 grid). Decorative
edges can be added to any component by setting showEdges:true.
EdgedCanvas is also used to construct dropshadows, which can be enabled on any component via
showShadow:true.
In some cases you need to create two variations in appearance for a component with the same
behavior. For example, you may want to create a specialized Window, called "PaletteWindow",
that behaves like a normal Window but has a very compact look & feel. To create a
separately skinnable component for PaletteWindow, use isc.defineClass. For
example:
isc.defineClass("PaletteWindow", "Window");
isc.PaletteWindow.addProperties({
showFooter:false,
...
})
This creates a SmartClient class, which does not exist as a Java class. To
make your SmartGWT widget use the settings on this SmartClient class, call setScClassName()
passing
the String name of the SmartClient class.
If you're creating a custom skin, you can place JavaScript snippets such as those shown above in your custom skin's load_skin.js file. If you prefer not to create a custom skin for small customizations, you can execute JavaScript via a JSNI method in your Java code. With this latter approach, be sure to change "isc." to "$wnd.isc." wherever it appears, and to call the JSNI method before creating any SmartGWT components.