Skip to content

Documentation

Kevin Harrison edited this page Oct 18, 2019 · 33 revisions

Context

ui = nuklear.newUI()

Initialize a new instance of the library. This must be called before any of the other functions.


Event

consumed = ui:keypressed(key, scancode, isrepeat)

Pass the given key press event to the UI, returning true if the event is consumed and false otherwise.

See love.keypressed.

consumed = ui:keyreleased(key, scancode)

Pass the given key release event to the UI, returning true if the event is consumed and false otherwise.

See love.keyreleased.

consumed = ui:mousepressed(x, y, button, istouch, presses)

Pass the given mouse press event to the UI, returning true if the event is consumed and false otherwise.

See love.mousepressed.

consumed = ui:mousereleased(x, y, button, istouch, presses)

Pass the given mouse release event to the UI, returning true if the event is consumed and false otherwise.

See love.mousereleased.

consumed = ui:mousemoved(x, y, dx, dy, istouch)

Pass the given mouse move event to the UI, returning true if the event is consumed and false otherwise.

See love.mousemoved.

consumed = ui:textinput(text)

Pass the given text input event to the UI, returning true if the event is consumed and false otherwise.

See love.textinput.

consumed = ui:wheelmoved(x, y)

Pass the given wheel move event to the UI, returning true if the event is consumed and false otherwise.

See love.wheelmoved.


Render

ui:draw()

Draw the UI. Call this once every love.draw.


Update

ui:frameBegin()

Begin a new frame for the UI. Call this once every love.update, before other UI calls.

ui:frameEnd()

End the current frame. Call this once every love.update, after other UI calls.

ui:frame(body)

Equivalent to:

ui:frameBegin()
body(ui)
ui:frameEnd()

Transform

All transform functions must be called after ui:frameBegin and before any non-transform functions.

ui:rotate(angle)

Rotate the UI by angle (in radians).

See love.graphics.rotate.

ui:scale(scale)

ui:scale(scaleX, scaleY)

Scale the UI by scale in both X and Y directions, or specify scaleX and scaleY separately.

See love.graphics.scale.

ui:shear(shearX, shearY)

Shear the UI by shearX in the X direction and shearY in the Y direction.

See love.graphics.shear.

ui:translate(dx, dy)

Translate the UI by dx in the X direction and dy in the Y direction.

See love.graphics.translate.


Window

open = ui:windowBegin(title, x, y, width, height, flags...)

open = ui:windowBegin(name, title, x, y, width, height, flags...)

Create or update a window with the given name. The name is a unique identifier used internally to differentiate between windows. If unspecified, the name defaults to the title. The x, y, width, and height parameters describe the window's initial bounds. All additional arguments are interpreted as window flags.

Returns true if the window is open and false if it is closed or collapsed.

ui:windowEnd()

End a window. This must always be called after ui:windowBegin, regardless of whether or not the window is open.

ui:window(title, x, y, width, height, flags..., body)

ui:window(name, title, x, y, width, height, flags..., body)

Equivalent to:

if ui:windowBegin(...) then
	body(ui)
end
ui:windowEnd()

x, y, width, height = ui:windowGetBounds()

Return the bounds of the current window.

x, y = ui:windowGetPosition()

Return the position of the current window.

width, height = ui:windowGetSize()

Return the size of the current window.

x, y, width, height = ui:windowGetContentRegion()

Return the bounds of the current window's content region.

focused = ui:windowHasFocus()

Return true if the current window is focused, and false otherwise.

sx, sy = ui:windowGetScroll()

Get the scroll position (sx, sy) of the current window.

ui:windowSetScroll(sx, sy)

Set the scroll position (sx, sy) of the current window.

collapsed = ui:windowIsCollapsed(name)

Return true if the given window is collapsed, and false otherwise.

closed = ui:windowIsClosed(name)

Return true if the given window was closed using ui:windowClose, and false otherwise.

hidden = ui:windowIsHidden(name)

Return true if the given window is hidden, and false otherwise.

active = ui:windowIsActive(name)

Return true if the given window is active, and false otherwise.

hovered = ui:windowIsHovered()

Return true if the current window is hovered by the mouse, and false otherwise.

hovered = ui:windowIsAnyHovered()

Return true if any window is hovered by the mouse, and false otherwise.

active = ui:itemIsAnyActive()

Return true if any item is active, and false otherwise.

ui:windowSetBounds(name, x, y, width, height)

Set the bounds of the given window.

ui:windowSetPosition(name, x, y)

Set the position of the given window.

ui:windowSetSize(name, width, height)

Set the size of the given window.

ui:windowSetFocus(name)

Focus on the given window.

ui:windowClose(name)

Close the given window.

ui:windowCollapse(name)

Collapse the given window.

ui:windowExpand(name)

Expand the given window.

ui:windowShow(name)

Show the given window.

ui:windowHide(name)

Hide the given window.

Flags

Windows and some window-like widgets can accept a number of window flags. Either specify the window flags separately as function arguments or bundle them all in a single table. Here is a list of the possible flags alongside their meanings:

'border'

Draw a border around the window.

'movable'

The window can be moved by dragging the header.

