Formspec: add some methods. #8

This commit is contained in:
Van
2026-01-20 14:11:22 +03:00
parent c9ce8e5f60
commit 4b9afcf97d

View File

@@ -7,22 +7,38 @@ local Formspec = {
---@class FormspecDef
---Set the formspec version to a certain number. If not specified, version `10` is assumed.
---
---**Element:** `formspec_version[<version>]`
---@field version? number
---Define the size of the menu in inventory slots. `fixed_size` is optional, default `true`
---Define the size of the menu in inventory slots. `fixed_size` is optional, default `true`.
---
---**Element:** `size[<W>,<H>,<fixed_size>]`
---@field size? {x:number, y:number, fixed_size:boolean?}
---Defines the position on the game window of the formspec's anchor point.
---
---**Element:** `position[<X>,<Y>]`
---@field position? {x:number, y:number}
---Defines the location of the anchor point within the formspec.
---
---**Element:** `anchor[<X>,<Y>]`
---@field anchor? {x:number, y:number}
---Defines how much space is padded around the formspec if the formspec tries to increase
---past the size of the screen and coordinates have to be shrunk.
---
---**Element:** `padding[<X>,<Y>]`
---@field padding? {x:number, y:number}
---Disables player:set_formspec_prepend() from applying to this formspec.
---
---**Element:** `no_prepend[]`
---@field noPrepend? boolean
---When set to true, all following formspec elements will use the new coordinate system.
---
---**Element:** `real_coordinates[<bool>]`
---@field realCoordinates? boolean
---When set to false, the formspec will not close when the user tries to close
---it with the Escape key or similar. Default true.
---
---**Element:** `allow_close[<bool>]`
---@field allowClose? boolean
---@param def FormspecDef?
@@ -115,6 +131,8 @@ end
---Start of a container block, moves all physical elements in the container by (X, Y).
---Containers can be nested, in which case the offsets are added (child containers are relative to parent containers).
---
---**Elements:** `container[<X>,<Y>]` & `container_end[]`
---@param container Formspec
---@param x number
---@param y number
@@ -129,6 +147,8 @@ end
---be additionally moved by the current value of the scrollbar with
---the name `scrollbar name` times `scroll factor` along the orientation `orientation` and
---be clipped to the rectangle defined by `X`, `Y`, `W` and `H`.
---
---**Elements:** `scroll_container[<X>,<Y>;<W>,<H>;<scrollbar name>;<orientation>;<scroll factor>;<content padding>]` & `scroll_container_end[]`
---@param container Formspec
---@param x number
---@param y number
@@ -148,25 +168,31 @@ end
---@alias Formspec.ListDef {inventoryLocation:string, listName:string, x:number, y:number, w:number, h:number,startingItemIndex:number}
---Show an inventory list if it has been sent to the client.
---If the inventory list changes (eg. it didn't exist before, it's resized,
---or its items are moved) while the formspec is open, the formspec element may
---(but is not guaranteed to) adapt to the new inventory list.
---Item slots are drawn in a grid from left to right,
---then up to down, ordered according to the slot index.
---
---**Element:** `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
---@param inventoryLocation string
---@param listName string
---@param x number
---@param y number
---@param w number Are in inventory slots, not in coordinates.
---@param h number Are in inventory slots, not in coordinates.
---@param startingItemIndex number?
function Formspec:list(inventoryLocation, listName, x, y, w, h,startingItemIndex)
if startingItemIndex == nil then
startingItemIndex = 0
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`.
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)
inventoryLocation, listName, x, y, w, h,startingItemIndex or '')
self:addElement(element)
end
---TODO: немного отличается от листринга луанти, так что надо дописать подробности
---
---**Elements:** `listring[<inventory location>;<list name>]` or `listring[]`
---@param lists [string, string][]? List of looping lists in the format `[inventory location, list name]`
function Formspec:listring(lists)
if lists == nil then
@@ -209,6 +235,8 @@ function Formspec:listColors(slotBackgroundNormal, slotBackgroundHover, slotBord
end
---Adds tooltip for an element.
---
---**Element:** `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>;<fontcolor>]`
---@param elementName string
---@param tooltipText string
---@param bgcolor ColorString?
@@ -221,6 +249,8 @@ function Formspec:tooltipForElement(elementName, tooltipText, bgcolor, fontcolor
end
---Adds tooltip for an area. Other tooltips will take priority when present.
---
---**Element:** `tooltip[<X>,<Y>;<W>,<H>;<tooltip_text>;<bgcolor>;<fontcolor>]`
---@param x number
---@param y number
---@param w number
@@ -236,6 +266,8 @@ function Formspec:tooltipForArea(x, y, w, h, tooltipText, bgcolor, fontcolor)
end
---Show an image.
---
---**Element:** `image[<X>,<Y>;<W>,<H>;<texture name>;<middle>]`
---@param x number
---@param y number
---@param w number
@@ -251,6 +283,8 @@ 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
@@ -272,6 +306,8 @@ function Formspec:animatedImage(x, y, w, h, textureName, frameCount, frameDurati
end
---Show a mesh model.
---
---**Element:** `model[<X>,<Y>;<W>,<H>;<name>;<mesh>;<textures>;<rotation>;<continuous>;<mouse control>;<frame loop range>;<animation speed>]`
---@param x number
---@param y number
---@param w number
@@ -292,6 +328,8 @@ function Formspec:model(x, y, w, h, name, mesh, textures, rotation, continuous,
end
---Show an inventory image of registered item/node.
---
---**Element:** `item_image[<X>,<Y>;<W>,<H>;<item name>]`
---@param x number
---@param y number
---@param w number
@@ -311,6 +349,8 @@ end
--- * `true`: Only the fullscreen background color is drawn.
--- * `both`: The non-fullscreen and the fullscreen background color are drawn.
--- * `neither`: No background color is drawn.
---
---**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.
@@ -322,6 +362,8 @@ function Formspec:bgcolor(bgcolor, fullscreen, fbgcolor)
end
---Example for formspec 8x4 in 16x resolution: image shall be sized 8 times 16px times 4 times 16px.
---
---**Element:** `background[<X>,<Y>;<W>,<H>;<texture name>]` or `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
---@param x number
---@param y number
---@param w number
@@ -345,6 +387,8 @@ function Formspec:background(x, y, w, h, textureName, autoClip)
end
---9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling
---
---**Element:** `background9[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>;<middle>]`
---@param x number
---@param y number
---@param w number
@@ -373,6 +417,8 @@ end
---With the new coordinate system, `H` will modify the height.
---
---See field_close_on_enter to stop enter closing the formspec.
---
---**Element:** `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
---@param x number
---@param y number
---@param w number
@@ -392,6 +438,8 @@ end
---With the new coordinate system, `H` will modify the height.
---
---See field_close_on_enter to stop enter closing the formspec.
---
---**Element:** `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
---@param x number
---@param y number
---@param w number
@@ -415,6 +463,8 @@ end
---A "Proceed" button will be added automatically
---
---See field_close_on_enter to stop enter closing the formspec.
---
---**Element:** `field[<name>;<label>;<default>]`
---@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 default string? is the default value of the field default may contain variable references
@@ -430,6 +480,8 @@ end
---**Experimental**, may be subject to change or removal at any time.
---Only affects Android clients.
---
---**Element:** `field_enter_after_edit[<name>;<enter_after_edit>]`
---@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`
@@ -441,6 +493,8 @@ function Formspec:fieldEnterAfterEdit(name, enterAfterEdit)
self:addElement(element)
end
---
---**Element:** `field_close_on_enter[<name>;<close_on_enter>]`
---@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).
@@ -454,6 +508,8 @@ end
---Same as text fields, but with multi-line input.
---Text is wrapped to fit within the given bounds.
---If the text overflows, a vertical scrollbar is added.
---
---**Element:** `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
---@param x number
---@param y number
---@param w number
@@ -479,6 +535,8 @@ end
---so label should not be used for big text chunks. Newlines can be used to make labels multiline.
---Note: With the new coordinate system, newlines are spaced with half a coordinate.
---With the old system, newlines are spaced 2/5 of an inventory slot.
---
---**Element:** `label[<X>,<Y>;<label>]`
---@param x number
---@param y number
---@param label string
@@ -493,6 +551,8 @@ end
---Text is wrapped to fit within the given bounds. If the text overflows, it is currently simply truncated,
---but this behavior is subject to change. There is no scrollbar.
---See also textarea for an alternative. Only available with the new coordinate system.
---
---**Element:** `label[<X>,<Y>;<W>,<H>;<label>]`
---@param x number
---@param y number
---@param w number
@@ -507,6 +567,8 @@ end
---Displays a static formatted text with hyperlinks.
---Note: This element is currently unstable and subject to change.
---
---**Element:** `hypertext[<X>,<Y>;<W>,<H>;<name>;<text>]`
---@param x number
---@param y number
---@param w number
@@ -521,6 +583,8 @@ function Formspec:hypertext(x, y, w, h, name, text)
end
---Textual label drawn vertically.
---
---**Element:** `vertlabel[<X>,<Y>;<label>]`
---@param x number
---@param y number
---@param label string
@@ -534,6 +598,8 @@ end
---Clickable button. When clicked, fields will be sent. With the old coordinate system,
---buttons are a set height, but will be vertically centered on H. With the new
---coordinate system, H will modify the height.
---
---**Element:** `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
---@param x number
---@param y number
---@param w number
@@ -551,6 +617,8 @@ end
---the option to open the URL in a browser. With the old coordinate system,
---buttons are a set height, but will be vertically centered on H.With the new coordinate system,
---H will modify the height. To make this into an image_button, you can use formspec styling.
---
---**Element:** `button_url[<X>,<Y>;<W>,<H>;<name>;<label>;<url>]`
---@param x number
---@param y number
---@param w number
@@ -565,11 +633,40 @@ function Formspec:buttonUrl(x, y, w, h, name, label, url)
self:addElement(element)
end
---TODO
function Formspec:imageButton()
---Clickable image button. When clicked, fields will be sent.
---
---Note: Height is supported on both the old and new coordinate systems for image_buttons.
---
---**Elements:** `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]` or
---`image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
---@overload fun(x:number, y:number, w:number, h:number, textureName:string, name:string, label:string)
---@param x number
---@param y number
---@param w number
---@param h number
---@param textureName string Is the filename of an image.
---@param name string
---@param label string?
---@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`
function Formspec:imageButton(x, y, w, h, textureName, name, label, pressedTextureName, noclip, drawborder)
local element
if pressedTextureName == nil then
element = ('image_button[%s,%s;%s,%s;%s;%s;%s]'):format(
x, y, w, h, textureName, name, label or '')
else
element = ('image_button[%s,%s;%s,%s;%s;%s;%s;%s;%s;%s]'):format(
x, y, w, h, textureName, name, label or '', pressedTextureName, noclip or true, drawborder or false)
end
self:addElement(element)
end
---TODO: описание
---
---**Element:** `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
---@param x number
---@param y number
---@param w number
@@ -584,34 +681,134 @@ function Formspec:itemImageButton(x, y, w, h, itemName, name, label)
self:addElement(element)
end
---TODO
function Formspec:buttonExit()
---When clicked, fields will be sent and the form will quit.
---Same as `button` in all other respects.
---
---**Element:** `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
---@param x number
---@param y number
---@param w number
---@param h number
---@param name string
---@param label string? Is the text on the button
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)
end
---TODO
function Formspec:buttonUrlExit()
---When clicked, fields will be sent and the form will quit.
---Same as `button_url` in all other respects.
---
---**Element:** `button_url_exit[<X>,<Y>;<W>,<H>;<name>;<label>;<url>]`
---@param x number
---@param y number
---@param w number
---@param h number
---@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://`.
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)
end
---TODO
function Formspec:imageButtonExit()
---When clicked, fields will be sent and the form will quit.
---Same as `image_button` in all other respects.
---
---**Element:** `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
---@param x number
---@param y number
---@param w number
---@param h number
---@param textureName string Is the filename of an image.
---@param name string
---@param label string?
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)
end
---TODO
function Formspec:textlist()
---Scrollable item list showing arbitrary text elements.
---
---**Elements:** `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]` or
---`textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
---@param x number
---@param y number
---@param w number
---@param h number
---@param name string
---@param listElements string[] Element can be prepended by `#RRGGBB` (only) in hexadecimal format.
--- If you want a listelement to start with "#" write "##"
---@param selectedIdx number? Index to be selected within textlist.
---@param transparent boolean? Draw transparent background.
function Formspec:textlist(x, y, w, h, name, listElements, selectedIdx, transparent)
local element
if selectedIdx == nil and transparent == nil then
element = ('textlist[%s,%s;%s,%s;%s;%s]'):format(
x, y, w, h, name, table.concat(listElements, ','))
else
element = ('textlist[%s,%s;%s,%s;%s;%s;%s;%s]'):format(
x, y, w, h, name, table.concat(listElements, ','), selectedIdx or '', transparent or '')
end
self:addElement(element)
end
---TODO
function Formspec:tabheader()
---Show a tabheader at specific position (ignores formsize).
---
---**Elements:**
--- * `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
--- * `tabheader[<X>,<Y>;<H>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
--- * `tabheader[<X>,<Y>;<W>,<H>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
---@param x number
---@param y number
---@param w number?
---@param h number?
---@param name string
---@param listCaptions string[]
---@param currentTab number?
---@param transparent boolean?
---@param drawBorder boolean?
function Formspec:tabheader(x, y, w, h, name, listCaptions, currentTab, transparent, drawBorder)
local element
if w == nil and h == nil then
element = ('tabheader[%s,%s;%s;%s;%s;%s;%s]'):format(
x, y, name, table.concat(listCaptions, ','), currentTab or '', transparent or '', drawBorder or '')
elseif w == nil then
element = ('tabheader[%s,%s;%s;%s;%s;%s;%s;%s]'):format(
x, y, name, h, table.concat(listCaptions, ','), currentTab or '', transparent or '', drawBorder or '')
else
element = ('tabheader[%s,%s;%s,%s;%s;%s,%s;%s;%s;%s]'):format(
x, y, name, w, h, table.concat(listCaptions, ','), currentTab or '', transparent or '', drawBorder or '')
end
self:addElement(element)
end
---TODO
function Formspec:box()
---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,
--- 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.
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)
end
---TODO
@@ -619,9 +816,22 @@ function Formspec:dropdown()
end
---TODO
function Formspec:checkbox()
---Show a checkbox.
---
---Note: If the new coordinate system is enabled, checkboxes
---are positioned from the center of the checkbox, not the top.
---
---**Element:** `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
---@param x number
---@param y number
---@param name string Fieldname data is transferred to Lua
---@param label string? To be shown left of checkbox
---@param selected boolean?
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)
end
---Show a scrollbar using options defined by the previous `scrollbaroptions[]`