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, 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)
```