'scalable'

The window can be scaled by dragging the corner.

'closable'

The window can be closed by clicking the close button.

'minimizable'

The window can be collapsed by clicking the minimize button.

'scrollbar'

Include a scrollbar for the window.

'title'

Display the window title on the header.

'scroll auto hide'

Automatically hide the scrollbar after a period of inactivity.

'background'

Keep the window behind all other windows.


Layout

ui:layoutRow('dynamic', height, cols)

ui:layoutRow('dynamic', height, ratios)

ui:layoutRow('static', height, itemWidth, cols)

ui:layoutRow('static', height, sizes)

Adopt a row layout for the proceeding widgets.

If the layout is 'dynamic', the row height and columns must be specified. If cols is a number, it specifies the number of equally sized columns to divide the row into. If there is a ratios table instead, the table is treated as an array of ratios from 0 to 1. Each ratio describes the width of the column with respect to the total row width.

If the layout is 'static', there must either be itemWidth and cols parameters describing the number of fixed-width columns to divide the row into, or there must be a sizes table, which is an array of fixed widths for the columns.

Examples:

-- Create a row which is 30 pixels high and is divided into 3 equally sized columns.
ui:layoutRow('dynamic', 30, 3)

-- Create a row which is 25 pixels high and divided into two columns with a size ratio of 1:3.
ui:layoutRow('dynamic', 25, {0.25, 0.75})

-- Create a row which is 120 pixels high and is divided into 3 columns, each of width 20.
ui:layoutRow('static', 120, 20, 3)

-- Create a row which is 40 pixels high and is divided into two columns, one 20 pixels wide and the other 30 pixels.
ui:layoutRow('static', 40, {20, 30})

ui:layoutRowBegin('dynamic'/'static', height, cols)

Adopt a row layout of the specified format type, height, and column count. Before each proceeding widget, call ui:layoutRowPush to set the column size. Don't forget to end the layout with ui:layoutRowEnd.

ui:layoutRowPush(ratio)

ui:layoutRowPush(size)

Specify the width of the next widget in a row layout started with ui:layoutRowBegin. If the layout is dynamic, the width is specified as a ratio of the total row width from 0 to 1. If the layout is static, the width is specified as a number of pixels.

ui:layoutRowEnd()

Call after ui:layoutRowBegin in order to properly end the row layout.

ui:layoutRow('dynamic'/'static', height, cols, body)

Equivalent to:

ui:layoutRowBegin(...)
body(ui)
ui:layoutRowEnd()

ui:layoutTemplateBegin(height)

Start a template layout with the given height. Make all of your ui:layoutTemplatePush and ui:layoutTemplateEnd calls before the widgets to be laid out. Template layouts repeat row-by-row until another layout is instituted.

ui:layoutTemplatePush('dynamic')

ui:layoutTemplatePush('variable'/'static', width)

Pushes a column onto a template layout. If the column is 'dynamic', it grows to fit space and shrinks to zero width when there is no room. If the column is 'variable', it grows to fit space and shrinks to a minimum of width pixels when there is no room. If the column is 'static', it stays at a constant width pixels. Remember to push all of your template columns and then call ui:layoutTemplatEnd before creating your widgets.

ui:layoutTemplateEnd()

End a template layout declaration. Remember to call this before creating your widgets.

ui:layoutTemplate(height, body)

Equivalent to:

ui:layoutTemplateBegin(height)
body(ui)
ui:layoutTemplateEnd()

Example:

ui:layoutTemplateBegin(100)
ui:layoutTemplatePush('static', 25)
ui:layoutTemplatePush('dynamic')
ui:layoutTemplatePush('variable', 25)
ui:layoutTemplateEnd()
ui:button(nil, '#ff0000') -- This button will always be 25 pixels wide.
ui:button(nil, '#00ff00') -- This button will grow to fit space and shrink to zero without space.
ui:button(nil, '#0000ff') -- This button will grow to fit space and shrink to a minimum of 25 pixels without space.

ui:layoutSpaceBegin('dynamic'/'static', height, widgetCount)

Start a space layout with the given height and widget count. Call ui:layoutSpacePush before each proceeding widget and ui:layoutSpaceEnd after the layout is finished.

ui:layoutSpacePush(x, y, width, height)

Specify the bounds of a widget in a space layout. If the layout is dynamic, the bounds are specified as ratios from 0 to 1 of the total width and height of the space layout. If the layout is static, the bounds are pixel valued offsets from the beginning of the layout.

ui:layoutSpaceEnd()

End a space layout.

ui:layoutSpace('dynamic'/'static', height, widgetCount, body)

Equivalent to:

ui:layoutSpaceBegin(...)
body(ui)
ui:layoutSpaceEnd()

x, y, width, height = ui:layoutSpaceBounds()

Return the bounds of the current space layout.

x, y = ui:layoutSpaceToScreen(x, y)

Convert a space layout local position to global screen position.

x, y = ui:layoutSpaceToLocal(x, y)

Convert a global screen position to space layout local position.

x, y, width, height = ui:layoutSpaceRectToScreen(x, y, width, height)

Convert space layout local bounds to global screen bounds.

