Nuklear

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

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.

The implementation mode requires to define the preprocessor macro NK_IMPLEMENTATION in one .c/.cpp file before #includeing this file, e.g.:

    #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.

Flags

Constants

Dependencies

Example

// 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);

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.

struct nk_context ctx;
nk_init_xxx(&ctx, ...);
while (1) {
    // [...]
    nk_clear(&ctx);
}
nk_free(&ctx);

Reference

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.

int nk_init_default(struct nk_context *ctx, const struct nk_user_font *font);

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.

int nk_init_fixed(struct nk_context *ctx, void *memory, nk_size size, const struct nk_user_font *font);

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.

int nk_init(struct nk_context *ctx, struct nk_allocator *alloc, const struct nk_user_font *font);

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.

int nk_init_custom(struct nk_context *ctx, struct nk_buffer *cmds, struct nk_buffer *pool, const struct nk_user_font *font);

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.

void nk_clear(struct nk_context *ctx);

nk_free

Frees all memory allocated by nuklear. Not needed if context was initialized with nk_init_fixed.

void nk_free(struct nk_context *ctx);

nk_set_user_data

Sets the currently passed userdata passed down into each draw command.

void nk_set_user_data(struct nk_context *ctx, nk_handle data);

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.

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 transistions. 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.

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

nk_input_begin

Begins the input mirroring process by resetting text, scroll mouse, previous mouse position and movement as well as key state transitions,

void nk_input_begin(struct nk_context*);

nk_input_motion

Mirrors current mouse position to nuklear

void nk_input_motion(struct nk_context *ctx, int x, int y);

nk_input_key

Mirrors the state of a specific key to nuklear

void nk_input_key(struct nk_context*, enum nk_keys key, int down);

nk_input_button

Mirrors the state of a specific mouse button to nuklear

void nk_input_button(struct nk_context *ctx, enum nk_buttons btn, int x, int y, int 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

void nk_input_scroll(struct nk_context *ctx, struct nk_vec2 val);

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.

void nk_input_char(struct nk_context *ctx, char c);

nk_input_glyph

Converts an encoded unicode rune into UTF-8 and copies the result into an internal text buffer.

void nk_input_glyph(struct nk_context *ctx, const nk_glyph g);

nk_input_unicode

Converts a unicode rune into UTF-8 and copies the result into an internal text buffer.

void nk_input_unicode(struct nk_context*, nk_rune rune);

nk_input_end

End the input mirroring process by resetting mouse grabbing state to ensure the mouse cursor is not grabbed indefinitely.

void nk_input_end(struct nk_context *ctx);

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:

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.

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.

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).

//[... 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:

// 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.null = dev->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

nk__begin

Returns a draw command list iterator to iterate all draw commands accumulated over one frame.

const struct nk_command* nk__begin(struct nk_context*);

nk__next

Returns draw command pointer pointing to the next command inside the draw command list

const struct nk_command* nk__next(struct nk_context*, const struct nk_command*);

nk_foreach

Iterates over each draw command inside the context draw command list

#define nk_foreach(c, ctx)

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.

