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/Löve2d](https://github.com/keharriso/love-nuklear) by Kevin Harrison
105- Python
106 - [pyNuklear](https://github.com/billsix/pyNuklear) by William Emerison Six (ctypes-based wrapper)
107 - [pynk](https://github.com/nathanrw/nuklear-cffi) by nathanrw@github.com (cffi binding)
108- [CSharp/.NET](https://github.com/cartman300/NuklearDotNet) by cartman300@github.com
109
110## Credits
111Developed by Micha Mettke and every direct or indirect contributor to the GitHub.
112
113
114Embeds `stb_texedit`, `stb_truetype` and `stb_rectpack` by Sean Barrett (public domain)
115Embeds `ProggyClean.ttf` font by Tristan Grimmer (MIT license).
116
117
118Big thank you to Omar Cornut (ocornut@github) for his [imgui](https://github.com/ocornut/imgui) library and
119giving me the inspiration for this library, Casey Muratori for handmade hero
120and his original immediate mode graphical user interface idea and Sean
121Barrett for his amazing single header [libraries](https://github.com/nothings/stb) which restored my faith
122in libraries and brought me to create some of my own.
123
124## License
125```
126------------------------------------------------------------------------------
127This software is available under 2 licenses -- choose whichever you prefer.
128------------------------------------------------------------------------------
129ALTERNATIVE A - MIT License
130Copyright (c) 2017 Micha Mettke
131Permission is hereby granted, free of charge, to any person obtaining a copy of
132this software and associated documentation files (the "Software"), to deal in
133the Software without restriction, including without limitation the rights to
134use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
135of the Software, and to permit persons to whom the Software is furnished to do
136so, subject to the following conditions:
137The above copyright notice and this permission notice shall be included in all
138copies or substantial portions of the Software.
139THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
140IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
141FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
142AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
143LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
144OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
145SOFTWARE.
146------------------------------------------------------------------------------
147ALTERNATIVE B - Public Domain (www.unlicense.org)
148This is free and unencumbered software released into the public domain.
149Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
150software, either in source code form or as a compiled binary, for any purpose,
151commercial or non-commercial, and by any means.
152In jurisdictions that recognize copyright laws, the author or authors of this
153software dedicate any and all copyright interest in the software to the public
154domain. We make this dedication for the benefit of the public at large and to
155the detriment of our heirs and successors. We intend this dedication to be an
156overt act of relinquishment in perpetuity of all present and future rights to
157this software under copyright law.
158THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
159IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
160FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
161AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
162ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
163WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
164-----------------------------------------------------------------------------
165```
166
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}