5.2 KiB
Formspec toolkit api 0.0.3
Formspec toolkit is a set of functions to create basic ui elements.
File: fst/ui.lua
ui.lua adds base ui interface to add additional components to.
ui.add(component) -> returns name of added component ^ add component to ui ^ component: component to add
ui.delete(component) -> true/false if a component was deleted or not ^ remove a component from ui ^ component: component to delete
ui.set_default(name) ^ set component to show if not a single component is set visible ^ name: name of component to set as default
ui.find_by_name(name) --> returns component or nil ^ find a component within ui ^ name: name of component to look for
File: fst/tabview.lua
tabview_create(name, size, tabheaderpos) --> returns tabview component ^ create a new tabview component ^ name: name of tabview (has to be unique per ui) ^ size: size of tabview { x, y } ^ tabheaderpos: upper left position of tabheader (relative to upper left fs corner) { x, y }
Class reference tabview:
methods:
- add_tab(tab) ^ add a tab to this tabview ^ tab: { name = "tabname", -- name of tab to create caption = "tab caption", -- text to show for tab header cbf_button_handler = function(tabview, fields, tabname, tabdata), -- callback for button events --TODO cbf_events = function(tabview, event, tabname), -- callback for events cbf_formspec = function(tabview, name, tabdata), -- get formspec tabsize = { x, -- x width y -- y height }, -- special size for this tab (only relevant if no parent for tabview set) on_change = function(type,old_tab,new_tab) -- called on tab chang, type is "ENTER" or "LEAVE" }
- set_autosave_tab(value) ^ tell tabview to automatically save current tabname as "tabview_name"_LAST ^ value: true/false
- set_tab(name) ^ set's tab to tab named "name", returns true/false on success ^ name: name of tab to set
- set_global_event_handler(handler) ^ set a handler to be called prior calling tab specific event handler ^ handler: function(tabview,event) --> returns true to finish event processing false to continue
- set_global_button_handler(handler) ^ set a handler to be called prior calling tab specific button handler ^ handler: function(tabview,fields) --> returns true to finish button processing false to continue
- set_parent(parent) ^ set parent to attach tabview to. TV's with parent are hidden if their parent is hidden and they don't set their specified size. ^ parent: component to attach to
- show() ^ show tabview
- hide() ^ hide tabview
- delete() ^ delete tabview
- set_fixed_size(state) ^ true/false set to fixed size, variable size
File: fst/dialog.lua
Only one dialog can be shown at a time. If a dialog is closed it's parent is gonna be activated and shown again.
dialog_create(name, cbf_formspec, cbf_button_handler, cbf_events) ^ create a dialog component ^ name: name of component (unique per ui) ^ cbf_formspec: function to be called to get formspec function(dialogdata) ^ cbf_button_handler: function to handle buttons function(dialog, fields) ^ cbf_events: function to handle events function(dialog, event)
messagebox(name, message) ^ creates a message dialog
Class reference dialog:
methods:
- set_parent(parent) ^ set parent to attach a dialog to ^ parent: component to attach to
- show() ^ show dialog
- hide() ^ hide dialog
- delete() ^ delete dialog from ui
members:
- data ^ variable data attached to this dialog
- parent ^ parent component to return to on exit
File: fst/buttonbar.lua
buttonbar_create(name, cbf_buttonhandler, pos, orientation, size) ^ create a buttonbar ^ name: name of component (unique per ui) ^ cbf_buttonhandler: function to be called on button pressed function(buttonbar,buttonname,buttondata) ^ pos: position relative to upper left of current shown formspec { x, y } ^ orientation: "vertical" or "horizontal" ^ size: size of bar { width, height }
Class reference buttonbar:
methods:
- add_button(btn_id, caption, button_image)
- set_parent(parent) ^ set parent to attach a buttonbar to ^ parent: component to attach to
- show() ^ show buttonbar
- hide() ^ hide buttonbar
- delete() ^ delete buttonbar from ui
Developer doc:
Skeleton for any component: { name = "some id", -- unique id type = "toplevel", -- type of component -- toplevel: component can be show without additional components -- addon: component is an addon to be shown along toplevel component hide = function(this) end, -- called to hide the component show = function(this) end, -- called to show the component delete = function(this) end, -- called to delete component from ui handle_buttons = function(this,fields) -- called upon button press handle_events = function(this,event) -- called upon event reception get_formspec = function(this) -- has to return formspec to be displayed }