diff --git a/Documentation.md b/Documentation.md index e5aa406..7ea6829 100644 --- a/Documentation.md +++ b/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) @@ -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. \ No newline at end of file +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: +``` + +``` \ No newline at end of file