89 lines
4 KiB
Markdown
89 lines
4 KiB
Markdown
|
smartfs
|
||
|
|
=======
|
||
|
|
|
||
|
|
This mod provides a 2nd generation way of creating forms - this means that the modder does not need to worry about complex formspec strings
|
||
|
|
|
||
|
|
* Expandable: you can register your own elements to use on the form.
|
||
|
|
* Easy event handling: use binding to handle events.
|
||
|
|
* New elements: Includes a toggle button
|
||
|
|
|
||
|
|
License: WTFPL
|
||
|
|
To install this library, place the smartfs.lua file in your mod and then include it (dofile).
|
||
|
|
There is an init.lua file in the download that shows you how to do this.
|
||
|
|
|
||
|
|
#Using Smart Formspec
|
||
|
|
Smartfs provides 2nd generation Minetest forms to replace clunky formspec strings. Each smartfs form is a container filled with GUI elements. A number of default elements are included with smartfs, but modders can also define their own custom elements. This document describes the basic usage of the smartfs API.
|
||
|
|
|
||
|
|
##Installation
|
||
|
|
Smartfs can be used as a library or a mod.
|
||
|
|
|
||
|
|
To use smartfs as a library, copy the smartfs.lua file to your mod folder and add
|
||
|
|
dofile(minetest.get\_modpath(minetest.get\_current\_modname()).."/smartfs.lua")
|
||
|
|
to the top of any files that use it.
|
||
|
|
|
||
|
|
To use smartfs as a mod, add it to your game's mods folder or to the user mods folder and enable it.
|
||
|
|
|
||
|
|
## Creating and showing forms
|
||
|
|
A form is a rectangular area of the screen upon which all elements are placed. Use the smartfs.create() function to create a new form. This function takes two arguments and returns a form object.
|
||
|
|
|
||
|
|
The first argument is a unique string that identifies the form. The second argument is a function that should take a single argument called state which is used to set form properties like size and background color. State also has constructors for all form elements and can be used with state:element_name. Below is a quick example.
|
||
|
|
|
||
|
|
myform = smartfs.create("My Form",function(state)
|
||
|
|
--sets the form's size
|
||
|
|
-- (width, hieght)
|
||
|
|
state:size(5,5)
|
||
|
|
|
||
|
|
--creates a label and places it on the form
|
||
|
|
--(x-pos, y-pos, name, text)
|
||
|
|
state:label(3,3,"label1", "A label!")
|
||
|
|
end)
|
||
|
|
|
||
|
|
Forms can be shown to the player by using the show(target) function. The target argument is the name of the player that will see the form.
|
||
|
|
|
||
|
|
myform:show("singleplayer")
|
||
|
|
|
||
|
|
Here is a list of steps the library takes.
|
||
|
|
* You create a new form using smartfs.create().
|
||
|
|
* The form is registered and stored for later use.
|
||
|
|
* You show a form to a player using the myform:show()
|
||
|
|
* The state is created and stored.
|
||
|
|
* The function in smartfs.create runs and creates the elements.
|
||
|
|
* The form is displayed to the player.
|
||
|
|
|
||
|
|
## Modifying Elements
|
||
|
|
Elements have functions of the form element:function(args) where you need to have access to the element object.
|
||
|
|
|
||
|
|
You can get the element object by assigning a variable to its creation function like so:
|
||
|
|
|
||
|
|
local button1 = state:button(0,0, 1,4, "btn1", "A button")
|
||
|
|
--button1 is now a table representing the button
|
||
|
|
|
||
|
|
You can also get the element by using state:get(name). The example below will retrieve a button with the name "btn1":
|
||
|
|
|
||
|
|
button1 = state:get("btn1")
|
||
|
|
--or
|
||
|
|
state:get("btn1"):onClick(your\_onclick\_function
|
||
|
|
|
||
|
|
Both of these methods should be used inside the form creation callback function, the function you pass to smartfs.create, or in event callbacks.
|
||
|
|
|
||
|
|
Now that you have located your element you can modify it.
|
||
|
|
|
||
|
|
button1:setPos(4,0)
|
||
|
|
|
||
|
|
## Inventory Support
|
||
|
|
Smartfs supports adding a button to Inventory+ or Unified Inventory which will open one of your own custom forms. Use the smartfs.add\_to\_inventory(form, icon, title) function where form is the smartfs form linked to by the button, icon is the button image (only for unified inventory), and title is the button text (only for inventory+).
|
||
|
|
|
||
|
|
smartfs.add_to_inventory(form, icon, title)
|
||
|
|
|
||
|
|
## Dynamic forms
|
||
|
|
Dynamic forms allow you to make a form without having to register it before the game finished loading.
|
||
|
|
|
||
|
|
local state = smartfs.dynamic("smartfs:dyn_form", name)
|
||
|
|
state:load(minetest.get_modpath("smartfs").."/example.smartfs")
|
||
|
|
state:get("btn"):click(function(self,state)
|
||
|
|
print("Button clicked!")
|
||
|
|
end)
|
||
|
|
state:show()
|
||
|
|
|
||
|
|
Make sure you call state:show()
|