Class UIObject
The superclass for all user-interface objects. It simply wraps a DOM element,
and cannot receive events. Most interesting user-interface classes derive
from
Widget.
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");
A corresponding CSS style rule can then be written as follows:
// Example of how you might choose to style a Button widget
.gwt-Button {
background-color: yellow;
color: black;
font-size: 24pt;
}
Note the dot prefix in the CSS style rule. This syntax is called a
CSS class
selector.
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
setStyleName(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 gwt-nostyle
.
More complex styling behavior can be achieved by manipulating an object's
secondary style names. Secondary style names can be added and removed
using addStyleName(String) and 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
addStyleName(String) for details.
Methods
addStyleName(String) | Adds a secondary or dependent style name to this object. |
getAbsoluteLeft() | Gets the object's absolute left position in pixels, as measured from the
browser window's client area. |
getAbsoluteTop() | Gets the object's absolute top position in pixels, as measured from the
browser window's client area. |
getElement() | Gets a handle to the object's underlying DOM element. |
getOffsetHeight() | Gets the object's offset height in pixels. |
getOffsetWidth() | Gets the object's offset width in pixels. |
getStyleElement() | Template method that returns the element to which style names will be
applied. |
getStyleName() | Gets the primary style name associated with the object. |
getTitle() | Gets the title associated with this object. |
isVisible(Element) | |
isVisible() | Determines whether or not this object is visible. |
removeStyleName(String) | Removes a secondary style name. |
resetStyleName(Element, String) | Sets the object's primary style name and updates all dependent style names. |
setElement(Element) | Sets this object's browser element. |
setHeight(String) | Sets the object's height. |
setPixelSize(int, int) | Sets the object's size, in pixels, not including decorations such as
border, margin, and padding. |
setSize(String, String) | Sets the object's size. |
setStyleName(Element, String, boolean) | This convenience method adds or removes a secondary style name to the
primary style name for a given element. |
setStyleName(String) | Sets the object's primary style name and updates all dependent style names. |
setTitle(String) | Sets the title associated with this object. |
setVisible(Element, boolean) | |
setVisible(boolean) | Sets whether this object is visible. |
setWidth(String) | Sets the object's width. |
sinkEvents(int) | Adds a set of events to be sunk by this object. |
toString() | This method is overridden so that any object can be viewed in the debugger
as an HTML snippet. |
unsinkEvents(int) | Removes a set of events from this object's event list. |
Method Detail
addStyleName
public void
addStyleName(
String style)
Adds a secondary or dependent style name to this object. A secondary style
name is an additional style name that is, in HTML/CSS terms, included as a
space-separated token in the value of the CSS
class
attribute for this object's root element.
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, prefix the 'style' argument with the result of
getStyleName(). 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 = getStyleName() + "-readonly";
if (readOnly) {
addStyleName(readOnlyStyle);
} else {
removeStyleName(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(getStyleName() + "-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:
setStyleName("my-TextThingy");
then the object would be re-associated with style rules below rather than
those above:
.my-TextThingy {
font-size: 12pt;
}
.my-TextThingy-readonly {
background-color: lightgrey;
border: none;
}
Secondary style names that are not dependent style names are not
automatically updated when the primary style name changes.
Parameters
- style
- the secondary style name to be added
See Also
UIObject,
removeStyleName(String)
getAbsoluteLeft
public int getAbsoluteLeft()
Gets the object's absolute left position in pixels, as measured from the
browser window's client area.
Return Value
the object's absolute left position
getAbsoluteTop
public int getAbsoluteTop()
Gets the object's absolute top position in pixels, as measured from the
browser window's client area.
Return Value
the object's absolute top position
getElement
Gets a handle to the object's underlying DOM element.
Return Value
the object's browser element
getOffsetHeight
public int getOffsetHeight()
Gets the object's offset height in pixels. This is the total height of the
object, including decorations such as border, margin, and padding.
Return Value
the object's offset height
getOffsetWidth
public int getOffsetWidth()
Gets the object's offset width in pixels. This is the total width of the
object, including decorations such as border, margin, and padding.
Return Value
the object's offset width
getStyleElement
protected
Element getStyleElement()
Template method that returns the element to which style names will be
applied. By default it returns the root element, but this method may be
overridden to apply styles to a child element.
Return Value
the element to which style names will be applied
getStyleName
Gets the primary style name associated with the object.
Return Value
the object's primary style name
See Also
setStyleName(String),
addStyleName(String),
removeStyleName(String)
getTitle
Gets the title associated with this object. The title is the 'tool-tip'
displayed to users when they hover over the object.
Return Value
the object's title
isVisible
public static boolean
isVisible(
Element elem)
Parameters
- elem
-
isVisible
public boolean isVisible()
Determines whether or not this object is visible.
Return Value
true
if the object is visible
removeStyleName
public void
removeStyleName(
String style)
Removes a secondary style name.
Parameters
- style
- the secondary style name to be removed
See Also
addStyleName(String)
resetStyleName
Sets the object's primary style name and updates all dependent style names.
Parameters
- elem
- the element whose style is to be reset
- style
- the new primary style name
See Also
setStyleName(Element, String, boolean)
setElement
protected void
setElement(
Element elem)
Sets this object's browser element. UIObject subclasses must call this
method before attempting to call any other methods.
If the browser element has already been set, then the current element's
position is located in the DOM and removed. The new element is added into
the previous element's position.
Parameters
- elem
- the object's new element
setHeight
public void
setHeight(
String height)
Sets the object's height. This height does not include decorations such as
border, margin, and padding.
Parameters
- height
- the object's new height, in CSS units (e.g. "10px", "1em")
setPixelSize
public void setPixelSize(int width, int height)
Sets the object's size, in pixels, not including decorations such as
border, margin, and padding.
Parameters
- width
- the object's new width, in pixels
- height
- the object's new height, in pixels
setSize
Sets the object's size. This size does not include decorations such as
border, margin, and padding.
Parameters
- width
- the object's new width, in CSS units (e.g. "10px", "1em")
- height
- the object's new height, in CSS units (e.g. "10px", "1em")
setStyleName
protected static void
setStyleName(
Element elem, String style, boolean add)
This convenience method adds or removes a secondary style name to the
primary style name for a given element. Set
setStyleName(String)
for a description of how primary and secondary style names are used.
Parameters
- elem
- the element whose style is to be modified
- style
- the secondary style name to be added or removed
- add
-
true
to add the given style, false
to remove it
setStyleName
public void
setStyleName(
String style)
Sets the object's primary style name and updates all dependent style names.
Parameters
- style
- the new primary style name
See Also
addStyleName(String),
removeStyleName(String)
setTitle
public void
setTitle(
String title)
Sets the title associated with this object. The title is the 'tool-tip'
displayed to users when they hover over the object.
Parameters
- title
- the object's new title
setVisible
public static void
setVisible(
Element elem, boolean visible)
Parameters
- elem
-
- visible
-
setVisible
public void setVisible(boolean visible)
Sets whether this object is visible.
Parameters
- visible
-
true
to show the object, false
to hide it
setWidth
public void
setWidth(
String width)
Sets the object's width. This width does not include decorations such as
border, margin, and padding.
Parameters
- width
- the object's new width, in CSS units (e.g. "10px", "1em")
sinkEvents
public void sinkEvents(int eventBitsToAdd)
Adds a set of events to be sunk by this object. Note that only
widgets may actually receive events, but can receive events
from all objects contained within them.
Parameters
- eventBitsToAdd
- a bitfield representing the set of events to be added
to this element's event set
See Also
Event
toString
This method is overridden so that any object can be viewed in the debugger
as an HTML snippet.
Return Value
a string representation of the object
unsinkEvents
public void unsinkEvents(int eventBitsToRemove)
Removes a set of events from this object's event list.
Parameters
- eventBitsToRemove
- a bitfield representing the set of events to be
removed from this element's event set
See Also
sinkEvents,
Event