XML Nodes | Boris FX

< Previous | Contents | Manuals Home | Boris FX | Next >

‌XML Nodes

You can read, manipulate, and write XML files using operations built into SynthEyes. XML files are widely used to communicate between applications in a relatively standard way, including as part of P2 file handling, and also used for the entire scene storage for some applications, such as Motion.

XML files represent large trees of data; Sizzle has kind of value called an XML Node that can represent the leaves of the tree, the junctions and branches, and root of the tree. For more information on XML files please see the extensive reference literature online.

Consider the following example.

</VideoIndex>

</Video>

The root tag is Video. It has one attribute, ValidAudioFlag, with the value false. Video has five child tags, Codec, FrameRate, StartTimecode, AspectRatio, and VideoIndex. The AspectRatio tag is a simple leaf, containing only the value 16:9. The VideoIndex tag has no value, but has two children, StartByteOffset and DataSize. Typical files are much more complex, but use these basic elements.

Create XML nodes using Scene.ReadXMLFile(filename) to read an existing file, or Scene.EmptyXMLNode(). The XMLNodes do “&” encoding on read and write, you do not have to think about it as you work on the trees.

Note that if the file starts with a “<?xml …. ?>” line, it will appear to be an enclosing super-root node; you can access its attributes if you like.

If you have read the XML and put it in a variable called tree, you could access the aspect ratio with tree.Video.AspectRatio.value to obtain the text string “16:9”, which you might change to “4:3”, say. You can save a sub-tree, for example info=tree.Video.VideoIndex and then refer to info.StartByteOffset.value. Notice that you need to refer to the “.value” of nodes, but when you talk about an attribute you do not, because there is no question whether it is the value or sub- tree that you are talking about. Also, in XML, you must match the case exactly, VideoIndex is NOT the same as videoIndex.

A tag may appear many times as a child for the same node, so you can use the index-based accessors to work your way through a file. The tree elements are reference-counted, so you can assign a sub-tree to several places

in the same file if you want to confuse yourself. The equals test checks for whether the same identical tree node is being referred to, not to whether the contents of the two trees are the same.

.AddAttrib(name, value) Add a new name/value attribute pair into the

tag

.AddChild(subtree) Adds a new child subtree (at the end)

.AddChild(name, value) Add a simple leaf node, and return it so you

can mess with it some more (ie to add it’s own children)

.AttribName(index) The name of the index’th attribute

.AttribValue(index) The value of the index’th attribute

.Child(index) Returns the index’th child subtree of the node.

.ChildName(index) Returns the tag name of the index’th child subtree

.Clone() Make an identical but separate copy of the XMLNode

.DeleteAttrib(index) Delete the index’th attribute

.DeleteChild(index) Remove the index’th child subtree as a child.

It will not be removed until there are no remaining references to it

.doctype The DOCTYPE information (usually) at the top, without its enclosing “<!” and “>” Root node only.

.FindAttrib(name) Returns the index of the first attribute with the given name, or zero if there is none.

.FindChild(name) Returns the index of the first child with the given tag name. Returns 0 if there is none. Note that it is common for there to be many children with the same name.

.InsertAttrib(index, name, value) Insert a new name/value attribute pair in front

of the index’th existing attribute.

.InsertChild(index, subtree) Insert the subtree as a new child, before the

index’th existing child.

.NAttrib() Number of attributes inside the tag

.NChild() Number of children inside the contents of the tab

.ReadFile(filename) Reads the given file into the current (empty)

node. Returns 1 on success, 0 on failure.

.SetAttribName(index, name) Set the name of the index’th attribute to name

.SetAttribValue(index, value) Set the value of the index’th attribute to value

.SetChild(index, subtree) Sets the index’th child to be the given

subtree, replacing the existing subtree

.tag The primary XML tag name of this node

.value The string value of the node

.WriteFile(filename) Using this node as the root, write a new XML

file. Returns 1 on success, 0 on failure. Beware of over-writing other important files!

* Functions above marked in red bold with an asterisk* are available only in the Pro version.

< Previous | Contents | Manuals Home | Boris FX | Next >