From 855b338736be6151981ced64aa0d040e3e1f43d7 Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Wed, 26 Aug 2026 12:01:33 -0500 Subject: [PATCH] feat(frame): add GetClickFrame global Backport the engine-registered C global behind the /click command: resolve a frame by its global name, returning it only when _G[name] holds a real frame whose GetName() matches. Mirrors 3.3.5's Script_GetClickFrame; reads the name from CFrameScriptObject vtable slot +4, verified against 1.12's own Script_GetName. --- README.md | 2 +- docs/API.md | 16 +++++++ src/frame/ClickFrame.cpp | 99 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 src/frame/ClickFrame.cpp diff --git a/README.md b/README.md index 777ca360..002d4417 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ reference in **[docs/API.md](docs/API.md)**. | [Expansion](docs/API.md#expansion) | `ClassicExpansionAtLeast`, `ClassicExpansionAtMost`, `GetClassicExpansionLevel` | | [Faction](docs/API.md#faction) | `C_Reputation.GetFactionDataByIndex`, `C_Reputation.GetFactionStandings`, `C_Reputation.GetLastStandingChange`, `C_Reputation.GetWatchedFactionData`, `C_Reputation.SetWatchedFactionByID`, `GetFactionIDByIndex`, `GetFactionInfoByID`, `GetFactionParentID` | | [Focus](docs/API.md#focus) | `ClearFocus`, `FocusUnit` | -| [Frame](docs/API.md#frame) | `region:SetPoint("point")` (one-arg form), `region:SetSize`, `region:GetSize`, `region:IsMouseOver`, `region:GetRect`, `region:IsDragging`, `GetMouseFoci`, `frame:SetShown`, `fontstring:GetStringHeight`, `fontstring:GetUnboundedStringWidth`, `fontstring:GetWrappedWidth`, `fontstring:GetNumLines`, `fontstring:GetLineHeight`, `fontstring:IsTruncated`, `fontstring:SetMaxLines`, `fontstring:GetMaxLines`, `fontstring:SetFormattedText`, `texture:SetRotation`, `texture:GetRotation`, `texture:SetVertexOffset`, `texture:GetVertexOffset`, `texture:SetColorTexture`, `texture:SetMask`, `frame:CreateMaskTexture`, `texture:AddMaskTexture`, `texture:RemoveMaskTexture`, `texture:GetNumMaskTextures`, `texture:GetMaskTexture`, `fontstring:SetRotation`, `fontstring:GetRotation`, `frame:SetResizeBounds`, `frame:HookScript`, `frame:IsEventRegistered`, `frame:GetEffectiveAlpha`, `frame:SetAttribute`, `frame:SetAttributeNoHandler`, `frame:ClearAttribute`, `frame:GetAttribute`, `OnAttributeChanged` (script), `SetModernScriptArgs`, `GetModernScriptArgs`, `SecureCmdOptionParse`, `RegisterStateDriver`, `UnregisterStateDriver`, `RegisterAttributeDriver`, `UnregisterAttributeDriver`, `RegisterUnitWatch`, `UnregisterUnitWatch`, `UnitWatchRegistered`, `SecureButton_GetAttribute`, `SecureButton_GetUnit`, `PreClick` (script), `PostClick` (script) | +| [Frame](docs/API.md#frame) | `region:SetPoint("point")` (one-arg form), `region:SetSize`, `region:GetSize`, `region:IsMouseOver`, `region:GetRect`, `region:IsDragging`, `GetMouseFoci`, `frame:SetShown`, `fontstring:GetStringHeight`, `fontstring:GetUnboundedStringWidth`, `fontstring:GetWrappedWidth`, `fontstring:GetNumLines`, `fontstring:GetLineHeight`, `fontstring:IsTruncated`, `fontstring:SetMaxLines`, `fontstring:GetMaxLines`, `fontstring:SetFormattedText`, `texture:SetRotation`, `texture:GetRotation`, `texture:SetVertexOffset`, `texture:GetVertexOffset`, `texture:SetColorTexture`, `texture:SetMask`, `frame:CreateMaskTexture`, `texture:AddMaskTexture`, `texture:RemoveMaskTexture`, `texture:GetNumMaskTextures`, `texture:GetMaskTexture`, `fontstring:SetRotation`, `fontstring:GetRotation`, `frame:SetResizeBounds`, `frame:HookScript`, `frame:IsEventRegistered`, `frame:GetEffectiveAlpha`, `frame:SetAttribute`, `frame:SetAttributeNoHandler`, `frame:ClearAttribute`, `frame:GetAttribute`, `OnAttributeChanged` (script), `SetModernScriptArgs`, `GetModernScriptArgs`, `SecureCmdOptionParse`, `RegisterStateDriver`, `UnregisterStateDriver`, `RegisterAttributeDriver`, `UnregisterAttributeDriver`, `RegisterUnitWatch`, `UnregisterUnitWatch`, `UnitWatchRegistered`, `SecureButton_GetAttribute`, `SecureButton_GetUnit`, `PreClick` (script), `PostClick` (script), `GetClickFrame` | | [FriendList](docs/API.md#friendlist) | `C_FriendList.GetFriendInfo`, `C_FriendList.GetFriendInfoByIndex`, `C_FriendList.GetNumFriends`, `C_FriendList.GetNumOnlineFriends`, `C_FriendList.GetNumWhoResults`, `C_FriendList.GetWhoInfo`, `C_FriendList.IsFriend`, `C_FriendList.IsIgnored`, `C_FriendList.IsIgnoredByGuid`, `C_FriendList.IsWhoQueryPending`, `C_FriendList.SendWhoQueryByName`, `C_FriendList.SetFriendNotes`, `C_FriendList.SetFriendNotesByIndex` | | [GameObject](docs/API.md#gameobject) | `C_GameObjectInfo.GetGameObjectInfoByID`, `C_GameObjectInfo.RequestLoadGameObjectByID`, `ClosestGameObjectPosition` | | [Glue](docs/API.md#glue) | `C_Glue.IsOnGlueScreen` | diff --git a/docs/API.md b/docs/API.md index 99557ddd..6ba2a78a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -204,6 +204,7 @@ build instructions. - [`RegisterUnitWatch` / `UnregisterUnitWatch` / `UnitWatchRegistered`](#registerunitwatch--unregisterunitwatch--unitwatchregistered) - [`SecureButton_GetAttribute` / `SecureButton_GetUnit`](#securebutton_getattribute--securebutton_getunit) - [`PreClick` / `PostClick` button scripts](#preclick--postclick-button-scripts) + - [`GetClickFrame(name)`](#getclickframename) - [FriendList](#friendlist) - [`C_FriendList.SendWhoQueryByName(name)`](#c_friendlistsendwhoquerybynamename) @@ -4995,6 +4996,21 @@ the normal use: run code just before or after a button's click action. (Modern WoW fires them even with no `OnClick`; that path is not available on this client.) +### `GetClickFrame(name)` + +Returns the frame with the given global name. The `/click` command uses it to +change a frame name into the frame. + +The function returns the frame only when `_G[name]` holds a real frame, and the +`GetName()` of that frame is equal to `name`. If the global holds a different +value, a plain table, or a frame with a different name, the function returns +nil. This name test makes sure that a changed global does not return the wrong +frame. + +```lua +GetClickFrame("MyButton") -- the frame named "MyButton", or nil +``` + ## FriendList ### `C_FriendList.SendWhoQueryByName(name)` diff --git a/src/frame/ClickFrame.cpp b/src/frame/ClickFrame.cpp new file mode 100644 index 00000000..1c90b3f6 --- /dev/null +++ b/src/frame/ClickFrame.cpp @@ -0,0 +1,99 @@ +// 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 . + +// `GetClickFrame(name)` — backport of the C global WoW registers for the +// `/click` handler to resolve a frame by its global name. Vanilla 1.12 +// never shipped it; 3.3.5's `Script_GetClickFrame` (`0x00564130`) is the +// reference. +// +// It lives in the DLL, not addon Lua, because Blizzard shipped it as an +// engine-registered C global — the backport mirrors where the real +// function lives, not the fact that Lua could fake it. +// +// Behaviour, matching the 3.3.5 resolver `FUN_00562990` (minus its private +// name→frame memoization cache, which is only a perf optimization over the +// global lookup): +// 1. `_G[name]` — a plain global-table lookup. +// 2. The value must be a frame wrapper table backed by a +// `CFrameScriptObject`. +// 3. Its real `GetName()` must equal `name`. This is the load-bearing +// check: it stops a reassigned global (`_G["Foo"] = someOtherFrame`) +// from resolving to a differently-named frame. +// Return the frame on a match, otherwise nil. +// +// `GetName()` is the object's vtable slot +4 (`__thiscall`, returns +// `const char *`) — verified from 1.12's own `Script_GetName` +// (`0x0079FF60` / `0x007A1390`), which resolves self the same way and reads +// the name from that slot. It's a base virtual present on every +// `CFrameScriptObject` subtype, so calling it after `ResolveObject` is +// safe without the RTTI subtype gate `Script_GetName` does first. + +#include "Game.h" +#include "Offsets.h" + +#include + +namespace Frame::ClickFrame { + +namespace { +// CFrameScriptObject::GetName — vtable slot +4, thiscall, no args. +using GetName_t = const char *(__thiscall *)(void *self); + +const char *ObjectName(void *obj) { + auto vtable = *reinterpret_cast(obj); + auto getName = reinterpret_cast(vtable[1]); + return getName(obj); +} +} // namespace + +static int __fastcall Script_GetClickFrame(void *L) { + using namespace Game::Lua; + + if (GetTop(L) < 1) { + Error(L, "Usage: GetClickFrame(\"name\")"); + return 0; + } + const char *name = ToString(L, 1); + if (name == nullptr) { + PushNil(L); + return 1; + } + + // getglobal(name): push _G[name]. + PushString(L, name); + GetTable(L, GLOBALS_INDEX); + + if (Type(L, -1) != TYPE_TABLE) { + PushNil(L); + return 1; + } + + void *obj = ResolveObject(L, -1); + if (obj != nullptr) { + const char *objName = ObjectName(obj); + if (objName != nullptr && std::strcmp(objName, name) == 0) + // The wrapper table is still on top — return it as-is. + return 1; + } + + PushNil(L); + return 1; +} + +static void RegisterLuaFunctions() { + Game::Lua::RegisterGlobalFunction("GetClickFrame", &Script_GetClickFrame); +} + +static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +} // namespace Frame::ClickFrame