x, y, width, height = ui:layoutSpaceRectToLocal(x, y, width, height)

Convert global screen bounds to space layout local bounds.

ratio = ui:layoutRatioFromPixel(pixelWidth)

Convert a pixel width to a ratio suitable for a dynamic layout.


Widgets

Groups

open = ui:groupBegin(title, flags...)

Start a group. Groups can have titles and scrollbars just like windows.

Return true if the group is open and false otherwise.

Call ui:groupEnd at the end of a group if it's open.

ui:groupEnd()

End a group. Remember to call this whenever the group is open.

ui:group(title, flags..., body)

Equivalent to:

ui:groupBegin(...)
body(ui)
ui:groupEnd()

sx, sy = ui:groupGetScroll(title)

Get the scroll position (sx, sy) of the group with the given title.

ui:groupSetScroll(title, sx, sy)

Set the scroll position (sx, sy) of the group with the given title.

Trees

open = ui:treePush('node'/'tab', title)

open = ui:treePush('node'/'tab', title, image)

open = ui:treePush('node'/'tab', title, image, 'collapsed'/'expanded')

Start a tree. The resulting item is either a 'node' or a 'tab', with the idea being that nodes are a level below tabs. Optionally specify an image (default is none) or a starting state (default is 'collapsed').

Return true if the item is expanded, and false if it is collapsed.

Remember to call ui:treePop if the item is open.

ui:treePop()

Ends a tree. Call this at the end of an open tree item.

ui:tree('node'/'tab', title, body)

ui:tree('node'/'tab', title, image, body)

ui:tree('node'/'tab', title, image, 'collapsed'/'expanded', body)

Equivalent to:

if ui:treePush(...) then
	body(ui)
	ui:treePop()
end

open = ui:treeStatePush('node'/'tab', title)

open = ui:treeStatePush('node'/'tab', title, image)

open = ui:treeStatePush('node'/'tab', title, image, 'collapsed'/'expanded')

Same as ui:treePush, but the 'collapsed'/'expanded' argument sets the current state of the tree instead of just specifying the initial state.

Be sure to call ui:treeStatePop if the tree is open.

ui:treeStatePop()

Ends an open tree started with ui:treeStatePush. Call this at the end of every open treeState.

ui:treeState('node'/'tab', title, body)

ui:treeState('node'/'tab', title, image, body)

ui:treeState('node'/'tab', title, image, 'collapsed'/'expanded', body)

Equivalent to:

if ui:treeStatePush(...) then
	body(ui)
	ui:treeStatePop()
end

Popups

open = ui:popupBegin('dynamic'/'static', title, x, y, width, height, flags...)

Start a popup with the given size and flags. Bounds can be given as either dynamic ratios or static pixel counts.

Return true if the popup is open, and false otherwise.

Call ui:popupEnd to end the popup if it is open.

ui:popupClose()

Close the current popup.

ui:popupEnd()

End a popup. Be sure to call this when ending an open popup.

ui:popup('dynamic'/'static', title, x, y, width, height, flags..., body)

Equivalent to:

if ui:popupBegin(...) then
	body(ui)
	ui:popupEnd()
end

sx, sy = ui:popupGetScroll()

Get the scroll position (sx, sy) of the current popup.

ui:popupSetScroll(sx, sy)

Set the scroll position (sx, sy) of the current popup.

Context Menus

open = ui:contextualBegin(width, height, triggerX, triggerY, triggerWidth, triggerHeight, flags...)

Set up a context menu of the given size and trigger bounds. Also takes window flags.

Return true if the context menu is open, and false otherwise.

activated = ui:contextualItem(text)

activated = ui:contextualItem(text, symbol/image)

activated = ui:contextualItem(text, symbol/image, align)

Add an item to a context menu. Optionally specify a symbol type, image, and/or alignment.

Return true if the item is activated, and false otherwise.

Call ui:contextualEnd at the end of an open context menu.

ui:contextualClose()

Close the current context menu.

ui:contextualEnd()

End the current context menu. Be sure to call this at the end of an open context menu.

ui:contextual(width, height, triggerX, triggerY, triggerWidth, triggerHeight, flags..., body)

Equivalent to:

if ui:contextualBegin(...) then
	body(ui)
	ui:contextualEnd()
end

Tooltips

ui:tooltip(text)

Show a tooltip with the given text.

open = ui:tooltipBegin(width)

Start a tooltip with the given width.

Return true if the tooltip is open, and false otherwise.

Be sure to call ui:tooltipEnd at the end of an open tooltip.

ui:tooltipEnd()

End a tooltip previously started with ui:tooltipBegin. Call this at the end of every open tooltip.

ui:tooltip(width, body)

Equivalent to:

if ui:tooltipBegin(width) then
	body(ui)
	ui:tooltipEnd()
end

Menus

ui:menubarBegin()

Start a menu bar. Menu bars stay at the top of a window even when scrolling. Call ui:menubarEnd to end one.

ui:menubarEnd()

Ends a menu bar. Always call this at the end of a menu bar started with ui:menubarBegin.

ui:menubar(body)

Equivalent to:

