Documentation for footer-button API

API.md

@@ -1,15 +1,16 @@
 # API :screwdriver:
 
 ### Table of Contents
-1. [**Tabs**](https://github.com/minetest-mods/i3/blob/main/API.md#tabs)
-2. [**Recipes**](https://github.com/minetest-mods/i3/blob/main/API.md#recipes)
-3. [**Minitabs**](https://github.com/minetest-mods/i3/blob/main/API.md#minitabs)
-4. [**Recipe filters**](https://github.com/minetest-mods/i3/blob/main/API.md#recipe-filters)
-5. [**Search filters**](https://github.com/minetest-mods/i3/blob/main/API.md#search-filters)
-6. [**Sorting methods**](https://github.com/minetest-mods/i3/blob/main/API.md#sorting-methods)
-7. [**Item list compression**](https://github.com/minetest-mods/i3/blob/main/API.md#item-list-compression)
-8. [**Waypoints**](https://github.com/minetest-mods/i3/blob/main/API.md#waypoints)
-9. [**Miscellaneous**](https://github.com/minetest-mods/i3/blob/main/API.md#miscellaneous)
+1. [**Tabs**](#tabs)
+2. [**Footer buttons**](#footer-buttons)
+3. [**Recipes**](#recipes)
+4. [**Minitabs**](#minitabs)
+5. [**Recipe filters**](#recipe-filters)
+6. [**Search filters**](#search-filters)
+7. [**Sorting methods**](#sorting-methods)
+8. [**Item list compression**](#item-list-compression)
+9. [**Waypoints**](#waypoints)
+10. [**Miscellaneous**](#miscellaneous)
 
 ---
 
@@ -88,6 +89,66 @@ A list of registered tabs.
 
 ---
 
+### Footer buttons
+
+`i3.new_footer_button(name, def)`
+
+* `name` is the footer button’s name.
+* `def` is the button defintion.
+
+Custom footer buttons can be added beside the trash, sort, and settings buttons. For example:
+
+```Lua
+i3.new_footer_button("broadcast_msg", {
+	description = "Broadcast message",
+	image = "speech_icon.png", -- Required, this is the button’s icon.
+
+	--
+	-- The functions below are all optional
+	--
+
+	-- Determine if the button is visible by a player, return false to hide the button.
+	access = function(player, data)
+		return true
+	end,
+
+	-- Build the formspec
+	formspec = function(player, data, fs)
+		-- Button style nicked from i3 directly.
+		fs([[
+		   style[send_msg_button,confirm_trash_no,set_home;noclip=true;font_size=16;
+		   bgimg=i3_btn9.png;bgimg_hovered=i3_btn9_hovered.png;
+		   bgimg_pressed=i3_btn9_pressed.png;bgimg_middle=4,6]
+		]])
+
+		fs("image[5,10.65;3,0.5;i3_bg_goto.png]")
+		fs("field[5,10.65;3,0.5;chat_msg_field;;]")
+		fs("button[8,10.65;1,0.5;send_msg_button;Send]")
+		-- No need to return anything
+	end,
+
+	-- Events handling happens here
+	fields = function(player, data, fields)
+		if fields.key_enter_field == "chat_msg_field" or fields.send_msg_button then
+			minetest.chat_send_all("Broadcast: " .. fields.chat_msg_field)
+			return false -- To close a footer button’s dialogue, return false.
+		end
+		return true -- To keep a footer button active, return true.
+	end,
+})
+```
+#### `i3.remove_footer_button(button_name)`
+
+Delete a footer button by name.
+
+#### `i3.override_footer_button(button_name, def)`
+
+Override a footer button by name. `def` is the button definition like seen in `i3.new_footer_button`
+
+#### `i3.footer_buttons`
+
+A list of registered footer buttons.
+
 ### Recipes
 
 Custom recipes are nonconventional crafts outside the main crafting grid.