Core Functions¶

The core functions can be divided into two parts: Functions of interest to the user and functions of interest to the (widget) developer.

External Interface¶

Drawing¶

draw()¶

Draw the GUI - call in love.draw.

theme¶

The current theme. See Themeing.

Mouse Input¶

updateMouse(x, y, buttonDown)¶

Arguments:	x,y (number) – Position of the mouse. buttonDown (boolean) – Whether the mouse button is down.

Update mouse position and button status. You do not need to call this function, unless you use some screen transformation (e.g., scaling, camera systems, …).

Keyboard Input¶

keypressed(key)¶

Arguments:	key (KeyConstant) – The pressed key.

Forwards a love.keypressed(key) event to SUIT.

textinput(char)¶

Arguments:	char (string) – The pressed character

Forwards a love.textinput(key) event to SUIT.

GUI State¶

anyHovered()¶

Returns:	`true` if any widget is hovered by the mouse.

Checks if any widget is hovered by the mouse.

isHovered(id)¶

Arguments:	id (mixed) – Identifier of the widget.
Returns:	`true` if the widget is hovered by the mouse.

Checks if the widget identified by id is hovered by the mouse.

wasHovered(id)¶

Arguments:	id (mixed) – Identifier of the widget.
Returns:	`true` if the widget was in the hovered by the mouse in the last frame.

Checks if the widget identified by id was hovered by the mouse in the last frame.

anyActive()¶

Returns:	`true` if any widget is in the `active` state.

Checks whether the mouse button is pressed and held on any widget.

isActive(id)¶

Arguments:	id (mixed) – Identifier of the widget.
Returns:	`true` if the widget is in the `active` state.

Checks whether the mouse button is pressed and held on the widget identified by id.

anyHit()¶

Returns:	`true` if the mouse was pressed and released on any widget.

Check whether the mouse was pressed and released on any widget.

isHit(id)¶

Arguments:	id (mixed) – Identifier of the widget.
Returns:	`true` if the mouse was pressed and released on the widget.

Check whether the mouse was pressed and released on the widget identified by id.

Internal Helpers¶

getOptionsAndSize(...)¶

Arguments:	... (mixed) – Varargs.
Returns:	`options, x,y,w,h`.

Converts varargs to option table and size definition. Used in the widget functions.

registerDraw(f, ...)¶

Arguments:	f (function) – Function to call in `draw()`. ... (mixed) – Arguments to f.

Registers a function to be executed during draw(). Used by widgets to make themselves visible.

enterFrame()¶

Prepares GUI state when entering a frame.

exitFrame()¶

Clears GUI state when exiting a frame.

Mouse Input¶

mouseInRect(x, y, w, h)¶

Arguments:	x,y,w,h (numbers) – Rectangle definition.
Returns:	`true` if the mouse cursor is in the rectangle.

Checks whether the mouse cursor is in the rectangle defined by x,y,w,h.

registerMouseHit(id, ul_x, ul_y, hit)¶

Arguments:	id (mixed) – Identifier of the widget. ul_x, ul_y (numbers) – Upper left corner of the widget. hit (function) – Function to perform the hit test.

Registers a hit-test defined by the function hit for the widget identified by id. Sets the widget to hovered if th hit-test returns true. Sets the widget to active if the hit-test returns true and the mouse button is pressed.

The hit test receives coordinates in the coordinate system of the widget, i.e. (0,0) is the upper left corner of the widget.

registerHitbox(id, x, y, w, h)¶

Arguments:	id (mixed) – Identifier of the widget. x,y,w,h (numbers) – Rectangle definition.

Registers a hitbox for the widget identified by id. Literally this function:

function registerHitbox(id, x,y,w,h)
    return registerMouseHit(id, x,y, function(u,v)
        return u >= 0 and u <= w and v >= 0 and v <= h
    end)
end

mouseReleasedOn(id)¶

Arguments:	id (mixed) – Identifier of the widget.
Returns:	`true` if the mouse was released on the widget.

Checks whether the mouse button was released on the widget identified by id.

getMousePosition()¶

Returns:	Mouse positon `mx, my`.

Get the mouse position.

Keyboard Input¶

getPressedKey()¶

Returns:	KeyConstant

Get the currently pressed key (if any).

grabKeyboardFocus(id)¶

Arguments:	id (mixed) – Identifier of the widget.

Try to grab keyboard focus. Successful only if the widget is in the active state.

hasKeyboardFocus(id)¶

Arguments:	id (mixed) – Identifier of the widget.
Returns:	`true` if the widget has keyboard focus.

Checks whether the widget identified by id currently has keyboard focus.

keyPressedOn(id, key)¶

Arguments:	id (mixed) – Identifier of the widget. key (KeyConstant) – Key to query.
Returns:	`true` if `key` was pressed on the widget.

Checks whether the key key was pressed while the widget identified by id has keyboard focus.

Instancing¶

new()¶

Returns:	Separate UI state.

Create a separate UI and layout state. Everything that happens in the new state will not affect any other state. You can use the new state like the “global” state suit, but call functions with the colon syntax instead of the dot syntax, e.g.:

function love.load()
    dress = suit.new()
end

function love.update()
    dress.layout:reset()
    dress:Label("Hello, World!", dress.layout:row(200,30))
    dress:Input(input, dress.layout:row())
end

function love.draw()
    dress:draw()
end

Warning

Unlike UI and layout state, the theme might be shared with other states. Changes in a shared theme will be shared across all themes. See the Instance Theme subsection in the Getting Started guide.