Xml#

This represents an HTML or an XML node. It is a helper class intended to access the DOM (Document Object Model) content of a Story object.

There is no need to ever directly construct an Xml object: after creating a Story, simply take Story.Body – which is an Xml node – and use it to navigate your way through the story’s DOM.

Method / Attribute	Description
`AddBulletList()`	Add a ul tag - bulleted list, context manager
`AddCodeBlock()`	Add a pre tag, context manager
`AddDescriptionList()`	Add a dl tag, context manager
`AddDivision()`	add a div tag (renamed from “section”), context manager
`AddHeader()`	Add a header tag (one of h1 to h6), context manager
`AddHorizontalLine()`	Add a hr tag
`AddImage()`	Add a img tag
`AddLink()`	Add a a tag
`AddNumberList()`	Add a ol tag, context manager
`AddParagraph()`	Add a p tag
`AddSpan()`	Add a span tag, context manager
`AddSubscript()`	Add subscript text(sub tag) - inline element, treated like text
`AddSuperscript()`	Add subscript text (sup tag) - inline element, treated like text
`AddCode()`	Add code text (code tag) - inline element, treated like text
`AddVar()`	Add code text (code tag) - inline element, treated like text
`AddSamp()`	Add code text (code tag) - inline element, treated like text
`AddKbd()`	Add code text (code tag) - inline element, treated like text
`AddText()`	Add a text string. Line breaks `n` are honored as br tags
`AppendChild()`	Append a child node
`Clone()`	Make a copy if this node
`CreateElement()`	Make a new node with a given tag name
`CreateTextNode()`	Create direct text for the current node
`Find()`	Find a sub-node with given properties
`FindNext()`	Repeat previous “find” with the same criteria
`InsertAfter()`	Insert an element after current node
`InsertBefore()`	Insert an element before current node
`Remove()`	Remove this node
`SetAlign()`	Set the alignment using a CSS style spec. Only works for block-level tags
`SetAttribute()`	Set an arbitrary key to some value (which may be empty)
`SetBgColor()`	Set the background color. Only works for block-level tags
`SetBold()`	Set bold on or off or to some string value
`SetColor()`	Set text color
`SetColumns()`	Set the number of columns. Argument may be any valid number or string
`SetFont()`	Set the font-family, e.g. “sans-serif”
`SetFontSize()`	Set the font size. Either a float or a valid HTML/CSS string
`SetId()`	Set a id. A check for uniqueness is performed
`SetItalic()`	Set italic on or off or to some string value
`SetLeading()`	Set inter-block text distance (`-mupdf-leading`), only works on block-level nodes
`SetLineHeight()`	Set height of a line. Float like 1.5, which sets to `1.5 * fontSize`
`SetMargins()`	Set the margin(s), float or string with up to 4 values
`SetPageBreakAfter()`	Insert a page break after this node
`SetPageBreakBefore()`	Insert a page break before this node
`SetProperties()`	Set any or all desired properties in one call
`AddStyle()`	Set (add) a “style” that is not supported by its own `set_` method
`AddClass()`	Set (add) a “class” attribute
`SetTextIndent()`	Set indentation for first textblock line. Only works for block-level nodes
`TagName`	Either the HTML tag name like p or `null` if a text node
`Text`	Either the node’s text or `null` if a tag node
`IsText`	Check if the node is a text
`FirstChild`	Contains the first node one level below this one (or `null`)
`LastChild`	Contains the last node one level below this one (or `null`)
`Next`	The next node at the same level (or `null`)
`Previous`	The previous node at the same level
`Root`	The top node of the DOM, which hence has the tagname html

Class API

class Xml#

AddBulletList()#: Add an ul tag - bulleted list, context manager. See ul.

AddCodeBlock()#: Add a pre tag, context manager. See pre.

AddDescriptionList()#: Add a dl tag, context manager. See dl.

AddDivision()#: Add a div tag, context manager. See div.

AddHeader(int level: 1)#

Add a header tag (one of h1 to h6), context manager. See headings.

Parameters:: value (int) – a value 1 - 6.

AddHorizontalLine()#: Add a hr tag. See hr.

AddImage(string name, string width: null, string height: null, string imgFloat: null, string align: null)#

