diff --git a/docs/API.md b/docs/API.md index 7f30f6d6..289161fa 100644 --- a/docs/API.md +++ b/docs/API.md @@ -644,7 +644,7 @@ build instructions. - [`GetMacroIcons` / `GetMacroItemIcons` / `GetLooseMacroIcons` / `GetLooseMacroItemIcons`](#getmacroicons--getmacroitemicons--getloosemacroicons--getloosemacroitemicons) - [`C_Macro.CreateMacro` / `C_Macro.EditMacro`](#c_macrocreatemacro--c_macroeditmacro) - [`C_Macro.GetMacroIcon(macroSlot)`](#c_macrogetmacroiconmacroslot) - - [`C_Macro.SetMacroDisplay(macroSlot, value)`](#c_macrosetmacrodisplaymacroslot-value) + - [`C_Macro.SetMacroDisplay(macroSlot, value [, unit])`](#c_macrosetmacrodisplaymacroslot-value--unit) - [Mail](#mail) - [`GetSendMailItemLink([attachmentIndex])`](#getsendmailitemlinkattachmentindex) @@ -14968,7 +14968,7 @@ to. If SuperCleveRoidMacros is loaded, it controls macro display, and ClassicAPI does not evaluate `#showtooltip`. A build that hands its own results over through -[`C_Macro.SetMacroDisplay`](#c_macrosetmacrodisplaymacroslot-value) keeps +[`C_Macro.SetMacroDisplay`](#c_macrosetmacrodisplaymacroslot-value--unit) keeps `#showtooltip` working for the macros it does not claim. A macro that names a condition @@ -15342,7 +15342,7 @@ mark, and the macro's own icon otherwise. selector edits. Use this function when you want the icon a macro shows, and `GetMacroInfo` when you want the one the player picked. -### `C_Macro.SetMacroDisplay(macroSlot, value)` +### `C_Macro.SetMacroDisplay(macroSlot, value [, unit])` Tells the client what a macro is about, so the action button shows it. For an addon that parses macros itself and wants the button to follow, instead @@ -15350,9 +15350,10 @@ of replacing `GetActionTexture`, `GetActionCooldown`, `IsUsableAction` and the rest in Lua. ```lua -C_Macro.SetMacroDisplay(1, "Frostbolt") -- show this -C_Macro.SetMacroDisplay(1, false) -- mine, nothing matched, show ? -C_Macro.SetMacroDisplay(1, nil) -- released, `#showtooltip` resumes +C_Macro.SetMacroDisplay(1, "Frostbolt") -- show this +C_Macro.SetMacroDisplay(1, "Flash Heal", "mouseover") -- show this, range to the mouseover +C_Macro.SetMacroDisplay(1, false) -- mine, nothing matched, show ? +C_Macro.SetMacroDisplay(1, nil) -- released, `#showtooltip` resumes ``` `macroSlot` is the macro index, the same one @@ -15366,6 +15367,31 @@ it, the same as a directive that names its own value. Returns `true` when the value named a spell or an item. +**The range unit.** `unit` is optional. It names the unit that the button's +range check uses in place of your target. Usually it is the `[@unit]` of the +clause that your parser matched. It takes any unit token or GUID string that +`UnitExists` takes, for example `"mouseover"`, `"focus"` or +`"party2target"`. If you give no `unit`, or `nil`, the range check uses your +target. + +The client finds the unit again each time it checks the button's range. So +if `"mouseover"` moves to a different unit, the range follows it with no new +call. The same is true for `"focus"`, `"target"` and every other token. This +is different from the `target` of +[`SetMacroSpell`](#setmacrospellmacro-spell--target--setmacroitemmacro-item--target), +which is found once, when you call it. + +If the token points at no unit at that time, for example `"mouseover"` with +nothing under the cursor, the range check uses your target. If the unit is +too far away for the client to see it, for example a party member in another +zone, the button has no range state. + +The function ignores `unit` when `value` is `false`, `nil` or an empty +string, because the macro then aims at nothing. A call with the same `value` +and a different `unit` changes the unit. If `unit` is not a unit token, the +function raises the error `Unknown unit name: `, the same error that +`UnitExists` gives. Then it publishes nothing. + **What the button picks up.** The spell is written where the client keeps each macro's spell, which is the field its own buttons read. So cooldown, range, usable, out-of-mana greying, the current-cast highlight and @@ -15379,8 +15405,8 @@ button, on the cursor while you drag the macro, and in the macro window. The icon replaces the macro's own only when that is the question mark, which is the same rule `#showtooltip` follows. A macro with a chosen icon keeps it. -**Call it whenever your answer changes.** Nothing is re-evaluated for you. -The value stands until you publish another, and it survives the client +**Call it whenever your answer changes.** Nothing is re-evaluated for you, +except the unit that a `unit` token points at. The value stands until you publish another, and it survives the client re-reading the macro, so an edit elsewhere cannot quietly replace it. Publishing takes the macro over: `#showtooltip` is not parsed for it while diff --git a/src/macro/Display.cpp b/src/macro/Display.cpp index c9b83c87..0b2e85f0 100644 --- a/src/macro/Display.cpp +++ b/src/macro/Display.cpp @@ -11,7 +11,7 @@ // You should have received a copy of the GNU General Public License along with // ClassicAPI. If not, see . -// `C_Macro.SetMacroDisplay(macroSlot, value)` — the Lua door onto +// `C_Macro.SetMacroDisplay(macroSlot, value [, unit])` — the Lua door onto // `Macro::ShowTooltip::Publish`, for an addon that has its own macro parser // and wants the display done properly rather than by replacing the action // globals. See the ShowTooltip header for what publishing buys. @@ -27,6 +27,12 @@ // item-before-spell precedence, `item:N`, links, inventory slots and // `bag slot` for free. // +// `unit` is the `[@unit]` the publisher's clause matched: the unit the +// button's range check uses. Unlike `SetMacroSpell`'s target it stays a +// token, resolved at every lookup (`PublishOptions::liveUnit`), so a +// publisher whose clause still matches need not republish when the +// mouseover, focus or target moves. +// // `SetMacroSpell(macro, spell [, target])` and `SetMacroItem(macro, item // [, target])` are 4.3.4's narrower doors onto the same publish: a spellbook // spell only, or an item only, aimed at `target` (the unit the button's range @@ -37,6 +43,7 @@ #include "Offsets.h" #include "macro/Arg.h" #include "macro/ShowTooltip.h" +#include "unit/Identity.h" #include @@ -46,7 +53,7 @@ namespace { int __fastcall Script_C_Macro_SetMacroDisplay(void *L) { if (!Game::Lua::IsNumber(L, 1)) { - Game::Lua::Error(L, "Usage: C_Macro.SetMacroDisplay(macroSlot, value)"); + Game::Lua::Error(L, "Usage: C_Macro.SetMacroDisplay(macroSlot, value [, unit])"); return 0; } const int macroSlot = static_cast(Game::Lua::ToNumber(L, 1)); @@ -63,7 +70,17 @@ int __fastcall Script_C_Macro_SetMacroDisplay(void *L) { } const char *value = Game::Lua::IsString(L, 2) ? Game::Lua::ToString(L, 2) : nullptr; - Game::Lua::PushBoolean(L, Macro::ShowTooltip::Publish(macroSlot, value) ? 1 : 0); + Macro::ShowTooltip::PublishOptions options; + // A value that names nothing aims at nothing, so its unit is not read. + if (value != nullptr && value[0] != '\0' && Game::Lua::IsString(L, 3)) { + options.unit = Game::Lua::ToString(L, 3); + options.liveUnit = true; + // The engine's resolver vets the token: anything that is not one + // raises its "Unknown unit name" error, exactly as UnitExists does, + // before anything is published. + Unit::Identity::GuidForToken(options.unit); + } + Game::Lua::PushBoolean(L, Macro::ShowTooltip::Publish(macroSlot, value, options) ? 1 : 0); return 1; } diff --git a/src/macro/ShowTooltip.cpp b/src/macro/ShowTooltip.cpp index 50435b29..c405e71d 100644 --- a/src/macro/ShowTooltip.cpp +++ b/src/macro/ShowTooltip.cpp @@ -160,6 +160,9 @@ struct Entry { uint32_t isPet = 0; int itemID = 0; uint64_t unit = 0; // Info::unit + // A published `PublishOptions::liveUnit` token, resolved afresh by every + // lookup in place of `unit`. Empty for none. + char unitToken[kOptionsMax] = {}; uint32_t lastEvalMs = 0; }; @@ -1233,7 +1236,8 @@ bool LookupEntries(uint32_t macroID, Info *out) { out->spellID = e.spellID; out->isPet = e.isPet; out->itemID = e.itemID; - out->unit = e.unit; + out->unit = e.unitToken[0] != '\0' ? ::Unit::Identity::GuidForToken(e.unitToken) + : e.unit; // A publisher re-publishes the moment its answer changes, so a claimed // macro never needs the polling refresh a condition of ours does. out->conditional = false; @@ -1327,7 +1331,13 @@ bool Publish(int macroSlot, const char *value, const PublishOptions &options) { ResolveValue(value, &r, /*explicitValue=*/true, /*itemOnly=*/options.accept == Accept::Item); } - r.unit = UnitGuid(options.unit); + // Set on every publish, so one that changes only the unit still lands: + // `ApplyResolution` stores the unit before its unchanged-value early out. + if (options.liveUnit && options.unit != nullptr) + std::snprintf(e.unitToken, sizeof(e.unitToken), "%s", options.unit); + else + e.unitToken[0] = '\0'; + r.unit = options.liveUnit ? 0 : UnitGuid(options.unit); BusyScope busy; ApplyResolution(L, e, r, matched); diff --git a/src/macro/ShowTooltip.h b/src/macro/ShowTooltip.h index 2e69d9ce..f42f42bc 100644 --- a/src/macro/ShowTooltip.h +++ b/src/macro/ShowTooltip.h @@ -72,8 +72,10 @@ struct Info { // from it has to keep re-reading while the cursor rests on the button. bool conditional; // The unit the macro's spell is aimed at, 4.3.4's MACRONODE::m_target: the - // `[@unit]` of the clause that matched, or the target a `SetMacroSpell` / - // `SetMacroItem` named. 0 means the current target, as for any action. + // `[@unit]` of the clause that matched, the target a `SetMacroSpell` / + // `SetMacroItem` named, or whoever the token a `SetMacroDisplay` named + // points at as of this lookup. 0 means the current target, as for any + // action. uint64_t unit; }; @@ -86,6 +88,12 @@ struct PublishOptions { Accept accept = Accept::Any; // A unit token or a name the spell is aimed at; null for the current target. const char *unit = nullptr; + // Resolve `unit` at every lookup rather than once, here, so the macro + // keeps following whoever the token names (a new mouseover, focus or + // target) with no republish. `unit` must then be a token the engine's + // resolver accepts: one that resolves once never raises later, since the + // resolver tells a token's family from its spelling alone. + bool liveUnit = false; // The claim ends when the macro's body is edited, as 4.3.4's SetMacroSpell // and SetMacroItem last only until the macro is parsed again. Otherwise it // lasts until `Release` or a reload.