GUI API

From TargetWiki

The GUI API is for creating and managing GUI elements, such as windows, buttons, and text boxes.

Contents 1 UI Scripts 1.1 Themes 1.2 Event Handler 1.3 Screenshots 1.4 Frame Interval 1.5 Cursor 1.6 Focus 1.7 Widgets 1.8 Debugging 2 Themes 2.1 Cursor 2.2 Components 2.3 Styles 2.4 Assigning Styles

UI Scripts

UI scripts are used to build user interfaces. They define the function of a UI, and the layout, but not the look of individual widgets. UI set the theme script in order to define the look of widgets.

Themes

gui.theme()

Returns the filename of the current theme script.

gui.settheme( <filename> )

Sets this UI to use the specified theme script.

Event Handler

gui.eventhandler()

This returns a standard Targetware event handler. When the event handler's function(s) are called, the first argument indicates the type of event.

• gui.idle. The second argument is the number of seconds elapsed since the last time a gui.idle event was issued.
• gui.shutdown. This event occurs just before a GUI is shut down, which allows a script to take any necessary last minute actions.

gui.idlefrequency()

Returns the number of seconds Targetware will allow to pass between gui.idle events. Events may sometimes occur less often than this, but never more often.

gui.setidlefrequency( <number> )

Sets the time in seconds between gui.idle events.

Screenshots

gui.screenshot()

This takes a screenshot of the current display.

gui.startfilm( <fps> )

Begins recording a video of the current display. FPS is the target frames per second that the video will attempt to maintain. Lower FPS videos have less of an impact on your frame rate.

gui.stopfilm()

This stops filming.

Frame Interval

gui.frameinterval()

This returns the target time to wait between drawing frames. Zero means maximum fps.

gui.setframeinterval( <number> )

This sets the target time to wait between drawing frames. To target a given fps value, pass in 1/fps. Passing zero will maximize frame rate. This is most useful to limit CPU load when not actively playing, such as when in the main UI.

Cursor

gui.cursorvisible()

Returns true or false depending on whether or not the cursor is currently visible.

gui.setcursorvisible( <boolean> )

Sets cursor visibility.

gui.multiclicktime()

Returns the time in seconds between clicks that will count for 'multiple clicking'. In other words, if two clicks come within this time period on the same widget, it will count as a double click. If a third comes within this time period from the second (not first) click, it will count as a triple click.

gui.setmulticlicktime( <number> )

Sets the multiclick time in seconds.

Focus

gui.mouseover()

This returns the widget that the mouse is currently over, or nil if it's not over one. Some widgets (such as a Group or a Grid) don't accept mouseover, and will return nil instead.

gui.focus()

This returns the widget that has the input focus. The widget with the input focus is the one that will process any key presses.

gui.setfocus( <Widget> )

This sets the current input focus to the specified widget. Not all types of widget will accept the input focus. If you specify a widget that won't accept the focus, the current focus won't change.

Widgets

gui.root()

This returns the Group widget that is the root of the gui. It always exists. When new widgets are created, they initially are attached to the root group.

gui.newbutton()

This returns a new Button widget.

gui.newcheckbox()

This returns a new Checkbox widget.

gui.newcombobox()

This returns a new Combobox widget.

gui.newconsole()

This returns a new Console widget.

gui.newgroup()

This returns a new Group widget.

gui.newgrid()

This returns a new Grid widget.

gui.newimage()

This returns a new Image widget.

gui.newjoystick()

This returns a new Joystick widget.

gui.newlabel()

This returns a new Label widget.

gui.newlines()

This returns a new Lines widget.

gui.newlistbox()

This returns a new Listbox widget.

gui.newmenu()

This returns a new Menu widget.

gui.newprogress()

This returns a new Progress widget.

gui.newscrollbar()

This returns a new Scrollbar widget.

gui.newslider()

This returns a new Slider widget.

gui.newtextedit()

This returns a new Textedit widget.

gui.newview()

This returns a new View widget.

gui.newwindow()

This returns a new Window widget.

Debugging

gui.debug()

Returns a boolean indicating whether debugging is on or off.

gui.debug( <boolean> )

