Google Web Toolkit
Search Google Code:

# Class UIObject

public class UIObject
extends Object
// Superclass of `MenuItem`, `TreeItem`, `Widget`
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 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) 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

addStyleDependentName(String) | Adds a dependent style name by specifying the style name's suffix.
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(Element) | Gets all of the element's style names, as a space-separated list.
getStyleName() | Gets all of the object's style names, as a space-separated list.
getStylePrimaryName(Element) | Gets the element's primary style name.
getStylePrimaryName() | 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.
removeStyleDependentName(String) | Removes a dependent style name by specifying the style name's suffix.
removeStyleName(String) | Removes a style name.
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) | Clears all of the element's style names and sets it to the given style.
setStyleName(Element, String, boolean) | This convenience method adds or removes a style name for a given element.
setStyleName(String) | Clears all of the object's style names and sets it to the given style.
setStylePrimaryName(Element, String) | Sets the element's primary style name and updates all dependent style names.
setStylePrimaryName(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

### addStyleDependentName

public void addStyleDependentName(String styleSuffix)
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

setStylePrimaryName(String), removeStyleDependentName(String), addStyleName(String)

### 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, 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;
     }

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

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

public Element 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

protected static String getStyleName(Element elem)
Gets all of the element's style names, as a space-separated list.

#### Parameters

elem
  the element whose style is to be retrieved

#### Return Value

the objects's space-separated style names

### getStyleName

public String getStyleName()
Gets all of the object's style names, as a space-separated list. If you wish to retrieve only the primary style name, call getStylePrimaryName().

#### Return Value

the objects's space-separated style names

#### See Also

getStylePrimaryName()

### getStylePrimaryName

protected static String getStylePrimaryName(Element elem)
Gets the element's primary style name.

#### Parameters

elem
  the element whose primary style name is to be retrieved

#### Return Value

the element's primary style name

### getStylePrimaryName

public String getStylePrimaryName()
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

public 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

### removeStyleDependentName

public void removeStyleDependentName(String styleSuffix)
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

setStylePrimaryName(Element, String), addStyleDependentName(String), addStyleName(String)

### removeStyleName

public void removeStyleName(String style)
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

addStyleName(String)

### 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

public void setSize(String width, String height)
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 styleName)
Clears all of the element's style names and sets it to the given style.

#### Parameters

elem
  the element whose style is to be modified
styleName
  the new style name

### setStyleName

protected static void setStyleName(Element elem, String style, boolean add)
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. See 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)
Clears all of the object's style names and sets it to the given style. You should normally use setStylePrimaryName(String) unless you wish to explicitly remove all existing styles.

#### Parameters

style
  the new style name

#### See Also

setStylePrimaryName(String)

### setStylePrimaryName

protected static void setStylePrimaryName(Element elem, String style)
Sets the element'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)

### setStylePrimaryName

public void setStylePrimaryName(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

public String 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