diff options
Diffstat (limited to 'streetsmod/libs/smartfs/README.md')
-rw-r--r-- | streetsmod/libs/smartfs/README.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/streetsmod/libs/smartfs/README.md b/streetsmod/libs/smartfs/README.md new file mode 100644 index 0000000..df0e166 --- /dev/null +++ b/streetsmod/libs/smartfs/README.md @@ -0,0 +1,88 @@ +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() |