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 +++++++++++++++++++++-
 Server/Plugins/APIDump/Classes/Plugins.lua         |  4 +++
 .../APIDump/Hooks/OnPlayerOpeningWindow.lua        | 20 ++++++++++++++
 3 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 Server/Plugins/APIDump/Hooks/OnPlayerOpeningWindow.lua

(limited to 'Server')

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);
 
diff --git a/Server/Plugins/APIDump/Classes/Plugins.lua b/Server/Plugins/APIDump/Classes/Plugins.lua
index c00735412..e22f4e3a0 100644
--- a/Server/Plugins/APIDump/Classes/Plugins.lua
+++ b/Server/Plugins/APIDump/Classes/Plugins.lua
@@ -840,6 +840,10 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage);
 			{
 				Notes = "Called when the player has moved and the movement is now being applied.",
 			},
+			HOOK_PLAYER_OPENING_WINDOW =
+			{
+				Notes = "Called when the player is about to open a window. The plugin can return true to cancel the window opening.",
+			},
 			HOOK_PLAYER_PLACED_BLOCK =
 			{
 				Notes = "Called when the player has just placed a block",
diff --git a/Server/Plugins/APIDump/Hooks/OnPlayerOpeningWindow.lua b/Server/Plugins/APIDump/Hooks/OnPlayerOpeningWindow.lua
new file mode 100644
index 000000000..04563df89
--- /dev/null
+++ b/Server/Plugins/APIDump/Hooks/OnPlayerOpeningWindow.lua
@@ -0,0 +1,20 @@
+return
+{
+	HOOK_PLAYER_OPENING_WINDOW =
+	{
+		CalledWhen = "Called when a player is about to open a window",
+		DefaultFnName = "OnPlayerOpeningWindow",  -- also used as pagename
+		Desc = [[
+			This hook is called when a player is about to open a window, e.g. when they click on a chest or a furnace.
+		]],
+		Params =
+		{
+			{ Name = "Player", Type = "{{cPlayer}}", Notes = "The player who is opening the window" },
+			{ Name = "Window", Type = "{{cWindow}}", Notes = "The window that is being opened" },
+		},
+		Returns = [[
+			If the function returns false or no value, the next plugin's callback is called, and finally
+			Cuberite will process the opening window. If the function returns true, no other callback is called for this event.
+		]],
+	},  -- HOOK_PLAYER_OPENING_WINDOW
+}
-- 
cgit v1.2.3