com.google.gwt.user.client.ui

## Class UIObject

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject

- All Implemented Interfaces:
    HasVisibility
  Direct Known Subclasses:
    CellTreeNodeView, MenuItem, MenuItemSeparator, TreeItem, Widget

      public abstract class UIObject
      extends java.lang.Object
      implements HasVisibility

  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)`, `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

    Nested Classes
    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` The implementation of the setDebugId method, which sets the id of the `Element`s in this `UIObject`.

  - ### Field Summary

    Fields
    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 Summary

    Constructors
    Constructor and Description
    `UIObject()`

  - ### Method Summary

    Methods
    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)` Ensure that the main `Element` for this `UIObject` has an ID property set, which allows it to integrate with third-party libraries and test tools.
    `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)` Sets this object's browser element.
    `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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEBUG_ID_PREFIX

          public static final java.lang.String DEBUG_ID_PREFIX

      See Also:
        Constant Field Values

    - #### MISSING_ELEMENT_ERROR

          static final java.lang.String MISSING_ELEMENT_ERROR

      See Also:
        Constant Field Values

    - #### SETELEMENT_TWICE_ERROR

          static final java.lang.String SETELEMENT_TWICE_ERROR

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### UIObject

          public UIObject()

  - ### Method Detail

    - #### ensureDebugId

          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"/>

      Parameters:
        `elem` - the target `Element`
        `id` - the ID to set on the element

    - #### isVisible

          public static boolean isVisible(Element elem)

      Returns whether the given element is visible in a way consistent with `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.

    - #### setVisible

          public static void setVisible(Element elem,
                        boolean visible)

      Shows or hides the given element. Also updates the "aria-hidden" attribute.

      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)`.

    - #### ensureDebugId

          protected static void ensureDebugId(Element elem,
                           java.lang.String baseID,
                           java.lang.String id)

      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 element
        `baseID` - the base ID used by the main element
        `id` - the id to append to the base debug id

    - #### getStyleName

          protected static java.lang.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
      Returns:
        the objects's space-separated style names

    - #### getStylePrimaryName

          protected static java.lang.String getStylePrimaryName(Element elem)

      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

          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.
      Parameters:
        `elem` - the element whose style is to be modified
        `styleName` - the new style name

    - #### setStyleName

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

    - #### setStylePrimaryName

          protected static void setStylePrimaryName(Element elem,
                                 java.lang.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)`

    - #### addStyleDependentName

          public void addStyleDependentName(java.lang.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)`, `setStyleDependentName(String, boolean)`, `addStyleName(String)`

    - #### addStyleName

          public void addStyleName(java.lang.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;
           }

      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:
        `UIObject`, `removeStyleName(String)`

    - #### ensureDebugId

          public final void ensureDebugId(java.lang.String id)

      Ensure that the main `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"/>

      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

          public Element 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 using `setElement(com.google.gwt.user.client.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

          public java.lang.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()`.
      Returns:
        the objects's space-separated style names
      See Also:
        `getStylePrimaryName()`

    - #### getStylePrimaryName

          public java.lang.String getStylePrimaryName()

      Gets the primary style name associated with the object.
      Returns:
        the object's primary style name
      See Also:
        `setStyleName(String)`, `addStyleName(String)`, `removeStyleName(String)`

    - #### getTitle

          public java.lang.String 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 the `Document`. The default implementation of this trait in `UIObject` is based on the value of a dom element's style object's display attribute.
      Specified by:
        `isVisible` in interface `HasVisibility`
      Returns:
        `true` if the object is visible

    - #### removeStyleDependentName

          public void removeStyleDependentName(java.lang.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)`, `setStyleDependentName(String, boolean)`

    - #### removeStyleName

          public void removeStyleName(java.lang.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)`, `setStyleName(String, boolean)`

    - #### setHeight

          public void setHeight(java.lang.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(java.lang.String width,
                     java.lang.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")

    - #### setStyleDependentName

          public void setStyleDependentName(java.lang.String styleSuffix,
                                   boolean add)

      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 removed
        `add` - `true` to add the given style, `false` to remove it
      See Also:
        `setStylePrimaryName(Element, String)`, `addStyleDependentName(String)`, `setStyleName(String, boolean)`, `removeStyleDependentName(String)`

    - #### setStyleName

          public void setStyleName(java.lang.String style,
                          boolean add)

      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 removed
        `add` - `true` to add the given style, `false` to remove it
      See Also:
        `addStyleName(String)`, `removeStyleName(String)`

    - #### setStyleName

          public void setStyleName(java.lang.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

          public void setStylePrimaryName(java.lang.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(java.lang.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 void setVisible(boolean visible)

      Description copied from interface: `HasVisibility`
      Sets whether this object is visible.
      Specified by:
        `setVisible` in interface `HasVisibility`
      Parameters:
        `visible` - `true` to show the object, `false` to hide it

    - #### setWidth

          public void setWidth(java.lang.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")

    - #### sinkBitlessEvent

          public void sinkBitlessEvent(java.lang.String eventTypeName)

      Sinks a named event. Note that only `widgets` 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:
        `Event`

    - #### 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 java.lang.String toString()

      This method is overridden so that any object can be viewed in the debugger as an HTML snippet.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        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(int)`, `Event`

    - #### 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.
      Returns:
        the element to which style names will be applied

    - #### onEnsureDebugId

          protected void onEnsureDebugId(java.lang.String baseID)

      Called when the user sets the id using the `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:
      - -mysubelement = Applies to my sub element.
      Subclasses should make a super call to this method to ensure that the ID of the main element is set. This method will not be called unless you inherit the DebugID module in your gwt.xml file by adding the following line:

           <inherits name="com.google.gwt.user.Debug"/>

      Parameters:
        `baseID` - the base ID used by the main element

    - #### resolvePotentialElement

          protected 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 calling `setElement(PotentialElement.build(this))`.

      The receiver must:

      - create a real `Element` to replace its `PotentialElement`
      - 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.user.client.Element, com.google.gwt.user.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)`.

      See Also:
        `PotentialElement`, `IsRenderable`

    - #### setElement

          protected final void setElement(Element elem)

      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

          protected void setElement(Element elem)

      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

          void replaceElement(Element elem)

      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