Documents and Elements

Documents

RmlContext.load_document() reads an RML file through the virtual file system and returns an RmlDocument; the document is hidden until show() is called. hide() keeps it loaded, close() unloads it. A shown document is pulled in front of the others; pull_to_front() and push_to_back() change the order explicitly.

A document can also come from a string, which is how generated interfaces and tests are built:

The context’s documents are listed by RmlContext.num_documents and unloaded with RmlContext.unload_document() or unload_all_documents(). While iterating on style, RmlDocument.reload_style_sheet() re-reads the document’s style sheets in place.

Elements

RmlDocument.get_element_by_id() finds an element by its id attribute; RmlElement.query_selector() finds the first element matching an RCSS selector below any element. The tree can be walked with num_children, get_child() and get_parent_node().

An RmlElement exposes what a script in a browser would use:

  • inner_rml – the element’s content as markup. Setting it parses RML, so generated lists and tables are built this way. Plain text with line breaks wants white-space: pre in the style, or <br/> tags in the markup.

  • set_class() / is_class_set() – toggle RCSS classes, the usual way to switch an element’s look.

  • set_attribute(), get_attribute(), has_attribute(), remove_attribute().

  • set_property() / remove_property() – an inline style, one property at a time ("opacity", "0.5").

  • value – the value of a form control (<input>, <select>, <textarea>); empty for anything else.

  • click() and focus() – act on the element as the user would.

  • scroll_into_view() – scroll the nearest scrolling ancestor so the element is visible.

  • is_pseudo_class_set() – "hover", "active", "focus", "checked" and the other pseudo-classes.

Building elements in code

RmlDocument.create_element() and RmlDocument.create_text_node() make detached elements; RmlElement.append_child() puts them into the tree and RmlElement.remove_child() takes them out again. For anything larger than a few nodes, assembling a string and assigning inner_rml is simpler and faster.

Geometry

RmlElement.get_absolute_offset() returns the position of the element’s content box in window pixels, measured from the top-left corner of the region; get_relative_offset() measures from the offset parent. offset_width and offset_height are the size of the border box. To compare the edges of a padded element, subtract its padding from the offset first. All of these are in pixels, not in RCSS dp units; see Off-screen Regions and High-DPI Displays for the difference on high-DPI displays.

Documents from memory have no default style

A document loaded from a string carries no user-agent style sheet: a bare <div> is an inline element, there is no float, nothing has a margin. Give such a document a <style> block, or link an RCSS file, before relying on block layout. Documents loaded from files behave the same way; the difference is only that file-based documents usually link a style sheet.