Document Object Model Documentation

Note

The API changed significantly in version 4. See the changelog for details.

The methods described in this page make it easy to modify the appearance and content of a loaded document and manage interaction with the document. For the most part, this page mirrors the core JavaScript DOM API.

class tkinterweb.dom.HTMLDocument(html)

Access this class via the document property of the HtmlFrame and HtmlLabel widgets.

Variables:: html – The associated TkinterWeb instance.

property body

The document body element.

Return type:: HTMLElement

property documentElement

The document root element.

Return type:: HTMLElement

write(*text)

Write into the current document or output stream. If the document is loaded, this first deletes all existing HTML.

Parameters:: text (str) – The text or HTML code to insert.

New in version 4.20.

createElement(tagname)

Create and return a new HTML element with the given tag name.

Parameters:: tagname (str) – The new element’s HTML tag.
Return type:: HTMLElement

createTextNode(text)

Create and return a new text node with the given text content.

Parameters:: text (str) – The text content of the new node.
Return type:: HTMLElement

getElementById(query, _root=None)

Return an element that matches a given id.

Parameters:: query (str) – The element id to be searched for.
Return type:: HTMLElement
Raises:: tkinter.TclError

getElementsByClassName(query, _root=None)

Return all elements that match a given class name.

Parameters:: query (str) – The class to be searched for.
Return type:: HTMLCollection
Raises:: tkinter.TclError

getElementsByName(query, _root=None)

Return all elements that match a given given name attribute.

Parameters:: query (str) – The name to be searched for.
Return type:: HTMLCollection
Raises:: tkinter.TclError

getElementsByTagName(query, _root=None)

Return all elements that match a given tag name.

Parameters:: query (str) – The tag to be searched for.
Return type:: HTMLCollection
Raises:: tkinter.TclError

querySelector(query, _root=None)

Return the first element that matches a given CSS selector.

Parameters:: query (str) – The CSS selector to be searched for.
Return type:: HTMLElement
Raises:: tkinter.TclError

querySelectorAll(query, _root=None)

Return all elements that match a given CSS selector.

Parameters:: query (str) – The CSS selector to be searched for.
Return type:: HTMLCollection
Raises:: tkinter.TclError

class tkinterweb.dom.HTMLElement(document_manager, node)

Parameters:

document_manager (HTMLDocument) – The HTMLDocument instance this class is tied to.
node (Tkhtml3 node) – The Tkhtml3 node this class represents.

Variables:

document – The element’s corresponding HTMLDocument instance.
html – The element’s corresponding TkinterWeb instance.
node – The element’s corresponding Tkhtml node.

property style

Manage the element’s styling. For instance, to make the element have a blue background, use yourhtmlelement.style.backgroundColor = "blue".

Return type:: CSSStyleDeclaration

property innerHTML

Get and set the inner HTML of the element. Cannot be set on <html> elements.

Return type:: str
Raises:: tkinter.TclError

property innerText

Get and set the text content of an element, as displayed. Cannot be set on <html> elements.

Return type:: str
Raises:: tkinter.TclError

New in version 4.14.

property textContent

Get and set the text content of an element. Cannot be used on <html> elements.

Return type:: str
Raises:: tkinter.TclError

property id

Get and set the element’s id attribute.

Return type:: str

New in version 4.4.

property className

Get and set the element’s class attribute.

Return type:: str

New in version 4.4.

property attributes

Return the element’s attributes.

Return type:: dict

property tagName

Return the element’s tag name.

Return type:: str

property parentElement

Get the element’s parent element.

Return type:: HTMLElement
Raises:: tkinter.TclError

property children

Get the element’s children elements.

Return type:: list
Raises:: tkinter.TclError

property previousSibling

Get the element’s preceding sibling.

Return type:: HTMLElement

New in version 4.8.

property nextSibling

Get the element’s following sibling.

Return type:: HTMLElement

New in version 4.8.

property widget

Get and set the element’s widget.

Prior to version 4.2 this only applies to <object> elements and a widget must be specified.

Since version 4.10 this can also be used to get the widget representing <input>, <textarea>, <select> , <iframe>, and some <object> elements.

If the widget already exists in the document, it will first be removed from its previous element.

Ensure your HtmlFrame widget was created before the widget you are embedding, or else the widget might not be visible.

Return type:: tkinter.Widget or None

New in version 4.1.

property value

Get and set the input’s value. Only works on <input>, <textarea>, <select>, and progress elements.

Return type:: str

New in version 4.1.

property checked

Convenience property for the checked HTML attribute. Check/uncheck a radiobutton or checkbox or see if the element is checked.

Return type:: bool

New in version 4.1.

getAttribute(attribute)

Return the value of the given attribute.

Parameters:: attribute (str) – The attribute to return.
Return type:: str

setAttribute(attribute, value)

Set the value of the given attribute.

Parameters:

attribute (str) – The attribute to set.
value (str) – The new value of the given attribute.

removeAttribute(attribute)

Remove the given attribute. At the moment this sets the value of the attribute to “”.

Parameters:: attribute (str) – The attribute to remove.

New in version 4.20.

remove()

Delete the element. Cannot be used on <html> or <body> elements. The element can be reinserted into the document later if needed.

Raises:: tkinter.TclError

appendChild(children)

Insert the specified children into the element.

Parameters:: children (list, tuple, or HTMLElement) – The element(s) to be added into the element.

insertBefore(children, before)

Insert the specified children before a given child element.

Parameters:

children (list, tuple, or HTMLElement) – The element(s) to be added into the element.
before (HTMLElement) – The child element that the added elements should be placed before.

Raises:

tkinter.TclError

getElementById(query)

Return an element that is a child of the current element and matches the given id.

Parameters:: query (str) – The element id to be searched for.
Return type:: HTMLElement
Raises:: tkinter.TclError

getElementsByClassName(query)

Return all elements that are children of the current element and match the given class name.

Parameters:: query (str) – The class to be searched for.
Return type:: HTMLCollection
Raises:: tkinter.TclError

getElementsByName(query)

Return all elements that are children of the current element and match the given name attribute.

Parameters:: query (str) – The name to be searched for.
Return type:: HTMLCollection
Raises:: tkinter.TclError

getElementsByTagName(query)

Return all elements that are children of the current element and match the given tag name.

Parameters:: query (str) – The tag to be searched for.
Return type:: HTMLCollection
Raises:: tkinter.TclError

querySelector(query)

Return the first element that is a child of the current element and matches the given CSS selector.

Parameters:: query (str) – The CSS selector to be searched for.
Return type:: HTMLElement
Raises:: tkinter.TclError

querySelectorAll(query)

Return all elements that are children of the current element and match the given CSS selector.

Parameters:: query (str) – The CSS selector to be searched for.
Return type:: HTMLCollection
Raises:: tkinter.TclError

scrollIntoView(): Scroll the viewport so that this element is visible.

getBoundingClientRect()

Get the element’s position and size.

Return type:: DOMRect

bind(sequence, func, add=None)

Tkinter-style method to add a binding to this element.

The following virtual events are supported:

<<ElementLoaded>>/utilities.ELEMENT_LOADED_EVENT: Generated whenever an element loads after the page finishes.
<<Modified>>`/utilities.FIELD_CHANGED_EVENT: Generated whenever the content of any <input> element changes.

The following Tkinter events are supported:

<Enter>
<Leave>
<MouseWheel>
All Tkinter button and motion events

Parameters:

sequence (str) – The Tkinter event to bind to.
func (callable) – The callback to evaluate when the binding fires.
add (str or None) – If set to “+”, add this binding onto existing ones. Otherwise, existing bindings will be overwritten.

Raises:

RuntimeError – If events are disabled.

New in version 4.10.

unbind(sequence, funcid=None)

Tkinter-style method to remove a binding to this element.

Parameters:

sequence (str) – The Tkinter event to unbind.
funcid (callable or None) – If specified, only the specified function will be removed from the list of bindings.

New in version 4.10.

The following JavaScript event properties are also supported: onchange, onclick, oncontextmenu, ondblclick, onload, onmousedown, onmouseenter, onmouseleave, onmousemove, onmouseout, onmouseover, and onmouseup.

class tkinterweb.dom.HTMLCollection(document_manager, search_string, root=None)

This class stores results from various HTMLElement methods. It behaves like a Python list, with some extras.

Parameters:

document_manager (HTMLDocument) – The HTMLDocument instance this class is tied to.
search_string (str) – The CSS query string to search using.
root (Tkhtml3 node) – The Tkhtml node to search.

Variables:

html – The element’s corresponding TkinterWeb instance.
node – The element’s corresponding Tkhtml node.

New in version 4.4.

property length: Returns the number of items in the collection.

item(index)

Returns the element at the given index into the list.

Parameters:: index (int) – The index of the element to get.
Return type:: HTMLElement
Raise:: KeyError

namedItem(key)

Returns the element whose id or name matches key.

Parameters:: key (str) – The id or name to search for.
Return type:: HTMLElement or None

class tkinterweb.dom.CSSStyleDeclaration(element_manager)

Access this class via the style property of the HTMLElement class.

Parameters:

element_manager (HTMLElement) – The HTMLElement instance this class is tied to.

Variables:

html – The element’s corresponding TkinterWeb instance.
node – The element’s corresponding Tkhtml node.

property cssText

Get and set the element’s inline style declaration.

Return type:: str

Updated in version 4.19.

property length

Return the number of style declarations in the element’s inline style declaration.

Return type:: int

property cssProperties

Return all computed properties for the element.

Return type:: dict

property cssInlineProperties

Return all inline properties for the element. Similar to the cssText property, but formatted as a dictionary.

Return type:: dict

property cssInlineStyles

Return the content of the element’s style attribute, formatted as a dictionary.

Return type:: dict

getPropertyPriority(property)

Return the priority of the given inline CSS property.

Parameters:: property (str) – The CSS property to search for.
Returns:: “important” or “”.
Return type:: str

getPropertyValue(property)

Return the value of the given inline CSS property.

You can also use JavaScript-style camel-cased properties to get a CSS property value. For instance, to get the element’s background color, use yourhtmlelement.style.backgroundColor

Parameters:: property (str) – The CSS property to get.
Return type:: str

New in version 4.1.

removeProperty(property)

Remove the given inline CSS property.

Parameters:: property (str) – The CSS property to remove.
Returns:: The old value of the given property, or “” if the property did not exist.
Return type:: str

New in version 4.1.

setProperty(property, value)

Set the value of the given inline CSS property.

You can also use JavaScript-style camel-cased properties to set a CSS property value. For instance, to make the element have a blue background, use yourhtmlelement.style.backgroundColor = "blue"

Parameters:: property (str) – The CSS property to set.
Returns:: The old value of the given property, or “” if the property did not exist.
Return type:: str

New in version 4.1.

class tkinterweb.dom.DOMRect(element_manager)

This class generates and stores information about the element’s position and size at this point in time.

Parameters:

element_manager (HTMLElement) – The HTMLElement instance this class is tied to.

Variables:

x – The element’s horizontal offset from the left-hand side of the page.
y – The element’s vertical offset from the top of the page.
width – The element’s width.
height – The element’s height.
html – The element’s corresponding TkinterWeb instance.
node – The element’s corresponding Tkhtml node.

Special thanks to Zamy846692 for the help making this happen!