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¶
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 theactive
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 theactive
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.
- f (function) – Function to call in
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
ifkey
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.