API:XML reference

From TheWarWiki

Jump to: navigation, search

Contents

Interfaces for WAR are created using a combination of Lua and XML code; typically the XML will define the layout and look of the interface, while the Lua code will determine the functionality of it. This page provides an overview of the XML side of things.

General interface XML wrapper

All interface XML files have a basic container format, inside of which other elements are placed (between the starting and ending Interface tags): 

<?xml version="1.0" encoding="UTF-8"?>
<Interface xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:noNamespaceSchemaLocation="../../Interface.xsd">

</Interface>

Basic container tags

Within the general wrapper, there are a couple of containers you might make use of, depending on what you're defining:

  • <Windows>...</Windows>
    The contents are a set of window templates which can be loaded into the interface. Most of what you'll find in a typical interface XML will be inside this container.
  • <Scripts>...</Scripts>
    Contains a set of Lua scripts which should be loaded when this XML file is loaded. Typically you'll only see 1-2 things inside this container at most in any given XML file.
  • <Assets>...</Assets>
    Asset declaration for loading textures and icons. These were working in beta, but are not working at release. Further research on these tags will be needed when they are fixed.

Loading Lua scripts from XML files

You can specify any number of Lua scripts that should be loaded along with the XML file when it is parsed. To do so, create a <Scripts></Scripts> container in the XML file, and inside it place one or more Script entries, like so: 

    <Scripts>
        <Script file="GenericLuaScript.lua" />
    </Scripts>

One thing to keep in mind is that the value for the file parameter is the path to the file from the base folder of the addon, so if you have YourAddonName\Sources, even if both the .xml and .lua files are in the Sources folder you'll still need to specify file="Sources\Whatever.lua" instead of just "Whatever.lua".

Alternatively, you can simply include all of your Lua scripts from the addon's .mod file, and never need to use the Scripts XML container at all.

Designing interfaces in XML

The top-level <Windows></Windows> container of the XML file is where the real nitty-gritty of interface specification is done. Below are listed the various tags that can be used and the paramaters they can have (as far as they are known). All tags are listed as just their beginning tag e.g. "<Window>". Assume that if you put anything inside a container, you will need a matching closing tag (e.g. "</Window>"), whereas if you don't need to put anything inside the tag container, you can just use the single-tag format of "<Window />".

General tags

<Interface>

  • Required param(s):
  • Optional param(s):
  • Allowed in:
The primary parent of the entire xml schema.

<Windows>

  • Required param(s):
  • Optional param(s):
  • Allowed in: <Interface>
The core Window collection element, in which all individual windows are built.

<Window>

  • Required param(s): name
  • Optional param(s): handleinput, skipinput, layer, sticky, savesettings, movable, popable, inherits
  • Allowed in: <Windows>
The basic window definition tag. Plain windows on their own are just invisible boxes.

<Size>

  • Required param(s):
  • Optional param(s):
  • Allowed in: <Window> or derivative
Size tags indicate the size of their parent element, typically via an <AbsPoint> tag contained within them to specify actual x and y values.

<AbsPoint>

  • Required param(s): x, y
  • Optional param(s):
  • Allowed in: <Size>, <Anchor>
AbsPoint tags specify x and y values for a few different tags that need them, such as <Size>.

<Anchors>

  • Required param(s):
  • Optional param(s):
  • Allowed in: <Window> or derivatives
The Anchors container contains a set of anchors that determines where the window is positioned on the game screen. A window can have one or two anchors; if it has one, then its size is generally fixed, whereas if it has two, it will resize to fit its anchors (handy for things such as a window that is attached to the side of another window).

<Anchor>

  • Required param(s): point
  • Optional param(s): relativePoint, relativeTo
  • Allowed in: <Anchors>
The Anchor tag specifies an actual anchor for the window containing its parent container. The relativeTo attribute, if included, specifies which window this anchor should be attached to (if not specified, the default is the parent of the window being anchored). The point attribute specifies where on the relativeTo window the anchor should be attached, and the relativePoint specifies where on the window being anchored should any offset be measured from. An Anchor tag can optionally contain an <AbsPoint> tag to specify the offset, otherwise an offset of (x=0, y=0) will be used.

A quick reference for the various components of an anchor is in picture form.

<EventHandlers>

  • Required param(s):
  • Optional param(s):
  • Allowed in: <Window> or derivative
Specifies a set of event handlers for the element that contains it, using <EventHandler> tags.

<EventHandler>

  • Required param(s): event, function
  • Optional param(s):
  • Allowed in: <EventHandlers>
Specifies a Lua function to provide functionality for a particular interface event triggered for this element. The event param should be set to the name of the event to handle, and the function param should be set to the fully-qualified (including any dot notation, if necessary, but not including parentheses) function name to call. The arguments that will be passed to the handler function are dependent on the event, and are not set in the XML file.

Examples 

               <EventHandler event="OnLButtonDown" function="LayoutEditor.OnControlFrameLButtonDown" />
               <EventHandler event="OnLButtonUp" function="LayoutEditor.OnControlFrameLButtonUp" />
               <EventHandler event="OnRButtonDown" function="LayoutEditor.OnControlFrameRButtonDown" />

Known valid events are: OnInitialize, OnInitializeCustomSettings, OnShutdown, OnUpdate, OnLButtonDown, OnLButtonUp, OnLButtonDblClk, OnRButtonDown, OnRButtonUp, OnRButtonDblClk, OnMButtonDown, OnMButtonUp, OnMButtonDblClk, OnMouseOver, OnMouseOverEnd, OnMouseDrag, OnMouseWheel, OnKeyEnter, OnKeyTab, OnKeyEscape, OnRawDeviceInput, OnGamepadInput, OnShown, OnHidden, OnTweenComplete, OnDock, OnUnDock, OnPositionTabs, OnSizeUpdated, OnSetTopDockWindow, OnSetMoving

<Sounds>

  • Required param(s):
  • Optional param(s):
  • Allowed in: <Window> or derivative
Specifies a set of sounds.

<Sound>

  • Required param(s): event, script
  • Optional param(s):
  • Allowed in: <Sounds>
Specifies a sound to play on a window event.

For example, 

  <Sound event="OnShown" script="Sound.Play( Sound.WINDOW_OPEN )" /> 
  <Sound event="OnHidden" script="Sound.Play( Sound.WINDOW_CLOSE )" />

See EventHandler for valid events

<TexDims>

  • Required param(s): x, y
  • Optional param(s):
  • Allowed in: <DynamicImage>
Specifies the size of a texture portion to use when displaying a texture.

<TexCoords>

  • Required param(s):
  • Optional param(s):
  • Allowed in: <Button>
Contains a set of coordinate definitions to specify where in the button's texture the various states of the button should be rendered from. This is specified via two specialized subtags, <Normal x="" y="" /> and <Pressed x="" y="" />.

<Color>

  • Required param(s): r, g, b, a
  • Optional param(s):
  • Allowed in: <Label>
Specifies a color in 32-bit format (0-255 red, 0-255 green, 0-255 blue, and 0-255 alpha transparency).

Script tags

<Scripts>

  • Required param(s):
  • Optional param(s):
  • Allowed in: <Interface>
The basis for script declarations within the xml, upon which scripts are based.

<Script>

  • Required param(s): file
  • Optional param(s):
  • Allowed in: <Scripts>
This is where scripts are listed for use with the EventHandlers throughout the xml file.

Visual Element tags

<CircleImage>

  • Required param(s): name
  • Optional param(s): textureScale, numsegments, texture, handleinput, popable, layer, slice, filtering, skipinput, sticky, savesettings, movable, inherits
  • Allowed in: <Windows>
The CircleImage element allows display of various images (textures) which can be changed on the fly. The displayed size of the image can be set with a <Size>, while the size of the portion of the specified texture that is use is specified via a <TexDims> tag. The CircleImage is present in the default PlayerWindow. A note regarding size and texture scale: the abs point in the size tag should reflect original size (namely x="38" y="38") multiplied by the 'texturescale' value in the CircleImage tag.

<DynamicImage>

  • Required param(s): name
  • Optional param(s): texture, slice, filtering, handleinput, skipinput, layer, sticky, savesettings, movable, popable, inherits
  • Allowed in: <Windows>
The DynamicImage element allows display of various images (textures) which can be changed on the fly. The displayed size of the image can be set with a <Size>, while the size of the portion of the specified texture that is use is specified via a <TexDims> tag.

<HorizontalResizeImage>

  • Required param(s): name
  • Optional param(s): texture, slice, filtering, handleinput, skipinput, layer, sticky, savesettings, movable, popable, inherits
  • Allowed in: <Windows>
Uses TexSlices to make a left, right, and several middle sections using small textures for a long bar.

<StatusBar>

  • Required param(s): name
  • Optional param(s): background, foreground, reverseFill, interpolate, handleinput, skipinput, layer, sticky, savesettings, movable, popable, inherits
  • Allowed in: <Windows>
Creates a basic status bar that will fill according to current and maximum values set for it via Lua API calls.

<Label>

  • Required param(s): name
  • Optional param(s): font, textalign, maxchars, autoresize, wordwrap, warnOnTextCropped, handleinput, skipinput, layer, sticky, savesettings, movable, popable, inherits
  • Allowed in: <Windows>
Defines a basic text label, the contents of which can be set via Lua API calls. Can contain <Size>, <Anchors>, and <Color> tags to specify those attributes.

<Button>

  • Required param(s): name
  • Optional param(s): font, backgroundtexture, texturescale, textalign, drawchildrenfirst, id, handleinput, skipinput, layer, sticky, savesettings, movable, popable, inherits
  • Allowed in: <Windows>
Creates a button which can visually respond to presses via mouse click.

<EditBox>

  • Required param(s): name
  • Optional param(s): id, maxchars, taborder, inherits
  • Allowed in: <Windows>
Creates a an edit box that can be used to input text for processing.

Asset tags

Assets are currently not functioning. They load textures, but display the pink 'no texture' in game. Information provided by default xml files.

<Assets>

  • Required param(s):
  • Optional param(s):
  • Allowed in: Interface
The primary tag for all assets, upon which each individual element is built.

<Icon>

  • Required param(s): id, texture, name
  • Optional param(s):
  • Allowed in: Assets
Definition of Icons, id is numeric, texture references a .dds file, name is a a string. Further documentation once assets are corrected will be needed.

<Texture>

  • Required param(s): name, file
  • Optional param(s):
  • Allowed in: <Assets>
Definition of a texture file. See also slice. Further documentation once assets are corrected will be needed.

<Slice>

  • Required param(s): id, left, top, width, height
  • Optional param(s):
  • Allowed in: <Texture>
For referencing pieces of a texture separately, to allow loading a single file for multiple uses. The id is the name used, the rest is self explanatory. Further documentation once assets are corrected will be needed.

Keywords

Keywords used in various tags, and their usage

Layer

  • Valid Param(s) = background, default, secondary, popup, overlay
Where an element is placed, three dimensionally, within the user interface. For instance, windows on the background layer will display behind the secondary layer. The order above is from "most backward" to "most front". Layers are relative to their parent.

To be continued...

This guide is not yet complete, and thus there may be many small (or large!) things missing from it. If you discover something that isn't here, add it!

This file of XML keywords could help you add to our knowledge.

Retrieved from "http://thewarwiki.com/wiki/API:XML_reference"
Personal tools