path: root/doc/fst_api.txt

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)

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
}