mirrors
/
Nuklear
mirror of https://github.com/Immediate-Mode-UI/Nuklear
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Nuklear/doc/index.html

2975 lines
173 KiB
Markdown
Raw Blame History

<meta charset='utf-8' emacsmode='-*- markdown -*-'>
<link rel='stylesheet' href='https://casual-effects.com/markdeep/latest/apidoc.css?'>
# Nuklear
![](https://cloud.githubusercontent.com/assets/8057201/11761525/ae06f0ca-a0c6-11e5-819d-5610b25f6ef4.gif)
## Contents
1. About section
2. Highlights section
3. Features section
4. Usage section
1. Flags section
2. Constants section
3. Dependencies section
5. Example section
6. API section
1. Context section
2. Input section
3. Drawing section
4. Window section
5. Layouting section
6. Groups section
7. Tree section
8. Properties section
7. License section
8. Changelog section
9. Gallery section
10. Credits section
## About
This is a minimal state immediate mode graphical user interface toolkit
written in ANSI C and licensed under public domain. It was designed as a simple
embeddable user interface for application and does not have any dependencies,
a default renderbackend or OS window and input handling but instead provides a very modular
library approach by using simple input state for input and draw
commands describing primitive shapes as output. So instead of providing a
layered library that tries to abstract over a number of platform and
render backends it only focuses on the actual UI.
## Highlights
- Graphical user interface toolkit
- Single header library
- Written in C89 (a.k.a. ANSI C or ISO C90)
- Small codebase (~18kLOC)
- Focus on portability, efficiency and simplicity
- No dependencies (not even the standard library if not wanted)
- Fully skinnable and customizable
- Low memory footprint with total memory control if needed or wanted
- UTF-8 support
- No global or hidden state
- Customizable library modules (you can compile and use only what you need)
- Optional font baker and vertex buffer output
- [Code available on github](https://github.com/Immediate-Mode-UI/Nuklear/)
## Features
- Absolutely no platform dependent code
- Memory management control ranging from/to
- Ease of use by allocating everything from standard library
- Control every byte of memory inside the library
- Font handling control ranging from/to
- Use your own font implementation for everything
- Use this libraries internal font baking and handling API
- Drawing output control ranging from/to
- Simple shapes for more high level APIs which already have drawing capabilities
- Hardware accessible anti-aliased vertex buffer output
- Customizable colors and properties ranging from/to
- Simple changes to color by filling a simple color table
- Complete control with ability to use skinning to decorate widgets
- Bendable UI library with widget ranging from/to
- Basic widgets like buttons, checkboxes, slider, ...
- Advanced widget like abstract comboboxes, contextual menus,...
- Compile time configuration to only compile what you need
- Subset which can be used if you do not want to link or use the standard library
- Can be easily modified to only update on user input instead of frame updates
## Usage
This library is self contained in one single header file and can be used either
in header only mode or in implementation mode. The header only mode is used
by default when included and allows including this header in other headers
and does not contain the actual implementation. <br /><br />
The implementation mode requires to define the preprocessor macro
NK_IMPLEMENTATION in *one* .c/.cpp file before #including this file, e.g.:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~C
#define NK_IMPLEMENTATION
#include "nuklear.h"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Also optionally define the symbols listed in the section "OPTIONAL DEFINES"
below in header and implementation mode if you want to use additional functionality
or need more control over the library.
!!! WARNING
Every time nuklear is included define the same compiler flags. This very important not doing so could lead to compiler errors or even worse stack corruptions.
### Flags
Flag | Description
--------------------------------|------------------------------------------
NK_PRIVATE | If defined declares all functions as static, so they can only be accessed inside the file that contains the implementation
NK_INCLUDE_FIXED_TYPES | If defined it will include header `<stdint.h>` for fixed sized types otherwise nuklear tries to select the correct type. If that fails it will throw a compiler error and you have to select the correct types yourself.
NK_INCLUDE_DEFAULT_ALLOCATOR | If defined it will include header `<stdlib.h>` and provide additional functions to use this library without caring for memory allocation control and therefore ease memory management.
NK_INCLUDE_STANDARD_IO | If defined it will include header `<stdio.h>` and provide additional functions depending on file loading.
NK_INCLUDE_STANDARD_VARARGS | If defined it will include header <stdarg.h> and provide additional functions depending on file loading.
NK_INCLUDE_STANDARD_BOOL | If defined it will include header `<stdbool.h>` for nk_bool otherwise nuklear defines nk_bool as int.
NK_INCLUDE_VERTEX_BUFFER_OUTPUT | Defining this adds a vertex draw command list backend to this library, which allows you to convert queue commands into vertex draw commands. This is mainly if you need a hardware accessible format for OpenGL, DirectX, Vulkan, Metal,...
NK_INCLUDE_FONT_BAKING | Defining this adds `stb_truetype` and `stb_rect_pack` implementation to this library and provides font baking and rendering. If you already have font handling or do not want to use this font handler you don't have to define it.
NK_INCLUDE_DEFAULT_FONT | Defining this adds the default font: ProggyClean.ttf into this library which can be loaded into a font atlas and allows using this library without having a truetype font
NK_INCLUDE_COMMAND_USERDATA | Defining this adds a userdata pointer into each command. Can be useful for example if you want to provide custom shaders depending on the used widget. Can be combined with the style structures.
NK_BUTTON_TRIGGER_ON_RELEASE | Different platforms require button clicks occurring either on buttons being pressed (up to down) or released (down to up). By default this library will react on buttons being pressed, but if you define this it will only trigger if a button is released.
NK_ZERO_COMMAND_MEMORY | Defining this will zero out memory for each drawing command added to a drawing queue (inside nk_command_buffer_push). Zeroing command memory is very useful for fast checking (using memcmp) if command buffers are equal and avoid drawing frames when nothing on screen has changed since previous frame.
NK_UINT_DRAW_INDEX | Defining this will set the size of vertex index elements when using NK_VERTEX_BUFFER_OUTPUT to 32bit instead of the default of 16bit
NK_KEYSTATE_BASED_INPUT | Define this if your backend uses key state for each frame rather than key press/release events
!!! WARNING
The following flags will pull in the standard C library:
- NK_INCLUDE_DEFAULT_ALLOCATOR
- NK_INCLUDE_STANDARD_IO
- NK_INCLUDE_STANDARD_VARARGS
!!! WARNING
The following flags if defined need to be defined for both header and implementation:
- NK_INCLUDE_FIXED_TYPES
- NK_INCLUDE_DEFAULT_ALLOCATOR
- NK_INCLUDE_STANDARD_VARARGS
- NK_INCLUDE_STANDARD_BOOL
- NK_INCLUDE_VERTEX_BUFFER_OUTPUT
- NK_INCLUDE_FONT_BAKING
- NK_INCLUDE_DEFAULT_FONT
- NK_INCLUDE_STANDARD_VARARGS
- NK_INCLUDE_COMMAND_USERDATA
- NK_UINT_DRAW_INDEX
### Constants
Define | Description
--------------------------------|---------------------------------------
NK_BUFFER_DEFAULT_INITIAL_SIZE | Initial buffer size allocated by all buffers while using the default allocator functions included by defining NK_INCLUDE_DEFAULT_ALLOCATOR. If you don't want to allocate the default 4k memory then redefine it.
NK_MAX_NUMBER_BUFFER | Maximum buffer size for the conversion buffer between float and string Under normal circumstances this should be more than sufficient.
NK_INPUT_MAX | Defines the max number of bytes which can be added as text input in one frame. Under normal circumstances this should be more than sufficient.
!!! WARNING
The following constants if defined need to be defined for both header and implementation:
- NK_MAX_NUMBER_BUFFER
- NK_BUFFER_DEFAULT_INITIAL_SIZE
- NK_INPUT_MAX
### Dependencies
Function | Description
------------|---------------------------------------------------------------
NK_ASSERT | If you don't define this, nuklear will use <assert.h> with assert().
NK_MEMSET | You can define this to 'memset' or your own memset implementation replacement. If not nuklear will use its own version.
NK_MEMCPY | You can define this to 'memcpy' or your own memcpy implementation replacement. If not nuklear will use its own version.
NK_INV_SQRT | You can define this to your own inverse sqrt implementation replacement. If not nuklear will use its own slow and not highly accurate version.
NK_SIN | You can define this to 'sinf' or your own sine implementation replacement. If not nuklear will use its own approximation implementation.
NK_COS | You can define this to 'cosf' or your own cosine implementation replacement. If not nuklear will use its own approximation implementation.
NK_STRTOD | You can define this to `strtod` or your own string to double conversion implementation replacement. If not defined nuklear will use its own imprecise and possibly unsafe version (does not handle nan or infinity!).
NK_DTOA | You can define this to `dtoa` or your own double to string conversion implementation replacement. If not defined nuklear will use its own imprecise and possibly unsafe version (does not handle nan or infinity!).
NK_VSNPRINTF| If you define `NK_INCLUDE_STANDARD_VARARGS` as well as `NK_INCLUDE_STANDARD_IO` and want to be safe define this to `vsnprintf` on compilers supporting later versions of C or C++. By default nuklear will check for your stdlib version in C as well as compiler version in C++. if `vsnprintf` is available it will define it to `vsnprintf` directly. If not defined and if you have older versions of C or C++ it will be defined to `vsprintf` which is unsafe.
!!! WARNING
The following dependencies will pull in the standard C library if not redefined:
- NK_ASSERT
!!! WARNING
The following dependencies if defined need to be defined for both header and implementation:
- NK_ASSERT
!!! WARNING
The following dependencies if defined need to be defined only for the implementation part:
- NK_MEMSET
- NK_MEMCPY
- NK_SQRT
- NK_SIN
- NK_COS
- NK_STRTOD
- NK_DTOA
- NK_VSNPRINTF
## Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
// init gui state
enum {EASY, HARD};
static int op = EASY;
static float value = 0.6f;
static int i = 20;
struct nk_context ctx;
nk_init_fixed(&ctx, calloc(1, MAX_MEMORY), MAX_MEMORY, &font);
if (nk_begin(&ctx, "Show", nk_rect(50, 50, 220, 220),
NK_WINDOW_BORDER|NK_WINDOW_MOVABLE|NK_WINDOW_CLOSABLE)) {
// fixed widget pixel width
nk_layout_row_static(&ctx, 30, 80, 1);
if (nk_button_label(&ctx, "button")) {
// event handling
}
// fixed widget window ratio width
nk_layout_row_dynamic(&ctx, 30, 2);
if (nk_option_label(&ctx, "easy", op == EASY)) op = EASY;
if (nk_option_label(&ctx, "hard", op == HARD)) op = HARD;
// custom widget pixel width
nk_layout_row_begin(&ctx, NK_STATIC, 30, 2);
{
nk_layout_row_push(&ctx, 50);
nk_label(&ctx, "Volume:", NK_TEXT_LEFT);
nk_layout_row_push(&ctx, 110);
nk_slider_float(&ctx, 0, &value, 1.0f, 0.1f);
}
nk_layout_row_end(&ctx);
}
nk_end(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
![](https://cloud.githubusercontent.com/assets/8057201/10187981/584ecd68-675c-11e5-897c-822ef534a876.png)
## API
### Context
Contexts are the main entry point and the majestro of nuklear and contain all required state.
They are used for window, memory, input, style, stack, commands and time management and need
to be passed into all nuklear GUI specific functions.
#### Usage
To use a context it first has to be initialized which can be achieved by calling
one of either `nk_init_default`, `nk_init_fixed`, `nk_init`, `nk_init_custom`.
Each takes in a font handle and a specific way of handling memory. Memory control
hereby ranges from standard library to just specifying a fixed sized block of memory
which nuklear has to manage itself from.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_context ctx;
nk_init_xxx(&ctx, ...);
while (1) {
// [...]
nk_clear(&ctx);
}
nk_free(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### Reference
Function | Description
--------------------|-------------------------------------------------------
__nk_init_default__ | Initializes context with standard library memory allocation (malloc,free)
__nk_init_fixed__ | Initializes context from single fixed size memory block
__nk_init__ | Initializes context with memory allocator callbacks for alloc and free
__nk_init_custom__ | Initializes context from two buffers. One for draw commands the other for window/panel/table allocations
__nk_clear__ | Called at the end of the frame to reset and prepare the context for the next frame
__nk_free__ | Shutdown and free all memory allocated inside the context
__nk_set_user_data__| Utility function to pass user data to draw command
#### nk_init_default
Initializes a `nk_context` struct with a default standard library allocator.
Should be used if you don't want to be bothered with memory management in nuklear.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_init_default(struct nk_context *ctx, const struct nk_user_font *font);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|---------------------------------------------------------------
__ctx__ | Must point to an either stack or heap allocated `nk_context` struct
__font__ | Must point to a previously initialized font handle for more info look at font documentation
Returns either `false(0)` on failure or `true(1)` on success.
#### nk_init_fixed
Initializes a `nk_context` struct from single fixed size memory block
Should be used if you want complete control over nuklear's memory management.
Especially recommended for system with little memory or systems with virtual memory.
For the later case you can just allocate for example 16MB of virtual memory
and only the required amount of memory will actually be committed.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_init_fixed(struct nk_context *ctx, void *memory, nk_size size, const struct nk_user_font *font);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!!! Warning
make sure the passed memory block is aligned correctly for `nk_draw_commands`.
Parameter | Description
------------|--------------------------------------------------------------
__ctx__ | Must point to an either stack or heap allocated `nk_context` struct
__memory__ | Must point to a previously allocated memory block
__size__ | Must contain the total size of __memory__
__font__ | Must point to a previously initialized font handle for more info look at font documentation
Returns either `false(0)` on failure or `true(1)` on success.
#### nk_init
Initializes a `nk_context` struct with memory allocation callbacks for nuklear to allocate
memory from. Used internally for `nk_init_default` and provides a kitchen sink allocation
interface to nuklear. Can be useful for cases like monitoring memory consumption.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_init(struct nk_context *ctx, struct nk_allocator *alloc, const struct nk_user_font *font);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|---------------------------------------------------------------
__ctx__ | Must point to an either stack or heap allocated `nk_context` struct
__alloc__ | Must point to a previously allocated memory allocator
__font__ | Must point to a previously initialized font handle for more info look at font documentation
Returns either `false(0)` on failure or `true(1)` on success.
#### nk_init_custom
Initializes a `nk_context` struct from two different either fixed or growing
buffers. The first buffer is for allocating draw commands while the second buffer is
used for allocating windows, panels and state tables.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_init_custom(struct nk_context *ctx, struct nk_buffer *cmds, struct nk_buffer *pool, const struct nk_user_font *font);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|---------------------------------------------------------------
__ctx__ | Must point to an either stack or heap allocated `nk_context` struct
__cmds__ | Must point to a previously initialized memory buffer either fixed or dynamic to store draw commands into
__pool__ | Must point to a previously initialized memory buffer either fixed or dynamic to store windows, panels and tables
__font__ | Must point to a previously initialized font handle for more info look at font documentation
Returns either `false(0)` on failure or `true(1)` on success.
#### nk_clear
Resets the context state at the end of the frame. This includes mostly
garbage collector tasks like removing windows or table not called and therefore
used anymore.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_clear(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
#### nk_free
Frees all memory allocated by nuklear. Not needed if context was
initialized with `nk_init_fixed`.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_free(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
#### nk_set_user_data
Sets the currently passed userdata passed down into each draw command.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_set_user_data(struct nk_context *ctx, nk_handle data);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|--------------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
__data__ | Handle with either pointer or index to be passed into every draw commands
### Input
The input API is responsible for holding the current input state composed of
mouse, key and text input states.
It is worth noting that no direct OS or window handling is done in nuklear.
Instead all input state has to be provided by platform specific code. This on one hand
expects more work from the user and complicates usage but on the other hand
provides simple abstraction over a big number of platforms, libraries and other
already provided functionality.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_input_begin(&ctx);
while (GetEvent(&evt)) {
if (evt.type == MOUSE_MOVE)
nk_input_motion(&ctx, evt.motion.x, evt.motion.y);
else if (evt.type == [...]) {
// [...]
}
} nk_input_end(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### Usage
Input state needs to be provided to nuklear by first calling `nk_input_begin`
which resets internal state like delta mouse position and button transitions.
After `nk_input_begin` all current input state needs to be provided. This includes
mouse motion, button and key pressed and released, text input and scrolling.
Both event- or state-based input handling are supported by this API
and should work without problems. Finally after all input state has been
mirrored `nk_input_end` needs to be called to finish input process.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_context ctx;
nk_init_xxx(&ctx, ...);
while (1) {
Event evt;
nk_input_begin(&ctx);
while (GetEvent(&evt)) {
if (evt.type == MOUSE_MOVE)
nk_input_motion(&ctx, evt.motion.x, evt.motion.y);
else if (evt.type == [...]) {
// [...]
}
}
nk_input_end(&ctx);
// [...]
nk_clear(&ctx);
} nk_free(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### Reference
Function | Description
--------------------|-------------------------------------------------------
__nk_input_begin__ | Begins the input mirroring process. Needs to be called before all other `nk_input_xxx` calls
__nk_input_motion__ | Mirrors mouse cursor position
__nk_input_key__ | Mirrors key state with either pressed or released
__nk_input_button__ | Mirrors mouse button state with either pressed or released
__nk_input_scroll__ | Mirrors mouse scroll values
__nk_input_char__ | Adds a single ASCII text character into an internal text buffer
__nk_input_glyph__ | Adds a single multi-byte UTF-8 character into an internal text buffer
__nk_input_unicode__| Adds a single unicode rune into an internal text buffer
__nk_input_end__ | Ends the input mirroring process by calculating state changes. Don't call any `nk_input_xxx` function referenced above after this call
#### nk_input_begin
Begins the input mirroring process by resetting text, scroll
mouse, previous mouse position and movement as well as key state transitions,
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_input_begin(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
#### nk_input_motion
Mirrors current mouse position to nuklear
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_input_motion(struct nk_context *ctx, int x, int y);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
__x__ | Must hold an integer describing the current mouse cursor x-position
__y__ | Must hold an integer describing the current mouse cursor y-position
#### nk_input_key
Mirrors the state of a specific key to nuklear
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_input_key(struct nk_context*, enum nk_keys key, nk_bool down);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
__key__ | Must be any value specified in enum `nk_keys` that needs to be mirrored
__down__ | Must be 0 for key is up and 1 for key is down
#### nk_input_button
Mirrors the state of a specific mouse button to nuklear
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_input_button(struct nk_context *ctx, enum nk_buttons btn, int x, int y, nk_bool down);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
__btn__ | Must be any value specified in enum `nk_buttons` that needs to be mirrored
__x__ | Must contain an integer describing mouse cursor x-position on click up/down
__y__ | Must contain an integer describing mouse cursor y-position on click up/down
__down__ | Must be 0 for key is up and 1 for key is down
#### nk_input_scroll
Copies the last mouse scroll value to nuklear. Is generally
a scroll value. So does not have to come from mouse and could also originate
TODO finish this sentence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_input_scroll(struct nk_context *ctx, struct nk_vec2 val);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
__val__ | vector with both X- as well as Y-scroll value
#### nk_input_char
Copies a single ASCII character into an internal text buffer
This is basically a helper function to quickly push ASCII characters into
nuklear.
!!! Note
Stores up to NK_INPUT_MAX bytes between `nk_input_begin` and `nk_input_end`.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_input_char(struct nk_context *ctx, char c);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
__c__ | Must be a single ASCII character preferable one that can be printed
#### nk_input_glyph
Converts an encoded unicode rune into UTF-8 and copies the result into an
internal text buffer.
!!! Note
Stores up to NK_INPUT_MAX bytes between `nk_input_begin` and `nk_input_end`.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_input_glyph(struct nk_context *ctx, const nk_glyph g);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
__g__ | UTF-32 unicode codepoint
#### nk_input_unicode
Converts a unicode rune into UTF-8 and copies the result
into an internal text buffer.
!!! Note
Stores up to NK_INPUT_MAX bytes between `nk_input_begin` and `nk_input_end`.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_input_unicode(struct nk_context*, nk_rune rune);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
__rune__ | UTF-32 unicode codepoint
#### nk_input_end
End the input mirroring process by resetting mouse grabbing
state to ensure the mouse cursor is not grabbed indefinitely.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_input_end(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to a previously initialized `nk_context` struct
### Drawing
This library was designed to be render backend agnostic so it does
not draw anything to screen directly. Instead all drawn shapes, widgets
are made of, are buffered into memory and make up a command queue.
Each frame therefore fills the command buffer with draw commands
that then need to be executed by the user and his own render backend.
After that the command buffer needs to be cleared and a new frame can be
started. It is probably important to note that the command buffer is the main
drawing API and the optional vertex buffer API only takes this format and
converts it into a hardware accessible format.
#### Usage
To draw all draw commands accumulated over a frame you need your own render
backend able to draw a number of 2D primitives. This includes at least
filled and stroked rectangles, circles, text, lines, triangles and scissors.
As soon as this criterion is met you can iterate over each draw command
and execute each draw command in a interpreter like fashion:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
const struct nk_command *cmd = 0;
nk_foreach(cmd, &ctx) {
switch (cmd->type) {
case NK_COMMAND_LINE:
your_draw_line_function(...)
break;
case NK_COMMAND_RECT
your_draw_rect_function(...)
break;
case //...:
//[...]
}
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In program flow context draw commands need to be executed after input has been
gathered and the complete UI with windows and their contained widgets have
been executed and before calling `nk_clear` which frees all previously
allocated draw commands.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_context ctx;
nk_init_xxx(&ctx, ...);
while (1) {
Event evt;
nk_input_begin(&ctx);
while (GetEvent(&evt)) {
if (evt.type == MOUSE_MOVE)
nk_input_motion(&ctx, evt.motion.x, evt.motion.y);
else if (evt.type == [...]) {
[...]
}
}
nk_input_end(&ctx);
//
// [...]
//
const struct nk_command *cmd = 0;
nk_foreach(cmd, &ctx) {
switch (cmd->type) {
case NK_COMMAND_LINE:
your_draw_line_function(...)
break;
case NK_COMMAND_RECT
your_draw_rect_function(...)
break;
case ...:
// [...]
}
nk_clear(&ctx);
}
nk_free(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You probably noticed that you have to draw all of the UI each frame which is
quite wasteful. While the actual UI updating loop is quite fast rendering
without actually needing it is not. So there are multiple things you could do.
First is only update on input. This of course is only an option if your
application only depends on the UI and does not require any outside calculations.
If you actually only update on input make sure to update the UI two times each
frame and call `nk_clear` directly after the first pass and only draw in
the second pass. In addition it is recommended to also add additional timers
to make sure the UI is not drawn more than a fixed number of frames per second.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_context ctx;
nk_init_xxx(&ctx, ...);
while (1) {
// [...wait for input ]
// [...do two UI passes ...]
do_ui(...)
nk_clear(&ctx);
do_ui(...)
//
// draw
const struct nk_command *cmd = 0;
nk_foreach(cmd, &ctx) {
switch (cmd->type) {
case NK_COMMAND_LINE:
your_draw_line_function(...)
break;
case NK_COMMAND_RECT
your_draw_rect_function(...)
break;
case ...:
//[...]
}
nk_clear(&ctx);
}
nk_free(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The second probably more applicable trick is to only draw if anything changed.
It is not really useful for applications with continuous draw loop but
quite useful for desktop applications. To actually get nuklear to only
draw on changes you first have to define `NK_ZERO_COMMAND_MEMORY` and
allocate a memory buffer that will store each unique drawing output.
After each frame you compare the draw command memory inside the library
with your allocated buffer by memcmp. If memcmp detects differences
you have to copy the command buffer into the allocated buffer
and then draw like usual (this example uses fixed memory but you could
use dynamically allocated memory).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
//[... other defines ...]
#define NK_ZERO_COMMAND_MEMORY
#include "nuklear.h"
//
// setup context
struct nk_context ctx;
void *last = calloc(1,64*1024);
void *buf = calloc(1,64*1024);
nk_init_fixed(&ctx, buf, 64*1024);
//
// loop
while (1) {
// [...input...]
// [...ui...]
void *cmds = nk_buffer_memory(&ctx.memory);
if (memcmp(cmds, last, ctx.memory.allocated)) {
memcpy(last,cmds,ctx.memory.allocated);
const struct nk_command *cmd = 0;
nk_foreach(cmd, &ctx) {
switch (cmd->type) {
case NK_COMMAND_LINE:
your_draw_line_function(...)
break;
case NK_COMMAND_RECT
your_draw_rect_function(...)
break;
case ...:
// [...]
}
}
}
nk_clear(&ctx);
}
nk_free(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Finally while using draw commands makes sense for higher abstracted platforms like
X11 and Win32 or drawing libraries it is often desirable to use graphics
hardware directly. Therefore it is possible to just define
`NK_INCLUDE_VERTEX_BUFFER_OUTPUT` which includes optional vertex output.
To access the vertex output you first have to convert all draw commands into
vertexes by calling `nk_convert` which takes in your preferred vertex format.
After successfully converting all draw commands just iterate over and execute all
vertex draw commands:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
// fill configuration
struct your_vertex
{
float pos[2]; // important to keep it to 2 floats
float uv[2];
unsigned char col[4];
};
struct nk_convert_config cfg = {};
static const struct nk_draw_vertex_layout_element vertex_layout[] = {
{NK_VERTEX_POSITION, NK_FORMAT_FLOAT, NK_OFFSETOF(struct your_vertex, pos)},
{NK_VERTEX_TEXCOORD, NK_FORMAT_FLOAT, NK_OFFSETOF(struct your_vertex, uv)},
{NK_VERTEX_COLOR, NK_FORMAT_R8G8B8A8, NK_OFFSETOF(struct your_vertex, col)},
{NK_VERTEX_LAYOUT_END}
};
cfg.shape_AA = NK_ANTI_ALIASING_ON;
cfg.line_AA = NK_ANTI_ALIASING_ON;
cfg.vertex_layout = vertex_layout;
cfg.vertex_size = sizeof(struct your_vertex);
cfg.vertex_alignment = NK_ALIGNOF(struct your_vertex);
cfg.circle_segment_count = 22;
cfg.curve_segment_count = 22;
cfg.arc_segment_count = 22;
cfg.global_alpha = 1.0f;
cfg.tex_null = dev->tex_null;
//
// setup buffers and convert
struct nk_buffer cmds, verts, idx;
nk_buffer_init_default(&cmds);
nk_buffer_init_default(&verts);
nk_buffer_init_default(&idx);
nk_convert(&ctx, &cmds, &verts, &idx, &cfg);
//
// draw
nk_draw_foreach(cmd, &ctx, &cmds) {
if (!cmd->elem_count) continue;
//[...]
}
nk_buffer_free(&cms);
nk_buffer_free(&verts);
nk_buffer_free(&idx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### Reference
Function | Description
--------------------|-------------------------------------------------------
__nk__begin__ | Returns the first draw command in the context draw command list to be drawn
__nk__next__ | Increments the draw command iterator to the next command inside the context draw command list
__nk_foreach__ | Iterates over each draw command inside the context draw command list
__nk_convert__ | Converts from the abstract draw commands list into a hardware accessible vertex format
__nk_draw_begin__ | Returns the first vertex command in the context vertex draw list to be executed
__nk__draw_next__ | Increments the vertex command iterator to the next command inside the context vertex command list
__nk__draw_end__ | Returns the end of the vertex draw list
__nk_draw_foreach__ | Iterates over each vertex draw command inside the vertex draw list
#### nk__begin
Returns a draw command list iterator to iterate all draw
commands accumulated over one frame.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
const struct nk_command* nk__begin(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | must point to an previously initialized `nk_context` struct at the end of a frame
Returns draw command pointer pointing to the first command inside the draw command list
#### nk__next
Returns draw command pointer pointing to the next command inside the draw command list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
const struct nk_command* nk__next(struct nk_context*, const struct nk_command*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct at the end of a frame
__cmd__ | Must point to an previously a draw command either returned by `nk__begin` or `nk__next`
Returns draw command pointer pointing to the next command inside the draw command list
#### nk_foreach
Iterates over each draw command inside the context draw command list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
#define nk_foreach(c, ctx)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct at the end of a frame
__cmd__ | Command pointer initialized to NULL
Iterates over each draw command inside the context draw command list
#### nk_convert
Converts all internal draw commands into vertex draw commands and fills
three buffers with vertexes, vertex draw commands and vertex indices. The vertex format
as well as some other configuration values have to be configured by filling out a
`nk_convert_config` struct.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_flags nk_convert(struct nk_context *ctx, struct nk_buffer *cmds,
struct nk_buffer *vertices, struct nk_buffer *elements, const struct nk_convert_config*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct at the end of a frame
__cmds__ | Must point to a previously initialized buffer to hold converted vertex draw commands
__vertices__| Must point to a previously initialized buffer to hold all produced vertices
__elements__| Must point to a previously initialized buffer to hold all produced vertex indices
__config__ | Must point to a filled out `nk_config` struct to configure the conversion process
Returns one of enum nk_convert_result error codes
Parameter | Description
--------------------------------|-----------------------------------------------------------
NK_CONVERT_SUCCESS | Signals a successful draw command to vertex buffer conversion
NK_CONVERT_INVALID_PARAM | An invalid argument was passed in the function call
NK_CONVERT_COMMAND_BUFFER_FULL | The provided buffer for storing draw commands is full or failed to allocate more memory
NK_CONVERT_VERTEX_BUFFER_FULL | The provided buffer for storing vertices is full or failed to allocate more memory
NK_CONVERT_ELEMENT_BUFFER_FULL | The provided buffer for storing indices is full or failed to allocate more memory
#### nk__draw_begin
Returns a draw vertex command buffer iterator to iterate over the vertex draw command buffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
const struct nk_draw_command* nk__draw_begin(const struct nk_context*, const struct nk_buffer*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct at the end of a frame
__buf__ | Must point to an previously by `nk_convert` filled out vertex draw command buffer
Returns vertex draw command pointer pointing to the first command inside the vertex draw command buffer
#### nk__draw_end
Returns the vertex draw command at the end of the vertex draw command buffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
const struct nk_draw_command* nk__draw_end(const struct nk_context *ctx, const struct nk_buffer *buf);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct at the end of a frame
__buf__ | Must point to an previously by `nk_convert` filled out vertex draw command buffer
Returns vertex draw command pointer pointing to the end of the last vertex draw command inside the vertex draw command buffer
#### nk__draw_next
Increments the vertex draw command buffer iterator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
const struct nk_draw_command* nk__draw_next(const struct nk_draw_command*, const struct nk_buffer*, const struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__cmd__ | Must point to an previously either by `nk__draw_begin` or `nk__draw_next` returned vertex draw command
__buf__ | Must point to an previously by `nk_convert` filled out vertex draw command buffer
__ctx__ | Must point to an previously initialized `nk_context` struct at the end of a frame
Returns vertex draw command pointer pointing to the end of the last vertex draw command inside the vertex draw command buffer
#### nk_draw_foreach
Iterates over each vertex draw command inside a vertex draw command buffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
#define nk_draw_foreach(cmd,ctx, b)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__cmd__ | `nk_draw_command`iterator set to NULL
__buf__ | Must point to an previously by `nk_convert` filled out vertex draw command buffer
__ctx__ | Must point to an previously initialized `nk_context` struct at the end of a frame
### Window
Windows are the main persistent state used inside nuklear and are life time
controlled by simply "retouching" (i.e. calling) each window each frame.
All widgets inside nuklear can only be added inside the function pair `nk_begin_xxx`
and `nk_end`. Calling any widgets outside these two functions will result in an
assert in debug or no state change in release mode.<br /><br />
Each window holds frame persistent state like position, size, flags, state tables,
and some garbage collected internal persistent widget state. Each window
is linked into a window stack list which determines the drawing and overlapping
order. The topmost window thereby is the currently active window.<br /><br />
To change window position inside the stack occurs either automatically by
user input by being clicked on or programmatically by calling `nk_window_focus`.
Windows by default are visible unless explicitly being defined with flag
`NK_WINDOW_HIDDEN`, the user clicked the close button on windows with flag
`NK_WINDOW_CLOSABLE` or if a window was explicitly hidden by calling
`nk_window_show`. To explicitly close and destroy a window call `nk_window_close`.<br /><br />
#### Usage
To create and keep a window you have to call one of the two `nk_begin_xxx`
functions to start window declarations and `nk_end` at the end. Furthermore it
is recommended to check the return value of `nk_begin_xxx` and only process
widgets inside the window if the value is not 0. Either way you have to call
`nk_end` at the end of window declarations. Furthermore, do not attempt to
nest `nk_begin_xxx` calls which will hopefully result in an assert or if not
in a segmentation fault.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
if (nk_begin_xxx(...) {
// [... widgets ...]
}
nk_end(ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the grand concept window and widget declarations need to occur after input
handling and before drawing to screen. Not doing so can result in higher
latency or at worst invalid behavior. Furthermore make sure that `nk_clear`
is called at the end of the frame. While nuklear's default platform backends
already call `nk_clear` for you if you write your own backend not calling
`nk_clear` can cause asserts or even worse undefined behavior.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_context ctx;
nk_init_xxx(&ctx, ...);
while (1) {
Event evt;
nk_input_begin(&ctx);
while (GetEvent(&evt)) {
if (evt.type == MOUSE_MOVE)
nk_input_motion(&ctx, evt.motion.x, evt.motion.y);
else if (evt.type == [...]) {
nk_input_xxx(...);
}
}
nk_input_end(&ctx);
if (nk_begin_xxx(...) {
//[...]
}
nk_end(ctx);
const struct nk_command *cmd = 0;
nk_foreach(cmd, &ctx) {
case NK_COMMAND_LINE:
your_draw_line_function(...)
break;
case NK_COMMAND_RECT
your_draw_rect_function(...)
break;
case //...:
//[...]
}
nk_clear(&ctx);
}
nk_free(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### Reference
Function | Description
------------------------------------|----------------------------------------
nk_begin | Starts a new window; needs to be called every frame for every window (unless hidden) or otherwise the window gets removed
nk_begin_titled | Extended window start with separated title and identifier to allow multiple windows with same name but not title
nk_end | Needs to be called at the end of the window building process to process scaling, scrollbars and general cleanup
nk_window_find | Finds and returns the window with give name
nk_window_get_bounds | Returns a rectangle with screen position and size of the currently processed window.
nk_window_get_position | Returns the position of the currently processed window
nk_window_get_size | Returns the size with width and height of the currently processed window
nk_window_get_width | Returns the width of the currently processed window
nk_window_get_height | Returns the height of the currently processed window
nk_window_get_panel | Returns the underlying panel which contains all processing state of the current window
nk_window_get_content_region | Returns the position and size of the currently visible and non-clipped space inside the currently processed window
nk_window_get_content_region_min | Returns the upper rectangle position of the currently visible and non-clipped space inside the currently processed window
nk_window_get_content_region_max | Returns the upper rectangle position of the currently visible and non-clipped space inside the currently processed window
nk_window_get_content_region_size | Returns the size of the currently visible and non-clipped space inside the currently processed window
nk_window_get_canvas | Returns the draw command buffer. Can be used to draw custom widgets
nk_window_get_scroll | Gets the scroll offset of the current window
nk_window_has_focus | Returns if the currently processed window is currently active
nk_window_is_collapsed | Returns if the window with given name is currently minimized/collapsed
nk_window_is_closed | Returns if the currently processed window was closed
nk_window_is_hidden | Returns if the currently processed window was hidden
nk_window_is_active | Same as nk_window_has_focus for some reason
nk_window_is_hovered | Returns if the currently processed window is currently being hovered by mouse
nk_window_is_any_hovered | Return if any window currently hovered
nk_item_is_any_active | Returns if any window or widgets is currently hovered or active
nk_window_set_bounds | Updates position and size of the currently processed window
nk_window_set_position | Updates position of the currently process window
nk_window_set_size | Updates the size of the currently processed window
nk_window_set_focus | Set the currently processed window as active window
nk_window_set_scroll | Sets the scroll offset of the current window
nk_window_close | Closes the window with given window name which deletes the window at the end of the frame
nk_window_collapse | Collapses the window with given window name
nk_window_collapse_if | Collapses the window with given window name if the given condition was met
nk_window_show | Hides a visible or reshows a hidden window
nk_window_show_if | Hides/shows a window depending on condition
#### nk_panel_flags
Flag | Description
----------------------------|----------------------------------------
NK_WINDOW_BORDER | Draws a border around the window to visually separate window from the background
NK_WINDOW_MOVABLE | The movable flag indicates that a window can be moved by user input or by dragging the window header
NK_WINDOW_SCALABLE | The scalable flag indicates that a window can be scaled by user input by dragging a scaler icon at the button of the window
NK_WINDOW_CLOSABLE | Adds a closable icon into the header
NK_WINDOW_MINIMIZABLE | Adds a minimize icon into the header
NK_WINDOW_NO_SCROLLBAR | Removes the scrollbar from the window
NK_WINDOW_TITLE | Forces a header at the top at the window showing the title
NK_WINDOW_SCROLL_AUTO_HIDE | Automatically hides the window scrollbar if no user interaction: also requires delta time in `nk_context` to be set each frame
NK_WINDOW_BACKGROUND | Always keep window in the background
NK_WINDOW_SCALE_LEFT | Puts window scaler in the left-bottom corner instead right-bottom
NK_WINDOW_NO_INPUT | Prevents window of scaling, moving or getting focus
#### nk_collapse_states
State | Description
----------------|-----------------------------------------------------------
__NK_MINIMIZED__| UI section is collapsed and not visible until maximized
__NK_MAXIMIZED__| UI section is extended and visible until minimized
<br /><br />
#### nk_begin
Starts a new window; needs to be called every frame for every
window (unless hidden) or otherwise the window gets removed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_begin(struct nk_context *ctx, const char *title, struct nk_rect bounds, nk_flags flags);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__title__ | Window title and identifier. Needs to be persistent over frames to identify the window
__bounds__ | Initial position and window size. However if you do not define `NK_WINDOW_SCALABLE` or `NK_WINDOW_MOVABLE` you can set window position and size every frame
__flags__ | Window flags defined in the nk_panel_flags section with a number of different window behaviors
Returns `true(1)` if the window can be filled up with widgets from this point
until `nk_end` or `false(0)` otherwise for example if minimized
#### nk_begin_titled
Extended window start with separated title and identifier to allow multiple
windows with same title but not name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_begin_titled(struct nk_context *ctx, const char *name, const char *title, struct nk_rect bounds, nk_flags flags);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Window identifier. Needs to be persistent over frames to identify the window
__title__ | Window title displayed inside header if flag `NK_WINDOW_TITLE` or either `NK_WINDOW_CLOSABLE` or `NK_WINDOW_MINIMIZED` was set
__bounds__ | Initial position and window size. However if you do not define `NK_WINDOW_SCALABLE` or `NK_WINDOW_MOVABLE` you can set window position and size every frame
__flags__ | Window flags defined in the nk_panel_flags section with a number of different window behaviors
Returns `true(1)` if the window can be filled up with widgets from this point
until `nk_end` or `false(0)` otherwise for example if minimized
#### nk_end
Needs to be called at the end of the window building process to process scaling, scrollbars and general cleanup.
All widget calls after this functions will result in asserts or no state changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_end(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
#### nk_window_find
Finds and returns a window from passed name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_window *nk_window_find(struct nk_context *ctx, const char *name);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Window identifier
Returns a `nk_window` struct pointing to the identified window or NULL if
no window with the given name was found
#### nk_window_get_bounds
Returns a rectangle with screen position and size of the currently processed window
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_rect nk_window_get_bounds(const struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns a `nk_rect` struct with window upper left window position and size
#### nk_window_get_position
Returns the position of the currently processed window.
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_vec2 nk_window_get_position(const struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns a `nk_vec2` struct with window upper left position
#### nk_window_get_size
Returns the size with width and height of the currently processed window.
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_vec2 nk_window_get_size(const struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns a `nk_vec2` struct with window width and height
#### nk_window_get_width
Returns the width of the currently processed window.
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
float nk_window_get_width(const struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns the current window width
#### nk_window_get_height
Returns the height of the currently processed window.
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
float nk_window_get_height(const struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns the current window height
#### nk_window_get_panel
Returns the underlying panel which contains all processing state of the current window.
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
!!! WARNING
Do not keep the returned panel pointer around, it is only valid until `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_panel* nk_window_get_panel(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns a pointer to window internal `nk_panel` state.
#### nk_window_get_content_region
Returns the position and size of the currently visible and non-clipped space
inside the currently processed window.
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_rect nk_window_get_content_region(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns `nk_rect` struct with screen position and size (no scrollbar offset)
of the visible space inside the current window
#### nk_window_get_content_region_min
Returns the upper left position of the currently visible and non-clipped
space inside the currently processed window.
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_vec2 nk_window_get_content_region_min(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
returns `nk_vec2` struct with upper left screen position (no scrollbar offset)
of the visible space inside the current window
#### nk_window_get_content_region_max
Returns the lower right screen position of the currently visible and
non-clipped space inside the currently processed window.
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_vec2 nk_window_get_content_region_max(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns `nk_vec2` struct with lower right screen position (no scrollbar offset)
of the visible space inside the current window
#### nk_window_get_content_region_size
Returns the size of the currently visible and non-clipped space inside the
currently processed window
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_vec2 nk_window_get_content_region_size(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns `nk_vec2` struct with size the visible space inside the current window
#### nk_window_get_canvas
Returns the draw command buffer. Can be used to draw custom widgets
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
!!! WARNING
Do not keep the returned command buffer pointer around it is only valid until `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_command_buffer* nk_window_get_canvas(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns a pointer to window internal `nk_command_buffer` struct used as
drawing canvas. Can be used to do custom drawing.
#### nk_window_get_scroll
Gets the scroll offset for the current window
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_get_scroll(struct nk_context *ctx, nk_uint *offset_x, nk_uint *offset_y);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
-------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__offset_x__ | A pointer to the x offset output (or NULL to ignore)
__offset_y__ | A pointer to the y offset output (or NULL to ignore)
#### nk_window_has_focus
Returns if the currently processed window is currently active
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_window_has_focus(const struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns `false(0)` if current window is not active or `true(1)` if it is
#### nk_window_is_hovered
Return if the current window is being hovered
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_window_is_hovered(struct nk_context *ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns `true(1)` if current window is hovered or `false(0)` otherwise
#### nk_window_is_collapsed
Returns if the window with given name is currently minimized/collapsed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_window_is_collapsed(struct nk_context *ctx, const char *name);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of window you want to check if it is collapsed
Returns `true(1)` if current window is minimized and `false(0)` if window not
found or is not minimized
#### nk_window_is_closed
Returns if the window with given name was closed by calling `nk_close`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_window_is_closed(struct nk_context *ctx, const char *name);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of window you want to check if it is closed
Returns `true(1)` if current window was closed or `false(0)` window not found or not closed
#### nk_window_is_hidden
Returns if the window with given name is hidden
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_window_is_hidden(struct nk_context *ctx, const char *name);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of window you want to check if it is hidden
Returns `true(1)` if current window is hidden or `false(0)` window not found or visible
#### nk_window_is_active
Same as nk_window_has_focus for some reason
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_window_is_active(struct nk_context *ctx, const char *name);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of window you want to check if it is active
Returns `true(1)` if current window is active or `false(0)` window not found or not active
#### nk_window_is_any_hovered
Returns if the any window is being hovered
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_window_is_any_hovered(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns `true(1)` if any window is hovered or `false(0)` otherwise
#### nk_item_is_any_active
Returns if the any window is being hovered or any widget is currently active.
Can be used to decide if input should be processed by UI or your specific input handling.
Example could be UI and 3D camera to move inside a 3D space.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_item_is_any_active(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
Returns `true(1)` if any window is hovered or any item is active or `false(0)` otherwise
#### nk_window_set_bounds
Updates position and size of window with passed in name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_set_bounds(struct nk_context*, const char *name, struct nk_rect bounds);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of the window to modify both position and size
__bounds__ | Must point to a `nk_rect` struct with the new position and size
#### nk_window_set_position
Updates position of window with passed name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_set_position(struct nk_context*, const char *name, struct nk_vec2 pos);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of the window to modify both position
__pos__ | Must point to a `nk_vec2` struct with the new position
#### nk_window_set_size
Updates size of window with passed in name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_set_size(struct nk_context*, const char *name, struct nk_vec2);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of the window to modify both window size
__size__ | Must point to a `nk_vec2` struct with new window size
#### nk_window_set_focus
Sets the window with given name as active
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_set_focus(struct nk_context*, const char *name);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of the window to set focus on
#### nk_window_set_scroll
Sets the scroll offset for the current window
!!! WARNING
Only call this function between calls `nk_begin_xxx` and `nk_end`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_set_scroll(struct nk_context *ctx, nk_uint offset_x, nk_uint offset_y);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
-------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__offset_x__ | The x offset to scroll to
__offset_y__ | The y offset to scroll to
#### nk_window_close
Closes a window and marks it for being freed at the end of the frame
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_close(struct nk_context *ctx, const char *name);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of the window to close
#### nk_window_collapse
Updates collapse state of a window with given name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_collapse(struct nk_context*, const char *name, enum nk_collapse_states state);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of the window to close
__state__ | value out of nk_collapse_states section
#### nk_window_collapse_if
Updates collapse state of a window with given name if given condition is met
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_collapse_if(struct nk_context*, const char *name, enum nk_collapse_states, int cond);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of the window to either collapse or maximize
__state__ | value out of nk_collapse_states section the window should be put into
__cond__ | condition that has to be met to actually commit the collapse state change
#### nk_window_show
updates visibility state of a window with given name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_show(struct nk_context*, const char *name, enum nk_show_states);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of the window to either collapse or maximize
__state__ | state with either visible or hidden to modify the window with
#### nk_window_show_if
Updates visibility state of a window with given name if a given condition is met
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_window_show_if(struct nk_context*, const char *name, enum nk_show_states, int cond);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__name__ | Identifier of the window to either hide or show
__state__ | state with either visible or hidden to modify the window with
__cond__ | condition that has to be met to actually commit the visibility state change
### Layouting
Layouting in general describes placing widget inside a window with position and size.
While in this particular implementation there are five different APIs for layouting
each with different trade offs between control and ease of use. <br /><br />
All layouting methods in this library are based around the concept of a row.
A row has a height the window content grows by and a number of columns and each
layouting method specifies how each widget is placed inside the row.
After a row has been allocated by calling a layouting functions and then
filled with widgets will advance an internal pointer over the allocated row. <br /><br />
To actually define a layout you just call the appropriate layouting function
and each subsequent widget call will place the widget as specified. Important
here is that if you define more widgets then columns defined inside the layout
functions it will allocate the next row without you having to make another layouting <br /><br />
call.
Biggest limitation with using all these APIs outside the `nk_layout_space_xxx` API
is that you have to define the row height for each. However the row height
often depends on the height of the font. <br /><br />
To fix that internally nuklear uses a minimum row height that is set to the
height plus padding of currently active font and overwrites the row height
value if zero. <br /><br />
If you manually want to change the minimum row height then
use nk_layout_set_min_row_height, and use nk_layout_reset_min_row_height to
reset it back to be derived from font height. <br /><br />
Also if you change the font in nuklear it will automatically change the minimum
row height for you and. This means if you change the font but still want
a minimum row height smaller than the font you have to repush your value. <br /><br />
For actually more advanced UI I would even recommend using the `nk_layout_space_xxx`
layouting method in combination with a cassowary constraint solver (there are
some versions on github with permissive license model) to take over all control over widget
layouting yourself. However for quick and dirty layouting using all the other layouting
functions should be fine.
#### Usage
1. __nk_layout_row_dynamic__<br /><br />
The easiest layouting function is `nk_layout_row_dynamic`. It provides each
widgets with same horizontal space inside the row and dynamically grows
if the owning window grows in width. So the number of columns dictates
the size of each widget dynamically by formula:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
widget_width = (window_width - padding - spacing) * (1/column_count)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Just like all other layouting APIs if you define more widget than columns this
library will allocate a new row and keep all layouting parameters previously
defined.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
if (nk_begin_xxx(...) {
// first row with height: 30 composed of two widgets
nk_layout_row_dynamic(&ctx, 30, 2);
nk_widget(...);
nk_widget(...);
//
// second row with same parameter as defined above
nk_widget(...);
nk_widget(...);
//
// third row uses 0 for height which will use auto layouting
nk_layout_row_dynamic(&ctx, 0, 2);
nk_widget(...);
nk_widget(...);
}
nk_end(...);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2. __nk_layout_row_static__<br /><br />
Another easy layouting function is `nk_layout_row_static`. It provides each
widget with same horizontal pixel width inside the row and does not grow
if the owning window scales smaller or bigger.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
if (nk_begin_xxx(...) {
// first row with height: 30 composed of two widgets with width: 80
nk_layout_row_static(&ctx, 30, 80, 2);
nk_widget(...);
nk_widget(...);
//
// second row with same parameter as defined above
nk_widget(...);
nk_widget(...);
//
// third row uses 0 for height which will use auto layouting
nk_layout_row_static(&ctx, 0, 80, 2);
nk_widget(...);
nk_widget(...);
}
nk_end(...);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3. __nk_layout_row_xxx__<br /><br />
A little bit more advanced layouting API are functions `nk_layout_row_begin`,
`nk_layout_row_push` and `nk_layout_row_end`. They allow to directly
specify each column pixel or window ratio in a row. It supports either
directly setting per column pixel width or widget window ratio but not
both. Furthermore it is a immediate mode API so each value is directly
pushed before calling a widget. Therefore the layout is not automatically
repeating like the last two layouting functions.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
if (nk_begin_xxx(...) {
// first row with height: 25 composed of two widgets with width 60 and 40
nk_layout_row_begin(ctx, NK_STATIC, 25, 2);
nk_layout_row_push(ctx, 60);
nk_widget(...);
nk_layout_row_push(ctx, 40);
nk_widget(...);
nk_layout_row_end(ctx);
//
// second row with height: 25 composed of two widgets with window ratio 0.25 and 0.75
nk_layout_row_begin(ctx, NK_DYNAMIC, 25, 2);
nk_layout_row_push(ctx, 0.25f);
nk_widget(...);
nk_layout_row_push(ctx, 0.75f);
nk_widget(...);
nk_layout_row_end(ctx);
//
// third row with auto generated height: composed of two widgets with window ratio 0.25 and 0.75
nk_layout_row_begin(ctx, NK_DYNAMIC, 0, 2);
nk_layout_row_push(ctx, 0.25f);
nk_widget(...);
nk_layout_row_push(ctx, 0.75f);
nk_widget(...);
nk_layout_row_end(ctx);
}
nk_end(...);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4. __nk_layout_row__<br /><br />
The array counterpart to API nk_layout_row_xxx is the single nk_layout_row
functions. Instead of pushing either pixel or window ratio for every widget
it allows to define it by array. The trade of for less control is that
`nk_layout_row` is automatically repeating. Otherwise the behavior is the
same.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
if (nk_begin_xxx(...) {
// two rows with height: 30 composed of two widgets with width 60 and 40
const float size[] = {60,40};
nk_layout_row(ctx, NK_STATIC, 30, 2, ratio);
nk_widget(...);
nk_widget(...);
nk_widget(...);
nk_widget(...);
//
// two rows with height: 30 composed of two widgets with window ratio 0.25 and 0.75
const float ratio[] = {0.25, 0.75};
nk_layout_row(ctx, NK_DYNAMIC, 30, 2, ratio);
nk_widget(...);
nk_widget(...);
nk_widget(...);
nk_widget(...);
//
// two rows with auto generated height composed of two widgets with window ratio 0.25 and 0.75
const float ratio[] = {0.25, 0.75};
nk_layout_row(ctx, NK_DYNAMIC, 30, 2, ratio);
nk_widget(...);
nk_widget(...);
nk_widget(...);
nk_widget(...);
}
nk_end(...);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5. __nk_layout_row_template_xxx__<br /><br />
The most complex and second most flexible API is a simplified flexbox version without
line wrapping and weights for dynamic widgets. It is an immediate mode API but
unlike `nk_layout_row_xxx` it has auto repeat behavior and needs to be called
before calling the templated widgets.
The row template layout has three different per widget size specifier. The first
one is the `nk_layout_row_template_push_static` with fixed widget pixel width.
They do not grow if the row grows and will always stay the same.
The second size specifier is `nk_layout_row_template_push_variable`
which defines a minimum widget size but it also can grow if more space is available
not taken by other widgets.
Finally there are dynamic widgets with `nk_layout_row_template_push_dynamic`
which are completely flexible and unlike variable widgets can even shrink
to zero if not enough space is provided.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
if (nk_begin_xxx(...) {
// two rows with height: 30 composed of three widgets
nk_layout_row_template_begin(ctx, 30);
nk_layout_row_template_push_dynamic(ctx);
nk_layout_row_template_push_variable(ctx, 80);
nk_layout_row_template_push_static(ctx, 80);
nk_layout_row_template_end(ctx);
//
// first row
nk_widget(...); // dynamic widget can go to zero if not enough space
nk_widget(...); // variable widget with min 80 pixel but can grow bigger if enough space
nk_widget(...); // static widget with fixed 80 pixel width
//
// second row same layout
nk_widget(...);
nk_widget(...);
nk_widget(...);
}
nk_end(...);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6. __nk_layout_space_xxx__<br /><br />
Finally the most flexible API directly allows you to place widgets inside the
window. The space layout API is an immediate mode API which does not support
row auto repeat and directly sets position and size of a widget. Position
and size hereby can be either specified as ratio of allocated space or
allocated space local position and pixel size. Since this API is quite
powerful there are a number of utility functions to get the available space
and convert between local allocated space and screen space.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
if (nk_begin_xxx(...) {
// static row with height: 500 (you can set column count to INT_MAX if you don't want to be bothered)
nk_layout_space_begin(ctx, NK_STATIC, 500, INT_MAX);
nk_layout_space_push(ctx, nk_rect(0,0,150,200));
nk_widget(...);
nk_layout_space_push(ctx, nk_rect(200,200,100,200));
nk_widget(...);
nk_layout_space_end(ctx);
//
// dynamic row with height: 500 (you can set column count to INT_MAX if you don't want to be bothered)
nk_layout_space_begin(ctx, NK_DYNAMIC, 500, INT_MAX);
nk_layout_space_push(ctx, nk_rect(0.5,0.5,0.1,0.1));
nk_widget(...);
nk_layout_space_push(ctx, nk_rect(0.7,0.6,0.1,0.1));
nk_widget(...);
}
nk_end(...);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### Reference
Function | Description
----------------------------------------|------------------------------------
nk_layout_set_min_row_height | Set the currently used minimum row height to a specified value
nk_layout_reset_min_row_height | Resets the currently used minimum row height to font height
nk_layout_widget_bounds | Calculates current width a static layout row can fit inside a window
nk_layout_ratio_from_pixel | Utility functions to calculate window ratio from pixel size
nk_layout_row_dynamic | Current layout is divided into n same sized growing columns
nk_layout_row_static | Current layout is divided into n same fixed sized columns
nk_layout_row_begin | Starts a new row with given height and number of columns
nk_layout_row_push | Pushes another column with given size or window ratio
nk_layout_row_end | Finished previously started row
nk_layout_row | Specifies row columns in array as either window ratio or size
nk_layout_row_template_begin | Begins the row template declaration
nk_layout_row_template_push_dynamic | Adds a dynamic column that dynamically grows and can go to zero if not enough space
nk_layout_row_template_push_variable | Adds a variable column that dynamically grows but does not shrink below specified pixel width
nk_layout_row_template_push_static | Adds a static column that does not grow and will always have the same size
nk_layout_row_template_end | Marks the end of the row template
nk_layout_space_begin | Begins a new layouting space that allows to specify each widgets position and size
nk_layout_space_push | Pushes position and size of the next widget in own coordinate space either as pixel or ratio
nk_layout_space_end | Marks the end of the layouting space
nk_layout_space_bounds | Callable after nk_layout_space_begin and returns total space allocated
nk_layout_space_to_screen | Converts vector from nk_layout_space coordinate space into screen space
nk_layout_space_to_local | Converts vector from screen space into nk_layout_space coordinates
nk_layout_space_rect_to_screen | Converts rectangle from nk_layout_space coordinate space into screen space
nk_layout_space_rect_to_local | Converts rectangle from screen space into nk_layout_space coordinates
#### nk_layout_set_min_row_height
Sets the currently used minimum row height.
!!! WARNING
The passed height needs to include both your preferred row height
as well as padding. No internal padding is added.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_set_min_row_height(struct nk_context*, float height);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__height__ | New minimum row height to be used for auto generating the row height
#### nk_layout_reset_min_row_height
Reset the currently used minimum row height back to `font_height + text_padding + padding`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_reset_min_row_height(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
#### nk_layout_widget_bounds
Returns the width of the next row allocate by one of the layouting functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_rect nk_layout_widget_bounds(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
Return `nk_rect` with both position and size of the next row
#### nk_layout_ratio_from_pixel
Utility functions to calculate window ratio from pixel size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
float nk_layout_ratio_from_pixel(struct nk_context*, float pixel_width);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__pixel__ | Pixel_width to convert to window ratio
Returns `nk_rect` with both position and size of the next row
#### nk_layout_row_dynamic
Sets current row layout to share horizontal space
between @cols number of widgets evenly. Once called all subsequent widget
calls greater than @cols will allocate a new row with same layout.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_dynamic(struct nk_context *ctx, float height, int cols);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__height__ | Holds height of each widget in row or zero for auto layouting
__columns__ | Number of widget inside row
#### nk_layout_row_static
Sets current row layout to fill @cols number of widgets
in row with same @item_width horizontal size. Once called all subsequent widget
calls greater than @cols will allocate a new row with same layout.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_static(struct nk_context *ctx, float height, int item_width, int cols);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__height__ | Holds height of each widget in row or zero for auto layouting
__width__ | Holds pixel width of each widget in the row
__columns__ | Number of widget inside row
#### nk_layout_row_begin
Starts a new dynamic or fixed row with given height and columns.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_begin(struct nk_context *ctx, enum nk_layout_format fmt, float row_height, int cols);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__fmt__ | either `NK_DYNAMIC` for window ratio or `NK_STATIC` for fixed size columns
__height__ | holds height of each widget in row or zero for auto layouting
__columns__ | Number of widget inside row
#### nk_layout_row_push
Specifies either window ratio or width of a single column
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_push(struct nk_context*, float value);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__value__ | either a window ratio or fixed width depending on @fmt in previous `nk_layout_row_begin` call
#### nk_layout_row_end
Finished previously started row
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_end(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
#### nk_layout_row
Specifies row columns in array as either window ratio or size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row(struct nk_context*, enum nk_layout_format, float height, int cols, const float *ratio);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__fmt__ | Either `NK_DYNAMIC` for window ratio or `NK_STATIC` for fixed size columns
__height__ | Holds height of each widget in row or zero for auto layouting
__columns__ | Number of widget inside row
#### nk_layout_row_template_begin
Begins the row template declaration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_template_begin(struct nk_context*, float row_height);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__height__ | Holds height of each widget in row or zero for auto layouting
#### nk_layout_row_template_push_dynamic
Adds a dynamic column that dynamically grows and can go to zero if not enough space
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_template_push_dynamic(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__height__ | Holds height of each widget in row or zero for auto layouting
#### nk_layout_row_template_push_variable
Adds a variable column that dynamically grows but does not shrink below specified pixel width
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_template_push_variable(struct nk_context*, float min_width);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__width__ | Holds the minimum pixel width the next column must always be
#### nk_layout_row_template_push_static
Adds a static column that does not grow and will always have the same size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_template_push_static(struct nk_context*, float width);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__width__ | Holds the absolute pixel width value the next column must be
#### nk_layout_row_template_end
Marks the end of the row template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_row_template_end(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
#### nk_layout_space_begin
Begins a new layouting space that allows to specify each widgets position and size.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_space_begin(struct nk_context*, enum nk_layout_format, float height, int widget_count);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_begin_xxx`
__fmt__ | Either `NK_DYNAMIC` for window ratio or `NK_STATIC` for fixed size columns
__height__ | Holds height of each widget in row or zero for auto layouting
__columns__ | Number of widgets inside row
#### nk_layout_space_push
Pushes position and size of the next widget in own coordinate space either as pixel or ratio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_space_push(struct nk_context *ctx, struct nk_rect bounds);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_layout_space_begin`
__bounds__ | Position and size in laoyut space local coordinates
#### nk_layout_space_end
Marks the end of the layout space
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_layout_space_end(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_layout_space_begin`
#### nk_layout_space_bounds
Utility function to calculate total space allocated for `nk_layout_space`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_rect nk_layout_space_bounds(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_layout_space_begin`
Returns `nk_rect` holding the total space allocated
#### nk_layout_space_to_screen
Converts vector from nk_layout_space coordinate space into screen space
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_vec2 nk_layout_space_to_screen(struct nk_context*, struct nk_vec2);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_layout_space_begin`
__vec__ | Position to convert from layout space into screen coordinate space
Returns transformed `nk_vec2` in screen space coordinates
#### nk_layout_space_to_local
Converts vector from layout space into screen space
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_vec2 nk_layout_space_to_local(struct nk_context*, struct nk_vec2);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_layout_space_begin`
__vec__ | Position to convert from screen space into layout coordinate space
Returns transformed `nk_vec2` in layout space coordinates
#### nk_layout_space_rect_to_screen
Converts rectangle from screen space into layout space
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_rect nk_layout_space_rect_to_screen(struct nk_context*, struct nk_rect);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_layout_space_begin`
__bounds__ | Rectangle to convert from layout space into screen space
Returns transformed `nk_rect` in screen space coordinates
#### nk_layout_space_rect_to_local
Converts rectangle from layout space into screen space
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_rect nk_layout_space_rect_to_local(struct nk_context*, struct nk_rect);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_layout_space_begin`
__bounds__ | Rectangle to convert from layout space into screen space
Returns transformed `nk_rect` in layout space coordinates
#### nk_spacer
Spacer is a dummy widget that consumes space as usual but doesn't draw anything
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_spacer(struct nk_context* );
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after call `nk_layout_space_begin`
### Groups
Groups are basically windows inside windows. They allow to subdivide space
in a window to layout widgets as a group. Almost all more complex widget
layouting requirements can be solved using groups and basic layouting
fuctionality. Groups just like windows are identified by an unique name and
internally keep track of scrollbar offsets by default. However additional
versions are provided to directly manage the scrollbar.
#### Usage
To create a group you have to call one of the three `nk_group_begin_xxx`
functions to start group declarations and `nk_group_end` at the end. Furthermore it
is required to check the return value of `nk_group_begin_xxx` and only process
widgets inside the window if the value is not 0.
Nesting groups is possible and even encouraged since many layouting schemes
can only be achieved by nesting. Groups, unlike windows, need `nk_group_end`
to be only called if the corresponding `nk_group_begin_xxx` call does not return 0:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
if (nk_group_begin_xxx(ctx, ...) {
// [... widgets ...]
nk_group_end(ctx);
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the grand concept groups can be called after starting a window
with `nk_begin_xxx` and before calling `nk_end`:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
struct nk_context ctx;
nk_init_xxx(&ctx, ...);
while (1) {
// Input
Event evt;
nk_input_begin(&ctx);
while (GetEvent(&evt)) {
if (evt.type == MOUSE_MOVE)
nk_input_motion(&ctx, evt.motion.x, evt.motion.y);
else if (evt.type == [...]) {
nk_input_xxx(...);
}
}
nk_input_end(&ctx);
//
// Window
if (nk_begin_xxx(...) {
// [...widgets...]
nk_layout_row_dynamic(...);
if (nk_group_begin_xxx(ctx, ...) {
//[... widgets ...]
nk_group_end(ctx);
}
}
nk_end(ctx);
//
// Draw
const struct nk_command *cmd = 0;
nk_foreach(cmd, &ctx) {
switch (cmd->type) {
case NK_COMMAND_LINE:
your_draw_line_function(...)
break;
case NK_COMMAND_RECT
your_draw_rect_function(...)
break;
case ...:
// [...]
}
nk_clear(&ctx);
}
nk_free(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### Reference
Function | Description
--------------------------------|-------------------------------------------
nk_group_begin | Start a new group with internal scrollbar handling
nk_group_begin_titled | Start a new group with separated name and title and internal scrollbar handling
nk_group_end | Ends a group. Should only be called if nk_group_begin returned non-zero
nk_group_scrolled_offset_begin | Start a new group with manual separated handling of scrollbar x- and y-offset
nk_group_scrolled_begin | Start a new group with manual scrollbar handling
nk_group_scrolled_end | Ends a group with manual scrollbar handling. Should only be called if nk_group_begin returned non-zero
nk_group_get_scroll | Gets the scroll offset for the given group
nk_group_set_scroll | Sets the scroll offset for the given group
#### nk_group_begin
Starts a new widget group. Requires a previous layouting function to specify a pos/size.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_group_begin(struct nk_context*, const char *title, nk_flags);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__title__ | Must be an unique identifier for this group that is also used for the group header
__flags__ | Window flags defined in the nk_panel_flags section with a number of different group behaviors
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_group_begin_titled
Starts a new widget group. Requires a previous layouting function to specify a pos/size.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_group_begin_titled(struct nk_context*, const char *name, const char *title, nk_flags);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__id__ | Must be an unique identifier for this group
__title__ | Group header title
__flags__ | Window flags defined in the nk_panel_flags section with a number of different group behaviors
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_group_end
Ends a widget group
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_group_end(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
#### nk_group_scrolled_offset_begin
starts a new widget group. requires a previous layouting function to specify
a size. Does not keep track of scrollbar.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_group_scrolled_offset_begin(struct nk_context*, nk_uint *x_offset, nk_uint *y_offset, const char *title, nk_flags flags);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__x_offset__| Scrollbar x-offset to offset all widgets inside the group horizontally.
__y_offset__| Scrollbar y-offset to offset all widgets inside the group vertically
__title__ | Window unique group title used to both identify and display in the group header
__flags__ | Window flags from the nk_panel_flags section
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_group_scrolled_begin
Starts a new widget group. requires a previous
layouting function to specify a size. Does not keep track of scrollbar.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_group_scrolled_begin(struct nk_context*, struct nk_scroll *off, const char *title, nk_flags);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__off__ | Both x- and y- scroll offset. Allows for manual scrollbar control
__title__ | Window unique group title used to both identify and display in the group header
__flags__ | Window flags from nk_panel_flags section
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_group_scrolled_end
Ends a widget group after calling nk_group_scrolled_offset_begin or nk_group_scrolled_begin.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_group_scrolled_end(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
#### nk_group_get_scroll
Gets the scroll position of the given group.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_group_get_scroll(struct nk_context*, const char *id, nk_uint *x_offset, nk_uint *y_offset);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
-------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__id__ | The id of the group to get the scroll position of
__x_offset__ | A pointer to the x offset output (or NULL to ignore)
__y_offset__ | A pointer to the y offset output (or NULL to ignore)
#### nk_group_set_scroll
Sets the scroll position of the given group.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_group_set_scroll(struct nk_context*, const char *id, nk_uint x_offset, nk_uint y_offset);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
-------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__id__ | The id of the group to scroll
__x_offset__ | The x offset to scroll to
__y_offset__ | The y offset to scroll to
### Tree
Trees represent two different concept. First the concept of a collapsible
UI section that can be either in a hidden or visible state. They allow the UI
user to selectively minimize the current set of visible UI to comprehend.
The second concept are tree widgets for visual UI representation of trees.<br /><br />
Trees thereby can be nested for tree representations and multiple nested
collapsible UI sections. All trees are started by calling of the
`nk_tree_xxx_push_tree` functions and ended by calling one of the
`nk_tree_xxx_pop_xxx()` functions. Each starting functions takes a title label
and optionally an image to be displayed and the initial collapse state from
the nk_collapse_states section.<br /><br />
The runtime state of the tree is either stored outside the library by the caller
or inside which requires a unique ID. The unique ID can either be generated
automatically from `__FILE__` and `__LINE__` with function `nk_tree_push`,
by `__FILE__` and a user provided ID generated for example by loop index with
function `nk_tree_push_id` or completely provided from outside by user with
function `nk_tree_push_hashed`.
#### Usage
To create a tree you have to call one of the seven `nk_tree_xxx_push_xxx`
functions to start a collapsible UI section and `nk_tree_xxx_pop` to mark the
end.
Each starting function will either return `false(0)` if the tree is collapsed
or hidden and therefore does not need to be filled with content or `true(1)`
if visible and required to be filled.
!!! Note
The tree header does not require and layouting function and instead
calculates a auto height based on the currently used font size
The tree ending functions only need to be called if the tree content is
actually visible. So make sure the tree push function is guarded by `if`
and the pop call is only taken if the tree is visible.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
if (nk_tree_push(ctx, NK_TREE_TAB, "Tree", NK_MINIMIZED)) {
nk_layout_row_dynamic(...);
nk_widget(...);
nk_tree_pop(ctx);
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### Reference
Function | Description
----------------------------|-------------------------------------------
nk_tree_push | Start a collapsible UI section with internal state management
nk_tree_push_id | Start a collapsible UI section with internal state management callable in a look
nk_tree_push_hashed | Start a collapsible UI section with internal state management with full control over internal unique ID use to store state
nk_tree_image_push | Start a collapsible UI section with image and label header
nk_tree_image_push_id | Start a collapsible UI section with image and label header and internal state management callable in a look
nk_tree_image_push_hashed | Start a collapsible UI section with image and label header and internal state management with full control over internal unique ID use to store state
nk_tree_pop | Ends a collapsible UI section
nk_tree_state_push | Start a collapsible UI section with external state management
nk_tree_state_image_push | Start a collapsible UI section with image and label header and external state management
nk_tree_state_pop | Ends a collapsabale UI section
#### nk_tree_type
Flag | Description
----------------|----------------------------------------
NK_TREE_NODE | Highlighted tree header to mark a collapsible UI section
NK_TREE_TAB | Non-highlighted tree header closer to tree representations
#### nk_tree_push
Starts a collapsible UI section with internal state management
!!! WARNING
To keep track of the runtime tree collapsible state this function uses
defines `__FILE__` and `__LINE__` to generate a unique ID. If you want
to call this function in a loop please use `nk_tree_push_id` or
`nk_tree_push_hashed` instead.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
#define nk_tree_push(ctx, type, title, state)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__type__ | Value from the nk_tree_type section to visually mark a tree node header as either a collapseable UI section or tree node
__title__ | Label printed in the tree header
__state__ | Initial tree state value out of nk_collapse_states
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_tree_push_id
Starts a collapsible UI section with internal state management callable in a look
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
#define nk_tree_push_id(ctx, type, title, state, id)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__type__ | Value from the nk_tree_type section to visually mark a tree node header as either a collapseable UI section or tree node
__title__ | Label printed in the tree header
__state__ | Initial tree state value out of nk_collapse_states
__id__ | Loop counter index if this function is called in a loop
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_tree_push_hashed
Start a collapsible UI section with internal state management with full
control over internal unique ID used to store state
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_tree_push_hashed(struct nk_context*, enum nk_tree_type, const char *title, enum nk_collapse_states initial_state, const char *hash, int len,int seed);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__type__ | Value from the nk_tree_type section to visually mark a tree node header as either a collapseable UI section or tree node
__title__ | Label printed in the tree header
__state__ | Initial tree state value out of nk_collapse_states
__hash__ | Memory block or string to generate the ID from
__len__ | Size of passed memory block or string in __hash__
__seed__ | Seeding value if this function is called in a loop or default to `0`
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_tree_image_push
Start a collapsible UI section with image and label header
!!! WARNING
To keep track of the runtime tree collapsible state this function uses
defines `__FILE__` and `__LINE__` to generate a unique ID. If you want
to call this function in a loop please use `nk_tree_image_push_id` or
`nk_tree_image_push_hashed` instead.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
#define nk_tree_image_push(ctx, type, img, title, state)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__type__ | Value from the nk_tree_type section to visually mark a tree node header as either a collapseable UI section or tree node
__img__ | Image to display inside the header on the left of the label
__title__ | Label printed in the tree header
__state__ | Initial tree state value out of nk_collapse_states
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_tree_image_push_id
Start a collapsible UI section with image and label header and internal state
management callable in a look
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
#define nk_tree_image_push_id(ctx, type, img, title, state, id)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__type__ | Value from the nk_tree_type section to visually mark a tree node header as either a collapseable UI section or tree node
__img__ | Image to display inside the header on the left of the label
__title__ | Label printed in the tree header
__state__ | Initial tree state value out of nk_collapse_states
__id__ | Loop counter index if this function is called in a loop
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_tree_image_push_hashed
Start a collapsible UI section with internal state management with full
control over internal unique ID used to store state
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_tree_image_push_hashed(struct nk_context*, enum nk_tree_type, struct nk_image, const char *title, enum nk_collapse_states initial_state, const char *hash, int len,int seed);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct
__type__ | Value from the nk_tree_type section to visually mark a tree node header as either a collapseable UI section or tree node
__img__ | Image to display inside the header on the left of the label
__title__ | Label printed in the tree header
__state__ | Initial tree state value out of nk_collapse_states
__hash__ | Memory block or string to generate the ID from
__len__ | Size of passed memory block or string in __hash__
__seed__ | Seeding value if this function is called in a loop or default to `0`
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_tree_pop
Ends a collapsabale UI section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_tree_pop(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling `nk_tree_xxx_push_xxx`
#### nk_tree_state_push
Start a collapsible UI section with external state management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_tree_state_push(struct nk_context*, enum nk_tree_type, const char *title, enum nk_collapse_states *state);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling `nk_tree_xxx_push_xxx`
__type__ | Value from the nk_tree_type section to visually mark a tree node header as either a collapseable UI section or tree node
__title__ | Label printed in the tree header
__state__ | Persistent state to update
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_tree_state_image_push
Start a collapsible UI section with image and label header and external state management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
nk_bool nk_tree_state_image_push(struct nk_context*, enum nk_tree_type, struct nk_image, const char *title, enum nk_collapse_states *state);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling `nk_tree_xxx_push_xxx`
__img__ | Image to display inside the header on the left of the label
__type__ | Value from the nk_tree_type section to visually mark a tree node header as either a collapseable UI section or tree node
__title__ | Label printed in the tree header
__state__ | Persistent state to update
Returns `true(1)` if visible and fillable with widgets or `false(0)` otherwise
#### nk_tree_state_pop
Ends a collapsabale UI section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_tree_state_pop(struct nk_context*);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling `nk_tree_xxx_push_xxx`
### Properties
Properties are the main value modification widgets in Nuklear. Changing a value
can be achieved by dragging, adding/removing incremental steps on button click
or by directly typing a number.
#### Usage
Each property requires a unique name for identification that is also used for
displaying a label. If you want to use the same name multiple times make sure
add a '#' before your name. The '#' will not be shown but will generate a
unique ID. Each property also takes in a minimum and maximum value. If you want
to make use of the complete number range of a type just use the provided
type limits from `limits.h`. For example `INT_MIN` and `INT_MAX` for
`nk_property_int` and `nk_propertyi`. In additional each property takes in
a increment value that will be added or subtracted if either the increment
decrement button is clicked. Finally there is a value for increment per pixel
dragged that is added or subtracted from the value.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
int value = 0;
struct nk_context ctx;
nk_init_xxx(&ctx, ...);
while (1) {
// Input
Event evt;
nk_input_begin(&ctx);
while (GetEvent(&evt)) {
if (evt.type == MOUSE_MOVE)
nk_input_motion(&ctx, evt.motion.x, evt.motion.y);
else if (evt.type == [...]) {
nk_input_xxx(...);
}
}
nk_input_end(&ctx);
//
// Window
if (nk_begin_xxx(...) {
// Property
nk_layout_row_dynamic(...);
nk_property_int(ctx, "ID", INT_MIN, &value, INT_MAX, 1, 1);
}
nk_end(ctx);
//
// Draw
const struct nk_command *cmd = 0;
nk_foreach(cmd, &ctx) {
switch (cmd->type) {
case NK_COMMAND_LINE:
your_draw_line_function(...)
break;
case NK_COMMAND_RECT
your_draw_rect_function(...)
break;
case ...:
// [...]
}
nk_clear(&ctx);
}
nk_free(&ctx);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### Reference
Function | Description
--------------------|-------------------------------------------
nk_property_int | Integer property directly modifying a passed in value
nk_property_float | Float property directly modifying a passed in value
nk_property_double | Double property directly modifying a passed in value
nk_propertyi | Integer property returning the modified int value
nk_propertyf | Float property returning the modified float value
nk_propertyd | Double property returning the modified double value
#### nk_property_int
Integer property directly modifying a passed in value
!!! WARNING
To generate a unique property ID using the same label make sure to insert
a `#` at the beginning. It will not be shown but guarantees correct behavior.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_property_int(struct nk_context *ctx, const char *name, int min, int *val, int max, int step, float inc_per_pixel);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
--------------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling a layouting function
__name__ | String used both as a label as well as a unique identifier
__min__ | Minimum value not allowed to be underflown
__val__ | Integer pointer to be modified
__max__ | Maximum value not allowed to be overflown
__step__ | Increment added and subtracted on increment and decrement button
__inc_per_pixel__ | Value per pixel added or subtracted on dragging
#### nk_property_float
Float property directly modifying a passed in value
!!! WARNING
To generate a unique property ID using the same label make sure to insert
a `#` at the beginning. It will not be shown but guarantees correct behavior.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_property_float(struct nk_context *ctx, const char *name, float min, float *val, float max, float step, float inc_per_pixel);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
--------------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling a layouting function
__name__ | String used both as a label as well as a unique identifier
__min__ | Minimum value not allowed to be underflown
__val__ | Float pointer to be modified
__max__ | Maximum value not allowed to be overflown
__step__ | Increment added and subtracted on increment and decrement button
__inc_per_pixel__ | Value per pixel added or subtracted on dragging
#### nk_property_double
Double property directly modifying a passed in value
!!! WARNING
To generate a unique property ID using the same label make sure to insert
a `#` at the beginning. It will not be shown but guarantees correct behavior.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
void nk_property_double(struct nk_context *ctx, const char *name, double min, double *val, double max, double step, double inc_per_pixel);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
--------------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling a layouting function
__name__ | String used both as a label as well as a unique identifier
__min__ | Minimum value not allowed to be underflown
__val__ | Double pointer to be modified
__max__ | Maximum value not allowed to be overflown
__step__ | Increment added and subtracted on increment and decrement button
__inc_per_pixel__ | Value per pixel added or subtracted on dragging
#### nk_propertyi
Integer property modifying a passed in value and returning the new value
!!! WARNING
To generate a unique property ID using the same label make sure to insert
a `#` at the beginning. It will not be shown but guarantees correct behavior.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
int nk_propertyi(struct nk_context *ctx, const char *name, int min, int val, int max, int step, float inc_per_pixel);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
--------------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling a layouting function
__name__ | String used both as a label as well as a unique identifier
__min__ | Minimum value not allowed to be underflown
__val__ | Current integer value to be modified and returned
__max__ | Maximum value not allowed to be overflown
__step__ | Increment added and subtracted on increment and decrement button
__inc_per_pixel__ | Value per pixel added or subtracted on dragging
Returns the new modified integer value
#### nk_propertyf
Float property modifying a passed in value and returning the new value
!!! WARNING
To generate a unique property ID using the same label make sure to insert
a `#` at the beginning. It will not be shown but guarantees correct behavior.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
float nk_propertyf(struct nk_context *ctx, const char *name, float min, float val, float max, float step, float inc_per_pixel);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
--------------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling a layouting function
__name__ | String used both as a label as well as a unique identifier
__min__ | Minimum value not allowed to be underflown
__val__ | Current float value to be modified and returned
__max__ | Maximum value not allowed to be overflown
__step__ | Increment added and subtracted on increment and decrement button
__inc_per_pixel__ | Value per pixel added or subtracted on dragging
Returns the new modified float value
#### nk_propertyd
Float property modifying a passed in value and returning the new value
!!! WARNING
To generate a unique property ID using the same label make sure to insert
a `#` at the beginning. It will not be shown but guarantees correct behavior.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
float nk_propertyd(struct nk_context *ctx, const char *name, double min, double val, double max, double step, double inc_per_pixel);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter | Description
--------------------|-----------------------------------------------------------
__ctx__ | Must point to an previously initialized `nk_context` struct after calling a layouting function
__name__ | String used both as a label as well as a unique identifier
__min__ | Minimum value not allowed to be underflown
__val__ | Current double value to be modified and returned
__max__ | Maximum value not allowed to be overflown
__step__ | Increment added and subtracted on increment and decrement button
__inc_per_pixel__ | Value per pixel added or subtracted on dragging
Returns the new modified double value
### Font
Font handling in this library was designed to be quite customizable and lets
you decide what you want to use and what you want to provide. There are three
different ways to use the font atlas. The first two will use your font
handling scheme and only requires essential data to run nuklear. The next
slightly more advanced features is font handling with vertex buffer output.
Finally the most complex API wise is using nuklear's font baking API.
#### Using your own implementation without vertex buffer output
So first up the easiest way to do font handling is by just providing a
`nk_user_font` struct which only requires the height in pixel of the used
font and a callback to calculate the width of a string. This way of handling
fonts is best fitted for using the normal draw shape command API where you
do all the text drawing yourself and the library does not require any kind
of deeper knowledge about which font handling mechanism you use.
IMPORTANT: the `nk_user_font` pointer provided to nuklear has to persist
over the complete life time! I know this sucks but it is currently the only
way to switch between fonts.
```c
float your_text_width_calculation(nk_handle handle, float height, const char *text, int len)
{
your_font_type *type = handle.ptr;
float text_width = ...;
return text_width;
}
struct nk_user_font font;
font.userdata.ptr = &your_font_class_or_struct;
font.height = your_font_height;
font.width = your_text_width_calculation;
struct nk_context ctx;
nk_init_default(&ctx, &font);
```
#### Using your own implementation with vertex buffer output
While the first approach works fine if you don't want to use the optional
vertex buffer output it is not enough if you do. To get font handling working
for these cases you have to provide two additional parameters inside the
`nk_user_font`. First a texture atlas handle used to draw text as subimages
of a bigger font atlas texture and a callback to query a character's glyph
information (offset, size, ...). So it is still possible to provide your own
font and use the vertex buffer output.
```c
float your_text_width_calculation(nk_handle handle, float height, const char *text, int len)
{
your_font_type *type = handle.ptr;
float text_width = ...;
return text_width;
}
void query_your_font_glyph(nk_handle handle, float font_height, struct nk_user_font_glyph *glyph, nk_rune codepoint, nk_rune next_codepoint)
{
your_font_type *type = handle.ptr;
glyph.width = ...;
glyph.height = ...;
glyph.xadvance = ...;
glyph.uv[0].x = ...;
glyph.uv[0].y = ...;
glyph.uv[1].x = ...;
glyph.uv[1].y = ...;
glyph.offset.x = ...;
glyph.offset.y = ...;
}
struct nk_user_font font;
font.userdata.ptr = &your_font_class_or_struct;
font.height = your_font_height;
font.width = your_text_width_calculation;
font.query = query_your_font_glyph;
font.texture.id = your_font_texture;
struct nk_context ctx;
nk_init_default(&ctx, &font);
```
#### Nuklear font baker
The final approach if you do not have a font handling functionality or don't
want to use it in this library is by using the optional font baker.
The font baker APIs can be used to create a font plus font atlas texture
and can be used with or without the vertex buffer output.
It still uses the `nk_user_font` struct and the two different approaches
previously stated still work. The font baker is not located inside
`nk_context` like all other systems since it can be understood as more of
an extension to nuklear and does not really depend on any `nk_context` state.
Font baker need to be initialized first by one of the nk_font_atlas_init_xxx
functions. If you don't care about memory just call the default version
`nk_font_atlas_init_default` which will allocate all memory from the standard library.
If you want to control memory allocation but you don't care if the allocated
memory is temporary and therefore can be freed directly after the baking process
is over or permanent you can call `nk_font_atlas_init`.
After successfully initializing the font baker you can add Truetype(.ttf) fonts from
different sources like memory or from file by calling one of the `nk_font_atlas_add_xxx`.
functions. Adding font will permanently store each font, font config and ttf memory block(!)
inside the font atlas and allows to reuse the font atlas. If you don't want to reuse
the font baker by for example adding additional fonts you can call
`nk_font_atlas_cleanup` after the baking process is over (after calling nk_font_atlas_end).
As soon as you added all fonts you wanted you can now start the baking process
for every selected glyph to image by calling `nk_font_atlas_bake`.
The baking process returns image memory, width and height which can be used to
either create your own image object or upload it to any graphics library.
No matter which case you finally have to call `nk_font_atlas_end` which
will free all temporary memory including the font atlas image so make sure
you created our texture beforehand. `nk_font_atlas_end` requires a handle
to your font texture or object and optionally fills a `struct nk_draw_null_texture`
which can be used for the optional vertex output. If you don't want it just
set the argument to `NULL`.
At this point you are done and if you don't want to reuse the font atlas you
can call `nk_font_atlas_cleanup` to free all truetype blobs and configuration
memory. Finally if you don't use the font atlas and any of it's fonts anymore
you need to call `nk_font_atlas_clear` to free all memory still being used.
```c
struct nk_font_atlas atlas;
nk_font_atlas_init_default(&atlas);
nk_font_atlas_begin(&atlas);
nk_font *font = nk_font_atlas_add_from_file(&atlas, "Path/To/Your/TTF_Font.ttf", 13, 0);
nk_font *font2 = nk_font_atlas_add_from_file(&atlas, "Path/To/Your/TTF_Font2.ttf", 16, 0);
const void* img = nk_font_atlas_bake(&atlas, &img_width, &img_height, NK_FONT_ATLAS_RGBA32);
nk_font_atlas_end(&atlas, nk_handle_id(texture), 0);
struct nk_context ctx;
nk_init_default(&ctx, &font->handle);
while (1) {
}
nk_font_atlas_clear(&atlas);
```
The font baker API is probably the most complex API inside this library and
I would suggest reading some of my examples `example/` to get a grip on how
to use the font atlas. There are a number of details I left out. For example
how to merge fonts, configure a font with `nk_font_config` to use other languages,
use another texture coordinate format and a lot more:
```c
struct nk_font_config cfg = nk_font_config(font_pixel_height);
cfg.merge_mode = nk_false or nk_true;
cfg.range = nk_font_korean_glyph_ranges();
cfg.coord_type = NK_COORD_PIXEL;
nk_font *font = nk_font_atlas_add_from_file(&atlas, "Path/To/Your/TTF_Font.ttf", 13, &cfg);
```
### Memory Buffer
A basic (double)-buffer with linear allocation and resetting as only
freeing policy. The buffer's main purpose is to control all memory management
inside the GUI toolkit and still leave memory control as much as possible in
the hand of the user while also making sure the library is easy to use if
not as much control is needed.
In general all memory inside this library can be provided from the user in
three different ways.
The first way and the one providing most control is by just passing a fixed
size memory block. In this case all control lies in the hand of the user
since he can exactly control where the memory comes from and how much memory
the library should consume. Of course using the fixed size API removes the
ability to automatically resize a buffer if not enough memory is provided so
you have to take over the resizing. While being a fixed sized buffer sounds
quite limiting, it is very effective in this library since the actual memory
consumption is quite stable and has a fixed upper bound for a lot of cases.
If you don't want to think about how much memory the library should allocate
at all time or have a very dynamic UI with unpredictable memory consumption
habits but still want control over memory allocation you can use the dynamic
allocator based API. The allocator consists of two callbacks for allocating
and freeing memory and optional userdata so you can plugin your own allocator.
The final and easiest way can be used by defining
NK_INCLUDE_DEFAULT_ALLOCATOR which uses the standard library memory
allocation functions malloc and free and takes over complete control over
memory in this library.
### Text Editor
Editing text in this library is handled by either `nk_edit_string` or
`nk_edit_buffer`. But like almost everything in this library there are multiple
ways of doing it and a balance between control and ease of use with memory
as well as functionality controlled by flags.
This library generally allows three different levels of memory control:
First of is the most basic way of just providing a simple char array with
string length. This method is probably the easiest way of handling simple
user text input. Main upside is complete control over memory while the biggest
downside in comparison with the other two approaches is missing undo/redo.
For UIs that require undo/redo the second way was created. It is based on
a fixed size nk_text_edit struct, which has an internal undo/redo stack.
This is mainly useful if you want something more like a text editor but don't want
to have a dynamically growing buffer.
The final way is using a dynamically growing nk_text_edit struct, which
has both a default version if you don't care where memory comes from and an
allocator version if you do. While the text editor is quite powerful for its
complexity I would not recommend editing gigabytes of data with it.
It is rather designed for uses cases which make sense for a GUI library not for
an full blown text editor.
### Drawing
This library was designed to be render backend agnostic so it does
not draw anything to screen. Instead all drawn shapes, widgets
are made of, are buffered into memory and make up a command queue.
Each frame therefore fills the command buffer with draw commands
that then need to be executed by the user and his own render backend.
After that the command buffer needs to be cleared and a new frame can be
started. It is probably important to note that the command buffer is the main
drawing API and the optional vertex buffer API only takes this format and
converts it into a hardware accessible format.
To use the command queue to draw your own widgets you can access the
command buffer of each window by calling `nk_window_get_canvas` after
previously having called `nk_begin`:
```c
void draw_red_rectangle_widget(struct nk_context *ctx)
{
struct nk_command_buffer *canvas;
struct nk_input *input = &ctx->input;
canvas = nk_window_get_canvas(ctx);
struct nk_rect space;
enum nk_widget_layout_states state;
state = nk_widget(&space, ctx);
if (!state) return;
if (state != NK_WIDGET_ROM)
update_your_widget_by_user_input(...);
nk_fill_rect(canvas, space, 0, nk_rgb(255,0,0));
}
if (nk_begin(...)) {
nk_layout_row_dynamic(ctx, 25, 1);
draw_red_rectangle_widget(ctx);
}
nk_end(..)
```
Important to know if you want to create your own widgets is the `nk_widget`
call. It allocates space on the panel reserved for this widget to be used,
but also returns the state of the widget space. If your widget is not seen and does
not have to be updated it is '0' and you can just return. If it only has
to be drawn the state will be `NK_WIDGET_ROM` otherwise you can do both
update and draw your widget. The reason for separating is to only draw and
update what is actually necessary which is crucial for performance.
Draw List
The optional vertex buffer draw list provides a 2D drawing context
with antialiasing functionality which takes basic filled or outlined shapes
or a path and outputs vertexes, elements and draw commands.
The actual draw list API is not required to be used directly while using this
library since converting the default library draw command output is done by
just calling `nk_convert` but I decided to still make this library accessible
since it can be useful.
The draw list is based on a path buffering and polygon and polyline
rendering API which allows a lot of ways to draw 2D content to screen.
In fact it is probably more powerful than needed but allows even more crazy
things than this library provides by default.
### Stack
The style modifier stack can be used to temporarily change a
property inside `nk_style`. For example if you want a special
red button you can temporarily push the old button color onto a stack
draw the button with a red color and then you just pop the old color
back from the stack:
nk_style_push_style_item(ctx, &ctx->style.button.normal, nk_style_item_color(nk_rgb(255,0,0)));
nk_style_push_style_item(ctx, &ctx->style.button.hover, nk_style_item_color(nk_rgb(255,0,0)));
nk_style_push_style_item(ctx, &ctx->style.button.active, nk_style_item_color(nk_rgb(255,0,0)));
nk_style_push_vec2(ctx, &cx->style.button.padding, nk_vec2(2,2));
nk_button(...);
nk_style_pop_style_item(ctx);
nk_style_pop_style_item(ctx);
nk_style_pop_style_item(ctx);
nk_style_pop_vec2(ctx);
Nuklear has a stack for style_items, float properties, vector properties,
flags, colors, fonts and for button_behavior. Each has it's own fixed size stack
which can be changed at compile time.
### Math
Since nuklear is supposed to work on all systems providing floating point
math without any dependencies I also had to implement my own math functions
for sqrt, sin and cos. Since the actual highly accurate implementations for
the standard library functions are quite complex and I do not need high
precision for my use cases I use approximations.
Sqrt
----
For square root nuklear uses the famous fast inverse square root:
https://en.wikipedia.org/wiki/Fast_inverse_square_root with
slightly tweaked magic constant. While on today's hardware it is
probably not faster it is still fast and accurate enough for
nuklear's use cases. IMPORTANT: this requires float format IEEE 754
Sine/Cosine
-----------
All constants inside both function are generated Remez's minimax
approximations for value range 0...2*PI. The reason why I decided to
approximate exactly that range is that nuklear only needs sine and
cosine to generate circles which only requires that exact range.
In addition I used Remez instead of Taylor for additional precision:
www.lolengine.net/blog/2011/12/21/better-function-approximations.
The tool I used to generate constants for both sine and cosine
(it can actually approximate a lot more functions) can be
found here: www.lolengine.net/wiki/oss/lolremez
-XXX.XXX- X...X - X...X -X....X - X....X"
X...XXXXXXXXXXXXX...X - "
## License
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~none
------------------------------------------------------------------------------
This software is available under 2 licenses -- choose whichever you prefer.
------------------------------------------------------------------------------
ALTERNATIVE A - MIT License
Copyright (c) 2016-2018 Micha Mettke
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
------------------------------------------------------------------------------
ALTERNATIVE B - Public Domain (www.unlicense.org)
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
software, either in source code form or as a compiled binary, for any purpose,
commercial or non-commercial, and by any means.
In jurisdictions that recognize copyright laws, the author or authors of this
software dedicate any and all copyright interest in the software to the public
domain. We make this dedication for the benefit of the public at large and to
the detriment of our heirs and successors. We intend this dedication to be an
overt act of relinquishment in perpetuity of all present and future rights to
this software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
------------------------------------------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Changelog
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~none
[date] ([x.y.z]) - [description]
- [date]: date on which the change has been pushed
- [x.y.z]: Version string, represented in Semantic Versioning format
- [x]: Major version with API and library breaking changes
- [y]: Minor version with non-breaking API and library changes
- [z]: Patch version with no direct changes to the API
- 2022/12/17 (4.10.5) - Fix nk_font_bake_pack() using TTC font offset incorrectly
- 2022/10/24 (4.10.4) - Fix nk_str_{append,insert}_str_utf8 always returning 0
- 2022/09/03 (4.10.3) - Renamed the `null` texture variable to `tex_null`
- 2022/08/01 (4.10.2) - Fix Apple Silicon with incorrect NK_SITE_TYPE and NK_POINTER_TYPE
- 2022/08/01 (4.10.1) - Fix cursor jumping back to beginning of text when typing more than
nk_edit_xxx limit
- 2022/05/27 (4.10.0) - Add nk_input_has_mouse_click_in_button_rect() to fix window move bug
- 2022/04/18 (4.9.7) - Change button behavior when NK_BUTTON_TRIGGER_ON_RELEASE is defined to
only trigger when the mouse position was inside the same button on down
- 2022/02/03 (4.9.6) - Allow overriding the NK_INV_SQRT function, similar to NK_SIN and NK_COS
- 2021/12/22 (4.9.5) - Revert layout bounds not accounting for padding due to regressions
- 2021/12/22 (4.9.4) - Fix checking hovering when window is minimized
- 2021/12/22 (4.09.3) - Fix layout bounds not accounting for padding
- 2021/12/19 (4.09.2) - Update to stb_rect_pack.h v1.01 and stb_truetype.h v1.26
- 2021/12/16 (4.09.1) - Fix the majority of GCC warnings
- 2021/10/16 (4.09.0) - Added nk_spacer() widget
- 2021/09/22 (4.08.6) - Fix "may be used uninitialized" warnings in nk_widget
- 2021/09/22 (4.08.5) - GCC __builtin_offsetof only exists in version 4 and later
- 2021/09/15 (4.08.4) - Fix "'num_len' may be used uninitialized" in nk_do_property
- 2021/09/15 (4.08.3) - Fix "Templates cannot be declared to have 'C' Linkage"
- 2021/09/08 (4.08.2) - Fix warnings in C89 builds
- 2021/09/08 (4.08.1) - Use compiler builtins for NK_OFFSETOF when possible
- 2021/08/17 (4.08.0) - Implemented 9-slice scaling support for widget styles
- 2021/08/16 (4.07.5) - Replace usage of memset in nk_font_atlas_bake with NK_MEMSET
- 2021/08/15 (4.07.4) - Fix conversion and sign conversion warnings
- 2021/08/08 (4.07.3) - Fix crash when baking merged fonts
- 2021/08/08 (4.07.2) - Fix Multiline Edit wrong offset
- 2021/03/17 (4.07.1) - Fix warning about unused parameter
- 2021/03/17 (4.07.0) - Fix nk_property hover bug
- 2021/03/15 (4.06.4) - Change nk_propertyi back to int
- 2021/03/15 (4.06.3) - Update documentation for functions that now return nk_bool
- 2020/12/19 (4.06.2) - Fix additional C++ style comments which are not allowed in ISO C90.
- 2020/10/11 (4.06.1) - Fix C++ style comments which are not allowed in ISO C90.
- 2020/10/07 (4.06.0) - Fix nk_combo return type wrongly changed to nk_bool
- 2020/09/05 (4.05.0) - Use the nk_font_atlas allocator for stb_truetype memory management.
- 2020/09/04 (4.04.1) - Replace every boolean int by nk_bool
- 2020/09/04 (4.04.0) - Add nk_bool with NK_INCLUDE_STANDARD_BOOL
- 2020/06/13 (4.03.1) - Fix nk_pool allocation sizes.
- 2020/06/04 (4.03.0) - Made nk_combo header symbols optional.
- 2020/05/27 (4.02.5) - Fix nk_do_edit: Keep scroll position when re-activating edit widget.
- 2020/05/09 (4.02.4) - Fix nk_menubar height calculation bug
- 2020/05/08 (4.02.3) - Fix missing stdarg.h with NK_INCLUDE_STANDARD_VARARGS
- 2020/04/30 (4.02.2) - Fix nk_edit border drawing bug
- 2020/04/09 (4.02.1) - Removed unused nk_sqrt function to fix compiler warnings
- Fixed compiler warnings if you bring your own methods for
nk_cos/nk_sin/nk_strtod/nk_memset/nk_memcopy/nk_dtoa
- 2020/04/06 (4.01.10) - Fix bug: Do not use pool before checking for NULL
- 2020/03/22 (4.01.9) - Fix bug where layout state wasn't restored correctly after
popping a tree.
- 2020/03/11 (4.01.8) - Fix bug where padding is subtracted from widget
- 2020/03/06 (4.01.7) - Fix bug where width padding was applied twice
- 2020/02/06 (4.01.6) - Update stb_truetype.h and stb_rect_pack.h and separate them
- 2019/12/10 (4.01.5) - Fix off-by-one error in NK_INTERSECT
- 2019/10/09 (4.01.4) - Fix bug for autoscrolling in nk_do_edit
- 2019/09/20 (4.01.3) - Fixed a bug wherein combobox cannot be closed by clicking the header
when NK_BUTTON_TRIGGER_ON_RELEASE is defined.
- 2019/09/10 (4.01.2) - Fixed the nk_cos function, which deviated significantly.
- 2019/09/08 (4.01.1) - Fixed a bug wherein re-baking of fonts caused a segmentation
fault due to dst_font->glyph_count not being zeroed on subsequent
bakes of the same set of fonts.
- 2019/06/23 (4.01.0) - Added nk_***_get_scroll and nk_***_set_scroll for groups, windows, and popups.
- 2019/06/12 (4.00.3) - Fix panel background drawing bug.
- 2018/10/31 (4.00.2) - Added NK_KEYSTATE_BASED_INPUT to "fix" state based backends
like GLFW without breaking key repeat behavior on event based.
- 2018/04/01 (4.00.1) - Fixed calling `nk_convert` multiple time per single frame.
- 2018/04/01 (4.00.0) - BREAKING CHANGE: nk_draw_list_clear no longer tries to
clear provided buffers. So make sure to either free
or clear each passed buffer after calling nk_convert.
- 2018/02/23 (3.00.6) - Fixed slider dragging behavior.
- 2018/01/31 (3.00.5) - Fixed overcalculation of cursor data in font baking process.
- 2018/01/31 (3.00.4) - Removed name collision with stb_truetype.
- 2018/01/28 (3.00.3) - Fixed panel window border drawing bug.
- 2018/01/12 (3.00.2) - Added `nk_group_begin_titled` for separated group identifier and title.
- 2018/01/07 (3.00.1) - Started to change documentation style.
- 2018/01/05 (3.00.0) - BREAKING CHANGE: The previous color picker API was broken
because of conversions between float and byte color representation.
Color pickers now use floating point values to represent
HSV values. To get back the old behavior I added some additional
color conversion functions to cast between nk_color and
nk_colorf.
- 2017/12/23 (2.00.7) - Fixed small warning.
- 2017/12/23 (2.00.7) - Fixed `nk_edit_buffer` behavior if activated to allow input.
- 2017/12/23 (2.00.7) - Fixed modifyable progressbar dragging visuals and input behavior.
- 2017/12/04 (2.00.6) - Added formatted string tooltip widget.
- 2017/11/18 (2.00.5) - Fixed window becoming hidden with flag `NK_WINDOW_NO_INPUT`.
- 2017/11/15 (2.00.4) - Fixed font merging.
- 2017/11/07 (2.00.3) - Fixed window size and position modifier functions.
- 2017/09/14 (2.00.2) - Fixed `nk_edit_buffer` and `nk_edit_focus` behavior.
- 2017/09/14 (2.00.1) - Fixed window closing behavior.
- 2017/09/14 (2.00.0) - BREAKING CHANGE: Modifying window position and size functions now
require the name of the window and must happen outside the window
building process (between function call nk_begin and nk_end).
- 2017/09/11 (1.40.9) - Fixed window background flag if background window is declared last.
- 2017/08/27 (1.40.8) - Fixed `nk_item_is_any_active` for hidden windows.
- 2017/08/27 (1.40.7) - Fixed window background flag.
- 2017/07/07 (1.40.6) - Fixed missing clipping rect check for hovering/clicked
query for widgets.
- 2017/07/07 (1.40.5) - Fixed drawing bug for vertex output for lines and stroked
and filled rectangles.
- 2017/07/07 (1.40.4) - Fixed bug in nk_convert trying to add windows that are in
process of being destroyed.
- 2017/07/07 (1.40.3) - Fixed table internal bug caused by storing table size in
window instead of directly in table.
- 2017/06/30 (1.40.2) - Removed unneeded semicolon in C++ NK_ALIGNOF macro.
- 2017/06/30 (1.40.1) - Fixed drawing lines smaller or equal zero.
- 2017/06/08 (1.40.0) - Removed the breaking part of last commit. Auto layout now only
comes in effect if you pass in zero was row height argument.
- 2017/06/08 (1.40.0) - BREAKING CHANGE: while not directly API breaking it will change
how layouting works. From now there will be an internal minimum
row height derived from font height. If you need a row smaller than
that you can directly set it by `nk_layout_set_min_row_height` and
reset the value back by calling `nk_layout_reset_min_row_height.
- 2017/06/08 (1.39.1) - Fixed property text edit handling bug caused by past `nk_widget` fix.
- 2017/06/08 (1.39.0) - Added function to retrieve window space without calling a `nk_layout_xxx` function.
- 2017/06/06 (1.38.5) - Fixed `nk_convert` return flag for command buffer.
- 2017/05/23 (1.38.4) - Fixed activation behavior for widgets partially clipped.
- 2017/05/10 (1.38.3) - Fixed wrong min window size mouse scaling over boundaries.
- 2017/05/09 (1.38.2) - Fixed vertical scrollbar drawing with not enough space.
- 2017/05/09 (1.38.1) - Fixed scaler dragging behavior if window size hits minimum size.
- 2017/05/06 (1.38.0) - Added platform double-click support.
- 2017/04/20 (1.37.1) - Fixed key repeat found inside glfw demo backends.
- 2017/04/20 (1.37.0) - Extended properties with selection and clipboard support.
- 2017/04/20 (1.36.2) - Fixed #405 overlapping rows with zero padding and spacing.
- 2017/04/09 (1.36.1) - Fixed #403 with another widget float error.
- 2017/04/09 (1.36.0) - Added window `NK_WINDOW_NO_INPUT` and `NK_WINDOW_NOT_INTERACTIVE` flags.
- 2017/04/09 (1.35.3) - Fixed buffer heap corruption.
- 2017/03/25 (1.35.2) - Fixed popup overlapping for `NK_WINDOW_BACKGROUND` windows.
- 2017/03/25 (1.35.1) - Fixed windows closing behavior.
- 2017/03/18 (1.35.0) - Added horizontal scroll requested in #377.
- 2017/03/18 (1.34.3) - Fixed long window header titles.
- 2017/03/04 (1.34.2) - Fixed text edit filtering.
- 2017/03/04 (1.34.1) - Fixed group closable flag.
- 2017/02/25 (1.34.0) - Added custom draw command for better language binding support.
- 2017/01/24 (1.33.0) - Added programmatic way to remove edit focus.
- 2017/01/24 (1.32.3) - Fixed wrong define for basic type definitions for windows.
- 2017/01/21 (1.32.2) - Fixed input capture from hidden or closed windows.
- 2017/01/21 (1.32.1) - Fixed slider behavior and drawing.
- 2017/01/13 (1.32.0) - Added flag to put scaler into the bottom left corner.
- 2017/01/13 (1.31.0) - Added additional row layouting method to combine both
dynamic and static widgets.
- 2016/12/31 (1.30.0) - Extended scrollbar offset from 16-bit to 32-bit.
- 2016/12/31 (1.29.2) - Fixed closing window bug of minimized windows.
- 2016/12/03 (1.29.1) - Fixed wrapped text with no separator and C89 error.
- 2016/12/03 (1.29.0) - Changed text wrapping to process words not characters.
- 2016/11/22 (1.28.6) - Fixed window minimized closing bug.
- 2016/11/19 (1.28.5) - Fixed abstract combo box closing behavior.
- 2016/11/19 (1.28.4) - Fixed tooltip flickering.
- 2016/11/19 (1.28.3) - Fixed memory leak caused by popup repeated closing.
- 2016/11/18 (1.28.2) - Fixed memory leak caused by popup panel allocation.
- 2016/11/10 (1.28.1) - Fixed some warnings and C++ error.
- 2016/11/10 (1.28.0) - Added additional `nk_button` versions which allows to directly
pass in a style struct to change buttons visual.
- 2016/11/10 (1.27.0) - Added additional `nk_tree` versions to support external state
storage. Just like last the `nk_group` commit the main
advantage is that you optionally can minimize nuklears runtime
memory consumption or handle hash collisions.
- 2016/11/09 (1.26.0) - Added additional `nk_group` version to support external scrollbar
offset storage. Main advantage is that you can externalize
the memory management for the offset. It could also be helpful
if you have a hash collision in `nk_group_begin` but really
want the name. In addition I added `nk_list_view` which allows
to draw big lists inside a group without actually having to
commit the whole list to nuklear (issue #269).
- 2016/10/30 (1.25.1) - Fixed clipping rectangle bug inside `nk_draw_list`.
- 2016/10/29 (1.25.0) - Pulled `nk_panel` memory management into nuklear and out of
the hands of the user. From now on users don't have to care
about panels unless they care about some information. If you
still need the panel just call `nk_window_get_panel`.
- 2016/10/21 (1.24.0) - Changed widget border drawing to stroked rectangle from filled
rectangle for less overdraw and widget background transparency.
- 2016/10/18 (1.23.0) - Added `nk_edit_focus` for manually edit widget focus control.
- 2016/09/29 (1.22.7) - Fixed deduction of basic type in non `<stdint.h>` compilation.
- 2016/09/29 (1.22.6) - Fixed edit widget UTF-8 text cursor drawing bug.
- 2016/09/28 (1.22.5) - Fixed edit widget UTF-8 text appending/inserting/removing.
- 2016/09/28 (1.22.4) - Fixed drawing bug inside edit widgets which offset all text
text in every edit widget if one of them is scrolled.
- 2016/09/28 (1.22.3) - Fixed small bug in edit widgets if not active. The wrong
text length is passed. It should have been in bytes but
was passed as glyphs.
- 2016/09/20 (1.22.2) - Fixed color button size calculation.
- 2016/09/20 (1.22.1) - Fixed some `nk_vsnprintf` behavior bugs and removed `<stdio.h>`
again from `NK_INCLUDE_STANDARD_VARARGS`.
- 2016/09/18 (1.22.0) - C89 does not support vsnprintf only C99 and newer as well
as C++11 and newer. In addition to use vsnprintf you have
to include <stdio.h>. So just defining `NK_INCLUDE_STD_VAR_ARGS`
is not enough. That behavior is now fixed. By default if
both varargs as well as stdio is selected I try to use
vsnprintf if not possible I will revert to vsprintf. If
varargs but not stdio was defined I will use my own function.
- 2016/09/15 (1.21.2) - Fixed panel `close` behavior for deeper panel levels.
- 2016/09/15 (1.21.1) - Fixed C++ errors and wrong argument to `nk_panel_get_xxxx`.
- 2016/09/13 (1.21.0) - !BREAKING! Fixed nonblocking popup behavior in menu, combo,
and contextual which prevented closing in y-direction if
popup did not reach max height.
In addition the height parameter was changed into vec2
for width and height to have more control over the popup size.
- 2016/09/13 (1.20.3) - Cleaned up and extended type selection.
- 2016/09/13 (1.20.2) - Fixed slider behavior hopefully for the last time. This time
all calculation are correct so no more hackery.
- 2016/09/13 (1.20.1) - Internal change to divide window/panel flags into panel flags and types.
Suprisinly spend years in C and still happened to confuse types
with flags. Probably something to take note.
- 2016/09/08 (1.20.0) - Added additional helper function to make it easier to just
take the produced buffers from `nk_convert` and unplug the
iteration process from `nk_context`. So now you can
just use the vertex,element and command buffer + two pointer
inside the command buffer retrieved by calls `nk__draw_begin`
and `nk__draw_end` and macro `nk_draw_foreach_bounded`.
- 2016/09/08 (1.19.0) - Added additional asserts to make sure every `nk_xxx_begin` call
for windows, popups, combobox, menu and contextual is guarded by
`if` condition and does not produce false drawing output.
- 2016/09/08 (1.18.0) - Changed confusing name for `NK_SYMBOL_RECT_FILLED`, `NK_SYMBOL_RECT`
to hopefully easier to understand `NK_SYMBOL_RECT_FILLED` and
`NK_SYMBOL_RECT_OUTLINE`.
- 2016/09/08 (1.17.0) - Changed confusing name for `NK_SYMBOL_CIRLCE_FILLED`, `NK_SYMBOL_CIRCLE`
to hopefully easier to understand `NK_SYMBOL_CIRCLE_FILLED` and
`NK_SYMBOL_CIRCLE_OUTLINE`.
- 2016/09/08 (1.16.0) - Added additional checks to select correct types if `NK_INCLUDE_FIXED_TYPES`
is not defined by supporting the biggest compiler GCC, clang and MSVC.
- 2016/09/07 (1.15.3) - Fixed `NK_INCLUDE_COMMAND_USERDATA` define to not cause an error.
- 2016/09/04 (1.15.2) - Fixed wrong combobox height calculation.
- 2016/09/03 (1.15.1) - Fixed gaps inside combo boxes in OpenGL.
- 2016/09/02 (1.15.0) - Changed nuklear to not have any default vertex layout and
instead made it user provided. The range of types to convert
to is quite limited at the moment, but I would be more than
happy to accept PRs to add additional.
- 2016/08/30 (1.14.2) - Removed unused variables.
- 2016/08/30 (1.14.1) - Fixed C++ build errors.
- 2016/08/30 (1.14.0) - Removed mouse dragging from SDL demo since it does not work correctly.
- 2016/08/30 (1.13.4) - Tweaked some default styling variables.
- 2016/08/30 (1.13.3) - Hopefully fixed drawing bug in slider, in general I would
refrain from using slider with a big number of steps.
- 2016/08/30 (1.13.2) - Fixed close and minimize button which would fire even if the
window was in Read Only Mode.
- 2016/08/30 (1.13.1) - Fixed popup panel padding handling which was previously just
a hack for combo box and menu.
- 2016/08/30 (1.13.0) - Removed `NK_WINDOW_DYNAMIC` flag from public API since
it is bugged and causes issues in window selection.
- 2016/08/30 (1.12.0) - Removed scaler size. The size of the scaler is now
determined by the scrollbar size.
- 2016/08/30 (1.11.2) - Fixed some drawing bugs caused by changes from 1.11.0.
- 2016/08/30 (1.11.1) - Fixed overlapping minimized window selection.
- 2016/08/30 (1.11.0) - Removed some internal complexity and overly complex code
handling panel padding and panel border.
- 2016/08/29 (1.10.0) - Added additional height parameter to `nk_combobox_xxx`.
- 2016/08/29 (1.10.0) - Fixed drawing bug in dynamic popups.
- 2016/08/29 (1.10.0) - Added experimental mouse scrolling to popups, menus and comboboxes.
- 2016/08/26 (1.10.0) - Added window name string prepresentation to account for
hash collisions. Currently limited to `NK_WINDOW_MAX_NAME`
which in term can be redefined if not big enough.
- 2016/08/26 (1.10.0) - Added stacks for temporary style/UI changes in code.
- 2016/08/25 (1.10.0) - Changed `nk_input_is_key_pressed` and 'nk_input_is_key_released'
to account for key press and release happening in one frame.
- 2016/08/25 (1.10.0) - Added additional nk_edit flag to directly jump to the end on activate.
- 2016/08/17 (1.09.6) - Removed invalid check for value zero in `nk_propertyx`.
- 2016/08/16 (1.09.5) - Fixed ROM mode for deeper levels of popup windows parents.
- 2016/08/15 (1.09.4) - Editbox are now still active if enter was pressed with flag
`NK_EDIT_SIG_ENTER`. Main reasoning is to be able to keep
typing after committing.
- 2016/08/15 (1.09.4) - Removed redundant code.
- 2016/08/15 (1.09.4) - Fixed negative numbers in `nk_strtoi` and remove unused variable.
- 2016/08/15 (1.09.3) - Fixed `NK_WINDOW_BACKGROUND` flag behavior to select a background
window only as selected by hovering and not by clicking.
- 2016/08/14 (1.09.2) - Fixed a bug in font atlas which caused wrong loading
of glyphs for font with multiple ranges.
- 2016/08/12 (1.09.1) - Added additional function to check if window is currently
hidden and therefore not visible.
- 2016/08/12 (1.09.1) - nk_window_is_closed now queries the correct flag `NK_WINDOW_CLOSED`
instead of the old flag `NK_WINDOW_HIDDEN`.
- 2016/08/09 (1.09.0) - Added additional double version to nk_property and changed
the underlying implementation to not cast to float and instead
work directly on the given values.
- 2016/08/09 (1.08.0) - Added additional define to overwrite library internal
floating pointer number to string conversion for additional
precision.
- 2016/08/09 (1.08.0) - Added additional define to overwrite library internal
string to floating point number conversion for additional
precision.
- 2016/08/08 (1.07.2) - Fixed compiling error without define `NK_INCLUDE_FIXED_TYPE`.
- 2016/08/08 (1.07.1) - Fixed possible floating point error inside `nk_widget` leading
to wrong widget width calculation which results in widgets falsely
becoming tagged as not inside window and cannot be accessed.
- 2016/08/08 (1.07.0) - Nuklear now differentiates between hiding a window (NK_WINDOW_HIDDEN) and
closing a window (NK_WINDOW_CLOSED). A window can be hidden/shown
by using `nk_window_show` and closed by either clicking the close
icon in a window or by calling `nk_window_close`. Only closed
windows get removed at the end of the frame while hidden windows
remain.
- 2016/08/08 (1.06.0) - Added `nk_edit_string_zero_terminated` as a second option to
`nk_edit_string` which takes, edits and outputs a '\0' terminated string.
- 2016/08/08 (1.05.4) - Fixed scrollbar auto hiding behavior.
- 2016/08/08 (1.05.3) - Fixed wrong panel padding selection in `nk_layout_widget_space`.
- 2016/08/07 (1.05.2) - Fixed old bug in dynamic immediate mode layout API, calculating
wrong item spacing and panel width.
- 2016/08/07 (1.05.1) - Hopefully finally fixed combobox popup drawing bug.
- 2016/08/07 (1.05.0) - Split varargs away from `NK_INCLUDE_STANDARD_IO` into own
define `NK_INCLUDE_STANDARD_VARARGS` to allow more fine
grained controlled over library includes.
- 2016/08/06 (1.04.5) - Changed memset calls to `NK_MEMSET`.
- 2016/08/04 (1.04.4) - Fixed fast window scaling behavior.
- 2016/08/04 (1.04.3) - Fixed window scaling, movement bug which appears if you
move/scale a window and another window is behind it.
If you are fast enough then the window behind gets activated
and the operation is blocked. I now require activating
by hovering only if mouse is not pressed.
- 2016/08/04 (1.04.2) - Fixed changing fonts.
- 2016/08/03 (1.04.1) - Fixed `NK_WINDOW_BACKGROUND` behavior.
- 2016/08/03 (1.04.0) - Added color parameter to `nk_draw_image`.
- 2016/08/03 (1.04.0) - Added additional window padding style attributes for
sub windows (combo, menu, ...).
- 2016/08/03 (1.04.0) - Added functions to show/hide software cursor.
- 2016/08/03 (1.04.0) - Added `NK_WINDOW_BACKGROUND` flag to force a window
to be always in the background of the screen.
- 2016/08/03 (1.03.2) - Removed invalid assert macro for NK_RGB color picker.
- 2016/08/01 (1.03.1) - Added helper macros into header include guard.
- 2016/07/29 (1.03.0) - Moved the window/table pool into the header part to
simplify memory management by removing the need to
allocate the pool.
- 2016/07/29 (1.02.0) - Added auto scrollbar hiding window flag which if enabled
will hide the window scrollbar after NK_SCROLLBAR_HIDING_TIMEOUT
seconds without window interaction. To make it work
you have to also set a delta time inside the `nk_context`.
- 2016/07/25 (1.01.1) - Fixed small panel and panel border drawing bugs.
- 2016/07/15 (1.01.0) - Added software cursor to `nk_style` and `nk_context`.
- 2016/07/15 (1.01.0) - Added const correctness to `nk_buffer_push' data argument.
- 2016/07/15 (1.01.0) - Removed internal font baking API and simplified
font atlas memory management by converting pointer
arrays for fonts and font configurations to lists.
- 2016/07/15 (1.00.0) - Changed button API to use context dependent button
behavior instead of passing it for every function call.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Gallery
![Figure [blue]: Feature overview with blue color styling](https://cloud.githubusercontent.com/assets/8057201/13538240/acd96876-e249-11e5-9547-5ac0b19667a0.png)
![Figure [red]: Feature overview with red color styling](https://cloud.githubusercontent.com/assets/8057201/13538243/b04acd4c-e249-11e5-8fd2-ad7744a5b446.png)
![Figure [widgets]: Widget overview](https://cloud.githubusercontent.com/assets/8057201/11282359/3325e3c6-8eff-11e5-86cb-cf02b0596087.png)
![Figure [blackwhite]: Black and white](https://cloud.githubusercontent.com/assets/8057201/11033668/59ab5d04-86e5-11e5-8091-c56f16411565.png)
![Figure [filexp]: File explorer](https://cloud.githubusercontent.com/assets/8057201/10718115/02a9ba08-7b6b-11e5-950f-adacdd637739.png)
![Figure [opengl]: OpenGL Editor](https://cloud.githubusercontent.com/assets/8057201/12779619/2a20d72c-ca69-11e5-95fe-4edecf820d5c.png)
![Figure [nodedit]: Node Editor](https://cloud.githubusercontent.com/assets/8057201/9976995/e81ac04a-5ef7-11e5-872b-acd54fbeee03.gif)
![Figure [skinning]: Using skinning in Nuklear](https://cloud.githubusercontent.com/assets/8057201/15991632/76494854-30b8-11e6-9555-a69840d0d50b.png)
![Figure [bf]: Heavy modified version](https://cloud.githubusercontent.com/assets/8057201/14902576/339926a8-0d9c-11e6-9fee-a8b73af04473.png)
## Credits
Developed by Micha Mettke and every direct or indirect github contributor. <br /><br />
Embeds [stb_texedit](https://github.com/nothings/stb/blob/master/stb_textedit.h), [stb_truetype](https://github.com/nothings/stb/blob/master/stb_truetype.h) and [stb_rectpack](https://github.com/nothings/stb/blob/master/stb_rect_pack.h) by Sean Barret (public domain) <br />
Uses [stddoc.c](https://github.com/r-lyeh/stddoc.c) from r-lyeh@github.com for documentation generation <br /><br />
Embeds ProggyClean.ttf font by Tristan Grimmer (MIT license). <br />
Big thank you to Omar Cornut (ocornut@github) for his [imgui library](https://github.com/ocornut/imgui) and
giving me the inspiration for this library, Casey Muratori for handmade hero
and his original immediate mode graphical user interface idea and Sean
Barret for his amazing single header libraries which restored my faith
in libraries and brought me to create some of my own. Finally Apoorva Joshi
for his single header file packer.
<script>markdeepOptions={tocStyle:'medium'};</script>
<!-- Markdeep: --><script src='https://casual-effects.com/markdeep/latest/markdeep.min.js?'></script>
Reference in New Issue View Git Blame Copy Permalink