Nuklear README

The project's README from github.com/Immediate-Mode-UI/Nuklear. As one markdown file: README.md.

Nuklear

This is a minimal-state, immediate-mode graphical user interface toolkit 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, 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 layered library that tries to abstract over a number of platform and render backends, it focuses only on the actual UI.

Features

Usage

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 by default when included and allows including this header in other headers and does not contain the actual implementation.

The implementation mode requires defining the preprocessor macro NK_IMPLEMENTATION in one .c/.cpp file before #includeing this file, e.g.:

#define NK_IMPLEMENTATION
#include "nuklear.h"

IMPORTANT: Every time you include "nuklear.h" you have to define the same optional flags. This is very important; not doing it either leads to compiler errors, or even worse, stack corruptions.

screenshot screen screen2 node skinning gamepad

Example

The example below shows the general structure of a Nuklear application: one-time setup, then once per frame mirror the input, build the user interface and draw it. Nuklear does no rendering itself, so the parts marked your_... are provided by your rendering backend:

/* init gui state (once at startup) */
struct nk_user_font font;
struct nk_context ctx;

font.userdata = nk_handle_ptr(your_font_data);
font.height = your_font_height;
font.width = your_text_width_calculation;
nk_init_fixed(&ctx, calloc(1, MAX_MEMORY), MAX_MEMORY, &font);

while (running) {
    /* mirror your window's input state into nuklear */
    nk_input_begin(&ctx);
    /* nk_input_motion(&ctx, ...), nk_input_button(&ctx, ...),
     * nk_input_key(&ctx, ...), ... */
    nk_input_end(&ctx);

    /* build the user interface */
    {
        enum {EASY, HARD};
        static int op = EASY;
        static float value = 0.6f;

        if (nk_begin(&ctx, "Show", nk_rect(50, 50, 220, 220),
            NK_WINDOW_BORDER|NK_WINDOW_MOVABLE|NK_WINDOW_CLOSABLE)) {
            /* fixed widget pixel width */
            nk_layout_row_static(&ctx, 30, 80, 1);
            if (nk_button_label(&ctx, "button")) {
                /* event handling */
            }

            /* fixed widget window ratio width */
            nk_layout_row_dynamic(&ctx, 30, 2);
            if (nk_option_label(&ctx, "easy", op == EASY)) op = EASY;
            if (nk_option_label(&ctx, "hard", op == HARD)) op = HARD;

            /* custom widget pixel width */
            nk_layout_row_begin(&ctx, NK_STATIC, 30, 2);
            {
                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);
            }
            nk_layout_row_end(&ctx);
        }
        nk_end(&ctx);
    }

    /* draw: hand this frame's draw commands to your renderer */
    {
        const struct nk_command *cmd;
        nk_foreach(cmd, &ctx) {
            switch (cmd->type) {
            case NK_COMMAND_LINE:
                your_draw_line_function((const struct nk_command_line*)cmd);
                break;
            case NK_COMMAND_RECT:
                your_draw_rect_function((const struct nk_command_rect*)cmd);
                break;
            default:
                /* [...] */
                break;
            }
        }
        nk_clear(&ctx);
    }
}

Ready-to-use rendering backends for GLFW, SDL, X11, GDI, Direct3D, Vulkan and more are in the demo folder, each with its own build instructions, e.g.:

make -C demo/glfw_opengl3

More complete programs can be found in the example folder. Rendered by one of the backends, the interface built above looks like this:

example

Bindings

There are a number of nuklear bindings for different languages created by other authors. I cannot attest for their quality since I am not necessarily proficient in any of these languages. Furthermore there are no guarantee that all bindings will always be kept up to date:

Credits

Developed by Micha Mettke and every direct or indirect contributor to the GitHub.

Embeds stb_texedit, stb_truetype and stb_rectpack by Sean Barrett (public domain) Embeds ProggyClean.ttf font by Tristan Grimmer (MIT license).

Big thank you to Omar Cornut (ocornut@github) for his imgui library and giving me the inspiration for this library, Casey Muratori for handmade hero and his original immediate-mode graphical user interface idea and Sean Barrett for his amazing single-header libraries which restored my faith in libraries and brought me to create some of my own. Finally Apoorva Joshi for his single-header file packer.

License

Nuklear is avaliable under either the MIT License or public domain. See LICENSE for more info.

Nuklear (Immediate-Mode-UI/Nuklear)

Searching Database…

11.5K ·GitHub
Nuklear
Что это такое?Nuklear — это минималистичный тулкит для графических интерфейсов в стиле immediate mode, написанный на ANSI C. Он задуман как простой встраиваемый UI, который вы собираете прямо в своё приложение.
Это библиотека, которую я компилирую в своё приложение, или отдельная программа?Это C-библиотека из одного заголовочного файла. Она занимается только самим интерфейсом: встроенного рендерера нет, как нет и работы с окнами ОС или вводом — подключить всё это ваша задача.
Как добавить её в свой проект?Скопируйте один заголовочный файл. Режим header-only работает по умолчанию; чтобы скомпилировать реализацию, определите NK_IMPLEMENTATION в одном файле .c/.cpp до подключения nuklear.h.
Нужно ли сначала установить какие-то другие библиотеки?Нет. У неё ноль зависимостей — её можно собрать даже без стандартной библиотеки C, а весь код занимает около 18 тысяч строк на C89.
Есть ли подводные камни при подключении?Да. При каждом подключении nuklear.h должны быть заданы одни и те же необязательные флаги; если их перепутать, будут ошибки компиляции, а в худшем случае — повреждение стека.
Если она сама ничего не рисует, как вывести интерфейс на экран?Нужно подключить бэкенд для рендеринга. В папке demo есть готовые бэкенды для GLFW, SDL, X11, GDI, Direct3D и Vulkan, и у каждого своя инструкция по сборке.
Есть ли что-то необычное в лицензии?Лицензия максимально свободная: можно использовать её под MIT License или как общественное достояние — как больше подходит вашему проекту.
Как Nuklear связана с Dear ImGui?Автор называет библиотеку imgui Омара Корню (Omar Cornut) прямым источником вдохновения. Nuklear взяла ту же идею immediate mode и реализовала её с нуля на ANSI C в виде компактного (~18 тысяч строк) единого заголовка без зависимостей.
Как выглядит написание приложения с её использованием?Один раз выполняется настройка, а затем в каждом кадре вы передаёте ввод в Nuklear, строите интерфейс и отрисовываете её команды через свой рендер-бэкенд — пример в README показывает именно такую структуру.
Можно ли использовать её из языков, кроме C?Да, через биндинги от сообщества для Java, D, Go, Rust, Nim, Lua, Python, C#/.NET, V и других. Их поддерживают сторонние авторы, поэтому качество и актуальность разные.
Насколько я могу управлять памятью и внешним видом?Очень сильно: интерфейс полностью настраивается и меняет оформление, расход памяти минимальный с полным контролем над её использованием, нет глобального или скрытого состояния, есть опциональный генератор шрифтов и вывод в вершинный буфер, плюс поддержка UTF-8.
What are similar projects?nuklear, imgui, sokol, DearPyGui, iced, cJSON, bgfx, DEsk
Which topics is it in?single-header-lib, imgui, multiplatform, directx, header-only, x11, toolkit, no-dependencies, vulkan, embedded, graphics, c
Creator
Immediate-Mode-UI
Size
21.1 MB
Stars
11.5K
Updated
CommitSep 20Releasev4.13.3May 05
Age
6y
Commits · 90 Days