Add an img tag. This causes the inclusion of the named image in the DOM.

Parameters:

name (string) – the filename of the image. This must be the member name of some entry of the Archive parameter of the Story constructor.
width (string) – if provided, either an absolute (int) value, or a percentage string like “30%”. A percentage value refers to the width of the specified where rectangle in Story.Place(). If this value is provided and height is omitted, the image will be included keeping its aspect ratio.
height (string) – if provided, either an absolute (int) value, or a percentage string like “30%”. A percentage value refers to the height of the specified where rectangle in Story.Place(). If this value is provided and width is omitted, the image’s aspect ratio will be honored.

AddLink(string href, string text: null)#

Add an a tag - inline element, treated like text.

Parameters:

href (string) – the URL target.
text (string) – the text to display. If omitted, the href text is shown instead.

AddNumberList()#: Add an ol tag, context manager.

AddParagraph()#: Add a p tag, context manager.

AddSpan()#: Add a span tag, context manager. See span

AddSubscript(string text)#: Add “subscript” text(sub tag) - inline element, treated like text.

AddSuperscript(string text)#: Add “superscript” text (sup tag) - inline element, treated like text.

AddCode(string text)#: Add “code” text (code tag) - inline element, treated like text.

AddVar(string text)#: Add “variable” text (var tag) - inline element, treated like text.

AddSamp(string text)#: Add “sample output” text (samp tag) - inline element, treated like text.

AddKbd(string text)#: Add “keyboard input” text (kbd tag) - inline element, treated like text.

AddText(string text)#: Add a text string. Line breaks n are honored as br tags.

SetAlign(dynamic value)#

Set the text alignment. Only works for block-level tags.

Parameters:: value – either one of the Text Alignment or the text-align values.

SetAttribute(string key, string value=null)#

Set an arbitrary key to some value (which may be empty).

Parameters:

key (string) – the name of the attribute.
value (string) – the (optional) value of the attribute.

GetAttributes()#

Retrieve all attributes of the current nodes as a dictionary.

Returns:: a dictionary with the attributes and their values of the node.

GetAttributeValue(string key)#

Get the attribute value of key.

Parameters:: key (string) – the name of the attribute.
Returns:: a string with the value of key.

RemoveAttribute(string key)#

Remove the attribute key from the node.

Parameters:: key (string) – the name of the attribute.

SetBgColor(int value)#

SetBgColor(float[] value)#

SetBgColor(string value)#

Set the background color. Only works for block-level tags.

Parameters:: value – either an RGB value like (255, 0, 0) (for “red”) or a valid background-color value.

SetBold(bool value)#

Set bold on or off or to some string value.

Parameters:: value – true, false or a valid font-weight value.

SetColor(dynamic value)#

Set the color of the text following.

Parameters:: value – either an RGB value like (255, 0, 0) (for “red”) or a valid color value.

SetColumns(int cols)#

Set the number of columns.

Parameters:: cols (int) – a valid columns value.

Note

Currently ignored - supported in a future MuPDF version.

SetFont(string font)#

Set the font-family.

Parameters:: value (string) – e.g. “sans-serif”.

SetFontSize(float fontSize)#

Set the font size for text following.

Parameters:: fontSize (float) – a float or a valid font-size value.

SetId(string unique)#

Set a id. This serves as a unique identification of the node within the DOM. Use it to easily locate the node to inspect or modify it. A check for uniqueness is performed.

Parameters:: unique (string) – id string of the node.

SetItalic(bool isItalic)#

Set italic on or off or to some string value for the text following it.

Parameters:: isItalic (bool) – true, false or some valid font-style value.

SetLeading(string leading)#

Set inter-block text distance (-mupdf-leading), only works on block-level nodes.

Parameters:: leading (float) – the distance in points to the previous block.

SetLineHeight(string lineHeight)#

Set height of a line.

Parameters:: lineHeight (string) – a float like 1.5 (which sets to 1.5 * fontSize), or some valid line-height value.

SetMargins(string val)#

Set the margin(s).

Parameters:: val (string) – float or string with up to 4 values. See CSS documentation.

SetPageBreakAfter()#: Insert a page break after this node.

SetPageBreakBefore()#: Insert a page break before this node.

