mirror of
https://github.com/keharriso/love-nuklear.git
synced 2025-09-11 00:27:48 -04:00
Updated Documentation (markdown)
Kevin Harrison
parent
fd1d2538ba
commit
c654f659ec
1 changed files with 390 additions and 42 deletions
430
Documentation.md
430
Documentation.md
|
|
@ -64,40 +64,8 @@ End the current frame. Call this once every [love.update](https://love2d.org/wik
|
|||
|
||||
## Window
|
||||
|
||||
### Flags
|
||||
Windows and some window-like widgets can accept a number of window flags. 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.
|
||||
|
||||
### Functions
|
||||
|
||||
#### open = nk.window_begin(name, title, x, y, width, height, flags...)
|
||||
#### open = nk.window_begin(title, x, y, width, height, flags...)
|
||||
#### open = nk.window_begin(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.
|
||||
|
|
@ -129,14 +97,14 @@ Return 'true' if the given window is hidden, and `false` otherwise.
|
|||
#### active = nk.window_is_active(name)
|
||||
Return `true` if the given window is active, and `false` otherwise.
|
||||
|
||||
#### nk.window_is_hovered()
|
||||
#### hovered = nk.window_is_hovered()
|
||||
Return `true` if the current window is hovered by the mouse, and `false` otherwise.
|
||||
|
||||
#### nk.window_is_any_hovered()
|
||||
#### hovered = nk.window_is_any_hovered()
|
||||
Return `true` if any window is hovered by the mouse, and `false` otherwise.
|
||||
|
||||
#### nk.item_is_any_active()
|
||||
Return `true` if any window is active, and `false` otherwise.
|
||||
#### active = nk.item_is_any_active()
|
||||
Return `true` if any item is active, and `false` otherwise.
|
||||
|
||||
#### nk.window_set_bounds(x, y, width, height)
|
||||
Set the bounds of the current window.
|
||||
|
|
@ -165,6 +133,36 @@ Show the given window.
|
|||
#### nk.window_hide(name)
|
||||
Hide the given window.
|
||||
|
||||
### Flags
|
||||
Windows and some window-like widgets can accept a number of window flags. 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
|
||||
|
|
@ -194,8 +192,7 @@ nk.layout_row('static', 120, 20, 3)
|
|||
nk.layout_row('static', 40, {20, 30})
|
||||
```
|
||||
|
||||
#### nk.layout_row_begin('dynamic', height, cols)
|
||||
#### nk.layout_row_begin('static', height, cols)
|
||||
#### nk.layout_row_begin('dynamic'/'static', height, cols)
|
||||
Adopt a row layout of the specified format type, height, and column count. Before each proceeding widget, call `nk.layout_row_push` to set the column size. Don't forget to end the layout with `nk.layout_row_end`.
|
||||
|
||||
#### nk.layout_row_push(ratio)
|
||||
|
|
@ -205,8 +202,7 @@ Specify the width of the next widget in a row layout started with `nk.layout_row
|
|||
#### nk.layout_row_end()
|
||||
Call after `nk.layout_row_begin` in order to properly end the row layout.
|
||||
|
||||
#### nk.layout_space_begin('dynamic', height, widget_count)
|
||||
#### nk.layout_space_begin('static', height, widget_count)
|
||||
#### nk.layout_space_begin('dynamic'/'static', height, widget_count)
|
||||
Start a space layout with the given height and widget count. Call `nk.layout_space_push` before each proceeding widget and `nk.layout_space_end` after the layout is finished.
|
||||
|
||||
#### nk.layout_space_push(x, y, width, height)
|
||||
|
|
@ -232,3 +228,355 @@ Convert global screen bounds to space layout local bounds.
|
|||
|
||||
#### ratio = nk.layout_ratio_from_pixel(pixel_width)
|
||||
Convert a pixel width to a ratio suitable for a dynamic layout.
|
||||
|
||||
***
|
||||
|
||||
## Widgets
|
||||
|
||||
### Groups
|
||||
|
||||
#### open = nk.group_begin(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 `nk.group_end` at the end of a group if it's open.
|
||||
|
||||
#### nk.group_end()
|
||||
End a group. Remember to call this whenever the group is open.
|
||||
|
||||
### Trees
|
||||
|
||||
#### open = nk.tree_push('node'/'tab', title)
|
||||
#### open = nk.tree_push('node'/'tab', title, image)
|
||||
#### open = nk.tree_push('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 `nk.tree_pop` if the item is open.
|
||||
|
||||
#### nk.tree_pop()
|
||||
Ends a tree. Call this at the end of an open tree item.
|
||||
|
||||
### Popups
|
||||
|
||||
#### open = nk.popup_begin('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 `nk.popup_end` to end the popup if it is open.
|
||||
|
||||
#### nk.popup_close()
|
||||
Close the current popup.
|
||||
|
||||
#### nk.popup_end()
|
||||
End a popup. Be sure to call this when ending an open popup.
|
||||
|
||||
### Context Menus
|
||||
|
||||
#### open = nk.contextual_begin(width, height, trigger_x, trigger_y, trigger_width, trigger_height, 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 = nk.contextual_item(text)
|
||||
#### activated = nk.contextual_item(text, symbol/image)
|
||||
#### activated = nk.contextual_item(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 `nk.contextual_end` at the end of an open context menu.
|
||||
|
||||
#### nk.contextual_close()
|
||||
Close the current context menu.
|
||||
|
||||
#### nk.contextual_end()
|
||||
End the current context menu. Be sure to call this at the end of an open context menu.
|
||||
|
||||
### Tooltips
|
||||
|
||||
#### nk.tooltip(text)
|
||||
Show a tooltip with the given text.
|
||||
|
||||
#### open = nk.tooltip_begin(width)
|
||||
Start a tooltip with the given width.
|
||||
|
||||
Return `true` if the tooltip is open, and `false` otherwise.
|
||||
|
||||
Be sure to call `nk.tooltip_end` at the end of an open tooltip.
|
||||
|
||||
#### nk.tooltip_end()
|
||||
End a tooltip previously started with `nk.tooltip_begin`. Call this at the end of every open tooltip.
|
||||
|
||||
### Menus
|
||||
|
||||
#### nk.menubar_begin()
|
||||
Start a menu bar. Menu bars stay at the top of a window even when scrolling. Call `nk.menubar_end` to end one.
|
||||
|
||||
#### nk.menubar_end()
|
||||
Ends a menu bar. Always call this at the end of a menu bar started with `nk.menubar_begin`.
|
||||
|
||||
#### open = nk.menu_begin(title, symbol/image, width, height)
|
||||
#### open = nk.menu_begin(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 `nk.menu_end` when ending open menus.
|
||||
|
||||
#### activated = nk.menu_item(title)
|
||||
#### activated = nk.menu_item(title, symbol/image)
|
||||
#### activated = nk.menu_item(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.
|
||||
|
||||
#### nk.menu_close()
|
||||
Close the current menu.
|
||||
|
||||
#### nk.menu_end()
|
||||
End the current menu. Always call this at the end of any open menu.
|
||||
|
||||
### General
|
||||
|
||||
#### nk.label(text)
|
||||
#### nk.label(text, align/'wrap')
|
||||
#### nk.label(text, align/'wrap', color)
|
||||
Show a text string. Optionally specify an alignment and/or color.
|
||||
|
||||
#### nk.image(img)
|
||||
Show an image.
|
||||
|
||||
See [LÖVE Image](https://love2d.org/wiki/Image).
|
||||
|
||||
#### activated = nk.button(title)
|
||||
#### activated = nk.button(title, color/symbol/image)
|
||||
Add a button with a title and/or a color, symbol, or image.
|
||||
|
||||
Return `true` if activated, and `false` otherwise.
|
||||
|
||||
#### nk.button_set_behavior('default'/'repeater')
|
||||
Sets whether a button is activated once per click (`'default'`) or every frame held down (`'repeater'`).
|
||||
|
||||
#### nk.button_push_behavior('default'/'repeater')
|
||||
Push button behavior.
|
||||
|
||||
#### nk.button_pop_behavior()
|
||||
Pop button behavior.
|
||||
|
||||
#### active = nk.checkbox(text, active)
|
||||
#### changed = nk.checkbox(text, value_table)
|
||||
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 = nk.radio(text, selection)
|
||||
#### selection = nk.radio(name, text, selection)
|
||||
#### changed = nk.radio(text, value_table)
|
||||
#### changed = nk.radio(name, text, value_table)
|
||||
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 = nk.selectable(text, selected)
|
||||
#### selected = nk.selectable(text, image, selected)
|
||||
#### selected = nk.selectable(text, image, align, selected)
|
||||
#### changed = nk.selectable(text, value_table)
|
||||
#### changed = nk.selectable(text, image, value_table)
|
||||
#### changed = nk.selectable(text, image, align, value_table)
|
||||
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 = nk.slider(min, current, max, step)
|
||||
#### changed = nk.slider(min, value_table, 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 = nk.progress(current, max)
|
||||
#### current = nk.progress(current, max, modifiable)
|
||||
#### changed nk.progress(value_table, max)
|
||||
#### changed = nk.progress(value_table, 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 = nk.color_picker(color)
|
||||
#### color = nk.color_picker(color, 'RGB'/'RGBA')
|
||||
#### changed = nk.color_picker(value_table)
|
||||
#### changed = nk.color_picker(value_table, '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 = nk.property(name, min, current, max, step, inc_per_pixel)
|
||||
#### changed = nk.property(name, min, value_table, max, step, inc_per_pixel)
|
||||
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 = nk.edit('simple'/'field'/'box', value_table)
|
||||
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 `value_table` 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.
|
||||
|
||||
#### index = nk.combobox(index, items)
|
||||
#### index = nk.combobox(index, items, item_height)
|
||||
#### index = nk.combobox(index, items, item_height, width)
|
||||
#### index = nk.combobox(index, items, item_height, width, height)
|
||||
#### changed = nk.combobox(value_table, items)
|
||||
#### changed = nk.combobox(value_table, items, item_height)
|
||||
#### changed = nk.combobox(value_table, items, item_height, width)
|
||||
#### changed = nk.combobox(value_table, items, item_height, width, height)
|
||||
Add a drop-down combobox widget. `items` should be an array of strings. `item_height` defaults to the widget height, `width` defaults to widget width, and `height` defaults to a sensible value based on `item_height`.
|
||||
|
||||
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 = nk.combobox_begin(text)
|
||||
#### open = nk.combobox_begin(text, color/symbol/image)
|
||||
#### open = nk.combobox_begin(text, color/symbol/image, width)
|
||||
#### open = nk.combobox_begin(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 `nk.combobox_end` if the combobox is open.
|
||||
|
||||
#### activated = nk.combobox_item(text, symbol/image, align)
|
||||
#### activated = nk.combobox_item(text, symbol/image)
|
||||
#### activated = nk.combobox_item(text)
|
||||
Add a combobox item, optionally specifying a symbol, image, and/or alignment.
|
||||
|
||||
Return `true` if the item is activated, and `false` otherwise.
|
||||
|
||||
#### nk.combobox_close()
|
||||
Close the current combobox.
|
||||
|
||||
#### nk.combobox_end()
|
||||
End the current combobox. Always call this at the end of open comboboxes.
|
||||
|
||||
### Utilities
|
||||
|
||||
#### x, y, width, height = nk.widget_bounds()
|
||||
Return the bounds of the current widget.
|
||||
|
||||
#### x, y = nk.widget_position()
|
||||
Return the position of the current widget.
|
||||
|
||||
#### width, height = nk.widget_size()
|
||||
Return the size of the current widget.
|
||||
|
||||
#### width = nk.widget_width()
|
||||
Return the width of the current widget.
|
||||
|
||||
#### height = nk.widget_height()
|
||||
Return the height of the current widget.
|
||||
|
||||
#### hovered = nk.widget_is_hovered()
|
||||
Return `true` if the widget is hovered by the mouse, and `false` otherwise.
|
||||
|
||||
#### clicked = nk.widget_is_mouse_clicked()
|
||||
#### clicked = nk.widget_is_mouse_clicked(button)
|
||||
Return `true` if the widget was just clicked by the given mouse button ('left'/'right'/'middle', defaults to 'left'), and `false` otherwise.
|
||||
|
||||
#### has_click = nk.widget_has_mouse_click()
|
||||
#### has_click = nk.widget_has_mouse_click(button)
|
||||
#### has_click = nk.widget_has_mouse_click(button, down)
|
||||
Returns `true` if the given mouse button is in the given state on the current widget, and `false` otherwise. `button` defaults to 'left', and `down` defaults to `true`.
|
||||
|
||||
#### nk.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'
|
||||
|
||||
***
|
||||
|
||||
## 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 = nk.color_rgba(r, g, b)
|
||||
#### color = nk.color_rgba(r, g, b, a)
|
||||
Construct a color string from the given components (each from 0 to 255). Alpha (`a`) defaults to 255.
|
||||
|
||||
#### color = nk.color_hsva(h, s, v)
|
||||
#### color = nk.color_hsva(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 = nk.color_parse_rgba(color)
|
||||
Split a color string into its number components.
|
||||
|
||||
#### h, s, v, a = nk.color_parse_hsva(color)
|
||||
Split a color string into its number components.
|
||||
|
||||
#### nk.style_default()
|
||||
Reset color styles to their default values.
|
||||
|
||||
#### nk.style_load_colors(color_table)
|
||||
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 color_table = {
|
||||
['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 the following style items:
|
||||
```
|
||||
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue