doc/fst_api.txt

   1 Formspec toolkit api 0.0.3
   2 ==========================
   3
   4 Formspec toolkit is a set of functions to create basic ui elements.
   5
   6
   7 File: fst/ui.lua
   8 ----------------
   9
  10 ui.lua adds base ui interface to add additional components to.
  11
  12 ui.add(component) -> returns name of added component
  13 ^ add component to ui
  14 ^ component: component to add
  15
  16 ui.delete(component) -> true/false if a component was deleted or not
  17 ^ remove a component from ui
  18 ^ component: component to delete
  19
  20 ui.set_default(name)
  21 ^ set component to show if not a single component is set visible
  22 ^ name: name of component to set as default
  23
  24 ui.find_by_name(name) --> returns component or nil
  25 ^ find a component within ui
  26 ^ name: name of component to look for
  27
  28 File: fst/tabview.lua
  29 ---------------------
  30
  31 tabview_create(name, size, tabheaderpos) --> returns tabview component
  32 ^ create a new tabview component
  33 ^ name: name of tabview (has to be unique per ui)
  34 ^ size: size of tabview
  35         {
  36                 x,
  37                 y
  38         }
  39 ^ tabheaderpos: upper left position of tabheader (relative to upper left fs corner)
  40         {
  41                 x,
  42                 y
  43         }
  44
  45 Class reference tabview:
  46
  47 methods:
  48 - add_tab(tab)
  49   ^ add a tab to this tabview
  50   ^ tab:
  51   {
  52         name               = "tabname",      -- name of tab to create
  53         caption            = "tab caption",  -- text to show for tab header
  54         cbf_button_handler = function(tabview, fields, tabname, tabdata), -- callback for button events
  55         --TODO cbf_events         = function(tabview, event, tabname),           -- callback for events
  56         cbf_formspec       = function(tabview, name, tabdata),            -- get formspec
  57         tabsize            =
  58                 {
  59                         x, -- x width
  60                         y  -- y height
  61                 },                                                            -- special size for this tab (only relevant if no parent for tabview set)
  62         on_change          = function(type,old_tab,new_tab)               -- called on tab chang, type is "ENTER" or "LEAVE"
  63   }
  64 - set_autosave_tab(value)
  65   ^ tell tabview to automatically save current tabname as "tabview_name"_LAST
  66   ^ value: true/false
  67 - set_tab(name)
  68   ^ set's tab to tab named "name", returns true/false on success
  69   ^ name: name of tab to set
  70 - set_global_event_handler(handler)
  71   ^ set a handler to be called prior calling tab specific event handler
  72   ^ handler: function(tabview,event) --> returns true to finish event processing false to continue
  73 - set_global_button_handler(handler)
  74   ^ set a handler to be called prior calling tab specific button handler
  75   ^ handler: function(tabview,fields) --> returns true to finish button processing false to continue
  76 - set_parent(parent)
  77   ^ set parent to attach tabview to. TV's with parent are hidden if their parent
  78         is hidden and they don't set their specified size.
  79   ^ parent: component to attach to
  80 - show()
  81   ^ show tabview
  82 - hide()
  83   ^ hide tabview
  84 - delete()
  85   ^ delete tabview
  86 - set_fixed_size(state)
  87   ^ true/false set to fixed size, variable size
  88
  89 File: fst/dialog.lua
  90 ---------------------
  91 Only one dialog can be shown at a time. If a dialog is closed it's parent is
  92 gonna be activated and shown again.
  93
  94 dialog_create(name, cbf_formspec, cbf_button_handler, cbf_events)
  95 ^ create a dialog component
  96 ^ name: name of component (unique per ui)
  97 ^ cbf_formspec: function to be called to get formspec
  98         function(dialogdata)
  99 ^ cbf_button_handler: function to handle buttons
 100         function(dialog, fields)
 101 ^ cbf_events: function to handle events
 102         function(dialog, event)
 103
 104 messagebox(name, message)
 105 ^ creates a message dialog
 106
 107 Class reference dialog:
 108
 109 methods:
 110 - set_parent(parent)
 111   ^ set parent to attach a dialog to
 112   ^ parent: component to attach to
 113 - show()
 114   ^ show dialog
 115 - hide()
 116   ^ hide dialog
 117 - delete()
 118   ^ delete dialog from ui
 119
 120 members:
 121 - data
 122   ^ variable data attached to this dialog
 123 - parent
 124   ^ parent component to return to on exit
 125
 126 File: fst/buttonbar.lua
 127 -----------------------
 128
 129 buttonbar_create(name, cbf_buttonhandler, pos, orientation, size)
 130 ^ create a buttonbar
 131 ^ name: name of component (unique per ui)
 132 ^ cbf_buttonhandler: function to be called on button pressed
 133         function(buttonbar,buttonname,buttondata)
 134 ^ pos: position relative to upper left of current shown formspec
 135         {
 136                 x,
 137                 y
 138         }
 139 ^ orientation: "vertical" or "horizontal"
 140 ^ size: size of bar
 141         {
 142                 width,
 143                 height
 144         }
 145
 146 Class reference buttonbar:
 147
 148 methods:
 149 - add_button(btn_id, caption, button_image)
 150 - set_parent(parent)
 151   ^ set parent to attach a buttonbar to
 152   ^ parent: component to attach to
 153 - show()
 154   ^ show buttonbar
 155 - hide()
 156   ^ hide buttonbar
 157 - delete()
 158   ^ delete buttonbar from ui
 159
 160 Developer doc:
 161 ==============
 162 Skeleton for any component:
 163 {
 164         name           = "some id",               -- unique id
 165         type           = "toplevel",              -- type of component
 166                                                   -- toplevel: component can be show without additional components
 167                                                   -- addon:    component is an addon to be shown along toplevel component
 168         hide           = function(this) end,      -- called to hide the component
 169         show           = function(this) end,      -- called to show the component
 170         delete         = function(this) end,      -- called to delete component from ui
 171         handle_buttons = function(this,fields)    -- called upon button press
 172         handle_events  = function(this,event)     -- called upon event reception
 173         get_formspec   = function(this)           -- has to return formspec to be displayed
 174 }