Window

=============================================================================

                            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

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