Formspec: add some methods. #8

This commit is contained in:
Van
2026-01-21 16:17:32 +03:00
parent 6fb06b7109
commit 19d6637a29

View File

@@ -813,9 +813,36 @@ function Formspec:box(x, y, w, h, color)
self:addElement(element) self:addElement(element)
end end
---TODO ---Show a dropdown field
function Formspec:dropdown() ---**Important note**: There are two different operation modes:
--- 1. handle directly on change (only changed dropdown is submitted)
--- 2.read the value on pressing a button (all dropdown values are available)
---
---**Elements:**
--- * `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>;<index event>]`
--- * `dropdown[<X>,<Y>;<W>,<H>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>;<index event>]`
---@param x number Position of the dropdown.
---@param y number Position of the dropdown.
---@param w number Width of the dropdown.
---@param h number? Height of the dropdown. May automatically adjust if not specified.
---@param name string Fieldname data is transferred to Lua.
---@param listItems string[] Items to be shown in dropdown.
---@param selectedIdx number? Index of currently selected dropdown item
---@param indexEvent boolean? (optional, allowed parameter since formspec version 4): Specifies the event field value for selected items.
--- * `true`: Selected item index
--- * `false` (default): Selected item value
function Formspec:dropdown(x, y, w, h, name, listItems, selectedIdx, indexEvent)
local element
if h == nil then
element = ('dropdown[%s,%s;%s;%s;%s;%s;%s]'):format(
x, y, w, name, table.concat(listItems, ','), selectedIdx or '', indexEvent or '')
else
element = ('dropdown[%s,%s;%s,%s;%s;%s;%s;%s]'):format(
x, y, w, h, name, table.concat(listItems, ','), selectedIdx or '', indexEvent or '')
end
self:addElement(element)
end end
---Show a checkbox. ---Show a checkbox.
@@ -837,6 +864,8 @@ function Formspec:checkbox(x, y, name, label, selected)
end end
---Show a scrollbar using options defined by the previous `scrollbaroptions[]` ---Show a scrollbar using options defined by the previous `scrollbaroptions[]`
---
---**Element**: `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
---@param x number ---@param x number
---@param y number ---@param y number
---@param w number ---@param w number
@@ -851,24 +880,125 @@ function Formspec:scrollbar(x, y, w, h, orientation, name, value)
self:addElement(element) self:addElement(element)
end end
---TODO ---@alias Formspec.scrollbarOptionsDef {min:integer?, max:integer?, smallstep:integer?, largestep:integer?, thumbsize:integer?, arrows:'show'|'hide'|'default'|nil}
function Formspec:scrollbarOptions()
---Sets options for all following scrollbar[] elements
--- * `min=<int>`
--- Sets scrollbar minimum value, defaults to `0`.
--- * `max=<int>`
--- Sets scrollbar maximum value, defaults to `1000`. If the max is equal to the min, the scrollbar will be disabled.
--- * `smallstep=<int>`
--- Sets scrollbar step value when the arrows are clicked or the mouse wheel is scrolled.
--- If this is set to a negative number, the value will be reset to `10`.
--- * `largestep=<int>`
--- Sets scrollbar step value used by page up and page down.
--- If this is set to a negative number, the value will be reset to `100`.
--- * `thumbsize=<int>`
--- Sets size of the thumb on the scrollbar. Size is calculated in the number of units the thumb spans out of the range of the scrollbar values.
--- Example: If a scrollbar has a `min` of 1 and a `max` of 100, a thumbsize of 10 would span a tenth of the scrollbar space.
--- If this is set to zero or less, the value will be reset to `1`.
--- * `arrows=<show/hide/default>`
--- Whether to show the arrow buttons on the scrollbar. `default` hides the arrows when the scrollbar gets too small, but shows them otherwise.
---
---**Element**: `scrollbaroptions[opt1;opt2;...]`
---@param options Formspec.scrollbarOptionsDef
function Formspec:scrollbarOptions(options)
local element = ('scrollbaroptions[%s]'):format(
table.key_value_list(options, ';'))
self:addElement(element)
end end
---TODO ---Show scrollable table using options defined by the previous `tableoptions[]`.
function Formspec:table() ---Displays cells as defined by the previous `tablecolumns[]`.
---
---See also `core.explode_table_event`.
---
---**Element**: `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
---@param x number
---@param y number
---@param w number
---@param h number
---@param name string Fieldname sent to server on row select or double-click
---@param listCells string[] Cells contents given in row-major order.
---@param selectedIdx number? Index of row to be selected within table (first row = `1`)
function Formspec:table(x, y, w, h, name, listCells, selectedIdx)
local element = ('table[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, name, table.concat(listCells, ','), selectedIdx or '')
self:addElement(element)
end end
---TODO ---@alias Formspec.tableOptionsDef {color:ColorString?, background:ColorString?, border:boolean?, highlight:ColorString?, highlight_text:ColorString?, opendepth:integer?}
function Formspec:tableOptions()
---Sets options for `table[]`
--- * `color=#RRGGBB`
--- default text color (`ColorString`), defaults to `#FFFFFF`
--- * `background=#RRGGBB`
--- table background color (`ColorString`), defaults to `#000000`
--- * `border=<true/false>`
--- should the table be drawn with a border? (default: `true`)
--- * `highlight=#RRGGBB`
--- highlight background color (`ColorString`), defaults to `#466432`
--- * `highlight_text=#RRGGBB`
--- highlight text color (`ColorString`), defaults to `#FFFFFF`
--- * `opendepth=<value>`
--- all subtrees up to depth < value are open (default value = `0`)
--- only useful when there is a column of type "tree"
---
---**Element:** `tableoptions[<opt 1>;<opt 2>;...]`
---@param options Formspec.tableOptionsDef
function Formspec:tableOptions(options)
local element = ('tableoptions[%s]'):format(
table.key_value_list(options, ';'))
self:addElement(element)
end end
---TODO ---@alias Formspec.tableColumnsTypes 'text'|'image'|'color'|'indent'|'tree'
function Formspec:tablecolumns() ---@alias Formspec.tableColumnsOptions {align:'left'|'center'|'right'|'inline'|nil, width:number?, padding:number?, tooltip:string?, span:integer?}
---@alias Formspec.tableColumn {type:Formspec.tableColumnsTypes, options:Formspec.tableColumnsOptions}
---Sets columns for `table[]`
---
---Types: `text`, `image`, `color`, `indent`, `tree`
--- * `text`: show cell contents as text
--- * `image`: cell contents are an image index, use column options to define images. images are scaled down to fit the row height if necessary.
--- * `color`: cell contents are a ColorString and define color of following cell.
--- * `indent`: cell contents are a number and define indentation of following cell.
--- * `tree`: same as indent, but user can open and close subtrees (treeview-like).
---
---Column options:
--- * `align=<value>`
--- for `text` and `image`: content alignment within cells. Available values: `left` (default), `center`, `right`, `inline`
--- * `width=<value>`
--- for `text` and `image`: minimum width in em (default: `0`)
--- for `indent` and `tree`: indent width in em (default: `1.5`)
--- * `padding=<value>`: padding left of the column, in em (default `0.5`). Exception: defaults to 0 for indent columns
--- * `tooltip=<value>`: tooltip text (default: empty)
--- * `image` column options:
--- * * `0=<value>` sets image for image index 0
--- * * `1=<value>` sets image for image index 1
--- * * `2=<value>` sets image for image index 2
--- * * and so on; defined indices need not be contiguous. empty or non-numeric cells are treated as `0`.
--- * `color` column options:
--- * * `span=<value>`: number of following columns to affect (default: infinite).
---
---**Element**: `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
---@param columns Formspec.tableColumn[]
function Formspec:tablecolumns(columns)
local columnsStrings = {}
for _, column in pairs(columns) do
table.insert(columnsStrings,
column.type..','..table.key_value_list(column.options,',')
)
end
local element = ('tablecolumns[%s]'):format(
table.key_value_list(columnsStrings, ';'))
self:addElement(element)
end end
---TODO ---TODO
@@ -877,15 +1007,37 @@ function Formspec:style()
end end
---TODO ---TODO
function Formspec:style_type() function Formspec:styleType()
end end
---TODO ---Sets the focus to the element with the same name parameter.
function Formspec:set_focus() ---
---**Note**: This element must be placed before the element it focuses.
---
---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
---@param name string
---@param force string? (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.
function Formspec:setFocus(name, force)
local element = ('set_focus[%s;%s]'):format(
name, force or '')
self:addElement(element)
end end
return Formspec return Formspec