WoW:XML/KeyValue

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ XML properties

← XML UI ← XML properties < KeyValue

A KeyValue element adds an arbitrary variable to the Lua runtime UI object. This mechanism is similar to the Attribute element, and to the parentKey, relativeKey, and targetKey XML attributes, as these all add arbitrary member variables to Lua objects from FrameXML. See also Attribute.

Inheritance

Inherited by: none, Inherits: none, Defined in: LayoutFrame > KeyValues

Elements

none

Attributes

• key (any) - Lua key, usually a name, for the attribute
• value (any) - the actual value for the attribute. will be converted to the Lua type defined by type at runtime
• keyType (KEYVALUETYPE) - the Lua type for the key. Default is 'string'.
• type (KEYVALUETYPE) - the Lua type for the value. Default is 'string'.

Summary

An KeyValue element defines a Lua runtime object variable for the XML element. KeyValue elements are designed to allow inheriting templates to override the final runtime value of any base template for the same key. Setting arbitrary frame variables through XML lessens the need for extra anonymous 'OnLoad' functions, and a lot complexity in trying to call overridden base templates 'OnLoad' functions afterwards.

Example

<Frame name="MyFrame">
  <KeyValues>
    <KeyValue key="myvar" value="0" type="number"/>
  </KeyValues>
</Frame>

This example will set a variable named 'myvar' with a number value of '0', when the frame is created.

Notes

• Required values - both 'key' and 'value' must be set to at least "" (empty string), unless the corresponding 'type' or 'keyType' is set to 'nil'. If 'key' is not set then the element ends up being ignored, regardless of the other attributes, and if 'value' is not set then the 'key' member in frame ends up being set to 'nil' regardless of any other attributes or inherited values.
• 'number' type - if 'type' or 'keyType' is 'number' and corresponding 'value' or 'key' is "" (empty string), then result is 0, but if 'value' or 'key' is 'nil' then result is 'nil'. Number can use used as key to allow regular table indexed values in UI Lua object.
• 'nil' type - if 'keyType' or 'type' set to 'nil' any corresponding 'key' or 'value' attribute to be ignored, but not cause an error. Additionally, for the 'key' attribute, setting 'nil' would be as though 'frame[nil] = "value"' had been called for 'value' attribute. For 'type' setting 'nil' would be as though 'frame["key"] = nil' had been called and is useful for overriding previous inherited value to 'nil'.
• 'global' type - if 'keyType' or 'type' set to 'global', the corresponding 'key' or 'value' will be used as key to look up a up a value from the global _G[] scope, as available before frame load time, and the result of that used instead. For the 'key' attribute, setting 'global' would be as though 'frame[_G["key"]] = "value"' had been called, and for 'value' setting 'global' would be as though 'frame["key"] = _G["value"]' had been called, and can be useful for setting values based on global language specific strings.