ui:menubarBegin()
body(ui)
ui:menubarEnd()

open = ui:menuBegin(title, symbol/image, width, height)

open = ui:menuBegin(title, symbol/image, width, height, align)

Start a menu of the given title and size. Optionally specify a symbol, image, and/or alignment.

Return true if the menu is open, and false otherwise.

Be sure to call ui:menuEnd when ending open menus.

activated = ui:menuItem(title)

activated = ui:menuItem(title, symbol/image)

activated = ui:menuItem(title, symbol/image, align)

Add a menu item to the current menu. Optionally specify a symbol, image, and/or alignment.

Return true if the menu item is activated, and false otherwise.

ui:menuClose()

Close the current menu.

ui:menuEnd()

End the current menu. Always call this at the end of any open menu.

ui:menu(title, symbol/image, width, height, body)

ui:menu(title, symbol/image, width, height, align, body)

Equivalent to:

if ui:menuBegin(...) then
	body(ui)
	ui:menuEnd()
end

General

ui:label(text)

ui:label(text, align/'wrap')

ui:label(text, align/'wrap', color)

Show a text string. Optionally specify an alignment and/or color.

ui:image(image)

Show an image.

See LÖVE Image.

activated = ui:button(title)

activated = ui:button(title, symbol/image)

activated = ui:button(nil, color)

Add a button with a title and/or a color, symbol, or image.

Return true if activated, and false otherwise.

ui:buttonSetBehavior('default'/'repeater')

Sets whether a button is activated once per click ('default') or every frame held down ('repeater').

ui:buttonPushBehavior('default'/'repeater')

Push button behavior.

ui:buttonPopBehavior()

Pop button behavior.

active = ui:checkbox(text, active)

changed = ui:checkbox(text, valueTable)

Add a checkbox with the given title. Either specify a boolean state active, in which case the function returns the new state, or specify a table with a boolean field called value, in which case the value is updated and the function returns true on toggled, and false otherwise.

selection = ui:radio(text, selection)

selection = ui:radio(name, text, selection)

changed = ui:radio(text, valueTable)

changed = ui:radio(name, text, valueTable)

Add a radio button with the given name and/or title. The title is displayed to the user while the name is used to report which button is selected. By default, the name is the same as the title.

If called with a string selection, the function returns the new selection, which should be the name of a radio button. If called with a table that has a string field value, the value gets updated and the function returns true on selection change and false otherwise.

selected = ui:selectable(text, selected)

selected = ui:selectable(text, image, selected)

selected = ui:selectable(text, image, align, selected)

changed = ui:selectable(text, valueTable)

changed = ui:selectable(text, image, valueTable)

changed = ui:selectable(text, image, align, valueTable)

Add a selectable item with the given text and/or image and alignment.

If given a boolean selected, return the new state of selected. If given a table with a boolean field named value instead, the field gets updated and the function returns true on a change and false otherwise.

current = ui:slider(min, current, max, step)

changed = ui:slider(min, valueTable, max, step)

Add a slider widget with the given range and step size.

If given a number current, return the new current value. If given a table with a number field named value instead, the field gets updated and the function returns true on a change and false otherwise.

current = ui:progress(current, max)

current = ui:progress(current, max, modifiable)

changed ui:progress(valueTable, max)

changed = ui:progress(valueTable, max, modifiable)

Add a progress widget, optionally making it modifiable.

If given a number current, return the new current value. If given a table with a number field named value instead, the field gets updated and the function returns true on a change and false otherwise.

color = ui:colorPicker(color)

color = ui:colorPicker(color, 'RGB'/'RGBA')

changed = ui:colorPicker(valueTable)

changed = ui:colorPicker(valueTable, 'RGB'/'RGBA')

Add a color picker widget, optionally specifying format (default 'RGB', no alpha).

If given a color string, return the new color. If given a table with a color string field named value instead, the field gets updated and the function returns true on change and false otherwise.

current = ui:property(name, min, current, max, step, incPerPixel)

changed = ui:property(name, min, valueTable, max, step, incPerPixel)

Add a property widget, which is a named number variable. Specify the range, step, and sensitivity.

If given a number current, return the new current. If given a table with a number field named value instead, the field gets updated and the function returns true on change and false otherwise.

state, changed = ui:edit('simple'/'field'/'box', valueTable)

Add an editable text field widget. The first argument defines the type of editor to use: single line 'simple' and 'field', or multi-line 'box'. The valueTable should be a table with a string field named value. The field gets updated and the function returns the edit state (one of 'commited'/'activated'/'deactivated'/'active'/'inactive') followed by true if the text changed or false if the text remained the same.

ui:editFocus()

Manually focus the following ui:edit widget.

ui:editUnfocus()

Manually unfocus the following ui:edit widget.

index = ui:combobox(index, items)

index = ui:combobox(index, items, itemHeight)

index = ui:combobox(index, items, itemHeight, width)

index = ui:combobox(index, items, itemHeight, width, height)

changed = ui:combobox(valueTable, items)

changed = ui:combobox(valueTable, items, itemHeight)

changed = ui:combobox(valueTable, items, itemHeight, width)

changed = ui:combobox(valueTable, items, itemHeight, width, height)

