* `color` is color specified as a `ColorString`.
If the alpha component is left blank, the box will be semitransparent.
-### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
+### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>;<index event>]`
* Show a dropdown field
* **Important note**: There are two different operation modes:
* Fieldname data is transferred to Lua
* Items to be shown in dropdown
* Index of currently selected dropdown item
+* `index event` (optional, allowed parameter since formspec version 4): Specifies the
+ event field value for selected items.
+ * `true`: Selected item index
+ * `false` (default): Selected item value
-### `dropdown[<X>,<Y>;<W>,<H>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
+### `dropdown[<X>,<Y>;<W>,<H>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>;<index event>]`
* Show a dropdown field
* **Important note**: This syntax for dropdowns can only be used with the
* Fieldname data is transferred to Lua
* Items to be shown in dropdown
* Index of currently selected dropdown item
+* `index event` (optional, allowed parameter since formspec version 4): Specifies the
+ event field value for selected items.
+ * `true`: Selected item index
+ * `false` (default): Selected item value
### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
* There are two ways to use it:
1. handle the changed event (only changed scrollbar is available)
2. read the value on pressing a button (all scrollbars are available)
-* `orientation`: `vertical`/`horizontal`
+* `orientation`: `vertical`/`horizontal`. Default horizontal.
* Fieldname data is transferred to Lua
* Value of this trackbar is set to (`0`-`1000`) by default
* See also `minetest.explode_scrollbar_event`
* All provided states must be active for the style to apply.
* See [Styling Formspecs].
+### `set_focus[<name>;<force>]`
+
+* Sets the focus to the element with the same `name` parameter.
+* **Note**: This element must be placed before the element it focuses.
+* `force` (optional, default `false`): By default, focus is not applied for
+ re-sent formspecs with the same name so that player-set focus is kept.
+ `true` sets the focus to the specified element for every sent formspec.
+* The following elements have the ability to be focused:
+ * checkbox
+ * button
+ * button_exit
+ * image_button
+ * image_button_exit
+ * item_image_button
+ * table
+ * textlist
+ * dropdown
+ * field
+ * pwdfield
+ * textarea
+ * scrollbar
+
Migrating to Real Coordinates
-----------------------------
* alpha - boolean, whether to draw alpha in bgimg. Default true.
* bgcolor - color, sets button tint.
* bgcolor_hovered - color when hovered. Defaults to a lighter bgcolor when not provided.
+ * This is deprecated, use states instead.
* bgcolor_pressed - color when pressed. Defaults to a darker bgcolor when not provided.
+ * This is deprecated, use states instead.
* bgimg - standard background image. Defaults to none.
* bgimg_hovered - background image when hovered. Defaults to bgimg when not provided.
+ * This is deprecated, use states instead.
* bgimg_middle - Makes the bgimg textures render in 9-sliced mode and defines the middle rect.
See background9[] documentation for more details. This property also pads the
button's content when set.
* bgimg_pressed - background image when pressed. Defaults to bgimg when not provided.
+ * This is deprecated, use states instead.
+ * font - Sets font type. This is a comma separated list of options. Valid options:
+ * Main font type options. These cannot be combined with each other:
+ * `normal`: Default font
+ * `mono`: Monospaced font
+ * Font modification options. If used without a main font type, `normal` is used:
+ * `bold`: Makes font bold.
+ * `italic`: Makes font italic.
+ Default `normal`.
+ * font_size - Sets font size. Default is user-set. Can have multiple values:
+ * `<number>`: Sets absolute font size to `number`.
+ * `+<number>`/`-<number>`: Offsets default font size by `number` points.
+ * `*<number>`: Multiplies default font size by `number`, similar to CSS `em`.
* border - boolean, draw border. Set to false to hide the bevelled button pane. Default true.
* content_offset - 2d vector, shifts the position of the button's content without resizing it.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* scrollbar
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* table, textlist
+ * font - Sets font type. See button `font` property for more information.
+ * font_size - Sets font size. See button `font_size` property for more information.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* dropdown
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* field, pwdfield, textarea
* border - set to false to hide the textbox background and border. Default true.
+ * font - Sets font type. See button `font` property for more information.
+ * font_size - Sets font size. See button `font_size` property for more information.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* textcolor - color. Default white.
* image
* item_image
* noclip - boolean, set to true to allow the element to exceed formspec bounds. Default to false.
* label, vertlabel
+ * font - Sets font type. See button `font` property for more information.
+ * font_size - Sets font size. See button `font_size` property for more information.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* image_button (additional properties)
* fgimg - standard image. Defaults to none.
* fgimg_hovered - image when hovered. Defaults to fgimg when not provided.
+ * This is deprecated, use states instead.
* fgimg_pressed - image when pressed. Defaults to fgimg when not provided.
+ * This is deprecated, use states instead.
* NOTE: The parameters of any given image_button will take precedence over fgimg/fgimg_pressed
* tabheader
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* a button was pressed,
* Enter was pressed while the focus was on a text field
* a checkbox was toggled,
- * something was selecteed in a drop-down list,
+ * something was selected in a dropdown list,
* a different tab was selected,
* selection was changed in a textlist or table,
* an entry was double-clicked in a textlist or table,
* `button` and variants: If pressed, contains the user-facing button
text as value. If not pressed, is `nil`
* `field`, `textarea` and variants: Text in the field
- * `dropdown`: Text of selected item
+ * `dropdown`: Either the index or value, depending on the `index event`
+ dropdown argument.
* `tabheader`: Tab index, starting with `"1"` (only if tab changed)
* `checkbox`: `"true"` if checked, `"false"` if unchecked
* `textlist`: See `minetest.explode_textlist_event`
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* `search_center` is an optional boolean (default: `false`)
If true `pos` is also checked for the nodes
-* `minetest.find_nodes_in_area(pos1, pos2, nodenames)`: returns a list of
- positions.
+* `minetest.find_nodes_in_area(pos1, pos2, nodenames, [grouped])`
+ * `pos1` and `pos2` are the min and max positions of the area to search.
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
- * First return value: Table with all node positions
- * Second return value: Table with the count of each node with the node name
- as index.
+ * If `grouped` is true the return value is a table indexed by node name
+ which contains lists of positions.
+ * If `grouped` is false or absent the return values are as follows:
+ first value: Table with all node positions
+ second value: Table with the count of each node with the node name
+ as index
* Area volume is limited to 4,096,000 nodes
* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a
list of positions.
HTTP Requests
-------------
-
-* `minetest.request_http_api()`:
- * returns `HTTPApiTable` containing http functions if the calling mod has
- been granted access by being listed in the `secure.http_mods` or
- `secure.trusted_mods` setting, otherwise returns `nil`.
- * The returned table contains the functions `fetch`, `fetch_async` and
+* `minetest.get_http_api()`
+ * returns `HTTPApiTable` containing http functions.
+ * The returned table contains the functions `fetch_sync`, `fetch_async` and
`fetch_async_get` described below.
- * Only works at init time and must be called from the mod's main scope
- (not from a function).
* Function only exists if minetest server was built with cURL support.
- * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN
- A LOCAL VARIABLE!**
-* `HTTPApiTable.fetch(HTTPRequest req, callback)`
- * Performs given request asynchronously and calls callback upon completion
- * callback: `function(HTTPRequestResult res)`
- * Use this HTTP function if you are unsure, the others are for advanced use
+* `HTTPApiTable.fetch_sync(HTTPRequest req)`: returns HTTPRequestResult
+ * Performs given request synchronously
* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
* Performs given request asynchronously and returns handle for
`HTTPApiTable.fetch_async_get`
* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
* Return response data for given asynchronous HTTP request
+### `HTTPRequest` definition
+
+Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`.
+
+ {
+ url = "http://example.org",
+
+ timeout = 10,
+ -- Timeout for connection in seconds. Default is 3 seconds.
+
+ post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
+ -- Optional, if specified a POST request with post_data is performed.
+ -- Accepts both a string and a table. If a table is specified, encodes
+ -- table as x-www-form-urlencoded key-value pairs.
+ -- If post_data is not specified, a GET request is performed instead.
+
+ user_agent = "ExampleUserAgent",
+ -- Optional, if specified replaces the default minetest user agent with
+ -- given string
+
+ extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
+ -- Optional, if specified adds additional headers to the HTTP request.
+ -- You must make sure that the header strings follow HTTP specification
+ -- ("Key: Value").
+
+ multipart = boolean
+ -- Optional, if true performs a multipart HTTP request.
+ -- Default is false.
+ }
+
+### `HTTPRequestResult` definition
+
+Passed to `HTTPApiTable.fetch` callback. Returned by
+`HTTPApiTable.fetch_async_get`.
+
+ {
+ completed = true,
+ -- If true, the request has finished (either succeeded, failed or timed
+ -- out)
+
+ succeeded = true,
+ -- If true, the request was successful
+
+ timeout = false,
+ -- If true, the request timed out
+
+ code = 200,
+ -- HTTP status code
+
+ data = "response"
+ }
+
+
Storage API
-----------
-- Otherwise, the default behavior is used. (currently: any random tile)
}
-`HTTPRequest` definition
-------------------------
-
-Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`.
-
- {
- url = "http://example.org",
-
- timeout = 10,
- -- Timeout for connection in seconds. Default is 3 seconds.
-
- post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
- -- Optional, if specified a POST request with post_data is performed.
- -- Accepts both a string and a table. If a table is specified, encodes
- -- table as x-www-form-urlencoded key-value pairs.
- -- If post_data is not specified, a GET request is performed instead.
-
- user_agent = "ExampleUserAgent",
- -- Optional, if specified replaces the default minetest user agent with
- -- given string
-
- extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
- -- Optional, if specified adds additional headers to the HTTP request.
- -- You must make sure that the header strings follow HTTP specification
- -- ("Key: Value").
-
- multipart = boolean
- -- Optional, if true performs a multipart HTTP request.
- -- Default is false.
- }
-
-`HTTPRequestResult` definition
-------------------------------
-
-Passed to `HTTPApiTable.fetch` callback. Returned by
-`HTTPApiTable.fetch_async_get`.
-
- {
- completed = true,
- -- If true, the request has finished (either succeeded, failed or timed
- -- out)
-
- succeeded = true,
- -- If true, the request was successful
-
- timeout = false,
- -- If true, the request timed out
-
- code = 200,
- -- HTTP status code
-
- data = "response"
- }
-
Authentication handler definition
---------------------------------