File ui/widget.lua
loveui is a love2d library to provide resuable GUI widgets to love2d developers.
Functions
widget:add (...) | Add elements to the widget. |
widget:addstyle (st) | Add a style to the widget, so all widget that matches the style's tags will have that style applied. |
widget:addtag (t) | Add a tag to the widget, so only styles with tags that this widget matches will be applied to this widget. |
widget:addwidget (w) | Add a widget to the widget. |
widget:apply (attrs) | Copies all key-value pairs into the widgets' attributes field. |
widget:bounds () | Calculates the left, top, width, height. |
widget:compute () | Compute the current style for a widget, and all sub-widgets. |
widget:contains (x, y) | Returns true if the bounds of the widget contains point x, y. |
widget:draw () | Draws the widget and any sub-widget within the widget. |
widget:drawbackground (st, left, top, width, height, bounds) | Draw the background of the widget. |
widget:drawborder (st, left, top, width, height, bounds) | Draw the border of the widget. |
widget:drawcontent (st, left, top, width, height, bounds) | Override to draw the content of the widget. |
widget:drawcorner (st, left, top, width, height, bounds) | Draw the corner of the widget where borders meet. |
widget:focus (w) | Switch focus to self or a subwidget and invoke to appropriate handlers. |
widget:get (tags) | Gets all sub-widgets of the widget with the matching tags. |
widget:init (tags, args) | Initiates a widget instance. |
widget:match (tags) | Checks whether the widget matches the specified tags. |
widget:mousepressed (x, y, button) | Send mousepressed event to widget, and/or sub-widgets. |
widget:mousereleased (x, y, button) | Send mousereleased event to the focused widget. |
widget:onblur (fn) | Sets the on lost focus handler for the widget. |
widget:onchange (fn) | Sets the on change handler for the widget. |
widget:onclick (fn) | Sets the on click handler for the widget. |
widget:onfocus (fn) | Sets the on focus handler for the widget. |
widget:onkeydown (fn) | Sets the on keydown handler for the widget. |
widget:onkeypress (fn) | Sets the on keypress handler for the widget. |
widget:onkeyup (fn) | Sets the on keyup handler for the widget. |
widget:onmousedown (fn) | Sets the on mousedown handler for the widget. |
widget:onmouseenter (fn) | Sets the on mouseenter handler for the widget. |
widget:onmouseleave (fn) | Sets the on mouseleave handler for the widget. |
widget:owns (..., elt) | Checks whether an element was added to a widget and not removed. |
widget:remove (...) | Remove elements from the widget. |
widget:removestyle (st) | Removes a style from the widget that was previously added. |
widget:removewidget (w) | Removes a widget from the widget that was previously added. |
widget:size () | Override to calculate a default size for the widget, when its style's width and height attributes are set to "auto" . |
widget:update (dt) | Update the widget, and sub-widgets |
Functions
- widget:add (...)
-
Add elements to the widget. An element could be
widget
orstyle
or tag.Parameters
-
...:
widget
s orstyle
s or a string.
-
...:
- widget:addstyle (st)
-
Add a style to the widget, so all widget that matches the style's tags will have that style applied.
Parameters
- st: The style to be added.
- widget:addtag (t)
-
Add a tag to the widget, so only styles with tags that this widget matches will be applied to this widget.
Parameters
- t: The tag to be added.
- widget:addwidget (w)
-
Add a widget to the widget.
Parameters
- w: The widget to be added.
- widget:apply (attrs)
-
Copies all key-value pairs into the widgets' attributes field.
Parameters
- attrs: A table containing key-value pairs
- widget:bounds ()
-
Calculates the left, top, width, height. Left, top are relative if the computed style's
position
attribute is"relative"
; It is absolute if theposition
attribute is"absolute"
. This method should be fast. - widget:compute ()
-
Compute the current style for a widget, and all sub-widgets. This function is expensive, do not call every frame.
Return value:
The current style - widget:contains (x, y)
-
Returns true if the bounds of the widget contains point x, y.
Parameters
- x: The x coordinate.
- y: The y coordinate.
- widget:draw ()
- Draws the widget and any sub-widget within the widget.
- widget:drawbackground (st, left, top, width, height, bounds)
-
Draw the background of the widget. Can be overridden by subclasses.
Parameters
- st: The computed style to follow.
- left:
- top:
- width:
- height:
- bounds: The bounding rectangle of the widget. The background will lie on or within the bounds
- widget:drawborder (st, left, top, width, height, bounds)
-
Draw the border of the widget. Can be overridden by subclasses.
Parameters
- st: The computed style to follow.
- left:
- top:
- width:
- height:
- bounds: The bounding rectangle of the widget. The border will reside on the outside of bounds.
- widget:drawcontent (st, left, top, width, height, bounds)
-
Override to draw the content of the widget. To be overridden by subclasses.
Parameters
- st: The computed style to follow.
- left:
- top:
- width:
- height:
- bounds: The bounding rectangle of the widget. The background will lie on or within the bounds
- widget:drawcorner (st, left, top, width, height, bounds)
-
Draw the corner of the widget where borders meet. Can be overridden by subclasses.
Parameters
- st: The computed style to follow.
- left:
- top:
- width:
- height:
- bounds: The bounding rectangle of the widget. The border will reside on the outside of bounds.
- widget:focus (w)
-
Switch focus to self or a subwidget and invoke to appropriate handlers.
Parameters
- w: The widget to focus. Should be a subwidget or self but this is not checked by the function.
- widget:get (tags)
-
Gets all sub-widgets of the widget with the matching tags. Excludes the widget being called even if it matches the tags specified in the argument.
Parameters
- tags: A string of whitespaced separated tags
Return value:
A table containing the matching widgets - widget:init (tags, args)
-
Initiates a widget instance. The widget class is meant to be subclassed by other widgets and is not designed to be instantiated. Subclasses are supposed to read args from self.attributes.
Parameters
- tags: A string of whitespaced separated tags
- args: A table of key-value object attributes
- widget:match (tags)
-
Checks whether the widget matches the specified tags.
Parameters
- tags: A string of whitespaced separated tags
Return value:
Returnstrue
if the widget matches the tags. - widget:mousepressed (x, y, button)
-
Send mousepressed event to widget, and/or sub-widgets.
Parameters
- x: The x coordinate.
- y: The y coordinate.
- button: The mouse button pressed.
- widget:mousereleased (x, y, button)
-
Send mousereleased event to the focused widget. A mouse release event only occurs when the mouse press was sent to the same widget.
Parameters
- x: The x coordinate.
- y: The y coordinate.
- button: The mouse button released.
- widget:onblur (fn)
-
Sets the on lost focus handler for the widget. A change occurs when a widget has lost focus by mouse or tab.
Parameters
-
fn: The handler function. Arguments to
fn
are (self).
-
fn: The handler function. Arguments to
- widget:onchange (fn)
-
Sets the on change handler for the widget. A change occurs when a widget's user value changes. It is up to the widget as to when the handler is called.
Parameters
-
fn: The handler function. Arguments to
fn
are (self, oldvalue, newvalue).
-
fn: The handler function. Arguments to
- widget:onclick (fn)
-
Sets the on click handler for the widget. A click occurs when a mouse press and a mouse release occurs on the same widget's bounds.
Parameters
-
fn: The handler function. Arguments to
fn
are (self, x, y, button).
-
fn: The handler function. Arguments to
- widget:onfocus (fn)
-
Sets the on focus handler for the widget. A change occurs when a widget has been focused by mouse or tab.
Parameters
-
fn: The handler function. Arguments to
fn
are (self).
-
fn: The handler function. Arguments to
- widget:onkeydown (fn)
-
Sets the on keydown handler for the widget. A keydown event is triggered when a key is helf while the element is focused.
Parameters
-
fn: The handler function. Arguments to
fn
are (self, key, unicode).
-
fn: The handler function. Arguments to
- widget:onkeypress (fn)
-
Sets the on keypress handler for the widget. A keypress event is triggered when a key is held and released while the element is focused.
Parameters
-
fn: The handler function. Arguments to
fn
are (self, key, unicode).
-
fn: The handler function. Arguments to
- widget:onkeyup (fn)
-
Sets the on keyup handler for the widget. A keyup event is triggered when a key is released while the element is focused.
Parameters
-
fn: The handler function. Arguments to
fn
are (self, key, unicode).
-
fn: The handler function. Arguments to
- widget:onmousedown (fn)
-
Sets the on mousedown handler for the widget.
Parameters
-
fn: The handler function. Arguments to
fn
are (self, x, y, button).
-
fn: The handler function. Arguments to
- widget:onmouseenter (fn)
-
Sets the on mouseenter handler for the widget. A mouseenter event is triggered when the mouse moves within the bounds of an event.
Parameters
-
fn: The handler function. Arguments to
fn
are (self, x, y).
-
fn: The handler function. Arguments to
- widget:onmouseleave (fn)
-
Sets the on mouseleave handler for the widget. A mouseleave event is triggered when the mouse moves out of the bounds of an event.
Parameters
-
fn: The handler function. Arguments to
fn
are (self, x, y).
-
fn: The handler function. Arguments to
- widget:owns (..., elt)
-
Checks whether an element was added to a widget and not removed.
Parameters
- ...:
- elt: The widget or style.
Return value:
Returnstrue
if the element was added to the widget and not removed. - widget:remove (...)
-
Remove elements from the widget. An element could be
widget
orstyle
or tag.Parameters
-
...:
widget
s orstyle
s or a string.
-
...:
- widget:removestyle (st)
-
Removes a style from the widget that was previously added.
Parameters
- st: The style to be removed.
- widget:removewidget (w)
-
Removes a widget from the widget that was previously added.
Parameters
- w: The widget to be removed.
- widget:size ()
-
Override to calculate a default size for the widget, when its style's
width
andheight
attributes are set to"auto"
. This method should be fast. - widget:update (dt)
-
Update the widget, and sub-widgets
Parameters
- dt: