diff --git a/docs/API.md b/docs/API.md index e0746584..bd9c599b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -20736,7 +20736,7 @@ local info = C_XMLUtil.GetTemplateInfo("StatFrameTemplate") |---|---|---| | `type` | string | The template's frame type — its XML element tag (`"Frame"`, `"Button"`, …). | | `width` / `height` | number | The size **statically declared on the template itself** via a `` element, or `0` if it declares none (including when the size comes from an inherited template rather than a direct ``). | -| `keyValues` | table | Always an **empty table** — the XML schema has no `` element, so no template can carry key/value pairs. Present for API parity. | +| `keyValues` | table | The template's own [``](#keyvalues-in-xml) entries, in file order. Each entry is `{ key, keyType, type, value }`, with the text as written in the file. `keyType` and `type` are `"string"` when the file leaves them out. Entries from inherited templates are not included. The table is empty when the template has no entries. | | `inherits` | string? | The template's `inherits=` attribute (a comma-delimited list), or `nil` if it inherits nothing. | Lookup is by name through the engine's own template registry — the same @@ -20807,6 +20807,50 @@ already sees them, and a `parentKey` inside a virtual template is set on every frame built from it. A button's `` works the same way. +### `KeyValues` in XML + +A `` element sets fields on the Lua table of the element that +holds it. Each `` inside it is the same as `object[key] = value`: + +```xml + + + + + + + + print(this.layoutIndex, this.title, this.tooltipFrame:GetName()) + + +``` + +Frames, textures, font strings, `` and animation elements +can hold a `` element. + +`type` sets how `value` is read. `keyType` sets how `key` is read. Both +are `string` if you leave them out: + +| Type | Result | +|---|---| +| `string` | The text as written. | +| `number` | The text as a number. | +| `boolean` | `true` if the text starts with `t`, `y` or a digit from `1` to `9` (any case), or is `on` or `enabled`. Otherwise `false`. | +| `nil` | `nil`. This type clears a field that a template set. | +| `global` | The global variable with that name, `_G[value]`. | + +Numbers keep about seven significant digits, so integers up to 16777216 +are exact. + +A template's entries apply first, so an element's own entries replace +entries with the same key. The fields are set before `OnLoad` runs, and a +`` element inside a virtual template applies to every frame +built from it. A `global` value reads the global when the element loads, so +the global must exist by then. + +If an entry has no `key`, has no `value`, or has an unknown type, +`FrameXML.log` gets a warning and the entry is skipped. + ### Masks in XML A `` element takes a `mask` attribute. It is the same as diff --git a/src/animation/Xml.cpp b/src/animation/Xml.cpp index e51197b4..5367ae05 100644 --- a/src/animation/Xml.cpp +++ b/src/animation/Xml.cpp @@ -25,6 +25,7 @@ #include "Offsets.h" #include "baselib/Ascii.h" #include "xml/FrameLoad.h" +#include "xml/KeyValues.h" #include #include @@ -102,6 +103,17 @@ void LoadScripts(Object *object, const void *node) { } } +// on a group or an animation, as on later clients' schema. +void LoadKeyValues(Object *object, const void *node, void *status) { + void *L = Game::Lua::State(); + if (L == nullptr) + return; + const int top = Game::Lua::GetTop(L); + Push(L, object); + ::Xml::KeyValues::Apply(L, top + 1, node, status, object->DisplayName()); + Game::Lua::SetTop(L, top); +} + // LoadXML_AnimOrigin: . void LoadOrigin(Anim *anim, const void *node) { const void *origin = FindChild(node, "Origin"); @@ -176,6 +188,7 @@ void LoadGroup(Group *group, const void *node, void *status) { group->initialOffsetY = y; } LoadScripts(group, node); + LoadKeyValues(group, node, status); LoadAnimChildren(group, node, status); } @@ -255,6 +268,7 @@ void LoadAnim(Anim *anim, const void *node, void *status) { anim->order = value < 0 ? 0 : (value > 99 ? 99 : value); } LoadScripts(anim, node); + LoadKeyValues(anim, node, status); // The subclasses' reads after the base. // CSimpleAlphaAnim::LoadXML sets the change, 0 when it is missing. diff --git a/src/xml/KeyValues.cpp b/src/xml/KeyValues.cpp new file mode 100644 index 00000000..17819efa --- /dev/null +++ b/src/xml/KeyValues.cpp @@ -0,0 +1,182 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU General Public License as published by the Free Software Foundation, either +// version 3 of the License, or (at your option) any later version. +// +// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY +// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE. See the GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License along with +// ClassicAPI. If not, see . + +// `` on XML elements, the later-client way to set fields on an +// element's Lua table at load time: +// +// +// +// +// +// +// +// +// Each entry is `object[key] = value`. `type` and `keyType` (default +// "string") are one of nil / boolean / number / string / global, the later +// clients' KEYVALUETYPE; "global" is `_G[text]`. Booleans and numbers go +// through the same loader helpers as `` (FUN_XML_ATTR_TO_BOOL, +// FUN_SSTR_TO_FLOAT). +// +// The schema allows it on every layout element and on animation groups and +// animations. Frames are read here, through the shared Xml::FrameLoad +// observer; textures and font strings from their loader co-hooks in +// Xml::ParentKey; groups and animations from Animation::Xml. Every one of +// those runs once per inherited template node before the element's own node, +// so a template's values are set first and the element's own win, and all of +// them run before the builder's finalize, so OnLoad sees the fields. + +#include "xml/KeyValues.h" + +#include "Game.h" +#include "Offsets.h" +#include "baselib/Ascii.h" +#include "xml/FrameLoad.h" + +namespace Xml::KeyValues { + +namespace { + +enum class Kind { Nil, Boolean, Number, String, Global, Invalid }; + +// A missing type is the schema's default, "string". +Kind KindOf(const char *type) { + if (type == nullptr || Ascii::EqualCI(type, "string")) + return Kind::String; + if (Ascii::EqualCI(type, "nil")) + return Kind::Nil; + if (Ascii::EqualCI(type, "boolean")) + return Kind::Boolean; + if (Ascii::EqualCI(type, "number")) + return Kind::Number; + if (Ascii::EqualCI(type, "global")) + return Kind::Global; + return Kind::Invalid; +} + +void Push(void *L, Kind kind, const char *text) { + using ToBool_t = int(__fastcall *)(const char *); + using ToFloat_t = float(__stdcall *)(const char *); + switch (kind) { + case Kind::Boolean: + Game::Lua::PushBool(L, reinterpret_cast(Offsets::FUN_XML_ATTR_TO_BOOL)(text) != 0); + break; + case Kind::Number: + Game::Lua::PushNumber(L, reinterpret_cast(Offsets::FUN_SSTR_TO_FLOAT)(text)); + break; + case Kind::String: + Game::Lua::PushString(L, text); + break; + case Kind::Global: + Game::Lua::PushString(L, text); + Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX); + break; + default: + Game::Lua::PushNil(L); + break; + } +} + +const void *FindKeyValues(const void *node) { + for (const void *c = FirstChild(node); c != nullptr; c = NextSibling(c)) + if (TagIs(c, "KeyValues")) + return c; + return nullptr; +} + +} // namespace + +void Apply(void *L, int index, const void *node, void *status, const char *owner) { + const void *keyValues = FindKeyValues(node); + if (keyValues == nullptr) + return; + const int top = Game::Lua::GetTop(L); + for (const void *e = FirstChild(keyValues); e != nullptr; e = NextSibling(e)) { + if (!TagIs(e, "KeyValue")) { + Warn(status, "%s: Unknown KeyValues element %s", owner, Tag(e)); + continue; + } + const char *key = Attr(e, "key"); + if (key == nullptr) { + Warn(status, "%s: KeyValue element missing key", owner); + continue; + } + const char *keyTypeName = Attr(e, "keyType"); + const char *typeName = Attr(e, "type"); + const Kind keyKind = KindOf(keyTypeName); + const Kind kind = KindOf(typeName); + if (keyKind == Kind::Invalid || kind == Kind::Invalid) { + Warn(status, "%s: KeyValue %s has unknown type %s", owner, key, + keyKind == Kind::Invalid ? keyTypeName : typeName); + continue; + } + const char *value = Attr(e, "value"); + if (value == nullptr && kind != Kind::Nil) { + Warn(status, "%s: KeyValue %s missing value", owner, key); + continue; + } + + Push(L, keyKind, key); // [key] + if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_NIL) { + // A nil key would raise from SetTable; nothing can be stored. + Warn(status, "%s: KeyValue %s has a nil key", owner, key); + Game::Lua::SetTop(L, top); + continue; + } + Push(L, kind, value); // [key, value] + Game::Lua::SetTable(L, index); // object[key] = value + Game::Lua::SetTop(L, top); + } +} + +void ApplyToRegion(void *object, const void *node, void *status) { + if (FindKeyValues(node) == nullptr) + return; + void *L = Game::Lua::State(); + if (L == nullptr) + return; + const int top = Game::Lua::GetTop(L); + if (PushWrapper(L, object)) + Apply(L, top + 1, node, status, Game::Lua::ObjectDisplayName(object)); + Game::Lua::SetTop(L, top); +} + +void PushInfo(void *L, const void *node) { + Game::Lua::NewTable(L); // [list] + const void *keyValues = FindKeyValues(node); + if (keyValues == nullptr) + return; + int n = 0; + for (const void *e = FirstChild(keyValues); e != nullptr; e = NextSibling(e)) { + const char *key = Attr(e, "key"); + if (!TagIs(e, "KeyValue") || key == nullptr) + continue; + const char *keyType = Attr(e, "keyType"); + const char *type = Attr(e, "type"); + const char *value = Attr(e, "value"); + Game::Lua::PushNumber(L, static_cast(++n)); // [list, n] + Game::Lua::NewTable(L); // [list, n, entry] + Game::Lua::SetFieldString(L, "key", key); + Game::Lua::SetFieldString(L, "keyType", keyType != nullptr ? keyType : "string"); + Game::Lua::SetFieldString(L, "type", type != nullptr ? type : "string"); + Game::Lua::SetFieldString(L, "value", value != nullptr ? value : ""); + Game::Lua::SetTable(L, -3); // list[n] = entry + } +} + +namespace { + +const FrameLoad::AutoSubscribe _frameNode{&ApplyToRegion}; + +} // namespace + +} // namespace Xml::KeyValues diff --git a/src/xml/KeyValues.h b/src/xml/KeyValues.h new file mode 100644 index 00000000..b6a6da50 --- /dev/null +++ b/src/xml/KeyValues.h @@ -0,0 +1,32 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU General Public License as published by the Free Software Foundation, either +// version 3 of the License, or (at your option) any later version. +// +// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY +// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE. See the GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License along with +// ClassicAPI. If not, see . + +#pragma once + +// `` on XML elements — see KeyValues.cpp. + +namespace Xml::KeyValues { + +// Sets each entry of `node` on the Lua table at stack index +// `index`. `owner` names the element in load warnings. +void Apply(void *L, int index, const void *node, void *status, const char *owner); + +// Apply() for a frame, texture or font string: pushes the object's wrapper +// only when `node` has a child. +void ApplyToRegion(void *object, const void *node, void *status); + +// Pushes `node`'s own entries as an array of { key, keyType, type, value } +// (C_XMLUtil.GetTemplateInfo's keyValues), the strings as written. +void PushInfo(void *L, const void *node); + +} // namespace Xml::KeyValues diff --git a/src/xml/ParentKey.cpp b/src/xml/ParentKey.cpp index ecabb0ae..b042b77d 100644 --- a/src/xml/ParentKey.cpp +++ b/src/xml/ParentKey.cpp @@ -70,6 +70,9 @@ // for that state (SetTextFontObject / SetHighlightFontObject / // SetDisabledFontObject) with `_G[style]`. // +// The texture and font string loaders also apply +// (Xml::KeyValues, which reads frames itself). +// // Every loader also loads an child (Animation::Xml), before the // builder finalizes, so OnLoad sees the groups. // @@ -82,6 +85,7 @@ #include "Offsets.h" #include "animation/Xml.h" #include "texture/Mask.h" +#include "xml/KeyValues.h" #include @@ -250,6 +254,7 @@ uintptr_t __fastcall TextureLoad_h(void *self, void *edx, const void *node, void const uintptr_t r = g_origTextureLoad(self, edx, node, status); if (self != nullptr && node != nullptr) { BindParentKey(RegionObject(self), node); + Xml::KeyValues::ApplyToRegion(RegionObject(self), node, status); Animation::Xml::LoadAnimations(RegionObject(self), node, status); if (const char *mask = Xml::Attr(node, "mask"); mask != nullptr && *mask != '\0') Texture::Mask::SetPath(RegionObject(self), mask); @@ -261,6 +266,7 @@ uintptr_t __fastcall FontStringLoad_h(void *self, void *edx, const void *node, v const uintptr_t r = g_origFontStringLoad(self, edx, node, status); if (self != nullptr && node != nullptr) { BindParentKey(RegionObject(self), node); + Xml::KeyValues::ApplyToRegion(RegionObject(self), node, status); Animation::Xml::LoadAnimations(RegionObject(self), node, status); } return r; diff --git a/src/xml/Templates.cpp b/src/xml/Templates.cpp index 0edfe4b9..85667acb 100644 --- a/src/xml/Templates.cpp +++ b/src/xml/Templates.cpp @@ -31,6 +31,7 @@ #include "Game.h" #include "Offsets.h" +#include "xml/KeyValues.h" #include #include @@ -179,10 +180,9 @@ int __fastcall Script_GetTemplateInfo(void *L) { Game::Lua::SetFieldNumber(L, "width", w); Game::Lua::SetFieldNumber(L, "height", h); - // keyValues: vanilla's XML schema has no element, so this is - // always an empty table (parity with retail's "empty if none defined"). + // keyValues: the template's own entries, as written. Game::Lua::PushString(L, "keyValues"); - Game::Lua::NewTable(L); + Xml::KeyValues::PushInfo(L, node); Game::Lua::SetTable(L, -3); // inherits: the comma-delimited `inherits=` attribute, or nil (field left