This document describes the loveui library when its implementation is complete.
To create a set of GUI widgets for love2d developers. The widgets should be easily customized and not fixed to a theme. The code for adding and styling widgets should be as concise and easy to read as possible.
loveui is a set of widgets.
A widget could be a button, a textfield, a progress bar, etc. It can also be a rectangle.
A widget can have widgets within it. E.g. A rectangle containing a progress bar.
There is a widget that is the top most widget, which catches mouse and key events and passes them along. It is the context widget.
To add a widget: widget1:add(widget2)
To remove, widget1:remove(widget2)
Widgets' appearance are described by styles.
A widget is tagged by multiple strings. loveui widgets are tagged with their own classes' names. E.g. ui.button widget instances are always tagged with "ui.button". When the mouse is hovering over it, it is tagged with "ui.button" and "ui.hover", as well.
Every style has a "selector" - A string of tags separated by whitespace. The style will apply to widgets that contain all of the tags in side the "selector".
To add a style: widget1:add(style1)
To remove, widget1:remove(widget2)
When a style is added to a widget, it can only ever apply to sub-widgets of that widget, irrespective of what is tagged with what and what tags are in the selector. It cannot apply to the widget you added to either; sub-widgets and their sub-widgets and their sub-widgets... only.
Once you add a style, even if you remove the widgets the style applies to and add them back again as sub-widgets, the style is still there and will still apply, similar to HTML elements and CSS styles.
Widgets' actions are described by callback functions.
There are several type of triggers that will invoke callback functions.
click -- When mouse pressed on the widget, and released on
the widget.
change -- When the value of the widget changes.
focus -- When the widget is focused by mouse or tab.
blur -- When the widget loses focus.
mousedown -- When the mouse is pressed down on the widget.
mouseenter -- When the mouse hovers into a widget.
mouseleave -- When the mouse hovers out of a widget.
keypress -- When a key is pressed and released while widget is
focused.
keyup -- When a key is released while widget is focused.
keydown -- When a key is pressed while widget is focused.
To add a callback function for e.g. mousedown: widget1:onmousedown(function(self, x, y, button) end)
Just add 'on' prefix to one of the trigger names and call it on the widget to add a callback for that trigger.
Note that the function returns widget1. See Example Code section.
function love.load()
context:add(
-- Add a style that applies to all `ui.button`s tagged with
-- "tag".
ui.style("ui.button tag", {
left = 100, top = 100,
width = 50, height = 50,
bordercolor = {255,255,0,255},
borderwidth = 1,
backgroundcolor = {255, 255, 255, 255},
backgroundimage = "./button.png"}),
-- Add a button that prints when mouse press or clicks on it.
-- Its label is "Click".
ui.button("tag tag2 tag3", {value = "Click"})
:onmousedown(
function(self, x, y, button)
print("mousedown", x, y, button)
end)
:onclick(
function(self, x, y, button)
print("click", x, y, button)
end))
end
-
ones are not implemented yet.
left top
width height
color font selectioncolor
backgroundcolor *backgroundimage *backgroundrepeat *backgroundposition
borderwidth borderleftwidth borderrightwidth bordertopwidth borderbottomwidth
borderradius bordertopleftradius bordertoprightradius borderbottomleftradius borderbottomrightradius
bordercolor borderleftcolor bordertopcolor borderrightcolor borderbottomcolor
*borderimage
*padding *paddingtop *paddingright *paddingleft *paddingbottom
onclick
onchange
onfocus
onblur
onmouseover
click(x, y)
change("content")
focus()
blur()
mouseover(x, y, dx, dy)
ui.hover
ui.view
ui.context
ui.button
ui.label
ui.textfield
ui.progressbar
ui.frame
:add(style/widget/tag)
:remove(style/widget/tag)
:owns(style/widget/tag)
:apply(attributes)
:get(tags)