Bindings Documentation

Note

This API has changed significantly recently. See the changelog for details.

The following objects offer the core bindings to the Tkhtml3 HTML widget and are largely internal. You will likely never need to access them, but they are described here just in case.

Refer to the Tkhtml Documentation for more details on some of the commands.

class tkinterweb.TkinterWeb(master, tkinterweb_options=None, **kwargs)

This object provides the low-level widget that bridges the gap between the underlying Tkhtml3 widget and Tkinter.

Do not use this widget on its own unless absolutely nessessary. Instead use the HtmlFrame widget.

This widget can be accessed through the html property of the HtmlFrame and HtmlLabel widgets to access underlying settings and commands that are not a part of the HtmlFrame API.

This widget stores many useful instance variables and configuration flags. Some are exposed through the main API, others are not. Please see the source code for more details.

property selection_manager

The widget’s selection manager.

Return type:: SelectionManager

New in version 4.11.

property caret_manager

The widget’s caret manager.

Return type:: CaretManager

New in version 4.8.

property event_manager

The widget’s event manager.

Return type:: EventManager

New in version 4.10.

property widget_manager

The widget’s widget manager.

Return type:: WidgetManager

New in version 4.11.

property search_manager

The widget’s document search manager.

Return type:: SearchManager

New in version 4.11.

property script_manager

The widget’s script manager.

Return type:: ScriptManager

New in version 4.11.

property style_manager

The widget’s style manager.

Return type:: StyleManager

New in version 4.11.

property image_manager

The widget’s image manager.

Return type:: ImageManager

New in version 4.11.

property object_manager

The widget’s object manager.

Return type:: ObjectManager

New in version 4.11.

property form_manager

The widget’s form manager.

Return type:: FormManager

New in version 4.11.

property node_manager

The widget’s node handler manager.

Return type:: NodeManager

New in version 4.11.

property tkhtml_default_style

Return the current document’s default stylesheet. Use for debugging.

New in version 4.19.

property images

Return a dictionary containing the document’s images. Use for debugging.

New in version 4.19.

property style_report

Return the document’s style report. Use for debugging.

New in version 4.19.

post_to_queue(callback, thread_safe=True)

Use this method to send a callback to TkinterWeb’s thread-safety queue. The callback will be evaluated on the main thread. Use this when running Tkinter commands from within a thread. If the queue is not running (i.e. threading is disabled), the callback will be evaluated immediately.

New in version 4.9.

post_event(event, thread_safe=False): Generate a virtual event.

post_message(message, thread_safe=False): Post a message.

parse(html, thread_safe=False): Parse HTML code. Call TkinterWeb.reset() before calling this method for the first time.

parse_css(sheetid=None, data='', url=None, fallback_priority='author'): Parse CSS code.

reset(thread_safe=False): Reset the widget.

stop(): Stop loading resources.

resolve_url(url, base=None): Generate a full url from the specified url.

node(*args): Retrieve one or more document node handles from the current document.

text(subcommand, *args): Interact with the text of the HTML document. Valid subcommands are bbox, index, offset, and text.

tag(subcommand, tag_name, *args): Highlight regions of text displayed by the widget. Valid subcommands are add, remove, configure, and delete.

search(selector, *a, cnf={}, **kw): Search the document for the specified CSS selector; return a Tkhtml node if found.

xview(*args, auto_scroll=False): Control horizontal scrolling.

xview_scroll(number, what, auto_scroll=False): Shifts the view in the window left or right, according to number and what. “number” is an integer, and “what” is either “units” or “pages”.

xview_moveto(number, auto_scroll=False): Shifts the view horizontally to the specified position

yview(*args, auto_scroll=False): Control vertical scrolling.

yview_scroll(number, what, auto_scroll=False): Shifts the view in the window left or right, according to number and what. “number” is an integer, and “what” is either “units” or “pages”.

yview_moveto(number, auto_scroll=False): Moves the view vertically to the specified position.

bbox(node=None): Get the bounding box of the viewport or a specified node.

parse_fragment(html): Parse a document fragment. A document fragment isn’t part of the active document but is comprised of nodes like the active document. Changes made to the fragment don’t affect the document. Returns a root node.

get_node_text(node_handle, *args): Get the text content of the given node.

set_node_text(node_handle, new): Set the text content of the given node.

get_child_text(node)

Get text of node and all its descendants recursively.

New in version 4.4.

get_node_tag(node_handle): Get the HTML tag of the given node.

get_node_parent(node_handle): Get the parent of the given node.

get_node_children(node_handle): Get the children of the given node.

get_node_attribute(node_handle, attribute, default='', value=None): Get the specified attribute of the given node.

