Blame src-nuklear/HEADER

b53a5c
/// # Nuklear
b53a5c
/// ![](https://cloud.githubusercontent.com/assets/8057201/11761525/ae06f0ca-a0c6-11e5-819d-5610b25f6ef4.gif)
b53a5c
///
b53a5c
/// ## Contents
b53a5c
/// 1. About section
b53a5c
/// 2. Highlights section
b53a5c
/// 3. Features section
b53a5c
/// 4. Usage section
b53a5c
///     1. Flags section
b53a5c
///     2. Constants section
b53a5c
///     3. Dependencies section
b53a5c
/// 5. Example section
b53a5c
/// 6. API section
b53a5c
///     1. Context section
b53a5c
///     2. Input section
b53a5c
///     3. Drawing section
b53a5c
///     4. Window section
b53a5c
///     5. Layouting section
b53a5c
///     6. Groups section
b53a5c
///     7. Tree section
b53a5c
///     8. Properties section
b53a5c
/// 7. License section
b53a5c
/// 8. Changelog section
b53a5c
/// 9. Gallery section
b53a5c
/// 10. Credits section
b53a5c
///
b53a5c
/// ## About
b53a5c
/// This is a minimal state immediate mode graphical user interface toolkit
b53a5c
/// written in ANSI C and licensed under public domain. It was designed as a simple
b53a5c
/// embeddable user interface for application and does not have any dependencies,
b53a5c
/// a default renderbackend or OS window and input handling but instead provides a very modular
b53a5c
/// library approach by using simple input state for input and draw
b53a5c
/// commands describing primitive shapes as output. So instead of providing a
b53a5c
/// layered library that tries to abstract over a number of platform and
b53a5c
/// render backends it only focuses on the actual UI.
b53a5c
///
b53a5c
/// ## Highlights
b53a5c
/// - Graphical user interface toolkit
b53a5c
/// - Single header library
b53a5c
/// - Written in C89 (a.k.a. ANSI C or ISO C90)
b53a5c
/// - Small codebase (~18kLOC)
b53a5c
/// - Focus on portability, efficiency and simplicity
b53a5c
/// - No dependencies (not even the standard library if not wanted)
b53a5c
/// - Fully skinnable and customizable
b53a5c
/// - Low memory footprint with total memory control if needed or wanted
b53a5c
/// - UTF-8 support
b53a5c
/// - No global or hidden state
b53a5c
/// - Customizable library modules (you can compile and use only what you need)
b53a5c
/// - Optional font baker and vertex buffer output
b53a5c
/// - [Code available on github](https://github.com/Immediate-Mode-UI/Nuklear/)
b53a5c
///
b53a5c
/// ## Features
b53a5c
/// - Absolutely no platform dependent code
b53a5c
/// - Memory management control ranging from/to
b53a5c
///     - Ease of use by allocating everything from standard library
b53a5c
///     - Control every byte of memory inside the library
b53a5c
/// - Font handling control ranging from/to
b53a5c
///     - Use your own font implementation for everything
b53a5c
///     - Use this libraries internal font baking and handling API
b53a5c
/// - Drawing output control ranging from/to
b53a5c
///     - Simple shapes for more high level APIs which already have drawing capabilities
b53a5c
///     - Hardware accessible anti-aliased vertex buffer output
b53a5c
/// - Customizable colors and properties ranging from/to
b53a5c
///     - Simple changes to color by filling a simple color table
b53a5c
///     - Complete control with ability to use skinning to decorate widgets
b53a5c
/// - Bendable UI library with widget ranging from/to
b53a5c
///     - Basic widgets like buttons, checkboxes, slider, ...
b53a5c
///     - Advanced widget like abstract comboboxes, contextual menus,...
b53a5c
/// - Compile time configuration to only compile what you need
b53a5c
///     - Subset which can be used if you do not want to link or use the standard library
b53a5c
/// - Can be easily modified to only update on user input instead of frame updates
b53a5c
///
b53a5c
/// ## Usage
b53a5c
/// This library is self contained in one single header file and can be used either
b53a5c
/// in header only mode or in implementation mode. The header only mode is used
b53a5c
/// by default when included and allows including this header in other headers
b53a5c
/// and does not contain the actual implementation. 

