minetest_select_item/API.md

# 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 existence first (`minetest.get_modpath`
returns non-`nil` value).

## Functions
### `select_item.show_dialog(playername, dialogname, filter, compare)`
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 all items with the exception of unknown
items and `ignore`. This also includes items which players may
normally not be supposed to see, like those usually not found in
so-called “creative inventories”. You should set the `filter` argument
to filter out unwanted items.

The items are also sorted by a sorting rule.

#### Parameters
* `playername`: Name of player to show dialog to
* `dialogname`: Identifier of the dialog (must not contain “%%”)
* `filter`: (optional) Filter function to narrow down the visible
            items (see below)
* `compare`: (optional) Custom compare function for sorting,
             used in `table.sort`.

Recommended form of `dialogname` is “`<modname>:<name>`”. Almost all
names are allowed, but they must never contain the substring “%%”.
Example: `example:select_my_item`

Default sorting sorts items alphabetically by itemstring. It
moves items with empty description to the end, preceded by items
with description, but `not_in_creative_inventory=1`, and then
everything else to the beginning.

##### 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 must 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 or cancels the selection,
`callback` is called.

#### `callback` function
This has the function signature `callback(playername, dialogname, itemstring)`.

* `playername` is the name of the player who selected the item
* `dialogname` is the dialog identifier of the item selection dialog being used
* `itemstring` is the itemstring of the chosen item or `nil` if aborted

Normally, if the player pushes any button, the formspec is closed.
But if you return `false` in this callback, the formspec is *not* closed.

## Examples
Display all items from Creative inventory to Player 1:

```
select_item.show_dialog("Player 1", "example:creative", select_item.filters.creative)
```

Display all flammable to Player 1:

```
select_item.show_dialog("Player 1", "example:flammable", function(itemstring)
	if minetest.get_item_group(itemstring, "flammable") >= 1 then
		return true
	else
		return false
	end
end
```

Note the different values for `dialogname`.

Adding a selected to the player's inventory after player selected item in the “Creative” dialog
above:

```
select_item.register_on_select_item(function(playername, dialogname, itemstring)
	--[[ Check for the dialog type you care about. This check should almost always be done
	to ensure interoperability with other mods. ]]
	if dialogname == "example:creative" then
		local inv = minetest.get_inventory({type="player", location=playername})
		inv:add_item("main", ItemStack(itemstring))
	end
end)
```