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

View File

@@ -12,13 +12,12 @@ listForm:list('current_player', 'main', 10.5, 6.5, 8, 4)
local listFormItems = Formspec:new() local listFormItems = Formspec:new()
local items = core.registered_nodes local items = table.get_keys(core.registered_nodes)
table.sort(items)
local w, h = 0, 0 local w, h = 0, 0
---@param name string ---@param name string
---@param def NodeDefinition for _, name in ipairs(items) do
for name, def in pairs(items) do
listFormItems:itemImageButton(w, h, 1, 1, name, name..'::item_button') listFormItems:itemImageButton(w, h, 1, 1, name, name..'::item_button')
w = w + 1 w = w + 1
@@ -31,10 +30,9 @@ end
--listFormItems:list('current_player', 'main', 0, 0, 1, 32) --listFormItems:list('current_player', 'main', 0, 0, 1, 32)
listForm:scrollContainer(listFormItems, 0.5, 0.5, 9, 11, 'admin_commands:list_items', 'vertical') listForm:
listForm:scrollbar(10, 0.5, 0.25, 10, 'vertical', 'admin_commands:list_items') scrollContainer(listFormItems, 0.5, 0.5, 9, 11, 'admin_commands:list_items', 'vertical'):
scrollbar(10, 0.5, 0.25, 10, 'vertical', 'admin_commands:list_items')
core.log(listForm:toString())
core.register_chatcommand('list', { core.register_chatcommand('list', {
privs = {server = true}, privs = {server = true},