From d7ff1dfa94448bdfbc8efc81c5e3e72deec62fca Mon Sep 17 00:00:00 2001 From: Kevin Harrison Date: Mon, 14 Nov 2016 19:11:14 -0500 Subject: [PATCH] Created Documentation (markdown) --- Documentation.md | 232 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 Documentation.md diff --git a/Documentation.md b/Documentation.md new file mode 100644 index 0000000..cb7db79 --- /dev/null +++ b/Documentation.md @@ -0,0 +1,232 @@ +## Context + +### nk.init() +Initialize the library. This must be called before any of the other functions. + +### nk.shutdown() +Close the library, freeing all associated resources. A subsequent call to `nk.init` is required before using any other functions. + +*** + +## Event + +### consumed = nk.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](https://love2d.org/wiki/love.keypressed). + +### consumed = nk.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](https://love2d.org/wiki/love.keyreleased). + +### consumed = nk.mousepressed(x, y, button, istouch) +Pass the given mouse press event to the UI, returning `true` if the event is consumed and `false` otherwise. + +See [love.mousepressed](https://love2d.org/wiki/love.mousepressed). + +### consumed = nk.mousereleased(x, y, button, istouch) +Pass the given mouse release event to the UI, returning `true` if the event is consumed and `false` otherwise. + +See [love.mousereleased](https://love2d.org/wiki/love.mousereleased). + +### consumed = nk.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](https://love2d.org/wiki/love.mousemoved). + +### consumed = nk.textinput(text) +Pass the given text input event to the UI, returning `true` if the event is consumed and `false` otherwise. + +See [love.textinput](https://love2d.org/wiki/love.textinput). + +### consumed = nk.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](https://love2d.org/wiki/love.wheelmoved). + +*** + +## Render + +### nk.draw() +Draw the UI. Call this once every [love.draw](https://love2d.org/wiki/love.draw). + +## Update + +### nk.frame_begin() +Begin a new frame for the UI. Call this once every [love.update](https://love2d.org/wiki/love.update), before other UI calls. + +### nk.frame_end() +End the current frame. Call this once every [love.update](https://love2d.org/wiki/love.update), after other UI calls. + +*** + +## 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. + +### open = nk.window_begin(name, title, x, y, width, height, flags...) +### open = nk.window_begin(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. + +### nk.window_end() +End a window. This must always be called after `nk.window_begin`, regardless of whether or not the window is open. + +### x, y, width, height = nk.window_get_bounds() +Return the bounds of the current window. + +### x, y = nk.window_get_position() +Return the position of the current window. + +### width, height = nk.window_get_size() +Return the size of the current window. + +### x, y, width, height = nk.window_get_content_region() +Return the bounds of the current window's content region. + +### focused = nk.window_has_focus() +Return `true` if the current window is focused, and `false` otherwise. + +### collapsed = nk.window_is_collapsed(name) +Return 'true' if the given window is collapsed, and `false` otherwise. + +### hidden = nk.window_is_hidden(name) +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() +Return `true` if the current window is hovered by the mouse, and `false` otherwise. + +### 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. + +### nk.window_set_bounds(x, y, width, height) +Set the bounds of the current window. + +### nk.window_set_position(x, y) +Set the position of the current window. + +### nk.window_set_size(width, height) +Set the size of the current window. + +### nk.window_set_focus(name) +Focus on the given window. + +### nk.window_close(name) +Close the given window. + +### nk.window_collapse(name) +Collapse the given window. + +### nk.window_expand(name) +Expand the given window. + +### nk.window_show(name) +Show the given window. + +### nk.window_hide(name) +Hide the given window. + +*** + +## Layout + +### nk.layout_row('dynamic', height, cols) +### nk.layout_row('dynamic', height, ratios) +### nk.layout_row('static', height, item_width, cols) +### nk.layout_row('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 `item_width` 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. +nk.layout_row('dynamic', 30, 3) + +-- Create a row which is 25 pixels high and divided into two columns with a size ratio of 1:3. +nk.layout_row('dynamic', 25, {0.25, 0.75}) + +-- Create a row which is 120 pixels high and is divided into 3 columns, each of width 20. +nk.layout_row('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. +nk.layout_row('static', 40, {20, 30}) +``` + +### nk.layout_row_begin('dynamic', 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) +### nk.layout_row_push(size) +Specify the width of the next widget in a row layout started with `nk.layout_row_begin`. 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. + +### 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) +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) +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. + +### nk.layout_space_end() +End a space layout. + +### x, y, width, height = nk.layout_space_bounds() +Return the bounds of the current space layout. + +### x, y nk.layout_space_to_screen(x, y) +Convert a space layout local position to global screen position. + +### x, y = nk.layout_space_to_local(x, y) +Convert a global screen position to space layout local position. + +### x, y, width, height = nk.layout_space_rect_to_screen(x, y, width, height) +Convert space layout local bounds to global screen bounds. + +### x, y, width, height = nk.layout_space_rect_to_local(x, y, width, height) +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