Interface Element

All Superinterfaces:
DomQueryable, EventTarget, Node
All Known Subinterfaces:
BodyElement, ButtonElement, CanvasElement, ComponentElement, DelphiElement, HeadElement, InputElement, ItemElement, JavaObjectElement, OptionElement, ScriptElement, StyleElement
public interface Element extends Node, EventTarget, DomQueryable
Represents an element with attributes in a DOM tree.

Elements are not guaranteed to have children. An element can only support children if canHaveChildren() returns true.

See Also:

  • Method Details

    • getStyle

      StyleProperties getStyle()
      Get the modifiable inline style properties.

      Any changes made to the returned properties will be reflected in the Attributes.STYLE attribute, and any changes to the Attributes.STYLE attribute will be reflected in the returned properties.

      Returns:
      Inline style

    • getCurrentStyle

      StylePropertiesReadonly getCurrentStyle()
      Get the element's current style.

      The returned result's properties will be the computed style values of all applicable stylesheet rules and the inline style for the element.

      Returns:
      Unmodifiable style properties

    • getAttribute

      @Nullable @Nullable String getAttribute(String key)
      Gets the value of an attribute.
      Parameters:
      key - Attribute key
      Returns:
      Attribute value, or null, if not set, or if key is null.

    • hasAttribute

      @Contract("null -> false") boolean hasAttribute(@Nullable @Nullable String key)
      Test if the element has an attribute with a mapped value.
      Parameters:
      key - Attribute name
      Returns:
      true, if the element has a value mapped for the specified attribute, false otherwise.

    • setAttribute

      void setAttribute(@NotNull @NotNull String key, @Nullable @Nullable String value)
      Sets an attribute's value.

      If the specified value is already set as the value for this attribute, nothing will change.
      Otherwise, an EventTypes.MODIFY_ATTR event will be triggered after the value is set.

      Parameters:
      key - Attribute key
      value - Attribute value, or null to remove.
      Throws:
      NullPointerException - if key is null or empty

    • removeAttribute

      @Nullable @Nullable String removeAttribute(String attributeName)
      Remove an attribute.

      If the specified attribute isn't set for this attribute, nothing will change.
      Otherwise, an EventTypes.MODIFY_ATTR event will be triggered after the attribute is removed

      Parameters:
      attributeName - Attribute name
      Returns:
      The attribute's value before being removed
      Throws:
      NullPointerException - if attributeName is null or empty

    • getAttributeNames

      Set<String> getAttributeNames()
      Get a set of attribute keys that exist on this element.
      Returns:
      Unmodifiable key set

    • getAttributeEntries

      Set<Map.Entry<String,String>> getAttributeEntries()
      Gets a set of attribute entries that exist on this element.
      Returns:
      Unmodifiable entry set

    • getId

      default String getId()
      Shorthand for getting the id attribute's value
      Returns:
      Element ID
      See Also:

    • setId

      default void setId(@Nullable @Nullable String elementId)
      Shorthand for setting the id attribute
      Parameters:
      elementId - Element ID
      See Also:

    • getClassName

      @Nullable default @Nullable String getClassName()
      Gets the element's Attributes.CLASS attribute value.
      Returns:
      Class name

    • setClassName

      default void setClassName(String className)
      Sets the element's Attributes.CLASS attribute value
      Parameters:
      className - Class name

    • getClassList

      @NotNull @NotNull List<String> getClassList()
      Gets the element's class array list.

      Any modifications made to the returned array will be reflected in the element's class attribute and getCurrentStyle()

      Returns:
      An array list containing all the classes of this element.

    • getTagName

      String getTagName()
      Gets the element's tag name.
      Returns:
      Tag name

    • getTooltip

      @Nullable @Nullable Node getTooltip()
      Gets the element's tooltip.
      Returns:
      Tooltip node
      See Also:

    • getTitleNode

      @Nullable @Nullable Element getTitleNode()
      Gets the element's title node.

      The title node is used as the element's hover tooltip.

      Returns:
      Title node

    • setTitleNode

      void setTitleNode(@Nullable @Nullable Element title)
      Sets the element's title node.

      The title node is used as the element's hover tooltip.

      Parameters:
      title - Title node

    • getTooltipDelay

      long getTooltipDelay()
      Get the tooltip appearance delay in ticks.

      Shorthand for accessing the Attributes.TOOLTIP_DELAY attribute's parsed value.

      If the attribute cannot be parsed, wasn't set, or an unknown time unit was used, this method defaults to 0.

      Returns:
      Tooltip delay in ticks.
      See Also:

    • setTooltipDelay

      void setTooltipDelay(@Nullable @Nullable String timeString)
      Set the tooltip appearance delay in ticks.

      Shorthand for modifying the Attributes.TOOLTIP_DELAY attribute value.

      Parameters:
      timeString - Tooltip delay, or null, to remove the attribute.
      See Also:

    • getTooltipBehaviour

      @NotNull @NotNull TooltipBehaviour getTooltipBehaviour()
      Get the tooltip behaviour.

      Shorthand for accessing the Attributes.TOOLTIP_BEHAVIOUR attribute's parsed value.

      If the value of the attribute couldn't be parsed or wasn't set, then TooltipBehaviour.CURSOR_STICKY is returned.

      Returns:
      Tooltip behaviour
      See Also:

    • setTooltipBehaviour

      void setTooltipBehaviour(@Nullable @Nullable TooltipBehaviour mode)
      Set the tooltip behaviour.

      Shorthand for modifying the Attributes.TOOLTIP_BEHAVIOUR attribute's value.

      Parameters:
      mode - Tooltip behaviour, or null, to remove the attribute's value

    • appendChild

      void appendChild(@NotNull @NotNull Node node)
      Adds a child node to the end of this element's child nodes.

      If the specified node belongs to a different document, it will be adopted to the current document. if the node already has a parent, it will be orphaned before addition.

      Will trigger an EventTypes.APPEND_CHILD event. Can additionally trigger a EventTypes.REMOVE_CHILD event on its previous parent, if it has one.

      Parameters:
      node - Node
      Throws:
      NullPointerException - if node is null

    • prependChild

      void prependChild(@NotNull @NotNull Node node)
      Adds a child node to start of this element's child nodes.

      If the specified node belongs to a different document, it will be adopted to the current document. if the node already has a parent, it will be orphaned before addition.

      Will trigger an EventTypes.APPEND_CHILD event. Can additionally trigger a EventTypes.REMOVE_CHILD event on its previous parent, if it has one.

      Parameters:
      node - Prepended node
      Throws:
      NullPointerException - if node is null

    • insertBefore

      void insertBefore(@NotNull @NotNull Node node, @NotNull @NotNull Node before)
      Inserts an element before the specified node

      If the specified node belongs to a different document, it will be adopted to the current document. if the node already has a parent, it will be orphaned before addition.

      If the specified before node does not belong to the children of this element, then nothing happens.

      Will trigger an EventTypes.APPEND_CHILD event. Can additionally trigger a EventTypes.REMOVE_CHILD event on its previous parent, if it has one.

      Parameters:
      node - Node to insert
      before - Node to insert before
      Throws:
      NullPointerException - If either node or before are null

    • insertAfter

      void insertAfter(@NotNull @NotNull Node node, @NotNull @NotNull Node after)
      Inserts an element after the specified node

      If the specified node belongs to a different document, it will be adopted to the current document. if the node already has a parent, it will be orphaned before addition.

      If the specified after node does not belong to the children of this element, then nothing happens.

      Will trigger an EventTypes.APPEND_CHILD event. Can additionally trigger a EventTypes.REMOVE_CHILD event on its previous parent, if it has one.

      Parameters:
      node - Node to insert
      after - Node to insert after
      Throws:
      NullPointerException - If either node or after are null

    • replaceChild

      void replaceChild(int idx, @NotNull @NotNull Node node)
      Replace a child element at the specified index.

      If the specified node belongs to a different element or document, it will be removed from its previous document and element and adopted to this one.

      Will trigger an EventTypes.REMOVE_CHILD on the child node that's being replaced and then a EventTypes.APPEND_CHILD when the node is inserted into the child node list. Can additionally trigger a EventTypes.REMOVE_CHILD event on the specified node's parent element, if there is one.

      Parameters:
      idx - Index of the child to replace
      node - Node to replace with
      Throws:
      IndexOutOfBoundsException - If the specified index is less than 0 or greater than or equal to getChildCount().
      NullPointerException - If node is null.

    • replaceChild

      void replaceChild(@NotNull @NotNull Node child, @NotNull @NotNull Node node)
      Replace a child element at the specified index.

      If the specified node belongs to a different element or document, it will be removed from its previous document and element and adopted to this one.

      If the specified child is not a child of this element, then nothing happens.

      Will trigger an EventTypes.REMOVE_CHILD on the child node that's being replaced and then a EventTypes.APPEND_CHILD when the node is inserted into the child node list. Can additionally trigger a EventTypes.REMOVE_CHILD event on the specified node's parent element, if there is one.

      Parameters:
      child - Child to replace
      node - Node to replace with
      Throws:
      NullPointerException - If node or child is null.

    • removeChild

      boolean removeChild(@NotNull @NotNull Node node)
      Removes a specified child from this element.

      If the specified node is not a child of this element, then false will be returned.

      Will trigger a EventTypes.REMOVE_CHILD event. The removed node will be orphaned after removal.

      Parameters:
      node - Node to remove
      Returns:
      true, if the node was removed, false if the node was not a child of this element.
      Throws:
      NullPointerException - if node is null
      See Also:

    • removeChild

      void removeChild(int childIndex) throws IndexOutOfBoundsException
      Removes a child element by its index.

      Will trigger a EventTypes.REMOVE_CHILD event. The removed node will be orphaned after removal.

      Parameters:
      childIndex - Index of the child element to remove
      Throws:
      IndexOutOfBoundsException - If the specified childIndex is invalid

    • removeMatchingChildren

      void removeMatchingChildren(@NotNull @NotNull Predicate<Node> filter)
      Remove all child nodes that match the specified filter predicate.

      Each child that is removed triggers a EventTypes.REMOVE_CHILD event. And each removed node will be orphaned after removal.

      Parameters:
      filter - Removal filter
      Throws:
      NullPointerException - If filter is null

    • clearChildren

      void clearChildren()
      Remove all child elements.

      Children are removed 1 by 1 using the removeChild(Node) method

    • getChildren

      List<Node> getChildren()
      Gets an immutable list of child nodes
      Returns:
      Child node list

    • hasChildren

      boolean hasChildren()
      Tests if this element has children.
      Returns:
      true, if the element has children, false otherwise

    • hasChild

      @Contract("null -> false") boolean hasChild(@Nullable @Nullable Node node)
      Tests if the specified node is a direct child of this element
      Parameters:
      node - Node to test
      Returns:
      true, if node is a direct child of this element, false otherwise.

    • indexOf

      int indexOf(@Nullable @Nullable Node node)
      Gets the index of a node that is the direct child of this element.
      Parameters:
      node - Direct child node
      Returns:
      The node's index, or -1, if the node is not a direct child of this element

    • getChildCount

      int getChildCount()
      Gets the amount of children the element has
      Returns:
      Child count

    • canHaveChildren

      boolean canHaveChildren()
      Tests if this element is capable of having child nodes.

      This returns true in most cases. It returns false if the element's tag is <item>.

      Returns:
      true, if this element can support child noes, false otherwise.

    • getChild

      Node getChild(int index) throws IndexOutOfBoundsException
      Gets the nth child of this element.
      Parameters:
      index - Child index from 0 (inclusive) to getChildCount() (exclusive)
      Returns:
      Child node.
      Throws:
      IndexOutOfBoundsException - If index is less than 0 or greater/equal to getChildCount().

    • firstChild

      @Nullable @Nullable Node firstChild()
      Gets the first child of this element.
      Returns:
      First child, or null, if this element has no children

    • lastChild

      @Nullable @Nullable Node lastChild()
      Gets the last child of this element.
      Returns:
      Last child, or null, if this element has no children

    • appendElement

      @NotNull default @NotNull Element appendElement(@NotNull @NotNull String tagName)
      Appends an element and returns it.
      Parameters:
      tagName - Element tag name
      Returns:
      Created element
      Throws:
      NullPointerException - if tagName is null
      See Also:

    • appendText

      @NotNull default @NotNull TextNode appendText(@Nullable @Nullable String text)
      Creates a text node and appends it to this element
      Parameters:
      text - Text content
      Returns:
      Created node
      See Also:

    • getTextContent

      String getTextContent()
      Get the element's text content.

      Returns the joined the text content of all descendants.

      Returns:
      Text content

    • setTextContent

      void setTextContent(String content)
      Remove all child elements and replace it with the specified content
      Parameters:
      content - New text content

    • forEachDescendant

      void forEachDescendant(@NotNull @NotNull Consumer<Node> consumer)
      Applies a consumer to all descendant nodes of this element.

      The specified consumer is applied to elements in a depth-first traversal.

      Parameters:
      consumer - Node consumer
      Throws:
      NullPointerException - If consumer is null

    • isDescendant

      @Contract("null -> false") boolean isDescendant(@Nullable @Nullable Node node)
      Test if a specified node is a descendant of the element.
      Parameters:
      node - Node to test
      Returns:
      true, if the node is a descendant of the element, false otherwise

    • matches

      boolean matches(String selector)
      Test if the element matches a CSS selector.
      Parameters:
      selector - Selector string
      Returns:
      true, if the element matches a selector, false otherwise