From f01a059cc06221cbd4846bfad9146fb8fe3db684 Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Tue, 27 Oct 2026 19:17:03 -0500
Subject: [PATCH] feat(frame): useParentLevel and
SetUsingParentLevel/IsUsingParentLevel
A frame that uses its parent's level draws at the parent's level instead
of one above it. Retail's ScrollBox and TrimScrollBar templates rely on it
for their scroll target and backgrounds.
4.3.4 keeps this as frame flag 0x100000, and its level setter replaces any
level it is given with the parent's while the flag is on. 1.12's setter
(0x0076A4F0) is the same function without that test; a hook adds it, so
SetParent, a parent moving its children, and SetFrameLevel all land on the
parent's level. Setting the flag moves the frame and its children to the
parent's level, as 4.3.4's SetUseParentLevel does.
The XML attribute is read after the node loads, when the frame has its
parent, and only when present, so a node's value overrides its template's.
---
docs/API.md | 23 +++++++
src/Offsets.h | 4 ++
src/frame/UseParentLevel.cpp | 126 +++++++++++++++++++++++++++++++++++
3 files changed, 153 insertions(+)
create mode 100644 src/frame/UseParentLevel.cpp
diff --git a/docs/API.md b/docs/API.md
index 3d5de9dd..c95cc030 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -345,6 +345,7 @@ build instructions.
- [`frame:CanChangeAttribute()` / `frame:AllowAttributeChanges()`](#framecanchangeattribute--frameallowattributechanges)
- [`frame:SetPropagateKeyboardInput([propagate])` / `frame:GetPropagateKeyboardInput()`](#framesetpropagatekeyboardinputpropagate--framegetpropagatekeyboardinput)
- [`frame:SetDontSavePosition([dontSave])` / `frame:GetDontSavePosition()`](#framesetdontsavepositiondontsave--framegetdontsaveposition)
+ - [`frame:SetUsingParentLevel(usingParentLevel)` / `frame:IsUsingParentLevel()`](#framesetusingparentlevelusingparentlevel--frameisusingparentlevel)
- [`frame:GetBoundsRect()`](#framegetboundsrect)
- [`frame:HookScript(scriptType, handler)`](#framehookscriptscripttype-handler)
- [`smf:SetHyperlinksEnabled(enabled)` / `smf:GetHyperlinksEnabled()`](#smfsethyperlinksenabledenabled--smfgethyperlinksenabled)
@@ -7865,6 +7866,28 @@ frame. Use this for a frame whose position your addon saves itself.
- `dontSave` is `true` when you omit it.
- `GetDontSavePosition` returns `1` or `nil`.
+### `frame:SetUsingParentLevel(usingParentLevel)` / `frame:IsUsingParentLevel()`
+
+Sets or gets whether the frame uses the frame level of its parent.
+
+A child frame usually has a frame level one more than its parent. When
+`usingParentLevel` is true, the frame has the same level as its parent. The
+frame stays at that level when you call `SetFrameLevel`, when you give it a
+new parent, and when its parent's level changes with its children.
+
+- `IsUsingParentLevel` returns `true` or `false`. The default is `false`.
+- When you set the value to `false`, the frame keeps its current level.
+
+You can also set the value in XML with the `useParentLevel` attribute:
+
+```xml
+
+
+
+
+
+```
+
### `frame:GetBoundsRect()`
Returns `left, bottom, width, height` of the smallest rectangle that holds
diff --git a/src/Offsets.h b/src/Offsets.h
index 5c79c62e..93222dbb 100644
--- a/src/Offsets.h
+++ b/src/Offsets.h
@@ -3987,6 +3987,7 @@ enum Offsets {
// to 1.
PATCH_SETPARENT_LEVEL_CHILDREN = 0x0076AB6B, // before `call` at 0x0076AB71 (parent)
PATCH_SETPARENT_NIL_LEVEL_CHILDREN = 0x0076ABAC, // before `call` at 0x0076ABB2 (no parent)
+ FUN_FRAME_SET_FRAME_LEVEL = 0x0076A4F0,
// Frame alpha. The byte at OFF_FRAME_ALPHA (0..255) is what the frame's
// regions are drawn with (each region's recolor reads it) and what
// FUN_SCRIPT_FRAME_GETALPHA returns (`[frame+0xC8] / 255`); it has one
@@ -4077,6 +4078,9 @@ enum Offsets {
// 4.3.4's SetPropagateKeyboardInput bit: a frame's key-down and character
// slots run the script and then answer "not handled", so the key goes on.
FRAME_FLAG_PROPAGATE_KEYBOARD = 0x200000,
+ // 4.3.4's SetUseParentLevel bit: its level setter replaces the level it
+ // is given with the parent's level while the frame has it.
+ FRAME_FLAG_USE_PARENT_LEVEL = 0x100000,
// `int` — nonzero when the frame is shown (4.3.4's m_shown).
// Script_IsShown (0x00775990) pushes `[frame+0xD0] != 0`.
OFF_FRAME_SHOWN = 0xD0,
diff --git a/src/frame/UseParentLevel.cpp b/src/frame/UseParentLevel.cpp
new file mode 100644
index 00000000..e14eb74f
--- /dev/null
+++ b/src/frame/UseParentLevel.cpp
@@ -0,0 +1,126 @@
+// 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 .
+
+// `useParentLevel` on XML frames, and `frame:SetUsingParentLevel(using)` /
+// `frame:IsUsingParentLevel()`.
+//
+// A frame that uses its parent's level draws at the parent's level instead
+// of one above it. 4.3.4 keeps this as frame flag 0x100000: setting it moves
+// the frame (and its children) to the parent's level, and the level setter
+// replaces any level it is given with the parent's while the flag is on. So
+// SetParent's parent level + 1, a parent's level change passed down to its
+// children, and SetFrameLevel all land on the parent's level. The XML
+// attribute is read after the node loads, when the frame has its parent, and
+// only when present and non-empty, so a node's value overrides its template's.
+//
+// 1.12's level setter (FUN_FRAME_SET_FRAME_LEVEL) is 4.3.4's without the
+// flag test; the hook adds it in front. The setter's recursion into children
+// calls its own entry, so it goes through the hook too.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "xml/FrameLoad.h"
+
+#include
+
+namespace Frame::UseParentLevel {
+
+namespace {
+
+using SetFrameLevel_t = void(__fastcall *)(void *frame, void *edx, int level, int children);
+using SetFrameFlag_t = void(__fastcall *)(void *frame, void *edx, uint32_t mask, int on);
+
+SetFrameLevel_t g_origSetFrameLevel = nullptr;
+
+bool Using(void *frame) {
+ return (Game::Read(frame, Offsets::OFF_FRAME_FLAGS) & Offsets::FRAME_FLAG_USE_PARENT_LEVEL) != 0;
+}
+
+void __fastcall SetFrameLevel_h(void *frame, void *edx, int level, int children) {
+ void *parent = Game::Read(frame, Offsets::OFF_REGION_PARENT);
+ if (parent != nullptr && Using(frame))
+ level = Game::Read(parent, Offsets::OFF_FRAME_LEVEL);
+ g_origSetFrameLevel(frame, edx, level, children);
+}
+
+const Game::HookAutoRegister _hook{Offsets::FUN_FRAME_SET_FRAME_LEVEL, reinterpret_cast(&SetFrameLevel_h),
+ reinterpret_cast(&g_origSetFrameLevel)};
+
+// 4.3.4's CSimpleFrame::SetUseParentLevel.
+void Set(void *frame, bool on) {
+ reinterpret_cast(Offsets::FUN_FRAME_SET_FRAME_FLAG)(
+ frame, nullptr, Offsets::FRAME_FLAG_USE_PARENT_LEVEL, on);
+ void *parent = Game::Read(frame, Offsets::OFF_REGION_PARENT);
+ if (on && parent != nullptr)
+ SetFrameLevel_h(frame, nullptr, Game::Read(parent, Offsets::OFF_FRAME_LEVEL), 1);
+}
+
+void OnFrameNode(void *object, const void *node, void * /*status*/) {
+ const char *value = Xml::Attr(node, "useParentLevel");
+ if (value == nullptr || *value == '\0')
+ return;
+ Set(object, Game::StringToFlag(value));
+}
+
+const Xml::FrameLoad::AutoSubscribe _xmlSub{&OnFrameNode};
+
+int __fastcall Script_SetUsingParentLevel(void *L) {
+ void *frame = Game::Lua::ResolveFrame(L);
+ if (frame == nullptr)
+ return 0;
+ Set(frame, Game::Lua::ToFlag(L, 2));
+ return 0;
+}
+
+int __fastcall Script_IsUsingParentLevel(void *L) {
+ void *frame = Game::Lua::ResolveFrame(L);
+ if (frame == nullptr)
+ return 0;
+ Game::Lua::PushBool(L, Using(frame));
+ return 1;
+}
+
+const Game::Lua::FrameMethodEntry g_methods[] = {
+ {"SetUsingParentLevel", &Script_SetUsingParentLevel},
+ {"IsUsingParentLevel", &Script_IsUsingParentLevel},
+};
+
+const Game::Doc::Field kSetArgs[] = {
+ Game::Doc::Req("usingParentLevel", "boolean",
+ "When true, the frame draws at its parent's frame level instead of one above it."),
+};
+const Game::Doc::Field kIsRets[] = {
+ Game::Doc::Req("usingParentLevel", "boolean", "True when the frame uses its parent's frame level."),
+};
+const Game::Doc::Function kSetUsingParentLevel{"Sets whether the frame uses its parent's frame level.", kSetArgs,
+ {}};
+const Game::Doc::Function kIsUsingParentLevel{"Returns whether the frame uses its parent's frame level.", {},
+ kIsRets};
+
+const Game::Doc::Method g_methodDocs[] = {
+ {"SetUsingParentLevel", &kSetUsingParentLevel},
+ {"IsUsingParentLevel", &kIsUsingParentLevel},
+};
+
+void RegisterLuaFunctions() {
+ Game::Lua::RegisterFrameMethods(
+ reinterpret_cast(Offsets::VAR_FRAME_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::UseParentLevel