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.