Lua XML Basics

[zgrssd]

I am trying to get the hang of UI XML and so far I am not getting good. So I think need to start with a lot more basic stuff.

The top element of all XML files must be the "<GuiXml>" Tag
The second tier must tbe the "<Controls>" Tag under wich you can define your actuall elements.

There seem to be at least 3 Container Elements (elements with a Controls child element):
GuiXML - the root of all XML files
TopLevelControl - For Windows. Is automatically added to the UI upon execution without needing to call it.
Control - for templates in particular. It also seems to be the only "Container" you can use at any level.


Data like the Dimensions, anchoring or fill mode are not listed as Atributes of the Element. Instead they are assigned via child elements called "Anchoring" or "Dimensions". Not sure how to call those class, "Child Atributes" perhaps?
Data like Backdrops (the background to be used) must be assigned as a Child of the Controls object that is itself asigned as child of the container. So the most basic Window XML looks somewhat like this:

<GuiXml>
    <Controls>
        <TopLevelControl name="testbedWindow">
            <Dimensions x="400" y="400" />
            <Anchor point="CENTER" />
            <Controls>
                <--Other Child elements like labels would go here too-->
                <Backdrop name="$(parent)BG" inherits="ZO_DefaultBackdrop" />
            </Controls>
        </TopLevelControl>
    </Controls>
</GuiXml>

Know Atributes:
name - (optional) a Reference to this element will be stored in the Global Variables with this name. This is nessesary if you want to access it from code behind directly. The '$(parent)[suffix]' Syntax allows you to name a Child based on the name of it's parent and a suffix.
inherits - Seems to allow high level behavior changes. A Control type Container where 'inherits="ZO_ScrollContainer"' is written, behaves as a Scroll Container (if the Content is bigger then the Containers dimension, a Scroll Bar appears).
hidden - boolean value. Determines if the element is hidden by default. Usefull in particular for TopLevelControls that should be initialised automatically, but not shown automatically (there but hidden)
font, text - common for Elements that show Text, be it labels, Editboxes.
virtual - if true, this is a virtual Element. It is used as template for teh "CreateFromVirtual" function. Is not put into the global namespace, but instead used as String Indentifier for the "CreateFromVirtual" function.


Questions:
Wich Elements can all have a "Controls" child element?
Wich common GUI Values must be assigned as atributes, wich as Direct level child element and wich as Controls Child Element?

[merlight]

Backdrop is a type of control, that's why it goes under <Controls>.

These are all control type constants, each has corresponding XML element:

ControlTypes
    CT_CONTROL = 0,
    CT_LABEL = 1,
    CT_DEBUGTEXT = 2,
    CT_TEXTURE = 3,
    CT_TOPLEVELCONTROL = 4,
    CT_ROOT_WINDOW = 5,
    CT_TEXTBUFFER = 6,
    CT_BUTTON = 7,
    CT_STATUSBAR = 8,
    CT_EDITBOX = 9,
    CT_COOLDOWN = 10,
    CT_TOOLTIP = 11,
    CT_SCROLL = 12,
    CT_SLIDER = 13,
    CT_BACKDROP = 14,
    CT_MAPDISPLAY = 15,
    CT_COLORSELECT = 16,
    CT_LINE = 17,
    CT_BROWSER = 18,
    CT_COMPASS = 19,
    CT_TEXTURECOMPOSITE = 20,

[zgrssd]

So iriterating what I said before on teh other thread, there are three basic types of UI XML Elements:

Property Children:
XML Child Elementes with the sole purpose of defining stuff about thier parent. They don't inherit from control, and are mostly structure like things. But they can have short inheritance chains and functions as well.
The Property Children every Control can have is preset.

Controls
Consisting of Control and every UI Element that inherits it.
They are all containers on top of being stand alone controls, having a "Controls" Property Child with the purpose of containing further Controls.

Atributes:
There are also conventinal XML atributes. They are always of type string.
Overall Property Children seem a lot more common then classical Atributes.

inherits & virtual:
A control can inherit values from every virtual control that was defined in xml.
Virtual controls do not appear in the global table, but propably are defined/listed in some subtable.
Only virtual controls can be inherited, but every control can be made virtual. There might be limitations that only elemenst of the same base type can inherit (a Label can only inherit from a virtual Label), but that is not confirmed.

[merlight]

Originally Posted by zgrssd Atributes: There are also conventinal XML atributes. They are always of type string.

In XML it always looks like a string, but interpretation may vary depending on the attribute. Some examples:

offsetX="-5" ... used in <Anchor>, this attribute probably undergoes ivalue = tonumber(value) before being passed to control:SetAnchor(...)

point="LEFT" ... named constant, not sure whether point="2" (since LEFT == 2) would work; but I still think it's converted to integer at some point, ivalue = _G[value]

color="3a6b9c" ... hex color code, may be parsed by a, r, g, b = ConvertHTMLColorToFloatValues(value)

color="INTERFACE_COLOR_TYPE_ALLIANCE:ALLIANCE_DAGGERFALL_COVENANT" ... another way of specifying color; the conversion would look something like:

local colorType, colorIndex = value:match("(%w+):(%w+)")
local r, g, b, a = GetInterfaceColor(colorType, colorIndex)

I'm not saying these conversions are done in Lua code, I only tried to illustrate how they'd be done in Lua.

[farangkao]

Maybe not very well known is the "Virtual/Inherits" Mechanism.

Basically it's used to create a template and use that one instead of repeating the same xml over and over

Here an example:

<!-- Virtual Controls -->
    <Button alpha="0.7" name="MB_Virtual_Button" virtual="true"> 
        <Anchor point="TOPRIGHT" relativeTo="MBUI_Container" relativePoint="TOPRIGHT" offsetX="-40" offsetY="0" />
        <Dimensions x="32" y="32" />   
        <OnMouseExit>
             ClearTooltip(InformationTooltip)
        </OnMouseExit>
    </Button>

This declares a virtual Control (means which is not used by itself) ,which already
predefines certain aspects ,even incl. programming logic ,as you can see on the "OnMouseExit" part.

Now later on in the XML i make use of the virtual template like this:

<Button name="$(parent)Close" inherits="MB_Virtual_Button">
                <OnMouseEnter>
                    InitializeTooltip(InformationTooltip, self, TOPRIGHT)
                    SetTooltipText(InformationTooltip, "Close")
                </OnMouseEnter>
        
                 <OnClicked>
                     MBUI_Container:SetHidden(true)
                     MB.PreviousButtonClicked=nil
                     MB.LastButtonClicked=nil
                 </OnClicked>
                 <Textures normal="EsoUI/Art/Buttons/decline_down.dds"                          
                   mouseOver="EsoUI/Art/Buttons/decline_over.dds" />
   </Button>

it then takes over the definition of "Alpha" ,"Dimensions" and "OnMouseExit" .
Meaning that the Button created has all the properties inherited by it's template.

By the way on the Wiki is clearly defined which Child are allowed for the Element "Control":
http://wiki.esoui.com/UI_XML#Control

Also i might add, if you use ZBS with my Plugin, there is some support for GuiXML build in: