Difference between revisions of "Category:Oblivion XML"

From the Oblivion ConstructionSet Wiki
Jump to navigation Jump to search
imported>JRoush
imported>JRoush
(Rebranding XML "traits" as "attributes"; cleaned up example code)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=== What is XML? ===
=== What is XML? ===
XML stands for [http://en.wikipedia.org/wiki/XML eXtensible Markup Language], a generic syntax used to encode a series of parent-child relationships.  An XML document contains a hierarchy of ''elements'', each described by a set of ''traits''.   
XML stands for [http://en.wikipedia.org/wiki/XML eXtensible Markup Language], a generic syntax used to encode a series of parent-child relationships.  An XML document contains a hierarchy of ''elements'', each described by a set of ''attributes''.   
In Oblivion, XML is used to encode the user interface.  Every button, box, piece of text, and colorful widget in a menu (or the HUD) is an element in that menus XML document.  And each of these elements has ''child'' elements that describe it's color, size, graphical texture, location, etc.
In Oblivion, XML is used to encode the user interface.  Every button, box, piece of text, and colorful widget in a menu (or the HUD) is an element in that menus XML document.  And each of these elements has ''child'' elements that describe it's color, size, graphical texture, location, etc.


Line 12: Line 12:
Or it might be another xml element:
Or it might be another xml element:
  <image> <text> </text> </image>
  <image> <text> </text> </image>
In this case, the "inner" element is the ''child'' of the outer element.  An element can generally have more than one child elements, and those child elements might have children of their own, and so on.  This is what creates the hierarchy that is characteristic of XML.
In this case, the "inner" element is the ''child'' of the outer element.  An element can have more than one child, and those children might have children of their own, and so on.  This is what creates the hierarchy that is characteristic of XML.


If an element has no children, like the first example above, then the opening/closing tag syntax can be abbreviated to:
If an element has no children, like the first example above, then the opening/closing tag syntax can be abbreviated to:
  <text />
  <text />


Element ''traits'' are written as name/value pairs in the opening tag:
Element ''attributes'' are written as name/value pairs in the opening tag:
  <image traitname="traitvalue"> </image>
  <image attributeName="attributeValue"> </image>
Traits are an essential part of XML, in that they can refine & control elements, and differentiate elements of the same type from one another.  '''Note''', though, that Oblivion only recognizes a few traits, and instead prefers to refine & control elements using ''child elements''.  See the next section, on [[#Oblivion XML Schema|Oblivion XML Schema]] for more details.
Attributes are an essential part of XML - they refine & control elements, and differentiate elements of the same type from one another.  Oblivion only recognizes a few attributes, however, using child elements to refine & control instead.  See the next section, on [[#Oblivion XML Schema|Oblivion XML Schema]] for more details.


''Comments'' can be added to the code by enclosing them with "&lt;!--"  and "--&gt;":
''Comments'' can be added by enclosing them with "&lt;!--"  and "--&gt;":
  &lt;!-- this is a comment --&gt;
  &lt;!-- this is a comment --&gt;


Line 27: Line 27:


=== Oblivion XML Schema ===
=== Oblivion XML Schema ===
  &lt;!-- An example of an '[[Object Element#Image|Image]]' Object Element --&gt;
  &lt;!--  
<image name="MyImage">    &lt;!-- This image has it's [[Trait|'name' trait]] set to 'MyImage', --&gt;
  An example of an '[[Object Element#Image|Image]]' Object Element.
    <height> 10 </height>  &lt;!-- and it's [[Property Element#Sizeable|'height' property]] set to 10 pixels. --&gt;
  This image has it's [[XML Attribute|'name' attribute]] set to 'MyImage', and it's [[Property Element#Sizeable|'height' property]] set to
    <width>                &lt;!-- It's [[Property Element#Sizeable|width]] is set to twice it's height --&gt;
  10 pixels. It's [[Property Element#Sizeable|width]] is set to twice it's height using the '[[Operator Element#Copy Operator|copy]]' and '[[Operator Element#Algebraic Operators|mul]]' operators
--&gt;
<image name="MyImage">   
    <height> 10 </height> 
    <width>               
       <copy src="MyImage" trait="height" />  
       <copy src="MyImage" trait="height" />  
       <mul> 2 </mul>      &lt;!-- using the '[[Operator Element#Copy Operator|copy]]' and '[[Operator Element#Algebraic Operators|mul]]' operators --&gt;
       <mul> 2 </mul>       
     </width>
     </width>
  </image>
  </image>
Line 38: Line 42:
XML is a general syntax - the meaning of a given element depends entirely on the program parsing the file.   
XML is a general syntax - the meaning of a given element depends entirely on the program parsing the file.   


The Oblivion XML parser divides elements into three basic categories.  They don't really have official names, so the names chosen below ("Object", "Property", and "Operator" Elements) were chosen just for this page.  This is important to remember when using the OBSE UI functions, which tend to refer to Property Elements as "Traits", even though they are not, strictly speaking, XML traits.
The Oblivion XML parser divides elements into three basic categories.  They don't really have official names, so the names chosen below ("Object", "Property", and "Operator" Elements) were chosen just for this wiki.


[[Object Element|"Object" Elements]] define actual objects in the menu, such as buttons, text, images, etc.  There are only a few different kinds of object elements, but they are used repeatedly to create the complex menu structures.
[[Object Element|"Object" Elements]] define actual objects in the menu, such as buttons, text, images, etc.  There are only a few different kinds of object elements, but they are used repeatedly to create the complex menu structures.
Line 52: Line 56:


It's also possible to insert new element types into a menu document.  Oblivion will
It's also possible to insert new element types into a menu document.  Oblivion will
interpret any element whose type it doesn't recognize as a Property Element.  Such elements obviously won't have any built-in affects, but they can be referred to by name from Operator Elements and OBSE script functions, and may contain Operator Elements as children.  It is common to break up long formulas by inventing one of these "psuedo-Property" elements to intermediate values.
interpret any element type that starts with an underscore as a 'custom' Property Element.  Such elements obviously won't have any built-in affects, but they can be referred to by name from Operator Elements and OBSE script functions, and may contain Operator Elements as children.  It is common to break up long formulas by inventing one of these custom elements to hold intermediate values.
  &lt;!--
  Use a custom property '_GreyColor' to set a common
  intensity level for all three color properties
  --&gt;
  <text name="sometext">
    <_GreyColor> 255 </_GreyColor>
    <string> This is some text </string>
    <red> <copy src="me()" trait="_GreyColor"/> </red>
    <blue> <copy src="me()" trait="_GreyColor"/> </blue>
    <green> <copy src="me()" trait="_GreyColor"/> </green>
</text>


Because most aspects of menu objects like buttons, icons, etc. are controlled by their Property Elements, Oblivion doesn't make much use of conventional XML traits.  However, the three [[Trait]]s it that are used ("name", "src", and "trait") are essential to the use of Operator and Include elements.  See those pages for more detail.
Because most aspects of menu objects like buttons, icons, etc. are controlled by their Property Elements, Oblivion doesn't make much use of conventional XML attributes.  However, the three [[XML Attribute|attributes]] that are recognized ("name", "src", and "trait") are essential for the use of [[Operator Element|Operators]].


=== Oblivion Menu Files ===
=== Oblivion Menu Files ===
Menu xml data is stored in the ''Oblivion\Data\Menus'' directory.  Each menu is stored in it's own file.  Oblivion reloads a menu from disk every time it is opened, so changes to the file can be seen by closing and re-opening the menu - a very useful trick for editing.  Note, however, that some menus are never closed (e.g. the HUD).  These menus can be reloaded in game using "Reload ''menuname''" [[:Category:Console Functions|console function]].
Menu xml data is stored in the ''Oblivion\Data\Menus'' directory.  Each menu is stored in it's own file.  Oblivion reloads a menu from disk every time it is opened, so changes to the file can be seen by closing and re-opening the menu - a very useful trick for editing.  Some menus never close (e.g. the HUD) - these can be reloaded in game using "Reload ''menuname''" [[:Category:Console Functions|console function]].

Latest revision as of 14:59, 3 May 2011

What is XML?[edit | edit source]

XML stands for eXtensible Markup Language, a generic syntax used to encode a series of parent-child relationships. An XML document contains a hierarchy of elements, each described by a set of attributes. In Oblivion, XML is used to encode the user interface. Every button, box, piece of text, and colorful widget in a menu (or the HUD) is an element in that menus XML document. And each of these elements has child elements that describe it's color, size, graphical texture, location, etc.

General Syntax[edit | edit source]

XML syntax is largely based on HTML syntax. As in HTML, an XML element is defined by opening and closing tags, which are just the type of the element enclosed by angle brackets. For example, the following xml code defines a Text element:

<text> </text>

Note that the closing tag is denoted by slash.

Anything that appears between the opening and closing tags of an element is considered the contents of that element. This might be raw text or numbers:

<string> This 'string' element contains this text. </string>

Or it might be another xml element:

<image> <text> </text> </image>

In this case, the "inner" element is the child of the outer element. An element can have more than one child, and those children might have children of their own, and so on. This is what creates the hierarchy that is characteristic of XML.

If an element has no children, like the first example above, then the opening/closing tag syntax can be abbreviated to:

<text />

Element attributes are written as name/value pairs in the opening tag:

<image attributeName="attributeValue"> </image>

Attributes are an essential part of XML - they refine & control elements, and differentiate elements of the same type from one another. Oblivion only recognizes a few attributes, however, using child elements to refine & control instead. See the next section, on Oblivion XML Schema for more details.

Comments can be added by enclosing them with "<!--" and "-->":

<!-- this is a comment -->

To learn more about XML syntax, read the complete specification or one of the tutorials provided by the World Wide Web Consortium.

Oblivion XML Schema[edit | edit source]

<!-- 
  An example of an 'Image' Object Element.
  This image has it's 'name' attribute set to 'MyImage', and it's 'height' property set to
  10 pixels.  It's width is set to twice it's height using the 'copy' and 'mul' operators 
-->
<image name="MyImage">     
   <height> 10 </height>   
   <width>                 
      <copy src="MyImage" trait="height" /> 
      <mul> 2 </mul>       
   </width>
</image>

XML is a general syntax - the meaning of a given element depends entirely on the program parsing the file.

The Oblivion XML parser divides elements into three basic categories. They don't really have official names, so the names chosen below ("Object", "Property", and "Operator" Elements) were chosen just for this wiki.

"Object" Elements define actual objects in the menu, such as buttons, text, images, etc. There are only a few different kinds of object elements, but they are used repeatedly to create the complex menu structures.

"Property" Elements are always children of Object Elements, defining things like the position, color, transparency, etc. of their parent. For example, an <image> object element might have <width> and <height> elements as children, which Oblivion will use to determine the size of the displayed image. Different Object Elements can have different sets of Property Elements.

Property elements can have literal text or numeric values, written directly into the xml code. However, they can instead contain arrangements of "Operator" Elements as children. These Operator Elements basically describe simple mathematical formulas, which Oblivion uses to calculate the value of the Property Element in real time. This concept is what makes the Oblivion XML schema so powerful and customizable - and confusing.

There are also a few special elements that don't fit into these three categories. The most common is the Include Element. It's use is similar to the include statement in C-style programming languages - it allows the menu designer to insert xml code from another file.

It's also possible to insert new element types into a menu document. Oblivion will interpret any element type that starts with an underscore as a 'custom' Property Element. Such elements obviously won't have any built-in affects, but they can be referred to by name from Operator Elements and OBSE script functions, and may contain Operator Elements as children. It is common to break up long formulas by inventing one of these custom elements to hold intermediate values.

 <!-- 
  Use a custom property '_GreyColor' to set a common
  intensity level for all three color properties
 -->
 <text name="sometext"> 
   <_GreyColor> 255 </_GreyColor>
   <string> This is some text </string>
   <red> <copy src="me()" trait="_GreyColor"/> </red>
   <blue> <copy src="me()" trait="_GreyColor"/> </blue>
   <green> <copy src="me()" trait="_GreyColor"/> </green>
</text>

Because most aspects of menu objects like buttons, icons, etc. are controlled by their Property Elements, Oblivion doesn't make much use of conventional XML attributes. However, the three attributes that are recognized ("name", "src", and "trait") are essential for the use of Operators.

Oblivion Menu Files[edit | edit source]

Menu xml data is stored in the Oblivion\Data\Menus directory. Each menu is stored in it's own file. Oblivion reloads a menu from disk every time it is opened, so changes to the file can be seen by closing and re-opening the menu - a very useful trick for editing. Some menus never close (e.g. the HUD) - these can be reloaded in game using "Reload menuname" console function.

Subcategories

This category has only the following subcategory.

U

Pages in category "Oblivion XML"

The following 7 pages are in this category, out of 7 total.