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 or style or tag.

Parameters

  • ...: widgets or styles 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 the position 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:

Returns true 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).
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).
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).
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).
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).
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).
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).
widget:onmousedown (fn)
Sets the on mousedown handler for the widget.

Parameters

  • fn: The handler function. Arguments to fn are (self, x, y, button).
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).
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).
widget:owns (..., elt)
Checks whether an element was added to a widget and not removed.

Parameters

  • ...:
  • elt: The widget or style.

Return value:

Returns true if the element was added to the widget and not removed.
widget:remove (...)
Remove elements from the widget. An element could be widget or style or tag.

Parameters

  • ...: widgets or styles 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 and height attributes are set to "auto". This method should be fast.
widget:update (dt)
Update the widget, and sub-widgets

Parameters

  • dt:

Valid XHTML 1.0!