diff --git a/docs/API.md b/docs/API.md
index bd9c599b..3c583ff0 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -885,8 +885,10 @@ build instructions.
- [`C_XMLUtil.DoesTemplateExist(name)`](#c_xmlutildoestemplateexistname)
- [`inherits` with more than one template](#inherits-with-more-than-one-template)
- [`parentKey` in XML](#parentkey-in-xml)
+ - [`KeyValues` in XML](#keyvalues-in-xml)
+ - [`mixin` in XML](#mixin-in-xml)
- [Masks in XML](#masks-in-xml)
- - [`function` on XML script handlers](#function-on-xml-script-handlers)
+ - [`function` and `method` on XML script handlers](#function-and-method-on-xml-script-handlers)
- [`style` on button font elements](#style-on-button-font-elements)
- [`C_TTSSettings` — getters & setters](#c_ttssettings--getters--setters)
- [TTS events](#tts-events)
@@ -20851,6 +20853,35 @@ 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.
+### `mixin` in XML
+
+A `mixin` attribute names one or more global tables. Commas or spaces
+divide the names. Each table's fields are copied onto the element's Lua
+table, the same as `Mixin(object, ...)`:
+
+```xml
+
+
+
+
+
+
+```
+
+Frames, textures, font strings and `` elements take a
+`mixin` attribute. The tables must exist when the XML loads, so define them
+in a Lua file that loads before the XML file.
+
+The mixins of the templates in `inherits` apply first, in template order.
+Then the element's own mixins apply, so a later mixin replaces fields of an
+earlier one. All mixins apply before the element's
+[``](#keyvalues-in-xml) and scripts load, so a ``
+replaces a default that a mixin gives. Frames from `CreateFrame` with a
+template get the template's mixins too.
+
+If a name is not a global table, `FrameXML.log` gets the warning
+`Couldn't find mixin` and the other names still apply.
+
### Masks in XML
A `` element takes a `mask` attribute. It is the same as
@@ -20896,7 +20927,7 @@ A `` can name a texture from any layer of the same frame. If
it names no texture, the load log gets a warning and the mask is not
attached.
-### `function` on XML script handlers
+### `function` and `method` on XML script handlers
A script element with `function="Name"` uses the global function `Name` as
that script's handler. It is the same as
@@ -20909,6 +20940,18 @@ that script's handler. It is the same as
```
+A script element with `method="Name"` uses the frame's own field
+`self.Name` as the handler. The field usually comes from a
+[mixin](#mixin-in-xml):
+
+```xml
+
+
+
+```
+
+Animation groups and animations take `function` and `method` the same way.
+
The function is looked up when the element loads, so it must be defined by then. A bound `OnLoad` runs at the
usual point, once the frame is built, and with
[positional script arguments](#setmodernscriptargsenable--getmodernscriptargs)
diff --git a/src/animation/Xml.cpp b/src/animation/Xml.cpp
index 5367ae05..0ddbc02e 100644
--- a/src/animation/Xml.cpp
+++ b/src/animation/Xml.cpp
@@ -26,6 +26,7 @@
#include "baselib/Ascii.h"
#include "xml/FrameLoad.h"
#include "xml/KeyValues.h"
+#include "xml/Mixin.h"
#include
#include
@@ -70,7 +71,8 @@ void BindParentKey(void *object, Object *child, const char *key) {
Game::Lua::SetTop(L, top);
}
-// : each element's body, or its `function` global.
+// : each element's body, its `function` global, or its `method`
+// field on the object.
void LoadScripts(Object *object, const void *node) {
const void *scripts = FindChild(node, "Scripts");
if (scripts == nullptr)
@@ -80,13 +82,22 @@ void LoadScripts(Object *object, const void *node) {
if (script == nullptr)
continue;
const char *function = ::Xml::Attr(s, "function");
- if (function != nullptr && *function != '\0') {
+ const char *method = ::Xml::Attr(s, "method");
+ const bool byFunction = function != nullptr && *function != '\0';
+ if (byFunction || (method != nullptr && *method != '\0')) {
uint32_t *slot = object->ScriptSlot(script);
void *L = Game::Lua::State();
if (slot == nullptr || L == nullptr)
continue;
- Game::Lua::PushString(L, function);
- Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX);
+ if (byFunction) {
+ Game::Lua::PushString(L, function);
+ Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX);
+ } else {
+ Push(L, object);
+ Game::Lua::PushString(L, method);
+ Game::Lua::GetTable(L, -2);
+ Game::Lua::Remove(L, -2);
+ }
if (Game::Lua::Type(L, -1) != Game::Lua::TYPE_FUNCTION) {
Game::Lua::SetTop(L, -2);
continue;
@@ -158,14 +169,41 @@ void LoadAnimChildren(Group *group, const void *node, void *status) {
const void *Template(const char *name) { return ::Xml::Template(name); }
+namespace {
+
+// LoadGroup re-enters itself for each inherited template; the mixins of the
+// whole chain go in once, from the outermost call, before any node's
+// KeyValues or scripts (see Xml::Mixin).
+int g_groupDepth = 0;
+
+void LoadGroupNode(Group *group, const void *node, void *status);
+
+} // namespace
+
void LoadGroup(Group *group, const void *node, void *status) {
+ if (g_groupDepth == 0) {
+ if (void *L = Game::Lua::State()) {
+ const int top = Game::Lua::GetTop(L);
+ Push(L, group);
+ ::Xml::Mixin::ApplyChain(L, top + 1, node, status, group->DisplayName(), false);
+ Game::Lua::SetTop(L, top);
+ }
+ }
+ ++g_groupDepth;
+ LoadGroupNode(group, node, status);
+ --g_groupDepth;
+}
+
+namespace {
+
+void LoadGroupNode(Group *group, const void *node, void *status) {
group->flags |= GROUP_LOADING;
if (const char *inherits = ::Xml::Attr(node, "inherits"); inherits != nullptr && *inherits != '\0') {
const void *base = ::Xml::Template(inherits);
if (base == nullptr)
::Xml::Warn(status, "Couldn't find inherited node: %s", inherits);
else
- LoadGroup(group, base, status);
+ LoadGroupNode(group, base, status);
}
BindParentKey(group->RegionObject(), group, ::Xml::Attr(node, "parentKey"));
if (const char *looping = ::Xml::Attr(node, "looping"); looping != nullptr && *looping != '\0') {
@@ -192,6 +230,8 @@ void LoadGroup(Group *group, const void *node, void *status) {
LoadAnimChildren(group, node, status);
}
+} // namespace
+
void LoadAnim(Anim *anim, const void *node, void *status) {
// The subclass reads its values, then CSimpleAnim::LoadXML (inherits
// first, then the shared attributes) - the order 4.3.4's overrides use.
diff --git a/src/baselib/Mixin.cpp b/src/baselib/Mixin.cpp
index 589e9cff..30afc0de 100644
--- a/src/baselib/Mixin.cpp
+++ b/src/baselib/Mixin.cpp
@@ -24,15 +24,15 @@
// CreateFromMixins(...) -- Mixin({}, ...); returns the new table.
// Non-table extra arguments are skipped (the Lua form guards nil the same way).
+#include "baselib/Mixin.h"
+
#include "Game.h"
namespace BaseLib::Mixin {
-namespace {
-
// Shallow-copy every pair from the table at `srcIdx` onto the table at
// `dstIdx` (both absolute, positive stack indices). Stack-balanced.
-void MixinInto(void *L, int dstIdx, int srcIdx) {
+void Into(void *L, int dstIdx, int srcIdx) {
Game::Lua::PushNil(L);
while (Game::Lua::Next(L, srcIdx) != 0) {
// stack top: ..., key (-2), value (-1). Copy both so the originals
@@ -44,6 +44,8 @@ void MixinInto(void *L, int dstIdx, int srcIdx) {
}
}
+namespace {
+
int __fastcall Script_Mixin(void *L) {
const int top = Game::Lua::GetTop(L);
if (top < 1 || Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) {
@@ -52,7 +54,7 @@ int __fastcall Script_Mixin(void *L) {
}
for (int i = 2; i <= top; ++i)
if (Game::Lua::Type(L, i) == Game::Lua::TYPE_TABLE)
- MixinInto(L, 1, i);
+ Into(L, 1, i);
Game::Lua::PushValue(L, 1); // return object
return 1;
}
@@ -63,7 +65,7 @@ int __fastcall Script_CreateFromMixins(void *L) {
const int objIdx = top + 1;
for (int i = 1; i <= top; ++i)
if (Game::Lua::Type(L, i) == Game::Lua::TYPE_TABLE)
- MixinInto(L, objIdx, i);
+ Into(L, objIdx, i);
Game::Lua::SetTop(L, objIdx); // the new table is the sole result
return 1;
}
diff --git a/src/baselib/Mixin.h b/src/baselib/Mixin.h
new file mode 100644
index 00000000..73be25b6
--- /dev/null
+++ b/src/baselib/Mixin.h
@@ -0,0 +1,22 @@
+// 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
+
+namespace BaseLib::Mixin {
+
+// dst[k] = v for every field of the table at `srcIdx` — Mixin()'s copy.
+// Both indices must be absolute.
+void Into(void *L, int dstIdx, int srcIdx);
+
+} // namespace BaseLib::Mixin
diff --git a/src/xml/Mixin.cpp b/src/xml/Mixin.cpp
new file mode 100644
index 00000000..473f5852
--- /dev/null
+++ b/src/xml/Mixin.cpp
@@ -0,0 +1,144 @@
+// 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 .
+
+// `mixin="A, B"` on frames, textures, font strings and animation groups, the
+// later-client attribute: each name is a global table whose fields are
+// copied onto the element's Lua table, as `Mixin(object, A, B)` does.
+//
+// ORDER. A mixin carries methods and default fields; and the
+// element's scripts build on them, so every mixin must be in place before
+// any of those load. The engine's loaders load a template by re-entering the
+// same loader for the template node (FUN_XML_FRAME_LOAD through
+// Xml::Inherits, the texture and font string loaders through
+// `(*self)->vtable[+8]` at their top), and the KeyValues for a template node
+// are set when that inner load returns. So mixins cannot be applied per
+// node: an element's own mixin would land after its template's KeyValues and
+// overwrite their defaults. Instead the OUTERMOST load of an object walks
+// the whole inherits chain once, before the engine runs, and mixes in each
+// template's mixins (templates first, in inherits order) and then the
+// element's own. Inner loads of the same object apply nothing.
+//
+// A name that is not a global table is skipped with a load warning.
+
+#include "xml/Mixin.h"
+
+#include "Game.h"
+#include "baselib/Mixin.h"
+#include "xml/FrameLoad.h"
+#include "xml/Inherits.h"
+
+#include
+
+namespace Xml::Mixin {
+
+namespace {
+
+// Objects whose load is in progress, outermost first. Nesting is the
+// inherits chain plus anything a Before subscriber loads, so this stays a
+// handful of entries deep.
+std::vector g_loading;
+
+// Deeper than any real chain; stops a template that inherits itself.
+constexpr int kMaxChainDepth = 32;
+
+void ApplyNode(void *L, int index, const void *node, void *status, const char *owner,
+ bool listInherits, int depth) {
+ if (depth > kMaxChainDepth)
+ return;
+ const char *inherits = Attr(node, "inherits");
+ if (inherits != nullptr && *inherits != '\0') {
+ const auto applyTemplate = [&](const char *name) {
+ if (const void *t = Template(name))
+ ApplyNode(L, index, t, status, owner, listInherits, depth + 1);
+ };
+ if (listInherits)
+ Inherits::ForEach(inherits, applyTemplate);
+ else
+ applyTemplate(inherits);
+ }
+
+ const char *mixins = Attr(node, "mixin");
+ if (mixins == nullptr || *mixins == '\0')
+ return;
+ Inherits::ForEach(mixins, [&](const char *name) {
+ Game::Lua::PushString(L, name);
+ Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX); // [mixin]
+ if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_TABLE)
+ BaseLib::Mixin::Into(L, index, Game::Lua::GetTop(L));
+ else
+ Warn(status, "%s: Couldn't find mixin %s", owner, name);
+ Game::Lua::SetTop(L, -2);
+ });
+}
+
+bool HasMixinInChain(const void *node, bool listInherits, int depth) {
+ if (depth > kMaxChainDepth)
+ return false;
+ if (const char *m = Attr(node, "mixin"); m != nullptr && *m != '\0')
+ return true;
+ const char *inherits = Attr(node, "inherits");
+ if (inherits == nullptr || *inherits == '\0')
+ return false;
+ bool found = false;
+ const auto check = [&](const char *name) {
+ if (!found)
+ if (const void *t = Template(name))
+ found = HasMixinInChain(t, listInherits, depth + 1);
+ };
+ if (listInherits)
+ Inherits::ForEach(inherits, check);
+ else
+ check(inherits);
+ return found;
+}
+
+} // namespace
+
+void ApplyChain(void *L, int index, const void *node, void *status, const char *owner,
+ bool listInherits) {
+ ApplyNode(L, index, node, status, owner, listInherits, 0);
+}
+
+void Begin(void *object, const void *node, void *status, bool listInherits) {
+ bool outer = true;
+ for (void *o : g_loading)
+ if (o == object)
+ outer = false;
+ g_loading.push_back(object);
+ if (!outer || !HasMixinInChain(node, listInherits, 0))
+ return;
+ void *L = Game::Lua::State();
+ if (L == nullptr)
+ return;
+ const int top = Game::Lua::GetTop(L);
+ if (PushWrapper(L, object))
+ ApplyChain(L, top + 1, node, status, Game::Lua::ObjectDisplayName(object), listInherits);
+ Game::Lua::SetTop(L, top);
+}
+
+void End(void *object) {
+ if (!g_loading.empty() && g_loading.back() == object)
+ g_loading.pop_back();
+}
+
+namespace {
+
+void BeginFrame(void *object, const void *node, void *status) { Begin(object, node, status, true); }
+void EndFrame(void *object, const void *, void *) { End(object); }
+
+const FrameLoad::AutoSubscribeBefore _frameBegin{&BeginFrame};
+const FrameLoad::AutoSubscribe _frameEnd{&EndFrame};
+
+} // namespace
+
+} // namespace Xml::Mixin
diff --git a/src/xml/Mixin.h b/src/xml/Mixin.h
new file mode 100644
index 00000000..08803bfb
--- /dev/null
+++ b/src/xml/Mixin.h
@@ -0,0 +1,35 @@
+// 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
+
+// `mixin="A, B"` on XML elements — see Mixin.cpp.
+
+namespace Xml::Mixin {
+
+// Mixes the mixins of `node`'s whole inherits chain into the Lua table at
+// stack index `index`: each template's (recursively) in inherits order, then
+// the node's own. `listInherits` reads `inherits` as a list, as frames do;
+// regions and animation groups take it as one name. `owner` names the
+// element in load warnings.
+void ApplyChain(void *L, int index, const void *node, void *status, const char *owner,
+ bool listInherits);
+
+// For a loader hook that the engine re-enters for each inherited template:
+// Begin before the engine loads `node`, End after. Only the object's
+// outermost load applies the chain, so every mixin is in place before any
+// node's KeyValues and scripts.
+void Begin(void *object, const void *node, void *status, bool listInherits);
+void End(void *object);
+
+} // namespace Xml::Mixin
diff --git a/src/xml/ParentKey.cpp b/src/xml/ParentKey.cpp
index b042b77d..7b54acd7 100644
--- a/src/xml/ParentKey.cpp
+++ b/src/xml/ParentKey.cpp
@@ -60,7 +60,9 @@
// binds its whole OnLoad this way). After the engine has loaded the node, each
// script element carrying `function` becomes `frame:SetScript(,
// _G[function])`. The loader runs before the builder's finalize, so a bound
-// OnLoad still fires at the usual point.
+// OnLoad still fires at the usual point. `method="Name"` does the same with
+// `frame[Name]`, the frame's own field - usually a function from its mixin
+// (Xml::Mixin), which is in place before any node of the frame loads.
//
// A button's font elements take their font from `style` on later clients
// (``) where vanilla reads `inherits`; the
@@ -86,6 +88,7 @@
#include "animation/Xml.h"
#include "texture/Mask.h"
#include "xml/KeyValues.h"
+#include "xml/Mixin.h"
#include
@@ -126,11 +129,12 @@ void BindParentKey(void *object, const void *node) {
Game::Lua::SetTop(L, top);
}
-// ---- function= ---------------------------------------------------
+// ---- function= / method= -----------------------------------------
// frame:SetScript(, _G[function]) for every child of `node`
-// that carries a `function` attribute. A name that is not a global function,
-// or a script the frame type does not have, is skipped.
+// that carries a `function` attribute, or frame:SetScript(,
+// frame[method]) for one that carries `method`. A name that is not a
+// function, or a script the frame type does not have, is skipped.
void BindScriptFunctions(void *object, const void *node) {
const void *scripts = nullptr;
for (const void *c = FirstChild(node); c != nullptr; c = NextSibling(c)) {
@@ -149,8 +153,10 @@ void BindScriptFunctions(void *object, const void *node) {
bool havePushed = false;
for (const void *e = FirstChild(scripts); e != nullptr; e = NextSibling(e)) {
const char *fn = Xml::Attr(e, "function");
+ const char *method = Xml::Attr(e, "method");
const char *script = Xml::Tag(e);
- if (fn == nullptr || *fn == '\0' || script == nullptr)
+ const bool byFunction = fn != nullptr && *fn != '\0';
+ if (script == nullptr || (!byFunction && (method == nullptr || *method == '\0')))
continue;
if (!havePushed) {
if (!PushWrapper(L, object)) // [frame]
@@ -163,8 +169,9 @@ void BindScriptFunctions(void *object, const void *node) {
break;
Game::Lua::PushValue(L, top + 1); // [frame, SetScript, frame]
Game::Lua::PushString(L, script); // [.., frame, script]
- Game::Lua::PushString(L, fn);
- Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX); // [.., frame, script, _G[fn]]
+ Game::Lua::PushString(L, byFunction ? fn : method);
+ Game::Lua::GetTable(L, byFunction ? Game::Lua::GLOBALS_INDEX
+ : top + 1); // [.., frame, script, handler]
if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_FUNCTION)
Game::Lua::PCall(L, 3, 0, 0);
Game::Lua::SetTop(L, top + 1); // [frame]
@@ -251,8 +258,12 @@ void *RegionObject(void *self) {
}
uintptr_t __fastcall TextureLoad_h(void *self, void *edx, const void *node, void *status) {
+ if (self == nullptr || node == nullptr)
+ return g_origTextureLoad(self, edx, node, status);
+ Xml::Mixin::Begin(RegionObject(self), node, status, false);
const uintptr_t r = g_origTextureLoad(self, edx, node, status);
- if (self != nullptr && node != nullptr) {
+ Xml::Mixin::End(RegionObject(self));
+ {
BindParentKey(RegionObject(self), node);
Xml::KeyValues::ApplyToRegion(RegionObject(self), node, status);
Animation::Xml::LoadAnimations(RegionObject(self), node, status);
@@ -263,8 +274,12 @@ uintptr_t __fastcall TextureLoad_h(void *self, void *edx, const void *node, void
}
uintptr_t __fastcall FontStringLoad_h(void *self, void *edx, const void *node, void *status) {
+ if (self == nullptr || node == nullptr)
+ return g_origFontStringLoad(self, edx, node, status);
+ Xml::Mixin::Begin(RegionObject(self), node, status, false);
const uintptr_t r = g_origFontStringLoad(self, edx, node, status);
- if (self != nullptr && node != nullptr) {
+ Xml::Mixin::End(RegionObject(self));
+ {
BindParentKey(RegionObject(self), node);
Xml::KeyValues::ApplyToRegion(RegionObject(self), node, status);
Animation::Xml::LoadAnimations(RegionObject(self), node, status);