API.md

   1 # Select Item API
   2 With this API you can open the item selection dialog as well as
   3 catch events when players select an item from this dialog.
   4
   5 You can safely optionally depend on this mod, just make sure
   6 to check for the mod's existence first (`minetest.get_modpath`
   7 returns non-`nil` value).
   8
   9 ## Functions
  10 ### `select_item.show_dialog(playername, dialogname, filter, compare)`
  11 Shows an item selection dialog to a player. The player can choose
  12 one item (which triggers a callback) or abort selection
  13 (in which case nothing happens).
  14
  15 By default, this displays all items with the exception of unknown
  16 items and `ignore`. This also includes items which players may
  17 normally not be supposed to see, like those usually not found in
  18 so-called “creative inventories”. You should set the `filter` argument
  19 to filter out unwanted items.
  20
  21 The items are also sorted by a sorting rule.
  22
  23 #### Parameters
  24 * `playername`: Name of player to show dialog to
  25 * `dialogname`: Identifier of the dialog (must not contain “%%”)
  26 * `filter`: (optional) Filter function to narrow down the visible
  27             items (see below)
  28 * `compare`: (optional) Custom compare function for sorting,
  29              used in `table.sort`.
  30
  31 Recommended form of `dialogname` is “`<modname>:<name>`”. Almost all
  32 names are allowed, but they must never contain the substring “%%”.
  33 Example: `example:select_my_item`
  34
  35 Default sorting sorts items alphabetically by itemstring. It
  36 moves items with empty description to the end, preceded by items
  37 with description, but `not_in_creative_inventory=1`, and then
  38 everything else to the beginning.
  39
  40 ##### Filter function
  41 The filter function has the function signature `filter(itemstring)`.
  42 This function will be called for each item with the itemstring
  43 given as argument. The function must return `true` if the item
  44 in question is allowed in the selection dialog and `false` if
  45 it must not appear.
  46
  47 You can also choose one of the following pre-defined filter functions:
  48
  49 * `select_item.filters.creative`: Removes all items with group
  50   `not_in_creative_inventory=1` and/or empty `description`
  51 * `select_item.filters.all`: Does not filter anything. Same as `nil`.
  52
  53 ### `select_item.register_on_select_item(callback)`
  54 Register a call function `callback` to the `select_item` mod.
  55 Whenever a player selects an item or cancels the selection,
  56 `callback` is called.
  57
  58 #### `callback` function
  59 This has the function signature `callback(playername, dialogname, itemstring)`.
  60
  61 * `playername` is the name of the player who selected the item
  62 * `dialogname` is the dialog identifier of the item selection dialog being used
  63 * `itemstring` is the itemstring of the chosen item or `nil` if aborted
  64
  65 Normally, if the player pushes any button, the formspec is closed.
  66 But if you return `false` in this callback, the formspec is *not* closed.
  67
  68 ## Examples
  69 Display all items from Creative inventory to Player 1:
  70
  71 ```
  72 select_item.show_dialog("Player 1", "example:creative", select_item.filters.creative)
  73 ```
  74
  75 Display all flammable to Player 1:
  76
  77 ```
  78 select_item.show_dialog("Player 1", "example:flammable", function(itemstring)
  79         if minetest.get_item_group(itemstring, "flammable") >= 1 then
  80                 return true
  81         else
  82                 return false
  83         end
  84 end
  85 ```
  86
  87 Note the different values for `dialogname`.
  88
  89 Adding a selected to the player's inventory after player selected item in the “Creative” dialog
  90 above:
  91
  92 ```
  93 select_item.register_on_select_item(function(playername, dialogname, itemstring)
  94         --[[ Check for the dialog type you care about. This check should almost always be done
  95         to ensure interoperability with other mods. ]]
  96         if dialogname == "example:creative" then
  97                 local inv = minetest.get_inventory({type="player", location=playername})
  98                 inv:add_item("main", ItemStack(itemstring))
  99         end
 100 end)
 101 ```