diff --git a/README.md b/README.md index 1ff3675..8617cd2 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,14 @@ Currently most of the items documented in [formspec](http://dev.minetest.net/for There is still more to implement as per the [Minetest Lua API](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt#L1653) (no support yet for those aded items) -A full API documentation is to follow. - ## Example Add a dependency to formspeccer, then use the `formspeccer` object to manage formspecs. Note that coordinates are expressed not in pixels but in a pieces of a grid. For brevity, and to distinguish from actual coordinates, I chose to simply supply them as comma-separated string vlues. +See the API documentation for details. + local formname = "mymod:myform" formspeccer:newform(formname,"10,7") -- a new form , 10x7 diff --git a/api.txt b/api.txt new file mode 100644 index 0000000..b88f2ff --- /dev/null +++ b/api.txt @@ -0,0 +1,231 @@ +FormSpeccer API + +v 0.3 (alpha) + +This API is still under development, please ensure you are aware of this. + +-------- + +The FormSpeccer API is a helper tool to allow you to create formspecs +using the more familiar "tabular" notation used throughout minetest, +rather than the more esoteric native formspec language. + + 1/ Form Spec Coordinates System + +Formspecs do not use a pixel-based coordinate system, because differing +client window sizes would need to have a corresponding matching set of +corrdinates programmed in advance. + +Instead, formspecs rely on an inventory grid coordinate system. A +coordinate, or size, of "1,1" would define the space of a single +inventory grid square. + +Width and heights in this API therefore follow on from this notation -- +a pair of width-height coordinates are denoted by a `wh` property; +and a pair of (x,y) coordinates are denoted by a `xy` property. + + 2/ Form + + 2.a / Basic manipulation + +Create a new form using + + formspeccer:newform ( FORMNAME , SIZE , PREFS ) + +The form name should be a unique name for the form you want to register. +PREFS is an optional table (see 2.b) + +For example: + + local formname = formspeccer:newform("spawnermod:spawnerform" , "10,7" ) + +The function returns the name of the form (in its current implementation), +in this instance, "spawnermod:spawnerform". Future implementations may +instead return an object representing the form instance. + +You cannot immediately call "newform" on an existing form name if that +form is being managed by FormSpeccer. + +Instead, you would need to clear it first, before re-defining it: + + formspeccer:clear("spawnermod:spawnerform") + formspeccer:newform("spawnermod:spawnerform" , "10,7" ) + +Any mod can clear any form by name. + + 2.b / Additional features + +In the PREFS argument you can provide a table with additional +parameters to customize the form with. + + PREFS = { + bgcolor = COLORNAME + } + +COLORNAME can by a HTML-compatible hex string (for exampple "#ccff00"), +or a colour name. + +Supported colour names are: red, green, blue, yellow, cyan, magenta, +white, black, lightgrey, mediumgrey, darkgrey. + + PREFS = { + background = { + xy = OFFSET, + WH = SIZE, + texture = TEXTURENAME, + auto_clip = BOOL_AUTOCLIP, + } + } + +A background image can be set instead of the default. It gets its image +from all available textures. + +If AUTOCLIP_BOOL is set to true, the image will be limited to displaying +within the confines of the form area, otherwise it will bleed outwards. +Default is true. + + 3/ Formspec Elements + +* All elements should be defined with a `name`, `xy` and `wh` + definition. +* All elements except the label element expect a `name` definition. +* Only the field element can be defined without `xy` or `wh`, but this + is considered bad practice. + +The `xy` definition places the form element at the corresponding offset. +Note that if you place an element at xy = "1,1", you will see it actually +displayed slightly offset. + +The `wh` definition determines what width and heigh the field part of the +form element will take. + +The `name` definition provides the field with a name, to be referenced +during `receive_fiuelds` callbacks. + +The `label` definition provides the field with a displayed label. This +definition is optional, but recommended. + + 3.a / Button + +formspeccer:add_button(formname, + { + xy = POSITION, + wh = SIZE, + name = ELEMENT_NAME, + label = ELEMENT_LABEL, + texture = IMAGE, + }, + BOOL_QUIT +) + +If BOOL_QUIT is set to true, then clicking the button closes the form. +Default is false. + +If IMAGE specifies a valid texture file, that image is used on the +button. Default is for there to be no image. + + 3.b / Field + +formspeccer:add_field(formname, + { + xy = POSITION, + wh = SIZE, + name = ELEMENT_NAME, + label = ELEMENT_LABEL, + }, + BOOL_PASS +) + +If BOOL_PASS is set to true, then the input field will be obfuscated +with asterisks. Default is false. + + 3.c / Label + +formspeccer:add_label(formname, + { + xy = POSITION, + wh = SIZE, + label = ELEMENT_LABEL, + }, + BOOL_VERTICAL +) + +If BOOL_VERTICAL is set to true, the etxt will be displayed with each +letter under the other, in vertical-style writing. Default is false. + + 3.d / List + +formspeccer.add_choice_list(formname, + { + xy = POSITION, + wh = SIZE, + name = ELEMENT_NAME, + label = ELEMENT_LABEL, + choices = ARRAY_OF_CHOICES, + }, + BOOL_MULTI, + BOOL_TRANSPARENT +) + +ARRAY_OF_CHOICES is an anonymous table of selectable items, for example, + + { "choice1", "choice 2", "another thing to choose" } + +If BOOL_MULTI is set to true, then the player can make multiple choices. +Default is false. + +If BOOL_TRANSPARENT is set tot true, then the background is made +transparent. Default is false. + + 3.e / Inventory + +formspeccer:add_label(formname, + { + xy = POSITION, + wh = SIZE, + name = ELEMENT_NAME, + location = INVENTORY_LOCATION, + start_index = IDX, + }, +) + +INVENTORY_LOCATION is the name of the location or detatched inventory to use +(needs elaboration). + +IDX is the index at which to start (needs elaboration) + + + +============================================ + +Still to document: + + form.lua:formspeccer.to_string = function(self,formname) + form.lua:formspeccer.show = function(self,player,formname) + + list.lua:formspeccer.add_inventory = function(self,form,def) + textarea.lua:formspeccer.add_textarea = function(self,form,def) + +Stil to implement: + listcolors + * http://dev.minetest.net/formspec#listcolors + * a formspec preference + container / container_end + listring / listring_end + tooltip + image + item_image_button + tabheader + box + checkbox + scrollbar + table + tableoptions + tablecolumns + inventorylocations + * flesh out the definition + * https://github.com/minetest/minetest/blob/master/doc/lua_api.txt#L1754 + colostring + colorspec + * my custom colour lookup may be unnecessary + * https://github.com/minetest/minetest/blob/master/doc/lua_api.txt#L1754