Class UIObject
- All Implemented Interfaces:
HasVisibility
- Direct Known Subclasses:
CellTreeNodeView
,MenuItem
,MenuItemSeparator
,TreeItem
,Widget
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
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.
Use in UiBinder Templates
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.
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
The implementation of the set debug id method, which does nothing by default.static class
-
Field Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addStyleDependentName
(String styleSuffix) Adds a dependent style name by specifying the style name's suffix.void
addStyleName
(String style) Adds a secondary or dependent style name to this object.static void
ensureDebugId
(Element elem, 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, String baseID, String id) Set the debug id of a specific element.final void
ensureDebugId
(String id) int
Gets the object's absolute left position in pixels, as measured from the browser window's client area.int
Gets the object's absolute top position in pixels, as measured from the browser window's client area.Gets a handle to the object's underlying DOM element.int
Gets the object's offset height in pixels.int
Gets the object's offset width in pixels.protected Element
Template method that returns the element to which style names will be applied.Gets all of the object's style names, as a space-separated list.protected static String
getStyleName
(Element elem) Gets all of the element's style names, as a space-separated list.Gets the primary style name associated with the object.protected static String
getStylePrimaryName
(Element elem) Gets the element's primary style name.getTitle()
Gets the title associated with this object.boolean
Determines whether or not this object is visible.static boolean
Returns whether the given element is visible in a way consistent withsetVisible(Element, boolean)
.protected void
onEnsureDebugId
(String baseID) Called when the user sets the id using theensureDebugId(String)
method.void
removeStyleDependentName
(String styleSuffix) Removes a dependent style name by specifying the style name's suffix.void
removeStyleName
(String style) Removes a style name.(package private) void
replaceElement
(Element elem) Replaces this object's browser element.protected Element
EXPERIMENTAL and subject to change.protected final void
setElement
(Element elem) Sets this object's browser element.protected void
setElement
(Element elem) Deprecated.void
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
Sets the object's size.void
setStyleDependentName
(String styleSuffix, boolean add) Adds or removes a dependent style name by specifying the style name's suffix.protected static void
setStyleName
(Element elem, String styleName) Clears all of the element's style names and sets it to the given style.protected static void
setStyleName
(Element elem, String style, boolean add) This convenience method adds or removes a style name for a given element.void
setStyleName
(String style) Clears all of the object's style names and sets it to the given style.void
setStyleName
(String style, boolean add) Adds or removes a style name.protected static void
setStylePrimaryName
(Element elem, String style) Sets the element's primary style name and updates all dependent style names.void
setStylePrimaryName
(String style) Sets the object's primary style name and updates all dependent style names.void
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
Sets the object's width.void
sinkBitlessEvent
(String eventTypeName) Sinks a named event.void
sinkEvents
(int eventBitsToAdd) 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.void
unsinkEvents
(int eventBitsToRemove) Removes a set of events from this object's event list.
-
Field Details
-
DEBUG_ID_PREFIX
- See Also:
-
MISSING_ELEMENT_ERROR
- See Also:
-
SETELEMENT_TWICE_ERROR
- See Also:
-
-
Constructor Details
-
UIObject
public UIObject()
-
-
Method Details
-
ensureDebugId
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"/>
- Parameters:
elem
- the targetElement
id
- the ID to set on the element
-
isVisible
Returns whether the given element is visible in a way consistent withsetVisible(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.
-
setVisible
Shows or hides the given element. Also updates the "aria-hidden" attribute by setting it to true when it is hidden and removing it when it is shown.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 tosetVisible(elem, true)
. -
ensureDebugId
Set the debug id of a specific element. The id will be appended to the end of the base debug id, with a dash separator. The base debug id is the ID of the main element in this UIObject.- Parameters:
elem
- the elementbaseID
- the base ID used by the main elementid
- the id to append to the base debug id
-
getStyleName
Gets all of the element's style names, as a space-separated list.- Parameters:
elem
- the element whose style is to be retrieved- Returns:
- the objects's space-separated style names
-
getStylePrimaryName
Gets the element's primary style name.- Parameters:
elem
- the element whose primary style name is to be retrieved- Returns:
- the element's primary style name
-
setStyleName
Clears all of the element's style names and sets it to the given style.- Parameters:
elem
- the element whose style is to be modifiedstyleName
- the new style name
-
setStyleName
This convenience method adds or removes a style name for a given element. This method is typically used to add and remove secondary style names, but it can be used to remove primary stylenames as well, but that is not recommended. SeesetStyleName(String)
for a description of how primary and secondary style names are used.- Parameters:
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 it
-
setStylePrimaryName
Sets the element's primary style name and updates all dependent style names.- Parameters:
elem
- the element whose style is to be resetstyle
- the new primary style name- See Also:
-
addStyleDependentName
Adds a dependent style name by specifying the style name's suffix. The actual form of the style name that is added is:getStylePrimaryName() + '-' + styleSuffix
- Parameters:
styleSuffix
- the suffix of the dependent style to be added.- See Also:
-
addStyleName
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 CSSclass
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 ofgetStylePrimaryName()
(followed by a '-'). For example, suppose the primary style name isgwt-TextBox
. If the following method is called asobj.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.
- Parameters:
style
- the secondary style name to be added- See Also:
-
ensureDebugId
Ensure that the mainElement
for thisUIObject
has an ID property set, which allows it to integrate with third-party libraries and test tools. ComplexWidget
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 stringDEBUG_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"/>
- Parameters:
id
- the ID to set on the main element
-
getAbsoluteLeft
public int getAbsoluteLeft()Gets the object's absolute left position in pixels, as measured from the browser window's client area.- Returns:
- 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.- Returns:
- the object's absolute top position
-
getElement
Gets a handle to the object's underlying DOM element. This method should not be overridden. It is non-final solely to support legacy code that depends upon overriding it. If it is overridden, the subclass implementation must not return a different element than was previously set usingsetElement(Element)
.- Returns:
- 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 and padding, but not margin.- Returns:
- 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 and padding, but not margin.- Returns:
- the object's offset width
-
getStyleName
Gets all of the object's style names, as a space-separated list. If you wish to retrieve only the primary style name, callgetStylePrimaryName()
.- Returns:
- the objects's space-separated style names
- See Also:
-
getStylePrimaryName
Gets the primary style name associated with the object.- Returns:
- the object's primary style name
- See Also:
-
getTitle
Gets the title associated with this object. The title is the 'tool-tip' displayed to users when they hover over the object.- Returns:
- the object's title
-
isVisible
public boolean isVisible()Description copied from interface:HasVisibility
Determines whether or not this object is visible. Note that this does not necessarily take into account whether or not the receiver's parent is visible, or even if it is attached to theDocument
. The default implementation of this trait inUIObject
is based on the value of a dom element's style object's display attribute.- Specified by:
isVisible
in interfaceHasVisibility
- Returns:
true
if the object is visible
-
removeStyleDependentName
Removes a dependent style name by specifying the style name's suffix.- Parameters:
styleSuffix
- the suffix of the dependent style to be removed- See Also:
-
removeStyleName
Removes a style name. This method is typically used to remove secondary style names, but it can be used to remove primary stylenames as well. That use is not recommended.- Parameters:
style
- the secondary style name to be removed- See Also:
-
setHeight
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 pixelsheight
- 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")
-
setStyleDependentName
Adds or removes a dependent style name by specifying the style name's suffix. The actual form of the style name that is added is:getStylePrimaryName() + '-' + styleSuffix
- Parameters:
styleSuffix
- the suffix of the dependent style to be added or removedadd
-true
to add the given style,false
to remove it- See Also:
-
setStyleName
Adds or removes a style name. This method is typically used to remove secondary style names, but it can be used to remove primary stylenames as well. That use is not recommended.- Parameters:
style
- the style name to be added or removedadd
-true
to add the given style,false
to remove it- See Also:
-
setStyleName
Clears all of the object's style names and sets it to the given style. You should normally usesetStylePrimaryName(String)
unless you wish to explicitly remove all existing styles.- Parameters:
style
- the new style name- See Also:
-
setStylePrimaryName
Sets the object's primary style name and updates all dependent style names.- Parameters:
style
- the new primary style name- See Also:
-
setTitle
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 void setVisible(boolean visible) Description copied from interface:HasVisibility
Sets whether this object is visible.- Specified by:
setVisible
in interfaceHasVisibility
- Parameters:
visible
-true
to show the object,false
to hide it
-
setWidth
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")
-
sinkBitlessEvent
Sinks a named event. Note that onlywidgets
may actually receive events, but can receive events from all objects contained within them.- Parameters:
eventTypeName
- name of the event to sink on this element- See Also:
-
sinkEvents
public void sinkEvents(int eventBitsToAdd) Adds a set of events to be sunk by this object. Note that onlywidgets
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:
-
toString
This method is overridden so that any object can be viewed in the debugger as an HTML snippet. -
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:
-
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.- Returns:
- the element to which style names will be applied
-
onEnsureDebugId
Called when the user sets the id using theensureDebugId(String)
method. Subclasses ofUIObject
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 subElement
with a short description. For example:- -mysubelement = Applies to my sub element.
<inherits name="com.google.gwt.user.Debug"/>
- Parameters:
baseID
- the base ID used by the main element
-
resolvePotentialElement
EXPERIMENTAL and subject to change. Do not use this in production code.To be overridden by
IsRenderable
subclasses that initialize themselves by by callingsetElement(PotentialElement.build(this))
.The receiver must:
- create a real
Element
to replace itsPotentialElement
- call
#setElement()
with the new Element - and return 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)
andIsRenderable.claimElement(Element)
.- See Also:
- create a real
-
setElement
Sets this object's browser element. UIObject subclasses must call this method before attempting to call any other methods, and it may only be called once.- Parameters:
elem
- the object's element
-
setElement
Deprecated.Use and overridesetElement(Element)
instead.Sets this object's browser element. UIObject subclasses must call this method before attempting to call any other methods, and it may only be called once. This method exists for backwards compatibility with pre-1.5 code. As of GWT 1.5,setElement(Element)
is the preferred method.- Parameters:
elem
- the object's element
-
replaceElement
Replaces this object's browser element. This method exists only to support a specific use-case in Image, and should not be used by other classes.- Parameters:
elem
- the object's new element
-
setElement(Element)
instead.