set_node_attribute(node_handle, attribute, value): Set the specified attribute of the given node.

get_node_attributes(node_handle): Get the attributes of the given node.

get_node_property(node_handle, node_property, *args): Get the specified CSS property of the given node.

get_node_properties(node_handle, *args): Get the CSS properties of the given node.

set_node_property(node_handle, node_property, new_value, *args): Set the specified CSS property of the given node.

override_node_properties(node_handle, *props): Get/set the CSS property override list.

insert_node(node_handle, child_nodes): Experimental, insert the specified nodes into the parent node.

insert_node_before(node_handle, child_nodes, before): Experimental, place the specified nodes is before another node.

replace_node_contents(node_handle, contents, *args, check=True)

Fill a node with either a Tk widget or with Tkhtml nodes.

New in version 4.2.

get_node_replacement(node_handle)

Return the Tk widget contained by the given node.

New in version 4.13.

delete_node(node_handle): Delete the given node.

destroy_node(node_handle): Destroy a node. May cause crashes so avoid it whenever possible.

set_node_flags(node, name): Set dynamic flags on the given node.

remove_node_flags(node, name): remove dynamic flags on the given node.

get_node_tkhtml(node_handle): Get the path name of the node’s corresponding Tkhtml instance.

get_node_stacking(node_handle)

Return the node-handle that forms the stacking context this node is located in. Return “” for the root-element or any element that is part of an orphan subtree.

New in version 4.2.

get_current_hovered_node(event): Get the current node.

get_current_hovered_node_parent(node): Get the parent of the node returned by TkinterWeb.get_current_hovered_node().

register_handler(handler_type, node_tag, callback): Register a node handler.

register_lazy_handler(handler_type, node_tag, manager_name): Register a node handler to run lazily in the given manager.

image(full=False): Return the name of a new Tk image containing the rendered document. The returned image should be deleted when the script has finished with it. Note that this command is mainly intended for automated testing. Be wary of running this command on large documents. Does not work on Windows unless experimental Tkhtml is used.

postscript(cnf={}, **kwargs): Print the contents of the canvas to a postscript file. Valid options: colormap, colormode, file, fontmap, height, pageanchor, pageheight, pagesize, pagewidth, pagex, pagey, nobg, noimages, rotate, width, x, and y. Does not work unless experimental Tkhtml is used.

preload_image(url): Preload an image for use later. Only useful if caches are enabled and reset() is not called after preloading.

get_computed_styles(): Get a tuple containing the computed CSS rules for each CSS selector.

override_node_CSS(node, *props)

Overrides the node’s properties; if it is a text node, it overrides the parent’s properties.

New in version 4.4.

write(*arg, cnf={}, **kw)

Write directly to an open HTML document stream, may be used when parsing.

New in version 4.4.

safe_tk_eval(expr)

Always evaluate the given expression on the main thread.

Since version 4.9 all callbacks are evaluated on the main thread. Except for niche cases this command should not need to be used.

This command may be removed at any time.

New in version 4.4.

serialize_node(ib=3)

Pretty-print a node’s contents. Similar to innerHTML, but formatted.

New in version 4.4.

serialize_node_style(ib=3, return_as_dict=False)

Pretty-print a node’s style.

New in version 4.4.

tkhtml_offset_to_text_index(node, offset, invert=False)

Translate a Tkhtml node offset to a node text index or back.

New in version 4.8.

decode_uri(uri, base64=False)

This command is designed to help scripts process data: URIs. It is completely separate from the html widget.

New in version 4.19.

encode_uri(uri)

Encodes the uri.

New in version 4.19.

escape_uri(uri, query=False)

Returns the decoded data.

New in version 4.19.

class tkinterweb.TkHtmlParsedURI(uri, html)

Bindings for the Tkhtml URI parsing system.

The underlying commands are largely unmaintained. Consider using the methods provided by the HtmlFrame widget and by Python’s urllib library.

New in version 4.4.

uri(uri): Returns name of parsed uri to be used in methods below.

tkhtml_uri_decode(uri, base64=False): This command is designed to help scripts process data: URIs. It is completely separate from the html widget

tkhtml_uri_encode(uri): Encodes the uri.

tkhtml_uri_escape(uri, query=False): Returns the decoded data.

uri_resolve(uri): Resolve a uri.

property load: Load a uri.

property get: Get the uri.

property defrag: Defrag the uri.

property scheme: Return the uri scheme.

property authority: Return the uri authority.

property path: Return the uri path.

property query: Return the uri query.

property fragment: Return the uri fragment.

property splitfrag: Return namedtuple with uri and fragment