Formspec: add method chaining to elements registrations

This commit is contained in:
Van
2026-01-23 15:10:01 +03:00
parent 5ec4bdd933
commit ce778673c7
2 changed files with 110 additions and 24 deletions

View File

@@ -142,10 +142,12 @@ end
---@param container Formspec
---@param x number
---@param y number
---@return Formspec
function Formspec:container(container, x, y)
local element = ('container[%s,%s]'):format(x, y)..container:getElements()..'container_end[]'
self:addElement(element)
return self
end
---Create scroll_container block. All contained elements will
@@ -165,12 +167,14 @@ end
---@param scrollFactor number? Defaults to 0.1.
---@param contentPadding number? In formspec coordinate units. If specified, the scrollbar properties `max` and `thumbsize` are calculated
--- automatically based on the content size plus `content padding` at the end of the container. `min` is set to `0`.
---@return Formspec
function Formspec:scrollContainer(container, x, y, w, h, scrollbarName, orientation, scrollFactor, contentPadding)
local element = ('scroll_container[%s,%s;%s,%s;%s;%s;%s;%s]'):format(
x, y, w, h, scrollbarName, orientation, scrollFactor or '', contentPadding or '')..
container:getElements()..'scroll_container_end[]'
self:addElement(element)
return self
end
---@alias Formspec.ListDef {inventoryLocation:string, listName:string, x:number, y:number, w:number, h:number,startingItemIndex:number}
@@ -190,22 +194,25 @@ end
---@param w number Are in inventory slots, not in coordinates.
---@param h number Are in inventory slots, not in coordinates.
---@param startingItemIndex number? The index of the first (upper-left) item to draw. Indices start at `0`. Default is `0`.
---@return Formspec
function Formspec:list(inventoryLocation, listName, x, y, w, h, startingItemIndex)
local element = ('list[%s;%s;%s,%s;%s,%s;%s]'):format(
inventoryLocation, listName, x, y, w, h,startingItemIndex or '')
self:addElement(element)
return self
end
---Creates and appends a list of `listring[<inventory location>;<list name>]` items based on the passed inventory list.
---
---**Elements:** `listring[<inventory location>;<list name>]` or `listring[]`
---@param lists [string, string][]? List of looping lists in the format `[inventory location, list name]`. If `nil`, it will be added `listring[]`.
---@return Formspec
function Formspec:listring(lists)
if lists == nil then
self:addElement('listring[]')
return
return self
end
local element = ''
@@ -215,6 +222,7 @@ function Formspec:listring(lists)
end
self:addElement(element)
return self
end
---The following descriptions are allowed:
@@ -226,6 +234,7 @@ end
---@param slotBorder ColorString?
---@param tooltipBgcolor ColorString?
---@param tooltipFontcolor ColorString?
---@return Formspec
function Formspec:listColors(slotBackgroundNormal, slotBackgroundHover, slotBorder, tooltipBgcolor, tooltipFontcolor)
local element
@@ -241,6 +250,7 @@ function Formspec:listColors(slotBackgroundNormal, slotBackgroundHover, slotBord
end
self:addElement(element)
return self
end
---Adds tooltip for an element.
@@ -250,11 +260,13 @@ end
---@param tooltipText string
---@param bgcolor ColorString?
---@param fontcolor ColorString?
---@return Formspec
function Formspec:tooltipForElement(elementName, tooltipText, bgcolor, fontcolor)
local element = ('tooltip[%s;%s;%s;%s]'):format(
elementName, tooltipText, bgcolor or '', fontcolor or '')
self:addElement(element)
return self
end
---Adds tooltip for an area. Other tooltips will take priority when present.
@@ -267,11 +279,13 @@ end
---@param tooltipText string
---@param bgcolor ColorString?
---@param fontcolor ColorString?
---@return Formspec
function Formspec:tooltipForArea(x, y, w, h, tooltipText, bgcolor, fontcolor)
local element = ('tooltip[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, tooltipText, bgcolor or '', fontcolor or '')
self:addElement(element)
return self
end
---Show an image.
@@ -283,26 +297,29 @@ end
---@param h number
---@param textureName string
---@param middle boolean? Makes the image render in 9-sliced mode and defines the middle rect.
---@return Formspec
function Formspec:image(x, y, w, h, textureName, middle)
local element = ('image[%s,%s;%s,%s;%s;%s]'):format(
x, y, w, h, textureName, middle or '')
self:addElement(element)
return self
end
---Show an animated image. The image is drawn like a "vertical_frames" tile animation
---(See Tile animation definition), but uses a frame count/duration for simplicity.
---
---**Element:** `animated_image[<X>,<Y>;<W>,<H>;<name>;<texture name>;<frame count>;<frame duration>;<frame start>;<middle>]`
---@param x number
---@param y number
---@param w number
---@param h number
---@param textureName string
---@param frameCount number
---@param x number
---@param y number
---@param w number
---@param h number
---@param textureName string
---@param frameCount number
---@param frameDuration number
---@param frameStart number
---@param middle boolean? Makes the image render in 9-sliced mode and defines the middle rect.
---@param frameStart number
---@param middle boolean? Makes the image render in 9-sliced mode and defines the middle rect.
---@return Formspec
function Formspec:animatedImage(x, y, w, h, textureName, frameCount, frameDuration, frameStart, middle)
if middle == nil then
middle = false
@@ -312,6 +329,7 @@ function Formspec:animatedImage(x, y, w, h, textureName, frameCount, frameDurati
x, y, w, h, textureName, frameCount, frameDuration, frameStart, middle)
self:addElement(element)
return self
end
---Show a mesh model.
@@ -329,11 +347,13 @@ end
---@param mouseControl boolean? Whether the model can be controlled with the mouse. Default `true`.
---@param frameLoopRange string? Range of the animation frames. Defaults to the full range of all available frames. Syntax: `<begin>,<end>`.
---@param animationSpeed number? Sets the animation speed. Default 0 FPS.
---@return Formspec
function Formspec:model(x, y, w, h, name, mesh, textures, rotation, continuous, mouseControl, frameLoopRange, animationSpeed)
local element = ('model[%s,%s;%s,%s;%s;%s;%s;%s;%s;%s;%s;%s]'):format(
x, y, w, h, name, mesh, textures, rotation or '', continuous or '', mouseControl or '', frameLoopRange or '', animationSpeed or '')
self:addElement(element)
return self
end
---Show an inventory image of registered item/node.
@@ -344,11 +364,13 @@ end
---@param w number
---@param h number
---@param itemName string
---@return Formspec
function Formspec:itemImage(x, y, w, h, itemName)
local element = ('item_image[%s,%s;%s,%s;%s]'):format(
x, y, w, h, itemName)
self:addElement(element)
return self
end
---Sets background color of formspec.
@@ -362,12 +384,14 @@ end
---**Element:** `bgcolor[<bgcolor>;<fullscreen>;<fbgcolor>]`
---@param bgcolor ColorString Define the color of the non-fullscreen and the fullscreen background.
---@param fullscreen 'false'|'true'|'both'|'neither'
---@param fbgcolor ColorString? Define the color of the non-fullscreen and the fullscreen background.
---@param fbgcolor ColorString? Define the color of the non-fullscreen and the fullscreen background.
---@return Formspec
function Formspec:bgcolor(bgcolor, fullscreen, fbgcolor)
local element = ('bgcolor[%s;%s;%s]'):format(
bgcolor, fullscreen or '', fbgcolor or '')
self:addElement(element)
return self
end
---Example for formspec 8x4 in 16x resolution: image shall be sized 8 times 16px times 4 times 16px.
@@ -381,6 +405,7 @@ end
---@param autoClip boolean? If is `true`, the background is clipped.
--- to the formspec size (x and y are used as offset
--- values, w and h are ignored)
---@return Formspec
function Formspec:background(x, y, w, h, textureName, autoClip)
local element
@@ -393,6 +418,7 @@ function Formspec:background(x, y, w, h, textureName, autoClip)
end
self:addElement(element)
return self
end
---9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling
@@ -413,11 +439,13 @@ end
--- Negative x2 and y2 values will be added to the width and height of
--- the texture, allowing it to be used as the distance from the far end.
--- * All numbers in middle are integers.
---@return Formspec
function Formspec:background9(x, y, w, h, textureName, autoClip, middle)
local element = ('background9[%s,%s;%s,%s;%s;%s]'):format(
x, y, w, h, textureName, autoClip, middle)
self:addElement(element)
return self
end
---Textual password style field; will be sent to server when a button is clicked
@@ -434,11 +462,13 @@ end
---@param h number
---@param name string Is the name of the field as returned in `fields to on_receive_fields`.
---@param label string? If not blank, will be text printed on the top left above the field.
---@return Formspec
function Formspec:pwdfield(x, y, w, h, name, label)
local element = ('pwdfield[%s,%s;%s,%s;%s;%s]'):format(
x, y, w, h, name, label or '')
self:addElement(element)
return self
end
---Textual field; will be sent to server when a button is clicked.
@@ -458,11 +488,13 @@ end
---@param default string? is the default value of the field default may contain variable references
--- such as `${text}` which will fill the value from the metadata value text.
--- Note: no extra text or more than a single variable is supported ATM.
---@return Formspec
function Formspec:field(x, y, w, h, name, label, default)
local element = ('field[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, name, label or '', default or '')
self:addElement(element)
return self
end
---Textual field; will be sent to server when a button is clicked.
@@ -479,11 +511,13 @@ end
---@param default string? is the default value of the field default may contain variable references
--- such as `${text}` which will fill the value from the metadata value text.
--- Note: no extra text or more than a single variable is supported ATM.
---@return Formspec
function Formspec:fieldWithoutPos(name, label, default)
local element = ('field[%s,%s;%s,%s;%s;%s;%s]'):format(
name, label or '', default or '')
self:addElement(element)
return self
end
@@ -491,15 +525,17 @@ end
---Only affects Android clients.
---
---**Element:** `field_enter_after_edit[<name>;<enter_after_edit>]`
---@param name string Is the name of the field.
---@param name string Is the name of the field.
---@param enterAfterEdit boolean? If is true, pressing the "Done" button in the Android
--- text input dialog will simulate an Enter keypress. Defaults to `false`
--- when not specified (i.e. no tag for a field).
---@return Formspec
function Formspec:fieldEnterAfterEdit(name, enterAfterEdit)
local element = ('field_enter_after_edit[%s;%s]'):format(
name, enterAfterEdit or false)
self:addElement(element)
return self
end
---
@@ -507,11 +543,13 @@ end
---@param name string Is the name of the field.
---@param closeOnEnter boolean? If` is false, pressing Enter in the field will submit the form but not close it.
--- Defaults to true when not specified (i.e. no tag for a field).
---@return Formspec
function Formspec:fieldCloseOnEnter(name, closeOnEnter)
local element = ('field_enter_after_edit[%s;%s]'):format(
name, closeOnEnter or false)
self:addElement(element)
return self
end
---Same as text fields, but with multi-line input.
@@ -531,11 +569,13 @@ end
---@param default string? is the default value of the field default may contain variable references
--- such as `${text}` which will fill the value from the metadata value text.
--- Note: no extra text or more than a single variable is supported ATM.
---@return Formspec
function Formspec:textArea(x, y, w, h, name, label, default)
local element = ('textarea[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, name or '', label or '', default or '')
self:addElement(element)
return self
end
---The label formspec element displays the text set in `label` at the specified position.
@@ -549,11 +589,13 @@ end
---@param x number
---@param y number
---@param label string
---@return Formspec
function Formspec:label(x, y, label)
local element = ('label[%s,%s;%s]'):format(
x, y, label)
self:addElement(element)
return self
end
---The "area label" formspec element displays the text set in label at the specified position and size.
@@ -567,11 +609,13 @@ end
---@param w number
---@param h number
---@param label string
---@return Formspec
function Formspec:areaLabel(x, y, w, h, label)
local element = ('label[%s,%s;%s,%s;%s]'):format(
x, y, w, h, label)
self:addElement(element)
return self
end
---Displays a static formatted text with hyperlinks.
@@ -584,11 +628,13 @@ end
---@param h number
---@param name string Is the name of the field as returned in fields to `on_receive_fields` in case of action in text.
---@param text string Is the formatted text using `Markup Language` described below.
---@return Formspec
function Formspec:hypertext(x, y, w, h, name, text)
local element = ('hypertext[%s,%s;%s,%s;%s;%s]'):format(
x, y, w, h, name, text)
self:addElement(element)
return self
end
---Textual label drawn vertically.
@@ -597,11 +643,13 @@ end
---@param x number
---@param y number
---@param label string
---@return Formspec
function Formspec:vertlabel(x, y, label)
local element = ('vertlabel[%s,%s;%s]'):format(
x, y, label)
self:addElement(element)
return self
end
---Clickable button. When clicked, fields will be sent. With the old coordinate system,
@@ -615,11 +663,13 @@ end
---@param h number
---@param name string
---@param label string? Is the text on the button
---@return Formspec
function Formspec:button(x, y, w, h, name, label)
local element = ('button[%s,%s;%s,%s;%s;%s]'):format(
x, y, w, h, name, label or '')
self:addElement(element)
return self
end
---Clickable button. When clicked, fields will be sent and the user will be given
@@ -635,11 +685,13 @@ end
---@param name string
---@param label string? Is the text on the button
---@param url string Must be a valid web URL, starting with `http://` or `https://`.
---@return Formspec
function Formspec:buttonUrl(x, y, w, h, name, label, url)
local element = ('button_url[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, name, label or '', url)
self:addElement(element)
return self
end
---Clickable image button. When clicked, fields will be sent.
@@ -659,6 +711,7 @@ end
---@param pressedTextureName string Is the filename of an image on pressed state.
---@param noclip boolean? Means the image button doesn't need to be within specified formsize. Default: `true`
---@param drawborder boolean? Draw button border or not. Default `false`
---@return Formspec
function Formspec:imageButton(x, y, w, h, textureName, name, label, pressedTextureName, noclip, drawborder)
local element
@@ -671,6 +724,7 @@ function Formspec:imageButton(x, y, w, h, textureName, name, label, pressedTextu
end
self:addElement(element)
return self
end
---Clickable item image button. When clicked, fields will be sent.
@@ -683,11 +737,13 @@ end
---@param itemName string
---@param name string
---@param label string?
---@return Formspec
function Formspec:itemImageButton(x, y, w, h, itemName, name, label)
local element = ('item_image_button[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, itemName, name, label or '')
self:addElement(element)
return self
end
---When clicked, fields will be sent and the form will quit.
@@ -700,11 +756,13 @@ end
---@param h number
---@param name string
---@param label string? Is the text on the button
---@return Formspec
function Formspec:buttonExit(x, y, w, h, name, label)
local element = ('button_exit[%s,%s;%s,%s;%s;%s]'):format(
x, y, w, h, name, label or '')
self:addElement(element)
return self
end
---When clicked, fields will be sent and the form will quit.
@@ -718,11 +776,13 @@ end
---@param name string
---@param label string? Is the text on the button
---@param url string Must be a valid web URL, starting with `http://` or `https://`.
---@return Formspec
function Formspec:buttonUrlExit(x, y, w, h, name, label, url)
local element = ('button_url_exit[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, name, label or '', url)
self:addElement(element)
return self
end
---When clicked, fields will be sent and the form will quit.
@@ -736,11 +796,13 @@ end
---@param textureName string Is the filename of an image.
---@param name string
---@param label string?
---@return Formspec
function Formspec:imageButtonExit(x, y, w, h, textureName, name, label)
local element = ('image_button_exit[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, textureName, name, label or '')
self:addElement(element)
return self
end
---Scrollable item list showing arbitrary text elements.
@@ -756,6 +818,7 @@ end
--- If you want a listelement to start with "#" write "##"
---@param selectedIdx number? Index to be selected within textlist.
---@param transparent boolean? Draw transparent background.
---@return Formspec
function Formspec:textlist(x, y, w, h, name, listElements, selectedIdx, transparent)
local element
@@ -768,6 +831,7 @@ function Formspec:textlist(x, y, w, h, name, listElements, selectedIdx, transpar
end
self:addElement(element)
return self
end
---Show a tabheader at specific position (ignores formsize).
@@ -785,6 +849,7 @@ end
---@param currentTab number?
---@param transparent boolean?
---@param drawBorder boolean?
---@return Formspec
function Formspec:tabheader(x, y, w, h, name, listCaptions, currentTab, transparent, drawBorder)
local element
@@ -800,24 +865,27 @@ function Formspec:tabheader(x, y, w, h, name, listCaptions, currentTab, transpar
end
self:addElement(element)
return self
end
---Simple colored box.
---
---**Element:** `box[<X>,<Y>;<W>,<H>;<color>]`
---@param x number
---@param y number
---@param w number
---@param h number
---@param color ColorString Is color specified as a `ColorString`. If the alpha component is left blank,
---@param x number
---@param y number
---@param w number
---@param h number
---@param color ColorString Is color specified as a `ColorString`. If the alpha component is left blank,
--- the box will be semitransparent. If the color is not specified, the box will
--- use the options specified by its style. If the color is specified, all styling
--- options will be ignored.
---@return Formspec
function Formspec:box(x, y, w, h, color)
local element = ('box[%s,%s;%s,%s;%s]'):format(
x, y, w, h, color)
self:addElement(element)
return self
end
---Show a dropdown field
@@ -838,6 +906,7 @@ end
---@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
---@return Formspec
function Formspec:dropdown(x, y, w, h, name, listItems, selectedIdx, indexEvent)
local element
@@ -850,6 +919,7 @@ function Formspec:dropdown(x, y, w, h, name, listItems, selectedIdx, indexEvent)
end
self:addElement(element)
return self
end
---Show a checkbox.
@@ -863,11 +933,13 @@ end
---@param name string Fieldname data is transferred to Lua
---@param label string? To be shown left of checkbox
---@param selected boolean?
---@return Formspec
function Formspec:checkbox(x, y, name, label, selected)
local element = ('checkbox[%s,%s;%s;%s;%s]'):format(
x, y, name, label or '', selected or '')
self:addElement(element)
return self
end
---Show a scrollbar using options defined by the previous `scrollbaroptions[]`
@@ -880,11 +952,13 @@ end
---@param orientation 'vertical'|'horizontal'
---@param name string
---@param value number?
---@return Formspec
function Formspec:scrollbar(x, y, w, h, orientation, name, value)
local element = ('scrollbar[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, orientation, name, value or '')
self:addElement(element)
return self
end
---@alias Formspec.scrollbarOptionsDef {min:integer?, max:integer?, smallstep:integer?, largestep:integer?, thumbsize:integer?, arrows:'show'|'hide'|'default'|nil}
@@ -909,11 +983,13 @@ end
---
---**Element**: `scrollbaroptions[opt1;opt2;...]`
---@param options Formspec.scrollbarOptionsDef
---@return Formspec
function Formspec:scrollbarOptions(options)
local element = ('scrollbaroptions[%s]'):format(
tableKeyValueList(options, ';'))
self:addElement(element)
return self
end
---Show scrollable table using options defined by the previous `tableoptions[]`.
@@ -929,11 +1005,13 @@ end
---@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`)
---@return Formspec
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, tableConcat(listCells, ','), selectedIdx or '')
self:addElement(element)
return self
end
---@alias Formspec.tableOptionsDef {color:ColorString?, background:ColorString?, border:boolean?, highlight:ColorString?, highlight_text:ColorString?, opendepth:integer?}
@@ -955,11 +1033,13 @@ end
---
---**Element:** `tableoptions[<opt 1>;<opt 2>;...]`
---@param options Formspec.tableOptionsDef
---@return Formspec
function Formspec:tableOptions(options)
local element = ('tableoptions[%s]'):format(
tableKeyValueList(options, ';'))
self:addElement(element)
return self
end
---@alias Formspec.tableColumnsTypes 'text'|'image'|'color'|'indent'|'tree'
@@ -993,6 +1073,7 @@ end
---
---**Element**: `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
---@param columns Formspec.tableColumn[]
---@return Formspec
function Formspec:tablecolumns(columns)
local columnsStrings = {}
@@ -1006,6 +1087,7 @@ function Formspec:tablecolumns(columns)
tableKeyValueList(columnsStrings, ';'))
self:addElement(element)
return self
end
---Set the style for the element(s) matching `selector` by name.
@@ -1023,6 +1105,7 @@ end
--- * `<name>` - An element name. Includes `*`, which represents every element.
--- * `<name>:<state>` - An element name, a colon, and one or more states.
---@param properties string[] TODO: добавить тут алиас, который бы содержал доступные настройки
---@return Formspec
function Formspec:style(selectors, properties)
if type(selectors) == 'string' then
selectors = { selectors }
@@ -1032,6 +1115,7 @@ function Formspec:style(selectors, properties)
tableConcat(selectors, ','), tableConcat(properties, ','))
self:addElement(element)
return self
end
---Set the style for the element(s) matching `selector` by type.
@@ -1049,6 +1133,7 @@ end
--- * `<name>` - An element name. Includes `*`, which represents every element.
--- * `<name>:<state>` - An element name, a colon, and one or more states.
---@param properties string[] TODO: добавить тут алиас, который бы содержал доступные настройки
---@return Formspec
function Formspec:styleType(selectors, properties)
if type(selectors) == 'string' then
selectors = { selectors }
@@ -1058,6 +1143,7 @@ function Formspec:styleType(selectors, properties)
tableConcat(selectors, ','), tableConcat(properties, ','))
self:addElement(element)
return self
end
---Sets the focus to the element with the same name parameter.
@@ -1082,11 +1168,13 @@ end
---@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.
---@return Formspec
function Formspec:setFocus(name, force)
local element = ('set_focus[%s;%s]'):format(
name, force or '')
self:addElement(element)
return self
end
return Formspec