SetProperties(string align: null, string bgcolor: null, bool bold: false, string color: null, int columns: 0, string font: null, int fontSize: 10, string indent: null, bool italic: false, string leading: null, string lineHeight: null, string margins: null, string pageBreakAfter: false, string pageBreakBefore: false, string wordSpacing: null, string unqid: null, string cls: null)#: Set any or all desired properties in one call. The meaning of argument values equal the values of the corresponding set_ methods.

Note

The properties set by this method are directly attached to the node, whereas every set_ method generates a new span below the current node that has the respective property. So to e.g. “globally” set some property for the body, this method must be used.

AddStyle(string text)#

Set (add) some style attribute not supported by its own set_ method.

Parameters:: value (string) – any valid CSS style value.

AddClass(string text)#

Set (add) some “class” attribute.

Parameters:: value (string) – the name of the class. Must have been defined in either the HTML or the CSS source of the DOM.

SetTextIndent(string value)#

Set indentation for the first textblock line. Only works for block-level nodes.

Parameters:: value – a valid text-indent value. Please note that negative values do not work.

AppendChild(Xml child)#

Append a child node. This is a low-level method used by other methods like Xml.AddParagraph().

Parameters:: child – the Xml node to append.

CreateTextNode(string text)#

Create direct text for the current node.

Parameters:: text (str) – the text to append.
Return type:: Xml
Returns:: the created element.

CreateElement(string tag)#

Create a new node with a given tag. This a low-level method used by other methods like Xml.AddParagraph().

Parameters:: tag (str) – the element tag.
Return type:: Xml
Returns:: the created element. To actually bind it to the DOM, use Xml.AppendChild().

InsertBefore(Xml node)#

Insert the given element elem before this node.

Parameters:: node – some Xml element.

InsertAfter(Xml node)#

Insert the given element elem after this node.

Parameters:: node – some Xml element.

Clone()#

Make a copy of this node, which then may be appended (using Xml.AppendChild()) or inserted (using one of Xml.InsertBefore(), Xml.InsertAfter()) in this DOM.

Returns:: the clone (Xml) of the current node.

Remove()#: Remove this node from the DOM.

Debug()#: For debugging purposes, print this node’s structure in a simplified form.

Find(string tag, string att, string match)#

Under the current node, find the first node with the given tag, attribute att and value match.

Parameters:

tag (str) – restrict search to this tag. May be null for unrestricted searches.
att (str) – check this attribute. May be null.
match (str) – the desired attribute value to match. May be null.

Return type:

Xml.

Returns:

null if nothing found, otherwise the first matching node.

FindNext(string tag, string att, string match)#

Continue a previous Xml.Find() (or FindNext()) with the same values.

Return type:: Xml.
Returns:: null if none more found, otherwise the next matching node.

TagName#: Either the HTML tag name like p or null if a text node.

Text#: Either the node’s text or null if a tag node.

IsText#: Check if a text node.

FirstChild#: Contains the first node one level below this one (or null).

LastChild#: Contains the last node one level below this one (or null).

Next#: The next node at the same level (or null).

Previous#: The previous node at the same level.

Root#: The top node of the DOM, which hence has the tagname html.

Setting Text properties#

In HTML tags can be nested such that innermost text inherits properties from the tag enveloping its parent tag. For example <p>.

To achieve the same effect, methods like Xml.SetBold() and Xml.SetItalic() each open a temporary span with the desired property underneath the current node.

In addition, these methods return there parent node, so they can be concatenated with each other.

Context Manager support#

The standard way to add nodes to a DOM is this:

Xml body = story.Body;
Xml para = body.AddParagraph();  // add a paragraph
para.SetBold();  // text that follows will be bold
para.AddText("some bold text");
para.SetItalic();  // text that follows will additionally be italic
para.add_txt("this is bold and italic");
para.SetItalic(false).SetBold(false);  // all following text will be regular
para.AddText("regular text");

Methods that are flagged as “context managers” can conveniently be used in this way:

Xml body = story.Body;
Xml para = body.AddParagraph();
para.SetBold().AddText("some bold text");
para.SetItalic().AddText("this is bold and italic");
para.SetItalic(false).SetBold(false).AddText("regular text");
para.AddText("more regular text");