public abstract class UIObject extends java.lang.Object implements HasVisibility
Widget
.
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.
Every UIObject
has a primary style name that identifies
the key CSS style rule that should always be applied to it. Use
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 addStyleName(String)
, removeStyleName(String)
, or
setStyleName(String, boolean)
. 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.
Setter methods that follow JavaBean property conventions are exposed as
attributes in UiBinder
templates. For example, because UiObject implements setWidth(String)
you can set the width of any widget like so:
<g:Label width='15em'>Hello there</g:Label>Generally speaking, values are parsed as if they were Java literals, so methods like
setVisible(boolean)
are also available:
<g:Label width='15em' visible='false'>Hello there</g:Label>Enum properties work this way too. Imagine a Bagel widget with a handy Type enum and a setType(Type) method:
enum Type { poppy, sesame, raisin, jalapeno } <my:Bagel type='poppy' />There is also special case handling for two common method signatures,
(int, int)
and (double, Unit
)
<g:Label pixelSize='100, 100'>Hello there</g:Label>Finally, a few UiObject methods get special handling. The debug id (see
ensureDebugId(com.google.gwt.dom.client.Element, java.lang.String)
) of any UiObject can be set via the
debugId
attribute, and addtional style names and dependent style
names can be set with the addStyleNames
and
addStyleDependentNames
attributes.<g:Label debugId='helloLabel' addStyleNames='pretty rounded big'>Hello there</g:Label>Style names can be space or comma separated.
Modifier and Type | Class and Description |
---|---|
static class |
UIObject.DebugIdImpl
The implementation of the set debug id method, which does nothing by
default.
|
static class |
UIObject.DebugIdImplEnabled
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
DEBUG_ID_PREFIX |
(package private) static java.lang.String |
MISSING_ELEMENT_ERROR |
(package private) static java.lang.String |
SETELEMENT_TWICE_ERROR |
Constructor and Description |
---|
UIObject() |
Modifier and Type | Method and Description |
---|---|
void |
addStyleDependentName(java.lang.String styleSuffix)
Adds a dependent style name by specifying the style name's suffix.
|
void |
addStyleName(java.lang.String style)
Adds a secondary or dependent style name to this object.
|
static void |
ensureDebugId(Element elem,
java.lang.String id)
Ensure that elem has an ID property set, which allows it to integrate with
third-party libraries and test tools.
|
protected static void |
ensureDebugId(Element elem,
java.lang.String baseID,
java.lang.String id)
Set the debug id of a specific element.
|
void |
ensureDebugId(java.lang.String id)
|
int |
getAbsoluteLeft()
Gets the object's absolute left position in pixels, as measured from the
browser window's client area.
|
int |
getAbsoluteTop()
Gets the object's absolute top position in pixels, as measured from the
browser window's client area.
|
Element |
getElement()
Gets a handle to the object's underlying DOM element.
|
int |
getOffsetHeight()
Gets the object's offset height in pixels.
|
int |
getOffsetWidth()
Gets the object's offset width in pixels.
|
protected Element |
getStyleElement()
Template method that returns the element to which style names will be
applied.
|
java.lang.String |
getStyleName()
Gets all of the object's style names, as a space-separated list.
|
protected static java.lang.String |
getStyleName(Element elem)
Gets all of the element's style names, as a space-separated list.
|
java.lang.String |
getStylePrimaryName()
Gets the primary style name associated with the object.
|
protected static java.lang.String |
getStylePrimaryName(Element elem)
Gets the element's primary style name.
|
java.lang.String |
getTitle()
Gets the title associated with this object.
|
boolean |
isVisible()
Determines whether or not this object is visible.
|
static boolean |
isVisible(Element elem)
Returns whether the given element is visible in a way consistent with
setVisible(Element, boolean) . |
protected void |
onEnsureDebugId(java.lang.String baseID)
Called when the user sets the id using the
ensureDebugId(String)
method. |
void |
removeStyleDependentName(java.lang.String styleSuffix)
Removes a dependent style name by specifying the style name's suffix.
|
void |
removeStyleName(java.lang.String style)
Removes a style name.
|
(package private) void |
replaceElement(Element elem)
Replaces this object's browser element.
|
protected Element |
resolvePotentialElement()
EXPERIMENTAL and subject to change.
|
protected void |
setElement(Element elem)
Sets this object's browser element.
|
protected void |
setElement(Element elem)
Deprecated.
Use and override
setElement(Element) instead. |
void |
setHeight(java.lang.String height)
Sets the object's height.
|
void |
setPixelSize(int width,
int height)
Sets the object's size, in pixels, not including decorations such as
border, margin, and padding.
|
void |
setSize(java.lang.String width,
java.lang.String height)
Sets the object's size.
|
void |
setStyleDependentName(java.lang.String styleSuffix,
boolean add)
Adds or removes a dependent style name by specifying the style name's
suffix.
|
protected static void |
setStyleName(Element elem,
java.lang.String styleName)
Clears all of the element's style names and sets it to the given style.
|
protected static void |
setStyleName(Element elem,
java.lang.String style,
boolean add)
This convenience method adds or removes a style name for a given element.
|
void |
setStyleName(java.lang.String style)
Clears all of the object's style names and sets it to the given style.
|
void |
setStyleName(java.lang.String style,
boolean add)
Adds or removes a style name.
|
protected static void |
setStylePrimaryName(Element elem,
java.lang.String style)
Sets the element's primary style name and updates all dependent style
names.
|
void |
setStylePrimaryName(java.lang.String style)
Sets the object's primary style name and updates all dependent style names.
|
void |
setTitle(java.lang.String title)
Sets the title associated with this object.
|
void |
setVisible(boolean visible)
Sets whether this object is visible.
|
static void |
setVisible(Element elem,
boolean visible)
Shows or hides the given element.
|
void |
setWidth(java.lang.String width)
Sets the object's width.
|
void |
sinkBitlessEvent(java.lang.String eventTypeName)
Sinks a named event.
|
void |
sinkEvents(int eventBitsToAdd)
Adds a set of events to be sunk by this object.
|
java.lang.String |
toString()
This method is overridden so that any object can be viewed in the debugger
as an HTML snippet.
|
void |
unsinkEvents(int eventBitsToRemove)
Removes a set of events from this object's event list.
|
public static final java.lang.String DEBUG_ID_PREFIX
static final java.lang.String MISSING_ELEMENT_ERROR
static final java.lang.String SETELEMENT_TWICE_ERROR
public static void ensureDebugId(Element elem, java.lang.String id)
Ensure that elem has an ID property set, which allows it to integrate with
third-party libraries and test tools. If elem already has an ID, this
method WILL override it. The ID that you specify will be prefixed by the
static string DEBUG_ID_PREFIX
.
This method will be compiled out and will have no effect unless you inherit the DebugID module in your gwt.xml file by adding the following line:
<inherits name="com.google.gwt.user.Debug"/>
elem
- the target Element
id
- the ID to set on the elementpublic static boolean isVisible(Element elem)
setVisible(Element, boolean)
.
Warning: implemented with a heuristic. The value returned takes into account only the "display" style, ignoring CSS and Aria roles, thus may not accurately reflect whether the element is actually visible in the browser.
public static void setVisible(Element elem, boolean visible)
Warning: implemented with a heuristic based on the "display" style:
clears the "display" style to its default value if visible
is true,
else forces the style to "none". If the "display" style is set to "none"
via CSS style sheets, the element remains invisible after a call to
setVisible(elem, true)
.
protected static void ensureDebugId(Element elem, java.lang.String baseID, java.lang.String id)
elem
- the elementbaseID
- the base ID used by the main elementid
- the id to append to the base debug idprotected static java.lang.String getStyleName(Element elem)
elem
- the element whose style is to be retrievedprotected static java.lang.String getStylePrimaryName(Element elem)
elem
- the element whose primary style name is to be retrievedprotected static void setStyleName(Element elem, java.lang.String styleName)
elem
- the element whose style is to be modifiedstyleName
- the new style nameprotected static void setStyleName(Element elem, java.lang.String style, boolean add)
setStyleName(String)
for a description of how
primary and secondary style names are used.elem
- the element whose style is to be modifiedstyle
- the secondary style name to be added or removedadd
- true
to add the given style, false
to
remove itprotected static void setStylePrimaryName(Element elem, java.lang.String style)
elem
- the element whose style is to be resetstyle
- the new primary style namesetStyleName(Element, String, boolean)
public void addStyleDependentName(java.lang.String styleSuffix)
getStylePrimaryName() + '-' + styleSuffix
styleSuffix
- the suffix of the dependent style to be added.setStylePrimaryName(String)
,
removeStyleDependentName(String)
,
setStyleDependentName(String, boolean)
,
addStyleName(String)
public void addStyleName(java.lang.String style)
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, use addStyleDependentName(String)
, which
will prefix the 'style' argument with the result of
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; }
The code can also be simplified with
setStyleDependentName(String, boolean)
:
public void setReadOnly(boolean readOnly) { isReadOnlyMode = readOnly; setStyleDependentName("readonly", readOnly); }
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.
style
- the secondary style name to be addedUIObject
,
removeStyleName(String)
public final void ensureDebugId(java.lang.String id)
Element
for this UIObject
has an ID
property set, which allows it to integrate with third-party libraries and
test tools. Complex Widget
s will also set the IDs of their
important sub-elements.
If the main element already has an ID, this method WILL override it.
The ID that you specify will be prefixed by the static string
DEBUG_ID_PREFIX
.
This method will be compiled out and will have no effect unless you inherit
the DebugID module in your gwt.xml file by adding the following line:
<inherits name="com.google.gwt.user.Debug"/>
id
- the ID to set on the main elementpublic int getAbsoluteLeft()
public int getAbsoluteTop()
public Element getElement()
setElement(Element)
.public int getOffsetHeight()
public int getOffsetWidth()
public java.lang.String getStyleName()
getStylePrimaryName()
.getStylePrimaryName()
public java.lang.String getStylePrimaryName()
setStyleName(String)
,
addStyleName(String)
,
removeStyleName(String)
public java.lang.String getTitle()
public boolean isVisible()
HasVisibility
Document
. The default
implementation of this trait in UIObject
is based on the value of a
dom element's style object's display attribute.isVisible
in interface HasVisibility
true
if the object is visiblepublic void removeStyleDependentName(java.lang.String styleSuffix)
styleSuffix
- the suffix of the dependent style to be removedsetStylePrimaryName(Element, String)
,
addStyleDependentName(String)
,
setStyleDependentName(String, boolean)
public void removeStyleName(java.lang.String style)
style
- the secondary style name to be removedaddStyleName(String)
,
setStyleName(String, boolean)
public void setHeight(java.lang.String height)
height
- the object's new height, in CSS units (e.g. "10px", "1em")public void setPixelSize(int width, int height)
width
- the object's new width, in pixelsheight
- the object's new height, in pixelspublic void setSize(java.lang.String width, java.lang.String height)
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")public void setStyleDependentName(java.lang.String styleSuffix, boolean add)
getStylePrimaryName() + '-' + styleSuffix
styleSuffix
- the suffix of the dependent style to be added or removedadd
- true
to add the given style, false
to
remove itsetStylePrimaryName(Element, String)
,
addStyleDependentName(String)
,
setStyleName(String, boolean)
,
removeStyleDependentName(String)
public void setStyleName(java.lang.String style, boolean add)
style
- the style name to be added or removedadd
- true
to add the given style, false
to
remove itaddStyleName(String)
,
removeStyleName(String)
public void setStyleName(java.lang.String style)
setStylePrimaryName(String)
unless you wish to
explicitly remove all existing styles.style
- the new style namesetStylePrimaryName(String)
public void setStylePrimaryName(java.lang.String style)
style
- the new primary style nameaddStyleName(String)
,
removeStyleName(String)
public void setTitle(java.lang.String title)
title
- the object's new titlepublic void setVisible(boolean visible)
HasVisibility
setVisible
in interface HasVisibility
visible
- true
to show the object, false
to
hide itpublic void setWidth(java.lang.String width)
width
- the object's new width, in CSS units (e.g. "10px", "1em")public void sinkBitlessEvent(java.lang.String eventTypeName)
widgets
may actually
receive events, but can receive events from all objects contained within
them.eventTypeName
- name of the event to sink on this elementEvent
public void sinkEvents(int eventBitsToAdd)
widgets
may actually receive events, but can receive events
from all objects contained within them.eventBitsToAdd
- a bitfield representing the set of events to be added
to this element's event setEvent
public java.lang.String toString()
toString
in class java.lang.Object
public void unsinkEvents(int eventBitsToRemove)
eventBitsToRemove
- a bitfield representing the set of events to be
removed from this element's event setsinkEvents(int)
,
Event
protected Element getStyleElement()
protected void onEnsureDebugId(java.lang.String baseID)
ensureDebugId(String)
method. Subclasses of UIObject
can override this method to add IDs
to their sub elements. If a subclass does override this method, it should
list the IDs (relative to the base ID), that will be applied to each sub
Element
with a short description. For example:
<inherits name="com.google.gwt.user.Debug"/>
baseID
- the base ID used by the main elementprotected Element resolvePotentialElement()
To be overridden by IsRenderable
subclasses that initialize
themselves by by calling
setElement(PotentialElement.build(this))
.
The receiver must:
Element
to replace its PotentialElement
#setElement()
with the new Element
This method is called when the receiver's element is about to be
added to a parent node, as a side effect of DOM.appendChild(com.google.gwt.dom.client.Element, com.google.gwt.dom.client.Element)
.
Note that this method is normally called only on the top element
of an IsRenderable tree. Children instead will receive IsRenderable.render(com.google.gwt.user.client.ui.RenderableStamper)
and IsRenderable.claimElement(Element)
.
PotentialElement
,
IsRenderable
protected final void setElement(Element elem)
elem
- the object's element@Deprecated protected void setElement(Element elem)
setElement(Element)
instead.setElement(Element)
is the preferred method.elem
- the object's elementvoid replaceElement(Element elem)
elem
- the object's new element