Write basic documentation

API.md

@@ -0,0 +1,72 @@
+# Select Item API
+With this API you can open the item selection dialog as well as
+catch events when players select an item from this dialog.
+
+You can safely optionally depend on this mod, just make sure
+to check for the mod's existance first (`minetest.get_modpath`
+returns non-`nil` value).
+
+## Functions
+### `select_item.show_dialog(playername, filter)`
+Shows an item selection dialog to a player. The player can choose
+one item (which triggers a callback) or abort selection
+(in which case nothing happens).
+
+By default, this displays almost all items with the exception of
+unknown items and `ignore`. This also includes items which players
+may normally not be supposed to see, especially those not
+found in Creative Inventory. You should set the `filter` argument
+to filter out unwanted items.
+
+#### Parameters
+* `playername`: Name of player to show dialog to
+* `filter`: Optional filter function to narrow down the visible
+   items (see below)
+
+#### Filter function
+The filter function has the function signature `filter(itemstring)`.
+This function will be called for each item with the itemstring
+given as argument. The function shall return `true` if the item
+in question is allowed in the selection dialog and `false` if
+it must not appear.
+
+You can also choose one of the following pre-defined filter functions:
+
+* `select_item.filters.creative`: Removes all items with group
+  `not_in_creative_inventory=1` and/or empty `description`
+* `select_item.filters.all`: Does not filter anything. Same as `nil`.
+
+### `select_item.register_on_select_item(callback)`
+Register a call function `callback` to the `select_item` mod.
+Whenever a player selects an item, `callback` is called.
+
+#### `callback` function
+This has the function signature `callback(playername, itemstring)`.
+
+`playername` is the name of the player who selected the item,
+`itemstring` is the itemstring of the chosen item.
+
+## Examples
+Display all items from Creative inventory to player 1:
+```
+select_item.show_dialog("Player 1", select_item.filters.creative)
+```
+
+Display all flammable to Player 1:
+```
+select_item.show_dialog("Player 1", function(itemstring)
+	if minetest.get_item_group(itemstring), "flammable") >= 1 then
+		return true
+	else
+		return false
+	end
+end
+```
+
+Adding a selected to the player's inventory:
+```
+select_item.register_on_select_item(function(playername, itemstring)
+	local inv = minetest.get_inventory({type="player" location=playername})
+	inv:add_item("main", ItemStack(itemstring))
+end)
+```

README.md

@@ -0,0 +1,13 @@
+# Item Selection [`select_item`]
+This mod provides a simple dialog for players to select an item from.
+
+This mod is useless on its own and is only required as a dependency
+by other mods. Modders can use this mod to improve their interfaces.
+
+If you're a modder, see `API.md` to learn how it works.
+
+Version: 0.1.0
+
+## License
+This mod is free software.
+License of this entire mod: MIT License