Marco Pontello's Home - Plugins - DogLua - Reference info

Reference info

GUI Server API

Using the GUI Server it's possible to generate rich dialog boxes with minimal coding effort.

Dialog control

GUI_OpenPanel()

GUI_ClosePanel()

GUI_WaitOnEvent()

Appareance

GUI_SetCaption()

GUI_AddLogo()

GUI_SetSpacing()

Controls

GUI_AddControl()

GUI_GetSettings()

GUI_SetSettings()

GUI_SetList()

Here's a small sample to get a general idea about how things works:


-- Set the dialog's title
GUI_SetCaption("My filter")
-- Add a couple of controls
h1 = GUI_AddControl("Scroller", "Threshold", 50, 1, 100)
h2 = GUI_AddControl("Check", "Best accuracy", 1)
-- Open the dialog
GUI_OpenPanel()

-- Main event loop
repeat
  idx, retval, retstr = GUI_WaitOnEvent()

  -- Here goes code to be executed on every
  -- controls change, with the dialog still open
  Dog_MessageBox("Control idx: "..idx,
                 "Value: "..retval,
                 "String: "..retstr)

  -- idx -1 = OK, -2 = Cancel
until idx < 0

-- Get the controls properties
value, dummystr = GUI_GetSettings(h1)
flag, dummystr = GUI_GetSettings(h2)
-- Close
GUI_ClosePanel()

GUI_OpenPanel()

Display the dialog box.
N.B. DogLua will automatically issue a GUI_OpenPanel() if a GUI_WaitOnEvent() is encountered and the dialog box isn't yet opened.

GUI_ClosePanel()

Close the dialog box.
N.B. DogLua will automatically close the dialog box when the script is finished, to avoid the possiblity of leaving dialogs floating around.

idx, retval, retstr = GUI_WaitOnEvent()

Wait for a dialog event: a button clicked, a scroller moved, etc. It returns the index of the control that generated the event, and both a numeric and a string parameters with values depending on the control's type. The index will be equal to -1 or -2 if the [OK] or [CANCEL] button was pressed.

Usually GUI_WaitOnEvent() is used in a repeat - until loop, eventualy executing some code on every iteration.

Example:


repeat
  -- wait for an event
  idx, retval, retstr = GUI_WaitOnEvent()
  -- query the settings of a control
  value, dummystr = GUI_GetSettings(hMyScroller)
  -- call a filter function passing the value
  MyFilter(value)
  -- cycle until [OK] or [CANCEL] is pressed
until idx < 0

GUI_SetCaption(title_string)

Specify a title for the dialog. Can be used anywhere, before the dialog is displayed.

GUI_AddLogo(bitmap_filename)

Specify a bitmap to be showed on top of the dialog. Like the GUI_SetCaption() functon, it should be used before opening the dialog. If the file name doesn't contain any path info, the bitmap will be searched on the DogLuaScripts folder.

GUI_SetSpacing(x)

Set how much space should be between controls.

GUI_AddControl()

retval, retstr = GUI_GetSettings(idx)

Used to retrive the settings / properties of a control. Should be used before closing the dialog. The only parameter needed is the control's index (obtained when the control was added). The function will always return both a numeric and a string parameters, with values depending on the control's type.

Example:


h1 = GUI_AddControl("Check", "Apply filter", 1)
h2 = GUI_AddControl("Text", "File name")
...
retval1, retstr1 = GUI_GetSettings(h1)
retval2, retstr2 = GUI_GetSettings(h2)

-- retval1 will be 1 or 0, retstr1 will be an empty string
-- retval2 will be 0, retstr2 will contain the file name string

GUI_SetSettings(idx, val, str)

Change the properties / settings of a control previously added to the dialog. The parameters to be supplied are the index of the control, a numeric value and a string value (with meaning depending on the control's type).

Example:


-- Add a text control, specifying its caption
h1 = GUI_AddControl("Text", "Text field")
-- Set control's text field contents
GUI_SetSettings(h1, 0, "my string")

GUI_SetList()

(work in progress...)

DogLua - Project Dogwaffle Lua scriptable interface

Reference info

GUI Server API