Updated Documentation (markdown)

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()
+#### active = nk.item_is_any_active()
-Return `true` if any window is active, and `false` otherwise.
+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('dynamic'/'static', height, cols)
-#### nk.layout_row_begin('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('dynamic'/'static', height, widget_count)
-#### nk.layout_space_begin('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)
@@ -231,4 +227,356 @@ Convert space layout local bounds to global screen bounds.
 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.
+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:
+```
+
+```