diff --git a/mods/CORE/Formspec/src/Formspec.lua b/mods/CORE/Formspec/src/Formspec.lua index 3bb8750..5cebd58 100644 --- a/mods/CORE/Formspec/src/Formspec.lua +++ b/mods/CORE/Formspec/src/Formspec.lua @@ -813,9 +813,36 @@ function Formspec:box(x, y, w, h, color) self:addElement(element) end ----TODO -function Formspec:dropdown() +---Show a dropdown field +---**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[,;;;,, ...,;;]` +--- * `dropdown[,;,;;,, ...,;;]` +---@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 ---Show a checkbox. @@ -837,6 +864,8 @@ function Formspec:checkbox(x, y, name, label, selected) end ---Show a scrollbar using options defined by the previous `scrollbaroptions[]` +--- +---**Element**: `scrollbar[,;,;;;]` ---@param x number ---@param y number ---@param w number @@ -851,24 +880,125 @@ function Formspec:scrollbar(x, y, w, h, orientation, name, value) self:addElement(element) end ----TODO -function Formspec:scrollbarOptions() +---@alias Formspec.scrollbarOptionsDef {min:integer?, max:integer?, smallstep:integer?, largestep:integer?, thumbsize:integer?, arrows:'show'|'hide'|'default'|nil} +---Sets options for all following scrollbar[] elements +--- * `min=` +--- Sets scrollbar minimum value, defaults to `0`. +--- * `max=` +--- Sets scrollbar maximum value, defaults to `1000`. If the max is equal to the min, the scrollbar will be disabled. +--- * `smallstep=` +--- 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=` +--- 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=` +--- 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=` +--- 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 ----TODO -function Formspec:table() +---Show scrollable table using options defined by the previous `tableoptions[]`. +---Displays cells as defined by the previous `tablecolumns[]`. +--- +---See also `core.explode_table_event`. +--- +---**Element**: `table[,;,;;,,...,;]` +---@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 ----TODO -function Formspec:tableOptions() +---@alias Formspec.tableOptionsDef {color:ColorString?, background:ColorString?, border:boolean?, highlight:ColorString?, highlight_text:ColorString?, opendepth:integer?} +---Sets options for `table[]` +--- * `color=#RRGGBB` +--- default text color (`ColorString`), defaults to `#FFFFFF` +--- * `background=#RRGGBB` +--- table background color (`ColorString`), defaults to `#000000` +--- * `border=` +--- 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=` +--- all subtrees up to depth < value are open (default value = `0`) +--- only useful when there is a column of type "tree" +--- +---**Element:** `tableoptions[;;...]` +---@param options Formspec.tableOptionsDef +function Formspec:tableOptions(options) + local element = ('tableoptions[%s]'):format( + table.key_value_list(options, ';')) + + self:addElement(element) end ----TODO -function Formspec:tablecolumns() +---@alias Formspec.tableColumnsTypes 'text'|'image'|'color'|'indent'|'tree' +---@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=` +--- for `text` and `image`: content alignment within cells. Available values: `left` (default), `center`, `right`, `inline` +--- * `width=` +--- for `text` and `image`: minimum width in em (default: `0`) +--- for `indent` and `tree`: indent width in em (default: `1.5`) +--- * `padding=`: padding left of the column, in em (default `0.5`). Exception: defaults to 0 for indent columns +--- * `tooltip=`: tooltip text (default: empty) +--- * `image` column options: +--- * * `0=` sets image for image index 0 +--- * * `1=` sets image for image index 1 +--- * * `2=` 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=`: number of following columns to affect (default: infinite). +--- +---**Element**: `tablecolumns[,,,...;,,;...]` +---@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 ---TODO @@ -877,15 +1007,37 @@ function Formspec:style() end ---TODO -function Formspec:style_type() +function Formspec:styleType() end ----TODO -function Formspec:set_focus() +---Sets the focus to the element with the same name parameter. +--- +---**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 - return Formspec -