2017-02-24 21:18:27 +03:00
# Nuklear
2019-12-20 01:29:07 +03:00
[![ ](https://github.com/Immediate-Mode-UI/Nuklear/workflows/C%2FC++%20CI/badge.svg )](https://github.com/Immediate-Mode-UI/Nuklear/actions)
2019-12-04 19:08:37 +03:00
2019-10-25 19:15:13 +03:00
This is a minimal-state, immediate-mode graphical user interface toolkit
2016-04-11 02:34:59 +03:00
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,
2019-10-25 19:15:13 +03:00
a default render backend or OS window/input handling but instead provides a
highly modular, library-based approach, with simple input state for input and
draw commands describing primitive shapes as output. So instead of providing a
2015-09-17 18:31:43 +03:00
layered library that tries to abstract over a number of platform and
2019-10-25 19:15:13 +03:00
render backends, it focuses only on the actual UI.
2015-03-11 16:00:59 +03:00
2015-03-14 19:05:30 +03:00
## Features
2017-02-24 21:18:27 +03:00
2019-10-25 19:15:13 +03:00
- Immediate-mode graphical user interface toolkit
- Single-header library
2015-03-14 19:05:30 +03:00
- Written in C89 (ANSI C)
2017-08-20 01:45:46 +03:00
- Small codebase (~18kLOC)
2016-01-26 16:52:00 +03:00
- Focus on portability, efficiency and simplicity
2016-04-11 02:34:59 +03:00
- No dependencies (not even the standard library if not wanted)
2016-03-26 18:05:19 +03:00
- Fully skinnable and customizable
2019-10-25 19:15:13 +03:00
- Low memory footprint with total control of memory usage if needed / wanted
2015-04-30 17:12:21 +03:00
- UTF-8 support
2016-04-11 02:34:59 +03:00
- No global or hidden state
2016-04-19 11:23:33 +03:00
- Customizable library modules (you can compile and use only what you need)
2016-04-11 02:34:59 +03:00
- Optional font baker and vertex buffer output
2020-04-30 13:41:07 +03:00
- [Documentation ](https://Immediate-Mode-UI.github.io/Nuklear/doc/nuklear.html )
2015-11-19 23:02:36 +03:00
## Building
2017-02-24 21:18:27 +03:00
2019-10-25 19:15:13 +03:00
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
2016-04-11 02:34:59 +03:00
by default when included and allows including this header in other headers
and does not contain the actual implementation.
2019-10-25 19:15:13 +03:00
The implementation mode requires defining the preprocessor macro
2016-05-02 15:44:22 +03:00
`NK_IMPLEMENTATION` in *one* .c/.cpp file before `#include` ing this file, e.g.:
2016-04-11 02:34:59 +03:00
```c
2016-05-02 15:44:22 +03:00
#define NK_IMPLEMENTATION
#include "nuklear.h"
2016-04-11 02:34:59 +03:00
```
2016-09-04 21:46:23 +03:00
IMPORTANT: Every time you include "nuklear.h" you have to define the same optional flags.
2019-10-25 19:15:13 +03:00
This is very important; not doing it either leads to compiler errors, or even worse, stack corruptions.
2015-09-17 18:31:43 +03:00
2015-05-09 16:22:23 +03:00
## Gallery
2017-02-24 21:18:27 +03:00
2015-12-12 13:53:15 +03:00
![screenshot ](https://cloud.githubusercontent.com/assets/8057201/11761525/ae06f0ca-a0c6-11e5-819d-5610b25f6ef4.gif )
2016-03-04 22:46:45 +03:00
![screen ](https://cloud.githubusercontent.com/assets/8057201/13538240/acd96876-e249-11e5-9547-5ac0b19667a0.png )
![screen2 ](https://cloud.githubusercontent.com/assets/8057201/13538243/b04acd4c-e249-11e5-8fd2-ad7744a5b446.png )
2015-09-19 18:59:10 +03:00
![node ](https://cloud.githubusercontent.com/assets/8057201/9976995/e81ac04a-5ef7-11e5-872b-acd54fbeee03.gif )
2016-06-12 17:14:24 +03:00
![skinning ](https://cloud.githubusercontent.com/assets/8057201/15991632/76494854-30b8-11e6-9555-a69840d0d50b.png )
2016-04-29 00:54:13 +03:00
![gamepad ](https://cloud.githubusercontent.com/assets/8057201/14902576/339926a8-0d9c-11e6-9fee-a8b73af04473.png )
2015-05-09 16:22:23 +03:00
2015-04-25 17:44:43 +03:00
## Example
2017-02-24 21:18:27 +03:00
2015-04-25 17:44:43 +03:00
```c
2015-12-30 18:31:08 +03:00
/* init gui state */
2016-04-11 02:34:59 +03:00
struct nk_context ctx;
nk_init_fixed(& ctx, calloc(1, MAX_MEMORY), MAX_MEMORY, &font);
2015-12-30 18:31:08 +03:00
2015-08-05 13:48:01 +03:00
enum {EASY, HARD};
2017-03-17 22:24:28 +03:00
static int op = EASY;
static float value = 0.6f;
static int i = 20;
2015-12-30 18:31:08 +03:00
2016-10-30 00:23:46 +03:00
if (nk_begin(& ctx, "Show", nk_rect(50, 50, 220, 220),
2016-09-18 03:31:45 +03:00
NK_WINDOW_BORDER|NK_WINDOW_MOVABLE|NK_WINDOW_CLOSABLE)) {
2016-01-04 23:34:48 +03:00
/* fixed widget pixel width */
2016-04-11 02:34:59 +03:00
nk_layout_row_static(& ctx, 30, 80, 1);
2016-09-18 03:31:45 +03:00
if (nk_button_label(& ctx, "button")) {
2016-01-04 23:34:48 +03:00
/* event handling */
2015-12-30 18:31:08 +03:00
}
2015-06-28 11:09:53 +03:00
2016-01-04 23:34:48 +03:00
/* fixed widget window ratio width */
2016-04-11 02:34:59 +03:00
nk_layout_row_dynamic(& ctx, 30, 2);
2016-09-18 03:31:45 +03:00
if (nk_option_label(& ctx, "easy", op == EASY)) op = EASY;
if (nk_option_label(& ctx, "hard", op == HARD)) op = HARD;
2016-01-04 23:34:48 +03:00
/* custom widget pixel width */
2016-04-11 02:34:59 +03:00
nk_layout_row_begin(& ctx, NK_STATIC, 30, 2);
2016-01-04 23:34:48 +03:00
{
2016-04-11 02:34:59 +03:00
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);
2015-04-25 17:44:43 +03:00
}
2016-04-11 02:34:59 +03:00
nk_layout_row_end(&ctx);
2015-04-25 17:44:43 +03:00
}
2016-09-18 03:31:45 +03:00
nk_end(&ctx);
2015-04-25 17:44:43 +03:00
```
2015-09-30 11:23:45 +03:00
![example ](https://cloud.githubusercontent.com/assets/8057201/10187981/584ecd68-675c-11e5-897c-822ef534a876.png )
2015-04-25 17:44:43 +03:00
2017-02-24 21:18:27 +03:00
## Bindings
2021-12-01 05:45:48 +03:00
There are a number of nuklear bindings for different languages created by other authors.
2019-10-25 19:15:13 +03:00
I cannot attest for their quality since I am not necessarily proficient in any of these
2017-02-24 21:18:27 +03:00
languages. Furthermore there are no guarantee that all bindings will always be kept up to date:
2016-05-17 19:37:13 +03:00
2017-02-24 21:18:27 +03:00
- [Java ](https://github.com/glegris/nuklear4j ) by Guillaume Legris
2019-06-07 01:06:01 +03:00
- [D ](https://github.com/Timu5/bindbc-nuklear ) by Mateusz Muszyński
2017-02-24 21:18:27 +03:00
- [Golang ](https://github.com/golang-ui/nuklear ) by golang-ui@github.com
- [Rust ](https://github.com/snuk182/nuklear-rust ) by snuk182@github.com
2018-01-09 07:52:18 +03:00
- [Chicken ](https://github.com/wasamasa/nuklear ) by wasamasa@github.com
2017-02-24 21:18:27 +03:00
- [Nim ](https://github.com/zacharycarter/nuklear-nim ) by zacharycarter@github.com
2018-04-12 19:48:53 +03:00
- Lua
- [LÖVE-Nuklear ](https://github.com/keharriso/love-nuklear ) by Kevin Harrison
- [MoonNuklear ](https://github.com/stetre/moonnuklear ) by Stefano Trettel
2018-03-24 20:20:26 +03:00
- Python
- [pyNuklear ](https://github.com/billsix/pyNuklear ) by William Emerison Six (ctypes-based wrapper)
- [pynk ](https://github.com/nathanrw/nuklear-cffi ) by nathanrw@github.com (cffi binding)
2018-01-09 07:55:25 +03:00
- [CSharp/.NET ](https://github.com/cartman300/NuklearDotNet ) by cartman300@github.com
2020-02-23 02:32:08 +03:00
- [V ](https://github.com/nsauzede/vnk ) by Nicolas Sauzede
2017-02-24 21:18:27 +03:00
## Credits
2016-04-11 02:34:59 +03:00
Developed by Micha Mettke and every direct or indirect contributor to the GitHub.
2018-02-11 14:28:19 +03:00
Embeds `stb_texedit` , `stb_truetype` and `stb_rectpack` by Sean Barrett (public domain)
2016-05-02 15:44:22 +03:00
Embeds `ProggyClean.ttf` font by Tristan Grimmer (MIT license).
2016-04-11 02:34:59 +03:00
2016-04-29 00:54:13 +03:00
Big thank you to Omar Cornut (ocornut@github) for his [imgui ](https://github.com/ocornut/imgui ) library and
2016-04-11 02:34:59 +03:00
giving me the inspiration for this library, Casey Muratori for handmade hero
2019-10-25 19:15:13 +03:00
and his original immediate-mode graphical user interface idea and Sean
Barrett for his amazing single-header [libraries ](https://github.com/nothings/stb ) which restored my faith
2019-12-04 18:41:37 +03:00
in libraries and brought me to create some of my own. Finally Apoorva Joshi for his single-header [file packer ](http://apoorvaj.io/single-header-packer.html ).
2016-04-11 02:34:59 +03:00
2017-02-24 21:18:27 +03:00
## License
2018-01-02 12:50:19 +03:00
```
------------------------------------------------------------------------------
This software is available under 2 licenses -- choose whichever you prefer.
------------------------------------------------------------------------------
ALTERNATIVE A - MIT License
Copyright (c) 2017 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.
2018-01-02 12:47:08 +03:00
-----------------------------------------------------------------------------
2018-01-02 12:50:19 +03:00
```
2020-03-08 22:19:30 +03:00
## Reviewers guide
When reviewing pull request there are common things a reviewer should keep
in mind.
Reviewing changes to `src/*` and `nuklear.h` :
* Ensure C89 compatibility.
* The code should work for several backends to an acceptable degree.
2020-03-31 15:52:08 +03:00
* Check no other parts of `nuklear.h` are related to the PR and thus nothing is missing.
2020-03-08 22:19:30 +03:00
* Recommend simple optimizations.
* Pass small structs by value instead of by pointer.
* Use local buffers over heap allocation when possible.
* Check that the coding style is consistent with code around it.
* Variable/function name casing.
* Indentation.
* Curly bracket (`{}`) placement.
2021-12-01 05:45:48 +03:00
* Ensure that the contributor has bumped the appropriate version in
2021-12-15 02:36:03 +03:00
[clib.json ](https://github.com/Immediate-Mode-UI/Nuklear/blob/master/clib.json )
2020-03-08 22:19:30 +03:00
and added their changes to the
[CHANGELOG ](https://github.com/Immediate-Mode-UI/Nuklear/blob/master/src/CHANGELOG ).
* Have at least one other person review the changes before merging.
Reviewing changes to `demo/*` , `example/*` and other files in the repo:
* Focus on getting working code merged.
* We want to make it easy for people to get started with Nuklear, and any
`demo` and `example` improvements helps in this regard.
* Use of newer C features, or even other languages is not discouraged.
* If another language is used, ensure that the build process is easy to figure out.
* Messy or less efficient code can be merged so long as these outliers are pointed out
and easy to find.
* Version shouldn't be bumped for these changes.
* Changes that improves code to be more inline with `nuklear.h` are ofc always welcome.