b53a5c
///
b53a5c
/// The implementation mode requires to define  the preprocessor macro
b53a5c
/// NK_IMPLEMENTATION in *one* .c/.cpp file before #including this file, e.g.:
b53a5c
///
b53a5c
/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~C
b53a5c
///     #define NK_IMPLEMENTATION
b53a5c
///     #include "nuklear.h"
b53a5c
/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
b53a5c
///
b53a5c
/// Also optionally define the symbols listed in the section "OPTIONAL DEFINES"
b53a5c
/// below in header and implementation mode if you want to use additional functionality
b53a5c
/// or need more control over the library.
b53a5c
///
b53a5c
/// !!! WARNING
b53a5c
///     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.
b53a5c
///
b53a5c
/// ### Flags
b53a5c
/// Flag                            | Description
b53a5c
/// --------------------------------|------------------------------------------
b53a5c
/// NK_PRIVATE                      | If defined declares all functions as static, so they can only be accessed inside the file that contains the implementation
b53a5c
/// 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.</stdint.h>
b53a5c
/// 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.</stdlib.h>
b53a5c
/// NK_INCLUDE_STANDARD_IO          | If defined it will include header `<stdio.h>` and provide additional functions depending on file loading.</stdio.h>
b53a5c
/// NK_INCLUDE_STANDARD_VARARGS     | If defined it will include header <stdarg.h> and provide additional functions depending on file loading.</stdarg.h>
b53a5c
/// NK_INCLUDE_STANDARD_BOOL        | If defined it will include header `<stdbool.h>` for nk_bool otherwise nuklear defines nk_bool as int.</stdbool.h>
b53a5c
/// 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,...
b53a5c
/// 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.
b53a5c
/// 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
b53a5c
/// 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.
b53a5c
/// 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.
b53a5c
/// 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.
b53a5c
/// 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
b53a5c
/// NK_KEYSTATE_BASED_INPUT         | Define this if your backend uses key state for each frame rather than key press/release events
b53a5c
///
b53a5c
/// !!! WARNING
b53a5c
///     The following flags will pull in the standard C library:
b53a5c
///     - NK_INCLUDE_DEFAULT_ALLOCATOR
b53a5c
///     - NK_INCLUDE_STANDARD_IO
b53a5c
///     - NK_INCLUDE_STANDARD_VARARGS
b53a5c
///
b53a5c
/// !!! WARNING
b53a5c
///     The following flags if defined need to be defined for both header and implementation:
b53a5c
///     - NK_INCLUDE_FIXED_TYPES
b53a5c
///     - NK_INCLUDE_DEFAULT_ALLOCATOR
b53a5c
///     - NK_INCLUDE_STANDARD_VARARGS
b53a5c
///     - NK_INCLUDE_STANDARD_BOOL
b53a5c
///     - NK_INCLUDE_VERTEX_BUFFER_OUTPUT
b53a5c
///     - NK_INCLUDE_FONT_BAKING
b53a5c
///     - NK_INCLUDE_DEFAULT_FONT
b53a5c
///     - NK_INCLUDE_STANDARD_VARARGS
b53a5c
///     - NK_INCLUDE_COMMAND_USERDATA
b53a5c
///     - NK_UINT_DRAW_INDEX
b53a5c
///
b53a5c
/// ### Constants
b53a5c
/// Define                          | Description
b53a5c
/// --------------------------------|---------------------------------------
b53a5c
/// 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.
b53a5c
/// NK_MAX_NUMBER_BUFFER            | Maximum buffer size for the conversion buffer between float and string Under normal circumstances this should be more than sufficient.
b53a5c
/// 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.
b53a5c
///
b53a5c
/// !!! WARNING
b53a5c
///     The following constants if defined need to be defined for both header and implementation:
b53a5c
///     - NK_MAX_NUMBER_BUFFER
b53a5c
///     - NK_BUFFER_DEFAULT_INITIAL_SIZE
b53a5c
///     - NK_INPUT_MAX
b53a5c
///
b53a5c
/// ### Dependencies
b53a5c
/// Function    | Description
b53a5c
/// ------------|---------------------------------------------------------------
b53a5c
/// NK_ASSERT   | If you don't define this, nuklear will use <assert.h> with assert().</assert.h>
b53a5c
/// NK_MEMSET   | You can define this to 'memset' or your own memset implementation replacement. If not nuklear will use its own version.
b53a5c
/// NK_MEMCPY   | You can define this to 'memcpy' or your own memcpy implementation replacement. If not nuklear will use its own version.
b53a5c
/// 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.
b53a5c
/// NK_SIN      | You can define this to 'sinf' or your own sine implementation replacement. If not nuklear will use its own approximation implementation.
b53a5c
/// NK_COS      | You can define this to 'cosf' or your own cosine implementation replacement. If not nuklear will use its own approximation implementation.
b53a5c
/// 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!).
b53a5c
/// 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!).
b53a5c
/// 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.
b53a5c
///
b53a5c
/// !!! WARNING
b53a5c
///     The following dependencies will pull in the standard C library if not redefined:
b53a5c
///     - NK_ASSERT
b53a5c
///
b53a5c
/// !!! WARNING
b53a5c
///     The following dependencies if defined need to be defined for both header and implementation:
b53a5c
///     - NK_ASSERT
b53a5c
///
b53a5c
/// !!! WARNING
b53a5c
///     The following dependencies if defined need to be defined only for the implementation part:
b53a5c
///     - NK_MEMSET
b53a5c
///     - NK_MEMCPY
b53a5c
///     - NK_SQRT
b53a5c
///     - NK_SIN
b53a5c
///     - NK_COS
b53a5c
///     - NK_STRTOD
b53a5c
///     - NK_DTOA
b53a5c
///     - NK_VSNPRINTF
b53a5c
///
b53a5c
/// ## Example
b53a5c
///
b53a5c
/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~c
b53a5c
/// // init gui state
b53a5c
/// enum {EASY, HARD};
b53a5c
/// static int op = EASY;
b53a5c
/// static float value = 0.6f;
b53a5c
/// static int i =  20;
b53a5c
/// struct nk_context ctx;
b53a5c
///
b53a5c
/// nk_init_fixed(&ctx, calloc(1, MAX_MEMORY), MAX_MEMORY, &font);
b53a5c
/// if (nk_begin(&ctx, "Show", nk_rect(50, 50, 220, 220),
b53a5c
///     NK_WINDOW_BORDER|NK_WINDOW_MOVABLE|NK_WINDOW_CLOSABLE)) {
b53a5c
///     // fixed widget pixel width
b53a5c
///     nk_layout_row_static(&ctx, 30, 80, 1);
b53a5c
///     if (nk_button_label(&ctx, "button")) {
b53a5c
///         // event handling
b53a5c
///     }
b53a5c
///
b53a5c
///     // fixed widget window ratio width
b53a5c
///     nk_layout_row_dynamic(&ctx, 30, 2);
b53a5c
///     if (nk_option_label(&ctx, "easy", op == EASY)) op = EASY;
b53a5c
///     if (nk_option_label(&ctx, "hard", op == HARD)) op = HARD;
b53a5c
///
b53a5c
///     // custom widget pixel width
b53a5c
///     nk_layout_row_begin(&ctx, NK_STATIC, 30, 2);
b53a5c
///     {
b53a5c
///         nk_layout_row_push(&ctx, 50);
b53a5c
///         nk_label(&ctx, "Volume:", NK_TEXT_LEFT);
b53a5c
///         nk_layout_row_push(&ctx, 110);
b53a5c
///         nk_slider_float(&ctx, 0, &value, 1.0f, 0.1f);
b53a5c
///     }
b53a5c
///     nk_layout_row_end(&ctx);
b53a5c
/// }
b53a5c
/// nk_end(&ctx);
b53a5c
/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
b53a5c
///
b53a5c
/// ![](https://cloud.githubusercontent.com/assets/8057201/10187981/584ecd68-675c-11e5-897c-822ef534a876.png)
b53a5c
///
b53a5c
/// ## API
b53a5c
///