input: add GetMouseButtonClicked()

Returns the button name of the most recent mouse-button message
("LeftButton"/.../"Button5"), or nil before any click. Rides the
existing WH_GETMESSAGE stream in GlobalMouse that already backs
GLOBAL_MOUSE_DOWN/UP and IsMouseButtonDown, so no engine hook is
needed: g_lastButton is captured on every press/release, and the
Script fn pushes it (null tail-jumps to pushnil for the "no click
yet" case).

The hook runs at message-dequeue, synchronously before the engine
dispatches the click to the Lua handler, so the value reflects the
button of the handler currently running (and is readable from nested
helpers where arg1 isn't in scope). Not cleared between events -- no
"handler ended" signal in the 1.12 stream -- so outside a mouse
handler it returns the last-clicked button rather than nil; documented.

Author: brues-code

README.md

@@ -39,7 +39,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [Gossip](docs/API.md#gossip) | `C_GossipInfo.CloseGossip`, `C_GossipInfo.GetActiveQuests`, `C_GossipInfo.GetAvailableQuests`, `C_GossipInfo.GetNumActiveQuests`, `C_GossipInfo.GetNumAvailableQuests`, `C_GossipInfo.GetNumOptions`, `C_GossipInfo.GetOptions`, `C_GossipInfo.GetText`, `C_GossipInfo.SelectActiveQuest`, `C_GossipInfo.SelectAvailableQuest`, `C_GossipInfo.SelectOption`, `C_GossipInfo.SelectOptionByIndex` |
 | [GameTooltip](docs/API.md#gametooltip) | `GameTooltip:GetGameObject`, `GameTooltip:GetItem`, `GameTooltip:GetOwner`, `GameTooltip:GetSpell`, `GameTooltip:GetUnitGUID`, `GameTooltip:HasGameObject`, `GameTooltip:HasItem`, `GameTooltip:HasSpell`, `GameTooltip:HasUnit`, `GameTooltip:IsEquippedItem`, `GameTooltip:SetEquipmentSet`, `GameTooltip:SetHyperlinkCompareItem`, `GameTooltip:SetInventoryItemByID`, `GameTooltip:SetItemByGUID`, `GameTooltip:SetItemByID`, `GameTooltip:SetSpellByID`, `GameTooltip:SetTalentByID`, `GameTooltip:SetUnitAura`, `OnTooltipSetItem` (script) |
 | [Hooks](docs/API.md#hooks) | `hooksecurefunc` |
-| [Input](docs/API.md#input) | `IsLeftAltKeyDown`, `IsLeftControlKeyDown`, `IsLeftShiftKeyDown`, `IsModifierKeyDown`, `IsMouseButtonDown`, `IsRightAltKeyDown`, `IsRightControlKeyDown`, `IsRightShiftKeyDown` |
+| [Input](docs/API.md#input) | `GetMouseButtonClicked`, `IsLeftAltKeyDown`, `IsLeftControlKeyDown`, `IsLeftShiftKeyDown`, `IsModifierKeyDown`, `IsMouseButtonDown`, `IsRightAltKeyDown`, `IsRightControlKeyDown`, `IsRightShiftKeyDown` |
 | [Instance](docs/API.md#instance) | `GetInstanceInfo` |
 | [Item](docs/API.md#item) | `C_Item.DoesItemExist`, `C_Item.DoesItemExistByID`, `C_Item.EquipItemByName`, `C_Item.GetCurrentItemLevel`, `C_Item.GetDetailedItemLevelInfo`, `C_Item.GetEnchantInfo`, `C_Item.GetItemCount`, `C_Item.GetItemFamily`, `C_Item.GetItemGUID`, `C_Item.GetItemIcon`, `C_Item.GetItemIconByID`, `C_Item.GetItemID`, `C_Item.GetItemInfoInstant`, `C_Item.GetItemInventorySlotInfo`, `C_Item.GetItemInventorySlotKey`, `C_Item.GetItemInventoryType`, `C_Item.GetItemInventoryTypeByID`, `C_Item.GetItemLink`, `C_Item.GetItemLocation`, `C_Item.GetItemMaxStackSize`, `C_Item.GetItemMaxStackSizeByID`, `C_Item.GetItemName`, `C_Item.GetItemNameByID`, `C_Item.GetItemQuality`, `C_Item.GetItemQualityByID`, `C_Item.GetItemSellPrice`, `C_Item.GetItemSellPriceByID`, `C_Item.GetItemSetID`, `C_Item.GetItemSetIDByID`, `C_Item.GetItemSetInfo`, `C_Item.GetItemSpell`, `C_Item.GetItemStatDelta`, `C_Item.GetItemStats`, `C_Item.GetItemSubClassInfo`, `C_Item.GetItemUniqueness`, `C_Item.GetItemUniquenessByID`, `C_Item.GetStackCount`, `C_Item.GetWeaponEnchantInfo`, `C_Item.IsBound`, `C_Item.IsEquippableItem`, `C_Item.IsEquippedItem`, `C_Item.IsItemDataCached`, `C_Item.IsItemDataCachedByID`, `C_Item.IsItemGUIDInInventory`, `C_Item.IsItemOpenable`, `C_Item.IsLocked`, `C_Item.LockItem`, `C_Item.LockItemByGUID`, `C_Item.UnlockAllItems`, `C_Item.UnlockItem`, `C_Item.RequestLoadItemData`, `C_Item.RequestLoadItemDataByID`, `C_Item.UseAtCursor`, `C_Item.UseAtUnit`, `C_Item.UseItemByName`, `GetAuctionItemID`, `GetAuctionSellItemID`, `GetAverageItemLevel`, `GetCraftReagentItemID`, `GetInboxItemID`, `GetInventoryItemDurability`, `GetInventoryItemID`, `GetInventoryItemsForSlot`, `GetInventoryItemRepairCost`, `GetItemIcon`, `GetLootRollItemID`, `GetLootSlotItemID`, `GetMerchantItemID`, `GetQuestItemID`, `GetQuestLogItemID`, `GetTradePlayerItemID`, `GetTradeSkillItemID`, `GetTradeSkillReagentItemID`, `GetTradeTargetItemID`, `OffhandHasWeapon` |
 | [Loot](docs/API.md#loot) | `C_Loot.GetNearbyLootableUnits`, `C_Loot.GetLastScanResults`, `C_Loot.IsScanInProgress`, `C_Loot.LootUnit`, `C_Loot.LootUnitItem`, `C_Loot.ScanNearbyLoot` |

docs/API.md

@@ -194,6 +194,7 @@ build instructions.
   - [`IsLeftAltKeyDown()` / `IsRightAltKeyDown()`](#isleftaltkeydown--isrightaltkeydown)
   - [`IsModifierKeyDown()`](#ismodifierkeydown)
   - [`IsMouseButtonDown([button])`](#ismousebuttondownbutton)
+  - [`GetMouseButtonClicked()`](#getmousebuttonclicked)
 
 - [Instance](#instance)
   - [`GetInstanceInfo()`](#getinstanceinfo)
@@ -4297,6 +4298,34 @@ if IsMouseButtonDown("RightButton") then
 end
 ```
 
+### `GetMouseButtonClicked()`
+
+Returns the name of the button from the most recent mouse-button
+message (`"LeftButton"`, `"RightButton"`, `"MiddleButton"`,
+`"Button4"`, `"Button5"`), or `nil` before any click has occurred.
+
+Modern addons call this inside a mouse handler (`OnClick`,
+`OnMouseDown`, `OnMouseUp`, `OnDragStart`, …) to learn which button
+drove it — an alternative to reading vanilla's `arg1`, and readable
+from nested helper functions where `arg1` isn't in scope. The value
+is captured by the same `WH_GETMESSAGE` hook behind
+`GLOBAL_MOUSE_DOWN` / `GLOBAL_MOUSE_UP`, at message-dequeue —
+synchronously *before* the engine dispatches the click to the Lua
+handler — so it reflects the button of the handler currently running.
+
+It is not cleared between events, so outside a mouse handler it
+returns the last-clicked button rather than `nil` (the 1.12 message
+stream carries no "handler ended" signal to clear on). In practice
+it's only meaningful inside a mouse handler, matching how it's used.
+
+```lua
+button:SetScript("OnClick", function()
+    if GetMouseButtonClicked() == "RightButton" then
+        -- right-click behavior
+    end
+end)
+```
+
 ## Instance
 
 ### `GetInstanceInfo()`

src/input/GlobalMouse.cpp

@@ -24,6 +24,14 @@
 // as the events (single source of truth — events firing and the
 // state being readable happen at the same point in the pipeline).
 //
+// `GetMouseButtonClicked()` — the button name of the most recent
+// mouse button message (`"LeftButton"` / … / `"Button5"`), or nil
+// before any click. Modern addons call it inside a mouse handler to
+// learn which button drove it. The `WH_GETMESSAGE` hook runs at
+// message-dequeue, synchronously *before* the engine dispatches that
+// click to the Lua handler, so the value captured there is the right
+// one throughout the handler that the same message triggers.
+//
 // Same `WH_GETMESSAGE` thread-message hook pattern as
 // [Input::Modifier](Modifier.cpp): we intercept the WM_*BUTTON*
 // messages on the engine's main thread *before* dispatch. The hook
@@ -59,6 +67,13 @@ constexpr uint32_t MASK_ANY_BUTTON = 0x1F;
 
 uint32_t g_mouseButtonMask = 0;
 
+// Name of the button from the most recent mouse-button message, or
+// nullptr before any click. Points at one of DecodeButton's string
+// literals (stable for the process lifetime), so storing the pointer
+// is safe. `lua_pushstring(L, nullptr)` tail-jumps to pushnil, so a
+// null here surfaces as nil to the Lua caller with no extra branch.
+const char *g_lastButton = nullptr;
+
 HHOOK g_msgHook = nullptr;
 
 // Maps WM_*BUTTON{DOWN,UP} → ("LeftButton"|..., isDown). Returns
@@ -101,6 +116,11 @@ void ProcessMouseMessage(UINT msg, WPARAM wParam) {
     if (name == nullptr)
         return;
 
+    // Capture for GetMouseButtonClicked on both press and release —
+    // during an OnClick / OnMouseUp handler the "clicked" button is the
+    // one just released, same as the press for a normal click.
+    g_lastButton = name;
+
     const int bitIdx = NameToBitIdx(name);
     if (bitIdx >= 0) {
         const uint32_t bit = 1u << bitIdx;
@@ -136,6 +156,13 @@ int __fastcall Script_IsMouseButtonDown(void *L) {
     return 1;
 }
 
+int __fastcall Script_GetMouseButtonClicked(void *L) {
+    // Null → pushnil (the engine's pushstring tail-jumps on NULL), so
+    // callers before any click see nil, matching the modern API.
+    Game::Lua::PushString(L, g_lastButton);
+    return 1;
+}
+
 LRESULT CALLBACK GetMsgHook(int code, WPARAM wParam, LPARAM lParam) {
     // Only process when the message is being removed from the queue
     // (`PM_REMOVE` / `GetMessage`); `PM_NOREMOVE` peeks would deliver
@@ -157,6 +184,8 @@ void InstallHook() {
 void RegisterLuaFunctions() {
     Game::Lua::RegisterGlobalFunction("IsMouseButtonDown",
                                       &Script_IsMouseButtonDown);
+    Game::Lua::RegisterGlobalFunction("GetMouseButtonClicked",
+                                      &Script_GetMouseButtonClicked);
     InstallHook();
 }