nk_flags nk_convert(struct nk_context *ctx, struct nk_buffer *cmds,

nk__draw_begin

Returns a draw vertex command buffer iterator to iterate over the vertex draw command buffer

const struct nk_draw_command* nk__draw_begin(const struct nk_context*, const struct nk_buffer*);

nk__draw_end

Returns the vertex draw command at the end of the vertex draw command buffer

const struct nk_draw_command* nk__draw_end(const struct nk_context *ctx, const struct nk_buffer *buf);

nk__draw_next

Increments the vertex draw command buffer iterator

const struct nk_draw_command* nk__draw_next(const struct nk_draw_command*, const struct nk_buffer*, const struct nk_context*);

nk_draw_foreach

Iterates over each vertex draw command inside a vertex draw command buffer

#define nk_draw_foreach(cmd,ctx, b)

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.

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.

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.

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.

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.

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

nk_panel_flags

nk_collapse_states

nk_begin

Starts a new window; needs to be called every frame for every window (unless hidden) or otherwise the window gets removed

int nk_begin(struct nk_context *ctx, const char *title, struct nk_rect bounds, nk_flags flags);

nk_begin_titled

Extended window start with separated title and identifier to allow multiple windows with same title but not name

int nk_begin_titled(struct nk_context *ctx, const char *name, const char *title, struct nk_rect bounds, nk_flags flags);

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

void nk_end(struct nk_context *ctx);

nk_window_find

Finds and returns a window from passed name

struct nk_window *nk_window_find(struct nk_context *ctx, const char *name);

nk_window_get_bounds

Returns a rectangle with screen position and size of the currently processed window

struct nk_rect nk_window_get_bounds(const struct nk_context *ctx);

nk_window_get_position

Returns the position of the currently processed window.

struct nk_vec2 nk_window_get_position(const struct nk_context *ctx);

nk_window_get_size

Returns the size with width and height of the currently processed window.

struct nk_vec2 nk_window_get_size(const struct nk_context *ctx);

nk_window_get_width

Returns the width of the currently processed window.

float nk_window_get_width(const struct nk_context *ctx);

nk_window_get_height

Returns the height of the currently processed window.

float nk_window_get_height(const struct nk_context *ctx);

nk_window_get_panel

Returns the underlying panel which contains all processing state of the current window.

struct nk_panel* nk_window_get_panel(struct nk_context *ctx);

nk_window_get_content_region

Returns the position and size of the currently visible and non-clipped space inside the currently processed window.

struct nk_rect nk_window_get_content_region(struct nk_context *ctx);

nk_window_get_content_region_min

Returns the upper left position of the currently visible and non-clipped space inside the currently processed window.

struct nk_vec2 nk_window_get_content_region_min(struct nk_context *ctx);

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.

struct nk_vec2 nk_window_get_content_region_max(struct nk_context *ctx);

nk_window_get_content_region_size

Returns the size of the currently visible and non-clipped space inside the currently processed window

struct nk_vec2 nk_window_get_content_region_size(struct nk_context *ctx);

nk_window_get_canvas

Returns the draw command buffer. Can be used to draw custom widgets

struct nk_command_buffer* nk_window_get_canvas(struct nk_context *ctx);

nk_window_get_scroll

Gets the scroll offset for the current window

void nk_window_get_scroll(struct nk_context *ctx, nk_uint *offset_x, nk_uint *offset_y);

nk_window_has_focus

Returns if the currently processed window is currently active

int nk_window_has_focus(const struct nk_context *ctx);

nk_window_is_hovered

Return if the current window is being hovered

int nk_window_is_hovered(struct nk_context *ctx);

nk_window_is_collapsed

Returns if the window with given name is currently minimized/collapsed

int nk_window_is_collapsed(struct nk_context *ctx, const char *name);

nk_window_is_closed

Returns if the window with given name was closed by calling nk_close

int nk_window_is_closed(struct nk_context *ctx, const char *name);

nk_window_is_hidden

Returns if the window with given name is hidden

int nk_window_is_hidden(struct nk_context *ctx, const char *name);

nk_window_is_active

Same as nk_window_has_focus for some reason

int nk_window_is_active(struct nk_context *ctx, const char *name);

nk_window_is_any_hovered

Returns if the any window is being hovered

int nk_window_is_any_hovered(struct nk_context*);

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.

int nk_item_is_any_active(struct nk_context*);

nk_window_set_bounds

Updates position and size of window with passed in name

void nk_window_set_bounds(struct nk_context*, const char *name, struct nk_rect bounds);

nk_window_set_position

Updates position of window with passed name

void nk_window_set_position(struct nk_context*, const char *name, struct nk_vec2 pos);

nk_window_set_size

Updates size of window with passed in name

void nk_window_set_size(struct nk_context*, const char *name, struct nk_vec2);

nk_window_set_focus

Sets the window with given name as active

void nk_window_set_focus(struct nk_context*, const char *name);

nk_window_set_scroll

Sets the scroll offset for the current window

void nk_window_set_scroll(struct nk_context *ctx, nk_uint offset_x, nk_uint offset_y);

nk_window_close

Closes a window and marks it for being freed at the end of the frame

void nk_window_close(struct nk_context *ctx, const char *name);

nk_window_collapse

Updates collapse state of a window with given name

void nk_window_collapse(struct nk_context*, const char *name, enum nk_collapse_states state);

nk_window_collapse_if

Updates collapse state of a window with given name if given condition is met

void nk_window_collapse_if(struct nk_context*, const char *name, enum nk_collapse_states, int cond);

nk_window_show

updates visibility state of a window with given name

void nk_window_show(struct nk_context*, const char *name, enum nk_show_states);

nk_window_show_if

Updates visibility state of a window with given name if a given condition is met

void nk_window_show_if(struct nk_context*, const char *name, enum nk_show_states, int cond);

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.

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.

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

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.

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.

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.

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.

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
   
   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:

   widget_width = (window_width - padding - spacing) * (1/colum_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.

   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
   
   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.

   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
   
   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.

   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
   
   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.

   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
   
   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.

   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
   
   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.

   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

nk_layout_set_min_row_height

Sets the currently used minimum row height.

void nk_layout_set_min_row_height(struct nk_context*, float height);

nk_layout_reset_min_row_height

Reset the currently used minimum row height back to font_height + text_padding + padding

void nk_layout_reset_min_row_height(struct nk_context*);

nk_layout_widget_bounds

Returns the width of the next row allocate by one of the layouting functions

struct nk_rect nk_layout_widget_bounds(struct nk_context*);

nk_layout_ratio_from_pixel

Utility functions to calculate window ratio from pixel size

float nk_layout_ratio_from_pixel(struct nk_context*, float pixel_width);

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.

void nk_layout_row_dynamic(struct nk_context *ctx, float height, int cols);

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.

void nk_layout_row_static(struct nk_context *ctx, float height, int item_width, int cols);

nk_layout_row_begin

Starts a new dynamic or fixed row with given height and columns.

void nk_layout_row_begin(struct nk_context *ctx, enum nk_layout_format fmt, float row_height, int cols);

nk_layout_row_push

Specifies either window ratio or width of a single column

void nk_layout_row_push(struct nk_context*, float value);

nk_layout_row_end

Finished previously started row

void nk_layout_row_end(struct nk_context*);

nk_layout_row

Specifies row columns in array as either window ratio or size

void nk_layout_row(struct nk_context*, enum nk_layout_format, float height, int cols, const float *ratio);

nk_layout_row_template_begin

Begins the row template declaration

void nk_layout_row_template_begin(struct nk_context*, float row_height);

nk_layout_row_template_push_dynamic

Adds a dynamic column that dynamically grows and can go to zero if not enough space

void nk_layout_row_template_push_dynamic(struct nk_context*);

nk_layout_row_template_push_variable

Adds a variable column that dynamically grows but does not shrink below specified pixel width

void nk_layout_row_template_push_variable(struct nk_context*, float min_width);

nk_layout_row_template_push_static

Adds a static column that does not grow and will always have the same size

void nk_layout_row_template_push_static(struct nk_context*, float width);

nk_layout_row_template_end

Marks the end of the row template

void nk_layout_row_template_end(struct nk_context*);

nk_layout_space_begin

Begins a new layouting space that allows to specify each widgets position and size.

void nk_layout_space_begin(struct nk_context*, enum nk_layout_format, float height, int widget_count);

nk_layout_space_push

Pushes position and size of the next widget in own coordinate space either as pixel or ratio

void nk_layout_space_push(struct nk_context *ctx, struct nk_rect bounds);

nk_layout_space_end

Marks the end of the layout space

void nk_layout_space_end(struct nk_context*);

nk_layout_space_bounds

Utility function to calculate total space allocated for nk_layout_space

struct nk_rect nk_layout_space_bounds(struct nk_context*);

nk_layout_space_to_screen

Converts vector from nk_layout_space coordinate space into screen space

struct nk_vec2 nk_layout_space_to_screen(struct nk_context*, struct nk_vec2);

nk_layout_space_to_local

Converts vector from layout space into screen space

struct nk_vec2 nk_layout_space_to_local(struct nk_context*, struct nk_vec2);

nk_layout_space_rect_to_screen

Converts rectangle from screen space into layout space

struct nk_rect nk_layout_space_rect_to_screen(struct nk_context*, struct nk_rect);

nk_layout_space_rect_to_local

Converts rectangle from layout space into screen space

struct nk_rect nk_layout_space_rect_to_local(struct nk_context*, struct nk_rect);

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 corosponding nk_group_begin_xxx call does not return 0:

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:

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_free(&ctx);

Reference

nk_group_begin

Starts a new widget group. Requires a previous layouting function to specify a pos/size.

int nk_group_begin(struct nk_context*, const char *title, nk_flags);

nk_group_begin_titled

Starts a new widget group. Requires a previous layouting function to specify a pos/size.

int nk_group_begin_titled(struct nk_context*, const char *name, const char *title, nk_flags);

nk_group_end

Ends a widget group

void nk_group_end(struct nk_context*);

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.

int nk_group_scrolled_offset_begin(struct nk_context*, nk_uint *x_offset, nk_uint *y_offset, const char *title, nk_flags flags);

nk_group_scrolled_begin

Starts a new widget group. requires a previous layouting function to specify a size. Does not keep track of scrollbar.

int nk_group_scrolled_begin(struct nk_context*, struct nk_scroll *off, const char *title, nk_flags);

nk_group_scrolled_end

Ends a widget group after calling nk_group_scrolled_offset_begin or nk_group_scrolled_begin.

void nk_group_scrolled_end(struct nk_context*);

nk_group_get_scroll

Gets the scroll position of the given group.

void nk_group_get_scroll(struct nk_context*, const char *id, nk_uint *x_offset, nk_uint *y_offset);

nk_group_set_scroll

Sets the scroll position of the given group.

void nk_group_set_scroll(struct nk_context*, const char *id, nk_uint x_offset, nk_uint y_offset);

Tree

Trees represent two different concept. First the concept of a collapsable UI section that can be either in a hidden or visibile 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.

Trees thereby can be nested for tree representations and multiple nested collapsable 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.

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 collapsable 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.

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.

if (nk_tree_push(ctx, NK_TREE_TAB, "Tree", NK_MINIMIZED)) {
    nk_layout_row_dynamic(...);
    nk_widget(...);
    nk_tree_pop(ctx);
}

Reference

nk_tree_type

nk_tree_push

Starts a collapsable UI section with internal state management

#define nk_tree_push(ctx, type, title, state)

nk_tree_push_id

Starts a collapsable UI section with internal state management callable in a look

#define nk_tree_push_id(ctx, type, title, state, id)

nk_tree_push_hashed

Start a collapsable UI section with internal state management with full control over internal unique ID used to store state

int 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);

nk_tree_image_push

Start a collapsable UI section with image and label header

#define nk_tree_image_push(ctx, type, img, title, state)

nk_tree_image_push_id

Start a collapsable UI section with image and label header and internal state management callable in a look

#define nk_tree_image_push_id(ctx, type, img, title, state, id)

nk_tree_image_push_hashed

Start a collapsable UI section with internal state management with full control over internal unique ID used to store state

int 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);

