Readme.md
1# Nuklear
2
3[](https://travis-ci.org/vurtun/nuklear)
4
5This is a minimal state immediate mode graphical user interface toolkit
6written in ANSI C and licensed under public domain. It was designed as a simple
7embeddable user interface for application and does not have any dependencies,
8a default render backend or OS window and input handling but instead provides a very modular
9library approach by using simple input state for input and draw
10commands describing primitive shapes as output. So instead of providing a
11layered library that tries to abstract over a number of platform and
12render backends it only focuses on the actual UI.
13
14## Features
15
16- Immediate mode graphical user interface toolkit
17- Single header library
18- Written in C89 (ANSI C)
19- Small codebase (~18kLOC)
20- Focus on portability, efficiency and simplicity
21- No dependencies (not even the standard library if not wanted)
22- Fully skinnable and customizable
23- Low memory footprint with total memory control if needed or wanted
24- UTF-8 support
25- No global or hidden state
26- Customizable library modules (you can compile and use only what you need)
27- Optional font baker and vertex buffer output
28- [Documentation](https://rawgit.com/vurtun/nuklear/master/doc/nuklear.html)
29
30## Building
31
32This library is self contained in one single header file and can be used either
33in header only mode or in implementation mode. The header only mode is used
34by default when included and allows including this header in other headers
35and does not contain the actual implementation.
36
37The implementation mode requires to define the preprocessor macro
38`NK_IMPLEMENTATION` in *one* .c/.cpp file before `#include`ing this file, e.g.:
39```c
40#define NK_IMPLEMENTATION
41#include "nuklear.h"
42```
43IMPORTANT: Every time you include "nuklear.h" you have to define the same optional flags.
44This is very important not doing it either leads to compiler errors or even worse stack corruptions.
45
46## Gallery
47
48
49
50
51
52
53
54
55## Example
56
57```c
58/* init gui state */
59struct nk_context ctx;
60nk_init_fixed(&ctx, calloc(1, MAX_MEMORY), MAX_MEMORY, &font);
61
62enum {EASY, HARD};
63static int op = EASY;
64static float value = 0.6f;
65static int i = 20;
66
67if (nk_begin(&ctx, "Show", nk_rect(50, 50, 220, 220),
68 NK_WINDOW_BORDER|NK_WINDOW_MOVABLE|NK_WINDOW_CLOSABLE)) {
69 /* fixed widget pixel width */
70 nk_layout_row_static(&ctx, 30, 80, 1);
71 if (nk_button_label(&ctx, "button")) {
72 /* event handling */
73 }
74
75 /* fixed widget window ratio width */
76 nk_layout_row_dynamic(&ctx, 30, 2);
77 if (nk_option_label(&ctx, "easy", op == EASY)) op = EASY;
78 if (nk_option_label(&ctx, "hard", op == HARD)) op = HARD;
79
80 /* custom widget pixel width */
81 nk_layout_row_begin(&ctx, NK_STATIC, 30, 2);
82 {
83 nk_layout_row_push(&ctx, 50);
84 nk_label(&ctx, "Volume:", NK_TEXT_LEFT);
85 nk_layout_row_push(&ctx, 110);
86 nk_slider_float(&ctx, 0, &value, 1.0f, 0.1f);
87 }
88 nk_layout_row_end(&ctx);
89}
90nk_end(&ctx);
91```
92
93
94## Bindings
95There are a number of nuklear bindings for different languges created by other authors.
96I cannot atest for their quality since I am not necessarily proficient in either of these
97languages. Furthermore there are no guarantee that all bindings will always be kept up to date:
98
99- [Java](https://github.com/glegris/nuklear4j) by Guillaume Legris
100- [Golang](https://github.com/golang-ui/nuklear) by golang-ui@github.com
101- [Rust](https://github.com/snuk182/nuklear-rust) by snuk182@github.com
102- [Chicken](https://github.com/wasamasa/nuklear) by wasamasa@github.com
103- [Nim](https://github.com/zacharycarter/nuklear-nim) by zacharycarter@github.com
104- Lua
105 - [LÖVE-Nuklear](https://github.com/keharriso/love-nuklear) by Kevin Harrison
106 - [MoonNuklear](https://github.com/stetre/moonnuklear) by Stefano Trettel
107- Python
108 - [pyNuklear](https://github.com/billsix/pyNuklear) by William Emerison Six (ctypes-based wrapper)
109 - [pynk](https://github.com/nathanrw/nuklear-cffi) by nathanrw@github.com (cffi binding)
110- [CSharp/.NET](https://github.com/cartman300/NuklearDotNet) by cartman300@github.com
111
112## Credits
113Developed by Micha Mettke and every direct or indirect contributor to the GitHub.
114
115
116Embeds `stb_texedit`, `stb_truetype` and `stb_rectpack` by Sean Barrett (public domain)
117Embeds `ProggyClean.ttf` font by Tristan Grimmer (MIT license).
118
119
120Big thank you to Omar Cornut (ocornut@github) for his [imgui](https://github.com/ocornut/imgui) library and
121giving me the inspiration for this library, Casey Muratori for handmade hero
122and his original immediate mode graphical user interface idea and Sean
123Barrett for his amazing single header [libraries](https://github.com/nothings/stb) which restored my faith
124in libraries and brought me to create some of my own. Finally Apoorva Joshi for his singe-header [file packer](http://apoorvaj.io/single-header-packer.html).
125
126## License
127```
128------------------------------------------------------------------------------
129This software is available under 2 licenses -- choose whichever you prefer.
130------------------------------------------------------------------------------
131ALTERNATIVE A - MIT License
132Copyright (c) 2017 Micha Mettke
133Permission is hereby granted, free of charge, to any person obtaining a copy of
134this software and associated documentation files (the "Software"), to deal in
135the Software without restriction, including without limitation the rights to
136use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
137of the Software, and to permit persons to whom the Software is furnished to do
138so, subject to the following conditions:
139The above copyright notice and this permission notice shall be included in all
140copies or substantial portions of the Software.
141THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
142IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
143FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
144AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
145LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
146OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
147SOFTWARE.
148------------------------------------------------------------------------------
149ALTERNATIVE B - Public Domain (www.unlicense.org)
150This is free and unencumbered software released into the public domain.
151Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
152software, either in source code form or as a compiled binary, for any purpose,
153commercial or non-commercial, and by any means.
154In jurisdictions that recognize copyright laws, the author or authors of this
155software dedicate any and all copyright interest in the software to the public
156domain. We make this dedication for the benefit of the public at large and to
157the detriment of our heirs and successors. We intend this dedication to be an
158overt act of relinquishment in perpetuity of all present and future rights to
159this software under copyright law.
160THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
161IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
162FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
163AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
164ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
165WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
166-----------------------------------------------------------------------------
167```
168
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}