Java Doc for UIObject.java in  » Ajax » GWT » com » google » gwt » user » client » ui » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Styling With CSS

All UIObject objects can be styled using CSS. Style names that are specified programmatically in Java source are implicitly associated with CSS style rules. In terms of HTML and CSS, a GWT style name is the element's CSS "class". By convention, GWT style names are of the form [project]-[widget].

For example, the Button widget has the style name gwt-Button, meaning that within the Button constructor, the following call occurs:

 setStyleName("gwt-Button");

 // Example of how you might choose to style a Button widget 
 .gwt-Button {
 background-color: yellow;
 color: black;
 font-size: 24pt;
 }

Style Name Specifics

Every UIObject has a primary style name that identifies the key CSS style rule that should always be applied to it. Use UIObject.setStylePrimaryName(String) to specify an object's primary style name. In most cases, the primary style name is set in a widget's constructor and never changes again during execution. In the case that no primary style name is specified, it defaults to the first style name that is added.

More complex styling behavior can be achieved by manipulating an object's secondary style names. Secondary style names can be added and removed using UIObject.addStyleName(String) and UIObject.removeStyleName(String) . The purpose of secondary style names is to associate a variety of CSS style rules over time as an object progresses through different visual states.

There is an important special formulation of secondary style names called dependent style names. A dependent style name is a secondary style name prefixed with the primary style name of the widget itself. See UIObject.addStyleName(String) for details.

 getStylePrimaryName() + '-' + styleSuffix
 

The most important use for this method is to add a special kind of secondary style name called a dependent style name. To add a dependent style name, use UIObject.addStyleDependentName(String) , which will prefix the 'style' argument with the result of UIObject.getStylePrimaryName() (followed by a '-'). For example, suppose the primary style name is gwt-TextBox. If the following method is called as obj.setReadOnly(true):

 public void setReadOnly(boolean readOnly) {
 isReadOnlyMode = readOnly;
 // Create a dependent style name.
 String readOnlyStyle = "readonly";
 if (readOnly) {
 addStyleDependentName(readOnlyStyle);
 } else {
 removeStyleDependentName(readOnlyStyle);
 }
 }

then both of the CSS style rules below will be applied:

 // This rule is based on the primary style name and is always active.
 .gwt-TextBox {
 font-size: 12pt;
 }
 // This rule is based on a dependent style name that is only active
 // when the widget has called addStyleName(getStylePrimaryName() +
 // "-readonly").
 .gwt-TextBox-readonly {
 background-color: lightgrey;
 border: none;
 }

Dependent style names are powerful because they are automatically updated whenever the primary style name changes. Continuing with the example above, if the primary style name changed due to the following call:

setStylePrimaryName("my-TextThingy");

then the object would be re-associated with following style rules, removing those that were shown above.

 .my-TextThingy {
 font-size: 20pt;
 }
 .my-TextThingy-readonly {
 background-color: red;
 border: 2px solid yellow;
 }

Secondary style names that are not dependent style names are not automatically updated when the primary style name changes.