nk_tree_pop

Ends a collapsabale UI section

void nk_tree_pop(struct nk_context*);

nk_tree_state_push

Start a collapsable UI section with external state management

int nk_tree_state_push(struct nk_context*, enum nk_tree_type, const char *title, enum nk_collapse_states *state);

nk_tree_state_image_push

Start a collapsable UI section with image and label header and external state management

int nk_tree_state_image_push(struct nk_context*, enum nk_tree_type, struct nk_image, const char *title, enum nk_collapse_states *state);

nk_tree_state_pop

Ends a collapsabale UI section

void nk_tree_state_pop(struct nk_context*);

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 identifaction 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 propery 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.

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_free(&ctx);

Reference

nk_property_int

Integer property directly modifing a passed in value

void nk_property_int(struct nk_context *ctx, const char *name, int min, int *val, int max, int step, float inc_per_pixel);

nk_property_float

Float property directly modifing a passed in value

void nk_property_float(struct nk_context *ctx, const char *name, float min, float *val, float max, float step, float inc_per_pixel);

nk_property_double

Double property directly modifing a passed in value

void nk_property_double(struct nk_context *ctx, const char *name, double min, double *val, double max, double step, double inc_per_pixel);

nk_propertyi

Integer property modifing a passed in value and returning the new value

