From 1ec85a2b2cb285bcc019258c8fddcddfcda84fa8 Mon Sep 17 00:00:00 2001
From: Lane Kolbly <lane@rscheme.org>
Date: Thu, 17 Aug 2017 09:27:43 -0500
Subject: Add cLuaWindow OnClicked Callback (#3901)

---
 Server/Plugins/APIDump/APIDesc.lua | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

(limited to 'Server/Plugins/APIDump/APIDesc.lua')

diff --git a/Server/Plugins/APIDump/APIDesc.lua b/Server/Plugins/APIDump/APIDesc.lua
index bcc9b8ec4..38340d0f3 100644
--- a/Server/Plugins/APIDump/APIDesc.lua
+++ b/Server/Plugins/APIDump/APIDesc.lua
@@ -8029,6 +8029,17 @@ This class is used by plugins wishing to display a custom window to the player,
 					},
 					Notes = "Returns the cItemGrid object representing the internal storage in this window",
 				},
+				SetOnClicked =
+				{
+					Params =
+					{
+						{
+							Name = "OnClickedCallback",
+							Type = "function",
+						},
+					},
+					Notes = "Sets the function that the window will call when it is about to process a click from a player. See {{#additionalinfo_1|below}} for the signature of the callback function.",
+				},
 				SetOnClosing =
 				{
 					Params =
@@ -8060,6 +8071,17 @@ This class is used by plugins wishing to display a custom window to the player,
 						The object calls the following functions at the appropriate time:
 					]],
 				},
+				{
+					Header = "OnClicked Callback",
+					Contents = [[
+						This callback, settable via the SetOnClicked() function, will be called when the player clicks a slot in the window. The callback can cancel the click.</p>
+<pre class="prettyprint lang-lua">
+function OnWindowClicked(a_Window, a_Player, a_SlotNum, a_ClickAction, a_ClickedItem)
+</pre>
+						<p>
+						The a_Window parameter is the cLuaWindow object representing the window, a_Player is the player who made the click, a_SlotNum is the slot the player clicked, a_ClickAction is the type of click the player made, and a_ClickedItem is the item the player clicked on, if applicable. If the function returns true, the click is cancelled (internally, the server resends the window slots to the player to keep the player in sync).
+					]],
+				},
 				{
 					Header = "OnClosing Callback",
 					Contents = [[
@@ -8086,7 +8108,7 @@ function OnWindowSlotChanged(a_Window, a_SlotNum)
 				{
 					Header = "Example",
 					Contents = [[
-						This example is taken from the Debuggers plugin, used to test the API functionality. It opens a window and refuse to close it 3 times. It also logs slot changes to the server console.
+						This example is taken from the Debuggers plugin, used to test the API functionality. It opens a window and refuse to close it 3 times. It also logs slot changes to the server console and prevents shift-clicking in the window.
 <pre class="prettyprint lang-lua">
 -- Callback that refuses to close the window twice, then allows:
 local Attempt = 1;
@@ -8101,10 +8123,18 @@ local OnSlotChanged = function(Window, SlotNum)
 	LOG("Window \"" .. Window:GetWindowTitle() .. "\" slot " .. SlotNum .. " changed.");
 end
 
+-- Prevent shift-clicking:
+local OnClicked = function(Window, ClickingPlayer, SlotNum, ClickAction, ClickedItem)
+	if ClickAction == caShiftLeftClick then
+		return true
+	end
+end
+
 -- Set window contents:
 -- a_Player is a cPlayer object received from the outside of this code fragment
 local Window = cLuaWindow(cWindow.wtHopper, 3, 3, "TestWnd");
 Window:SetSlot(a_Player, 0, cItem(E_ITEM_DIAMOND, 64));
+Window:SetOnClicked(OnClicked);
 Window:SetOnClosing(OnClosing);
 Window:SetOnSlotChanged(OnSlotChanged);
 
-- 
cgit v1.2.3