When debugging is on, some additional information is rendered to the screen.

Themes

Themes define the look of widgets.

Cursor

gui.cursor()

This returns the Cursor object that will be used if the mouse isn't over a GUI element that has specified a custom cursor.

gui.setcursor( <Cursor> )

This sets the Cursor object that will be used if the mouse isn't over a GUI element that has specified a custom cursor.

Components

Components are usually used to help specify a Widget style.

gui.newcursor()

This returns a new Cursor object.

gui.newfont()

This returns a new Font object.

gui.newtexture()

This returns a new Texture object.

gui.newboxstyle()

This returns a new Box style object.

Styles

Most widget types have an associated style type. A Widget style determines how a widget looks, but not how it behaves.

gui.newbuttonstyle()

This returns a new Button style object.

gui.newcheckboxstyle()

This returns a new Checkbox style object.

gui.newcomboboxstyle()

This returns a new Combobox style object.

gui.newconsolestyle()

This returns a new Console style object.

gui.newgridstyle()

This returns a new Grid style object.

gui.newgroupstyle()

This returns a new Group style object.

gui.newjoystickstyle()

This returns a new Joystick style object.

gui.newlabelstyle()

This returns a new Label style object.

gui.newlistboxstyle()

This returns a new Listbox style object.

gui.newmenustyle()

This returns a new Menu style object.

gui.newprogressstyle()

This returns a new Progress style object.

gui.newscrollbarstyle()

This returns a new Scrollbar style object.

gui.newsliderstyle()

This returns a new Slider style object.

gui.newtexteditstyle()

This returns a new Textedit style object.

gui.newwindowstyle()

This returns a new Window style object.

Assigning Styles

A theme uses these functions to set up the styles for all widgets.

gui.font()

Returns the default font.

gui.setfont( <Font> )

Sets the default font.

gui.buttonstyle()

Returns the Button style.

gui.setbuttonstyle( <Button style> )

Sets the Button style.

gui.checkboxstyle()

Returns the Checkbox style.

gui.setcheckboxstyle( <Checkbox style> )

Sets the Checkbox style.

gui.comboboxstyle()

Returns the Combobox style.

gui.setcomboboxstyle( <Combobox style> )

Sets the Combobox style.

gui.consolestyle()

Returns the Console style.

gui.setconsolestyle( <Console style> )

Sets the Console style.

gui.gridstyle()

Returns the Grid style.

gui.setgridstyle( <Grid style> )

Sets the Grid style.

gui.groupstyle()

Returns the Group style.

gui.setgroupstyle( <Group style> )

Sets the Group style.

gui.joystickstyle()

Returns the Joystick style.

gui.setjoystickstyle( <Joystick style> )

Sets the Joystick style.

gui.labelstyle()

Returns the Label style.

gui.setlabelstyle( <Label style> )

Sets the Label style.

gui.listboxstyle()

Returns the Listbox style.

gui.setlistboxstyle( <Listbox style> )

Sets the Listbox style.

gui.menustyle()

Returns the Menu style.

gui.setmenustyle( <Menu style> )

Sets the Menu style.

gui.progressstyle()

Returns the Progress style.

gui.setprogressstyle( <Progress style> )

Sets the Progress style.

gui.vertscrollbarstyle()

Returns the vertical Scrollbar style.

gui.setvertscrollbarstyle( <Scrollbar style> )

Sets the vertical Scrollbar style.

gui.horizscrollbarstyle()

Returns the horizontal Scrollbar style.

gui.sethorizscrollbarstyle( <Scrollbar style> )

Sets the horizontal Scrollbar style.

gui.vertsliderstyle()

Returns the vertical Slider style.

gui.setvertsliderstyle( <Slider style> )

Sets the vertical Slider style.

gui.horizsliderstyle()

Returns the horizontal Slider style.

gui.sethorizsliderstyle( <Slider style> )

Sets the horizontal Slider style.

gui.texteditstyle()

Returns the Textedit style.

gui.settexteditstyle( <Textedit style> )

Sets the Textedit style.

gui.windowstyle()

Returns the Window style.

gui.setwindowstyle( <Window style> )

Sets the Window style.