int nk_propertyi(struct nk_context *ctx, const char *name, int min, int val, int max, int step, float inc_per_pixel);

nk_propertyf

Float property modifing a passed in value and returning the new value

float nk_propertyf(struct nk_context *ctx, const char *name, float min, float val, float max, float step, float inc_per_pixel);

nk_propertyd

Float property modifing a passed in value and returning the new value

float nk_propertyd(struct nk_context *ctx, const char *name, double min, double val, double max, double step, double inc_per_pixel);

License

   ------------------------------------------------------------------------------
   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

[date][x.yy.zz]-[description]
-[date]: date on which the change has been pushed
-[x.yy.zz]: Numerical version string representation. Each version number on the right
            resets back to zero if version on the left is incremented.
   - [x]: Major version with API and library breaking changes
   - [yy]: Minor version with non-breaking API and library changes
   - [zz]: Bug fix version with no direct changes to API
- 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 separed 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 formated 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: Modifing window position and size funtions 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 boundries.
- 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 programatic way of 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 seperator 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 glyphes.
- 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 commiting.
- 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 glyphes 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 wiget width calculation which results in widgets falsly
                       becomming 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 dependend button
                       behavior instead of passing it for every function call.

Gallery

Figure 1: Feature overview with blue color styling

Figure 2: Feature overview with red color styling

Figure 3: Widget overview

Figure 4: Black and white

Figure 5: File explorer

Figure 6: OpenGL Editor

Figure 7: Node Editor

Figure 8: Using skinning in Nuklear

Figure 9: Heavy modified version

Credits

Developed by Micha Mettke and every direct or indirect github contributor.

Embeds stb_texedit, stb_truetype and stb_rectpack by Sean Barret (public domain)
Uses stddoc.c from r-lyeh@github.com for documentation generation

Embeds ProggyClean.ttf font by Tristan Grimmer (MIT license).
Big thank you to Omar Cornut (ocornut@github) for his imgui library 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.