Formspec: add some methods. #8

This commit is contained in:
Van
2026-01-18 16:34:37 +03:00
parent 79111b3cbd
commit 8742b86a44

View File

@@ -9,7 +9,7 @@ local Formspec = {
---Set the formspec version to a certain number. If not specified, version `10` is assumed. ---Set the formspec version to a certain number. If not specified, version `10` is assumed.
---@field version? number ---@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`
---@field size {x:number, y:number, fixed_size:boolean?} ---@field size? {x:number, y:number, fixed_size:boolean?}
---Defines the position on the game window of the formspec's anchor point. ---Defines the position on the game window of the formspec's anchor point.
---@field position? {x:number, y:number} ---@field position? {x:number, y:number}
---Defines the location of the anchor point within the formspec. ---Defines the location of the anchor point within the formspec.
@@ -36,7 +36,12 @@ function Formspec:new(def)
local version = ('formspec_version[%s]'):format( def.version or 10) -- formspec version 10 (5.13.0) local version = ('formspec_version[%s]'):format( def.version or 10) -- formspec version 10 (5.13.0)
local size = ('size[%s,%s,%s]'):format(def.size.x, def.size.y, def.size.fixed_size or true) local size
if def.size ~= nil then
size = ('size[%s,%s,%s]'):format(def.size.x, def.size.y, def.size.fixed_size or true)
else
size = ''
end
local position local position
if def.position ~= nil then if def.position ~= nil then
@@ -322,8 +327,9 @@ end
---@param w number ---@param w number
---@param h number ---@param h number
---@param textureName string ---@param textureName string
---@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 values, w and h are ignored) --- to the formspec size (x and y are used as offset
--- values, w and h are ignored)
function Formspec:background(x, y, w, h, textureName, autoClip) function Formspec:background(x, y, w, h, textureName, autoClip)
local element local element
@@ -338,54 +344,225 @@ function Formspec:background(x, y, w, h, textureName, autoClip)
self:addElement(element) self:addElement(element)
end end
---TODO ---9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling
function Formspec:background9() ---@param x number
---@param y number
---@param w number
---@param h number
---@param textureName string
---@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)
---@param middle string Middle is a rect which defines the middle of the 9-slice.
--- * `x` - The middle will be x pixels from all sides.
--- * `x,y` - The middle will be x pixels from the horizontal and y from the vertical.
--- * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2.
--- 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.
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)
end end
---TODO ---Textual password style field; will be sent to server when a button is clicked
function Formspec:pwdfield() ---When enter is pressed in field, `fields.key_enter_field` will be sent with the name of this field.
---With the old coordinate system, fields are a set height, but will be vertically centered on `H`.
---With the new coordinate system, `H` will modify the height.
---
---See field_close_on_enter to stop enter closing the formspec.
---@param x number
---@param y number
---@param w number
---@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.
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)
end end
---TODO ---Textual field; will be sent to server when a button is clicked.
function Formspec:field() ---When enter is pressed in field, `fields.key_enter_field` will be sent with the name of this field.
---With the old coordinate system, fields are a set height, but will be vertically centered on `H`.
---With the new coordinate system, `H` will modify the height.
---
---See field_close_on_enter to stop enter closing the formspec.
---@param x number
---@param y number
---@param w number
---@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.
---@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.
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)
end end
---TODO ---Textual field; will be sent to server when a button is clicked.
function Formspec:fieldCloseOnEnter() ---When enter is pressed in field, `fields.key_enter_field` will be sent with the name of this field.
---Special field for creating simple forms, such as sign text input
---Must be used without a `size[]` element
---A "Proceed" button will be added automatically
---
---See field_close_on_enter to stop enter closing the formspec.
---@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
--- 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.
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)
end end
---TODO
function Formspec:textArea()
---**Experimental**, may be subject to change or removal at any time.
---Only affects Android clients.
---@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).
function Formspec:fieldEnterAfterEdit(name, enterAfterEdit)
local element = ('field_enter_after_edit[%s;%s]'):format(
name, enterAfterEdit or false)
self:addElement(element)
end end
---TODO ---@param name string Is the name of the field.
function Formspec:label() ---@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).
function Formspec:fieldCloseOnEnter(name, closeOnEnter)
local element = ('field_enter_after_edit[%s;%s]'):format(
name, closeOnEnter or false)
self:addElement(element)
end end
---TODO ---Same as text fields, but with multi-line input.
function Formspec:hypertext() ---Text is wrapped to fit within the given bounds.
---If the text overflows, a vertical scrollbar is added.
---@param x number
---@param y number
---@param w number
---@param h number
---@param name string? Is the name of the field as returned in `fields to on_receive_fields`.
--- If the name is empty, the textarea is read-only and the background is not shown,
--- which corresponds to a multi-line label. See also `label[<X>,<Y>;<W>,<H>;<label>]`
--- for an alternative.
---@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
--- 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.
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)
end end
---TODO ---The label formspec element displays the text set in `label` at the specified position.
function Formspec:vertlabel() ---Note: If the new coordinate system is enabled, labels are positioned from the center of
---the text, not the top. The text is displayed directly without automatic line breaking,
---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.
---@param x number
---@param y number
---@param label string
function Formspec:label(x, y, label)
local element = ('label[%s,%s;%s]'):format(
x, y, label)
self:addElement(element)
end end
---TODO ---The "area label" formspec element displays the text set in label at the specified position and size.
function Formspec:button() ---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.
---@param x number
---@param y number
---@param w number
---@param h number
---@param label string
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)
end end
---TODO ---Displays a static formatted text with hyperlinks.
function Formspec:buttonUrl() ---Note: This element is currently unstable and subject to change.
---@param x number
---@param y number
---@param w 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 text string Is the formatted text using `Markup Language` described below.
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)
end
---Textual label drawn vertically.
---@param x number
---@param y number
---@param label string
function Formspec:vertlabel(x, y, label)
local element = ('vertlabel[%s,%s;%s]'):format(
x, y, label)
self:addElement(element)
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.
---@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: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)
end
---Clickable button. When clicked, fields will be sent and the user will be given
---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.
---@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: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)
end end
---TODO ---TODO