Add a drop-down combobox widget. items should be an array of strings. itemHeight defaults to the widget height, width defaults to widget width, and height defaults to a sensible value based on itemHeight.

If a number index is specified, then the function returns the new selected index. If a table with a number field value is given instead, then the field gets updated with the currently selected index and the function returns true on change and false otherwise.

open = ui:comboboxBegin(text)

open = ui:comboboxBegin(text, color/symbol/image)

open = ui:comboboxBegin(text, color/symbol/image, width)

open = ui:comboboxBegin(text, color/symbol/image, width, height)

Start a combobox widget. This form gives complete control over the drop-down list (it's treated like a new window). Color/symbol/image defaults to none, while width and height default to sensible values based on widget bounds.

Remember to call ui:comboboxEnd if the combobox is open.

activated = ui:comboboxItem(text)

activated = ui:comboboxItem(text, symbol/image)

activated = ui:comboboxItem(text, symbol/image, align)

Add a combobox item, optionally specifying a symbol, image, and/or alignment.

Return true if the item is activated, and false otherwise.

ui:comboboxClose()

Close the current combobox.

ui:comboboxEnd()

End the current combobox. Always call this at the end of open comboboxes.

ui:combobox(text, body)

ui:combobox(text, color/symbol/image, body)

ui:combobox(text, color/symbol/image, width, body)

ui:combobox(text, color/symbol/image, width, height, body)

Equivalent to:

if ui:comboboxBegin(...) then
	body(ui)
	ui:comboboxEnd()
end

Utilities

x, y, width, height = ui:widgetBounds()

Return the bounds of the current widget.

x, y = ui:widgetPosition()

Return the position of the current widget.

width, height = ui:widgetSize()

Return the size of the current widget.

width = ui:widgetWidth()

Return the width of the current widget.

height = ui:widgetHeight()

Return the height of the current widget.

hovered = ui:widgetIsHovered()

Return true if the widget is hovered by the mouse, and false otherwise.

pressed = ui:widgetHasMousePressed()

pressed = ui:widgetHasMousePressed(button)

Return true if the given mouse button was pressed on the current widget and has not yet been released, and false otherwise. button is one of 'left'/'right'/'middle' (defaults to 'left').

released = ui:widgetHasMouseReleased()

released = ui:widgetHasMouseReleased(button)

Return true if the given mouse button was released on the current widget and has not since been pressed, and false otherwise. button is one of 'left'/'right'/'middle' (defaults to 'left').

pressed = ui:widgetIsMousePressed()

pressed = ui:widgetIsMousePressed(button)

Return true if the given mouse button was pressed on the current widget this frame, and false otherwise. button is one of 'left'/'right'/'middle' (defaults to 'left').

released = ui:widgetIsMouseReleased()

released = ui:widgetIsMouseReleased(button)

Return true if the given mouse button was released on the current widget this frame, and false otherwise. button is one of 'left'/'right'/'middle' (defaults to 'left').

ui:spacing(cols)

Empty space taking up the given number of columns.

Symbols

Various widgets accept symbol type strings as parameters. Here is a complete list of symbol types:

  • 'none'
  • 'x'
  • 'underscore'
  • 'circle solid'
  • 'circle outline'
  • 'rect solid'
  • 'rect outline'
  • 'triangle up'
  • 'triangle down'
  • 'triangle left'
  • 'triangle right'
  • 'plus'
  • 'minus'

Alignment

Some widgets accept alignment arguments for text, symbols, and/or images. Here is a complete list of alignment types:

  • 'left'
  • 'centered'
  • 'right'
  • 'top left'
  • 'top centered'
  • 'top right'
  • 'bottom left'
  • 'bottom centered'
  • 'bottom right'

Drawing

Use the following functions to draw custom widgets. They use the current LÖVE line thickness and color.

ui:line(x1, y1, x2, y2, ...)

Draw a multi-segment line at the given screen coordinates.

ui:curve(x1, y1, crtl1x, ctrl1y, ctrl2x, ctrl2y, x2, y2)

Draw a Bézier curve with the given start, control, and end points.

ui:polygon('fill'/'line', x1, y1, x2, y2, x3, y3, ...)

Draw a polygon with the given draw mode and screen coordinates.

ui:circle('fill'/'line', x, y, r)

Draw a circle with the given draw mode, center screen coordinates, and radius.

ui:ellipse('fill'/'line', x, y, rx, ry)

Draw an ellipse with the given draw mode, center screen coordinates, and radii.

ui:arc('fill'/'line', x, y, r, startAngle, endAngle)

Draw an arc with the given draw mode, screen coordinates, radius, and angles.

ui:rectMultiColor(x, y, width, height, topLeftColor, topRightColor, bottomLeftColor, bottomRightColor)

Draw a gradient rectangle with the given screen coordinates, size, and corner colors.

ui:scissor(x, y, width, height)

Set the scissor area to the given screen coordinates and size.

ui:image(img, x, y, width, height)

Draw the given image at the given screen bounds.

See LÖVE Image.

ui:text(str, x, y, width, height)

Draw the given string at the given screen bounds.


Images

Any function that accepts a LÖVE Image as an argument also accepts a LÖVE Canvas. You can also specify a LÖVE Quad to use by passing a two-item array {Image, Quad} or {Canvas, Quad}, where Quad specifies which part of the image to draw.

See skin.lua for an example of both methods.


Input

hovered = ui:inputWasHovered(x, y, width, height)

Return true if the given screen bounds were hovered by the mouse in the previous frame, and false otherwise.

hovered = ui:inputIsHovered(x, y, width, height)

Return true if the given screen bounds are hovered by the mouse, and false otherwise.

pressed = ui:inputHasMousePressed(button, x, y, width, height)

Return true if the given mouse button was pressed in the given screen bounds and has not yet been released, and false otherwise. button is one of 'left'/'right'/'middle' (defaults to 'left').

released = ui:inputHasMouseReleased(button, x, y, width, height)

Return true if the given mouse button was released in the given screen bounds and has not since been pressed, and false otherwise. button is one of 'left'/'right'/'middle' (defaults to 'left').

pressed = ui:inputIsMousePressed(button, x, y, width, height)

Return true if the given mouse button was pressed in the given screen bounds this frame, and false otherwise. button is one of 'left'/'right'/'middle' (defaults to 'left').

released = ui:inputIsMouseReleased(button, x, y, width, height)

Return true if the given mouse button was released in the given screen bounds this frame, and false otherwise. button is one of 'left'/'right'/'middle' (defaults to 'left').


Styling

Colors

Some styles and widgets accept a "color string" parameter. This is a string of the format '#RRGGBB' or '#RRGGBBAA', where RR, GG, BB, and AA are each a byte in hexadecimal. Either use these strings directly or convert to and from the string format via the following functions.

color = nuklear.colorRGBA(r, g, b)

color = nuklear.colorRGBA(r, g, b, a)

Construct a color string from the given components (each from 0 to 255). Alpha (a) defaults to 255.

color = nuklear.colorHSVA(h, s, v)

color = nuklear.colorHSVA(h, s, v, a)

Construct a color string from the given components (each from 0 to 255). Alpha (a) defaults to 255.

r, g, b, a = nuklear.colorParseRGBA(color)

Split a color string into its number components (each from 0 to 255).

h, s, v, a = nuklear.colorParseHSVA(color)

Split a color string into its number components (each from 0 to 255).

ui:styleDefault()

Reset color styles to their default values.

ui:styleLoadColors(colorTable)

Load a color table for quick color styling.

Below is the default color table. Custom color tables must provide all of the same fields.

local colorTable = {
	['text'] = '#afafaf',
	['window'] = '#2d2d2d',
	['header'] = '#282828',
	['border'] = '#414141',
	['button'] = '#323232',
	['button hover'] = '#282828',
	['button active'] = '#232323',
	['toggle'] = '#646464',
	['toggle hover'] = '#787878',
	['toggle cursor'] = '#2d2d2d',
	['select'] = '#2d2d2d',
	['select active'] = '#232323',
	['slider'] = '#262626',
	['slider cursor'] = '#646464',
	['slider cursor hover'] = '#787878',
	['slider cursor active'] = '#969696',
	['property'] = '#262626',
	['edit'] = '#262626',
	['edit cursor'] = '#afafaf',
	['combo'] = '#2d2d2d',
	['chart'] = '#787878',
	['chart color'] = '#2d2d2d',
	['chart color highlight'] = '#ff0000',
	['scrollbar'] = '#282828',
	['scrollbar cursor'] = '#646464',
	['scrollbar cursor hover'] = '#787878',
	['scrollbar cursor active'] = '#969696',
	['tab header'] = '#282828'
}

Styles

For finer-grained control over styles, including custom image-based skinning, Nuklear provides a wide arrangement of style items.

ui:styleSetFont(font)

Set the current font.

See LÖVE Font.

ui:stylePush(style)

Push any number of style items onto the style stack.

Example (see skin.lua):

ui:stylePush {
	['text'] = {
		['color'] = '#000000'
	},
	['button'] = {
		['normal'] = love.graphics.newImage 'skin/button.png',
		['hover'] = love.graphics.newImage 'skin/button_hover.png',
		['active'] = love.graphics.newImage 'skin/button_active.png',
		['text background'] = '#00000000',
		['text normal'] = '#000000',
		['text hover'] = '#000000',
		['text active'] = '#ffffff'
	}
}

ui:stylePop()

Pop the most recently pushed style.

ui:style(style, body)

Equivalent to:

ui:stylePush(style)
body(ui)
ui:stylePop()

Style Items

local style = {
	['font'] = Font,
	['text'] = {
		['color'] = color,
		['padding'] = {x = number, y = number}
	},
	['button'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['text background'] = color,
		['text normal'] = color,
		['text hover'] = color,
		['text active'] = color,
		['text alignment'] = align,
		['border'] = number,
		['rounding'] = number,
		['padding'] = {x = number, y = number},
		['image padding'] = {x = number, y = number},
		['touch padding'] = {x = number, y = number}
	},
	['contextual button'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['text background'] = color,
		['text normal'] = color,
		['text hover'] = color,
		['text active'] = color,
		['text alignment'] = align,
		['border'] = number,
		['rounding'] = number,
		['padding'] = {x = number, y = number},
		['image padding'] = {x = number, y = number},
		['touch padding'] = {x = number, y = number}
	},
	['menu button'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['text background'] = color,
		['text normal'] = color,
		['text hover'] = color,
		['text active'] = color,
		['text alignment'] = align,
		['border'] = number,
		['rounding'] = number,
		['padding'] = {x = number, y = number},
		['image padding'] = {x = number, y = number},
		['touch padding'] = {x = number, y = number}
	},
	['option'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['cursor normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['text normal'] = color,
		['text hover'] = color,
		['text active'] = color,
		['text background'] = color,
		['text alignment'] = align,
		['padding'] = {x = number, y = number},
		['touch padding'] = {x = number, y = number},
		['spacing'] = number,
		['border'] = number
	},
	['checkbox'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['cursor normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['text normal'] = color,
		['text hover'] = color,
		['text active'] = color,
		['text background'] = color,
		['text alignment'] = align,
		['padding'] = {x = number, y = number},
		['touch padding'] = {x = number, y = number},
		['spacing'] = number,
		['border'] = number
	},
	['selectable'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['pressed'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['normal active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['pressed active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['text normal'] = color,
		['text hover'] = color,
		['text pressed'] = color,
		['text normal active'] = color,
		['text hover active'] = color,
		['text pressed active'] = color,
		['text background'] = color,
		['text alignment'] = align,
		['rounding'] = number,
		['padding'] = {x = number, y = number},
		['touch padding'] = {x = number, y = number},
		['image padding'] = {x = number, y = number}
	},
	['slider'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['bar normal'] = color,
		['bar active'] = color,
		['bar filled'] = color,
		['cursor normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border'] = number,
		['rounding'] = number,
		['bar height'] = number,
		['padding'] = {x = number, y = number},
		['spacing'] = {x = number, y = number},
		['cursor size'] = {x = number, y = number}
	},
	['progress'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['cursor normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor border color'] = color,
		['rounding'] = number,
		['border'] = number,
		['cursor border'] = number,
		['cursor rounding'] = number,
		['padding'] = {x = number, y = number}
	},
	['property'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['label normal'] = color,
		['label hover'] = color,
		['label active'] = color,
		['border'] = number,
		['rounding'] = number,
		['padding'] = {x = number, y = number},
		['edit'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['border color'] = color,
			['scrollbar'] = {
				['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['border color'] = color,
				['cursor normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['cursor hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['cursor active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['cursor border color'] = color,
				['border'] = number,
				['rounding'] = number,
				['border cursor'] = number,
				['rounding cursor'] = number,
				['padding'] = {x = number, y = number}
			},
			['cursor normal'] = color,
			['cursor hover'] = color,
			['cursor text normal'] = color,
			['cursor text hover'] = color,
			['text normal'] = color,
			['text hover'] = color,
			['text active'] = color,
			['selected normal'] = color,
			['selected hover'] = color,
			['selected text normal'] = color,
			['selected text hover'] = color,
			['border'] = number,
			['rounding'] = number,
			['cursor size'] = number,
			['scrollbar size'] = {x = number, y = number},
			['padding'] = {x = number, y = number},
			['row padding'] = number
		},
		['inc button'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['border color'] = color,
			['text background'] = color,
			['text normal'] = color,
			['text hover'] = color,
			['text active'] = color,
			['text alignment'] = align,
			['border'] = number,
			['rounding'] = number,
			['padding'] = {x = number, y = number},
			['image padding'] = {x = number, y = number},
			['touch padding'] = {x = number, y = number}
		},
		['dec button'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['border color'] = color,
			['text background'] = color,
			['text normal'] = color,
			['text hover'] = color,
			['text active'] = color,
			['text alignment'] = align,
			['border'] = number,
			['rounding'] = number,
			['padding'] = {x = number, y = number},
			['image padding'] = {x = number, y = number},
			['touch padding'] = {x = number, y = number}
		}
	},
	['edit'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['scrollbar'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['border color'] = color,
			['cursor normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['cursor hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['cursor active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['cursor border color'] = color,
			['border'] = number,
			['rounding'] = number,
			['border cursor'] = number,
			['rounding cursor'] = number,
			['padding'] = {x = number, y = number}
		},
		['cursor normal'] = color,
		['cursor hover'] = color,
		['cursor text normal'] = color,
		['cursor text hover'] = color,
		['text normal'] = color,
		['text hover'] = color,
		['text active'] = color,
		['selected normal'] = color,
		['selected hover'] = color,
		['selected text normal'] = color,
		['selected text hover'] = color,
		['border'] = number,
		['rounding'] = number,
		['cursor size'] = number,
		['scrollbar size'] = {x = number, y = number},
		['padding'] = {x = number, y = number},
		['row padding'] = number
	},
	['chart'] = {
		['background'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['selected color'] = color,
		['color'] = color,
		['border'] = number,
		['rounding'] = number,
		['padding'] = {x = number, y = number}
	},
	['scrollh'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['cursor normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor border color'] = color,
		['border'] = number,
		['rounding'] = number,
		['border cursor'] = number,
		['rounding cursor'] = number,
		['padding'] = {x = number, y = number}
	},
	['scrollv'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['cursor normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['cursor border color'] = color,
		['border'] = number,
		['rounding'] = number,
		['border cursor'] = number,
		['rounding cursor'] = number,
		['padding'] = {x = number, y = number}
	},
	['tab'] = {
		['background'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['text'] = color,
		['tab maximize button'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['border color'] = color,
			['text background'] = color,
			['text normal'] = color,
			['text hover'] = color,
			['text active'] = color,
			['text alignment'] = align,
			['border'] = number,
			['rounding'] = number,
			['padding'] = {x = number, y = number},
			['image padding'] = {x = number, y = number},
			['touch padding'] = {x = number, y = number}
		},
		['tab minimize button'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['border color'] = color,
			['text background'] = color,
			['text normal'] = color,
			['text hover'] = color,
			['text active'] = color,
			['text alignment'] = align,
			['border'] = number,
			['rounding'] = number,
			['padding'] = {x = number, y = number},
			['image padding'] = {x = number, y = number},
			['touch padding'] = {x = number, y = number}
		},
		['node maximize button'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['border color'] = color,
			['text background'] = color,
			['text normal'] = color,
			['text hover'] = color,
			['text active'] = color,
			['text alignment'] = align,
			['border'] = number,
			['rounding'] = number,
			['padding'] = {x = number, y = number},
			['image padding'] = {x = number, y = number},
			['touch padding'] = {x = number, y = number}
		},
		['node minimize button'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['border color'] = color,
			['text background'] = color,
			['text normal'] = color,
			['text hover'] = color,
			['text active'] = color,
			['text alignment'] = align,
			['border'] = number,
			['rounding'] = number,
			['padding'] = {x = number, y = number},
			['image padding'] = {x = number, y = number},
			['touch padding'] = {x = number, y = number}
		},
		['border'] = number,
		['rounding'] = number,
		['indent'] = number,
		['padding'] = {x = number, y = number},
		['spacing'] = {x = number, y = number}
	},
	['combo'] = {
		['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border color'] = color,
		['label normal'] = color,
		['label hover'] = color,
		['label active'] = color,
		['symbol normal'] = color,
		['symbol hover'] = color,
		['symbol active'] = color,
		['button'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['border color'] = color,
			['text background'] = color,
			['text normal'] = color,
			['text hover'] = color,
			['text active'] = color,
			['text alignment'] = align,
			['border'] = number,
			['rounding'] = number,
			['padding'] = {x = number, y = number},
			['image padding'] = {x = number, y = number},
			['touch padding'] = {x = number, y = number}
		},
		['border'] = number,
		['rounding'] = number,
		['content padding'] = {x = number, y = number},
		['button padding'] = {x = number, y = number}
		['spacing'] = {x = number, y = number}
	},
	['window'] = {
		['header'] = {
			['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
			['close button'] = {
				['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['border color'] = color,
				['text background'] = color,
				['text normal'] = color,
				['text hover'] = color,
				['text active'] = color,
				['text alignment'] = align,
				['border'] = number,
				['rounding'] = number,
				['padding'] = {x = number, y = number},
				['image padding'] = {x = number, y = number},
				['touch padding'] = {x = number, y = number}
			},
			['minimize button'] = {
				['normal'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['hover'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['active'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
				['border color'] = color,
				['text background'] = color,
				['text normal'] = color,
				['text hover'] = color,
				['text active'] = color,
				['text alignment'] = align,
				['border'] = number,
				['rounding'] = number,
				['padding'] = {x = number, y = number},
				['image padding'] = {x = number, y = number},
				['touch padding'] = {x = number, y = number}
			},
			['label normal'] = color,
			['label hover'] = color,
			['label active'] = color,
			['padding'] = {x = number, y = number},
			['label padding'] = {x = number, y = number},
			['spacing'] = {x = number, y = number},
			
		},
		['fixed background'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['background'] = color,
		['border color'] = color,
		['popup border color'] = color,
		['combo border color'] = color,
		['contextual border color'] = color,
		['menu border color'] = color,
		['group border color'] = color,
		['tooltip border color'] = color,
		['scaler'] = color or Image or Canvas or {Image, Quad} or {Canvas, Quad},
		['border'] = number,
		['combo border'] = number,
		['contextual border'] = number,
		['menu border'] = number,
		['group border'] = number,
		['tooltip border'] = number,
		['popup border'] = number,
		['rounding'] = number,
		['spacing'] = {x = number, y = number},
		['scrollbar size'] = {x = number, y = number},
		['min size'] = {x = number, y = number},
		['padding'] = {x = number, y = number},
		['group padding'] = {x = number, y = number},
		['popup padding'] = {x = number, y = number},
		['combo padding'] = {x = number, y = number},
		['contextual padding'] = {x = number, y = number},
		['menu padding'] = {x = number, y = number},
		['tooltip padding'] = {x = number, y = number}
	}
}
Clone this wiki locally