From 7add0fc88f5752196bf4619eae9ae987f9432514 Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Tue, 27 Oct 2026 18:06:38 -0500 Subject: [PATCH] feat(frame): region:GetDebugName([preferParentKey]) Retail's debug name for a region: its global name; else its parent's debug name, a dot, and the key that holds it in the parent's Lua table, or its address in hex when no key holds it; "" for an unnamed region with no parent. preferParentKey puts the key path ahead of a global name. The key comes from the parent's table, so a plain Lua assignment resolves once the region is parented, as on retail. The frame stack tooltip prints names through it, which removes the debug tools' local _DebugName. Game::Lua::ObjectName exposes the engine's GetName virtual for unnamed-aware callers. --- docs/API.md | 23 ++++ src/Game.cpp | 9 +- src/Game.h | 6 +- .../ClassicAPI_DebugTools/DebugTools.lua | 14 +- src/frame/DebugName.cpp | 123 ++++++++++++++++++ 5 files changed, 160 insertions(+), 15 deletions(-) create mode 100644 src/frame/DebugName.cpp diff --git a/docs/API.md b/docs/API.md index 48a92544..2eeb69fa 100644 --- a/docs/API.md +++ b/docs/API.md @@ -267,6 +267,7 @@ build instructions. - [`region:GetRect()`](#regiongetrect) - [`region:GetPoint([index])`](#regiongetpointindex) - [`region:IsDragging()`](#regionisdragging) + - [`region:GetDebugName([preferParentKey])`](#regiongetdebugnamepreferparentkey) - [`region:GetSourceLocation()`](#regiongetsourcelocation) - [`GetMouseFoci()`](#getmousefoci) - [`CreateFrame(frameType [, name, parent, template, id])`](#createframeframetype--name-parent-template-id) @@ -6652,6 +6653,28 @@ fontstrings) always report `false`, since only frames can be dragged. if self:IsDragging() then ... end ``` +### `region:GetDebugName([preferParentKey])` + +Returns the name that the debug tools show for a region. + +```lua +local f = CreateFrame("Frame", "SomeFrame", UIParent) +f.Icon = f:CreateTexture() +print(f:GetDebugName()) -- "SomeFrame" +print(f.Icon:GetDebugName()) -- "SomeFrame.Icon" +print(f:CreateTexture():GetDebugName()) -- "SomeFrame.1a2b3c4d" +print(CreateFrame("Frame"):GetDebugName() == "") -- true +``` + +- A region with a global name returns that name. +- A region with no name returns the debug name of its parent, a dot, and + the key that holds the region in the parent's table. +- If no key in the parent holds the region, the address of the region (in + hex) replaces the key. +- A region with no name and no parent returns an empty string. +- If `preferParentKey` is `true`, the parent-key form comes before the + global name, at each level of the chain. + ### `region:GetSourceLocation()` Returns where the region was created, as a string. diff --git a/src/Game.cpp b/src/Game.cpp index 5b9b3f9a..67be1b03 100644 --- a/src/Game.cpp +++ b/src/Game.cpp @@ -150,11 +150,14 @@ bool ToFlag(void *L, int index, bool defaultValue) { defaultValue ? 1 : 0) != 0; } -const char *ObjectDisplayName(void *object) { +const char *ObjectName(void *object) { using GetName_t = const char *(__thiscall *)(void *); const void *vtable = Game::Read(object, 0); - const char *name = Game::Read( - vtable, Offsets::VTBL_SCRIPTOBJECT_GET_NAME)(object); + return Game::Read(vtable, Offsets::VTBL_SCRIPTOBJECT_GET_NAME)(object); +} + +const char *ObjectDisplayName(void *object) { + const char *name = ObjectName(object); return name != nullptr ? name : reinterpret_cast(Offsets::VAR_STR_UNNAMED); } diff --git a/src/Game.h b/src/Game.h index dcd82a77..6fa07ab1 100644 --- a/src/Game.h +++ b/src/Game.h @@ -395,8 +395,12 @@ int ObjectLuaRef(void *object); // Pushes the object's Lua table (registry[ObjectLuaRef(object)]). void PushObject(void *L, void *object); +// The object's global name (VTBL_SCRIPTOBJECT_GET_NAME), or nullptr when it +// has none. +const char *ObjectName(void *object); + // How the engine names an object in its frame-script usage errors: -// `GetName() ?: ""` (VTBL_SCRIPTOBJECT_GET_NAME). +// `GetName() ?: ""`. const char *ObjectDisplayName(void *object); // Same resolve, then the type gate every engine frame method applies to its diff --git a/src/embed/AddOns/ClassicAPI_DebugTools/DebugTools.lua b/src/embed/AddOns/ClassicAPI_DebugTools/DebugTools.lua index d3383256..ca61a26d 100644 --- a/src/embed/AddOns/ClassicAPI_DebugTools/DebugTools.lua +++ b/src/embed/AddOns/ClassicAPI_DebugTools/DebugTools.lua @@ -1042,14 +1042,6 @@ local function _StringToBoolean(stringToCheck, defaultReturn) return defaultReturn; end --- What the modern tooltip prints through GetDebugName: the global name, --- else the object's table. -local function _DebugName(obj) - local name = obj.GetName and obj:GetName(); - if (name and name ~= "") then return name; end - return tostring(obj); -end - local function _WrapColor(text, colorHex) return "|c" .. colorHex .. text .. "|r"; end @@ -1084,7 +1076,7 @@ end function FrameStackTooltip_InspectTable(self) if (self.highlightFrame) then - TableInspector_Show(self.highlightFrame, _DebugName(self.highlightFrame)); + TableInspector_Show(self.highlightFrame, self.highlightFrame:GetDebugName()); end end @@ -1114,7 +1106,7 @@ local function _FormatTextureInfo(region) if (file == nil) then return nil; end - return string.format("%s : %s: %s %s", _DebugName(region), _WrapColor("File", "ffff0000"), + return string.format("%s : %s: %s %s", region:GetDebugName(), _WrapColor("File", "ffff0000"), tostring(file), _FormatTextureCoordinates(region:GetTexCoord())); end @@ -1153,7 +1145,7 @@ function FrameStackTooltip_OnTooltipSetFrameStack(self, highlightFrame) end if (fsobj) then - self:AddLine(string.format("\nfsobj = %s", _DebugName(fsobj))); + self:AddLine(string.format("\nfsobj = %s", fsobj:GetDebugName())); end end diff --git a/src/frame/DebugName.cpp b/src/frame/DebugName.cpp new file mode 100644 index 00000000..b59395fe --- /dev/null +++ b/src/frame/DebugName.cpp @@ -0,0 +1,123 @@ +// 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 . + +// `region:GetDebugName([preferParentKey])` — the name the debug tools print +// for a region. Retail's rules, as its documented examples show them: +// - a named region gives its global name; +// - an unnamed region gives its parent's debug name, a dot, and the key the +// parent's table holds it under ("CharacterFrame.TitleBg"), or its address +// in hex when the parent holds it under no key ("SomeFrame.156f1390860"); +// - an unnamed region with no parent gives "". +// The key comes from the parent's Lua table, not from a recorded parentKey: +// retail resolves a plain `CharacterFrame.b = frame` once b is parented. +// `preferParentKey` puts the parent-key path ahead of a global name, all the +// way up the chain. + +#include "Game.h" +#include "Offsets.h" + +#include +#include + +namespace Frame::DebugName { + +namespace { + +// The string key under which the table at `parentIdx` holds the table at +// `childIdx`, or "" when it holds it under none. Both are object tables, so +// identity is pointer equality. +std::string FindKey(void *L, int parentIdx, int childIdx) { + const void *child = Game::Lua::ToPointer(L, childIdx); + Game::Lua::PushNil(L); + while (Game::Lua::Next(L, parentIdx) != 0) { + if (Game::Lua::Type(L, -2) == Game::Lua::TYPE_STRING && + Game::Lua::Type(L, -1) == Game::Lua::TYPE_TABLE && + Game::Lua::ToPointer(L, -1) == child) { + std::string key = Game::Lua::ToString(L, -2); + Game::Lua::SetTop(L, -3); // value and key + return key; + } + Game::Lua::SetTop(L, -2); // value; keep the key for the next step + } + return {}; +} + +std::string Build(void *L, void *object, bool preferParentKey) { + const char *name = Game::Lua::ObjectName(object); + const bool named = name != nullptr && *name != '\0'; + if (named && !preferParentKey) + return name; + + void *parent = Game::Read(object, Offsets::OFF_REGION_PARENT); + if (parent == nullptr) + return named ? name : ""; + std::string parentName = Build(L, parent, preferParentKey); + if (parentName.empty()) + return named ? name : ""; + + const int top = Game::Lua::GetTop(L); + Game::Lua::PushObject(L, parent); + Game::Lua::PushObject(L, object); + std::string key = FindKey(L, top + 1, top + 2); + Game::Lua::SetTop(L, top); + + if (!key.empty()) + return parentName + "." + key; + if (named) + return name; + char address[16]; + std::snprintf(address, sizeof(address), "%x", + static_cast(reinterpret_cast(object))); + return parentName + "." + address; +} + +int __fastcall Script_GetDebugName(void *L) { + void *self = Game::Lua::ResolveRegion(L); + if (self == nullptr) + return 0; + const bool preferParentKey = Game::Lua::ToBoolean(L, 2) != 0; + Game::Lua::PushString(L, Build(L, self, preferParentKey).c_str()); + return 1; +} + +const Game::Lua::FrameMethodEntry g_methods[] = { + {"GetDebugName", &Script_GetDebugName}, +}; + +const Game::Doc::Field kArgs[] = { + Game::Doc::Opt("preferParentKey", "bool", "false", + "Uses the parent-key path even when the region has a global name."), +}; +const Game::Doc::Field kRets[] = { + Game::Doc::Req("debugName", "string"), +}; +const Game::Doc::Function kGetDebugName{ + "Returns the region's global name, or its parent's debug name and the key or address " + "the parent holds it under; empty for an unnamed region with no parent.", + kArgs, kRets}; +const Game::Doc::Method g_methodDocs[] = { + {"GetDebugName", &kGetDebugName}, +}; + +void RegisterLuaFunctions() { + Game::Lua::RegisterFrameMethods( + reinterpret_cast(Offsets::VAR_REGION_METHOD_REGISTRY), g_methods, + static_cast(sizeof(g_methods) / sizeof(g_methods[0])), g_methodDocs, + static_cast(sizeof(g_methodDocs) / sizeof(g_methodDocs[0]))); +} + +const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +} // namespace + +} // namespace Frame::DebugName