Docs / Packages / nuklear

nuklear

Kindffi-c
Capabilitiesffi
Categoriesgui ffi
Keywordsgui ui nuklear immediate-mode graphics

Nuklear immediate-mode GUI library bindings for Kit

Files

FileDescription
.editorconfigEditor formatting configuration
.gitignoreGit ignore rules for build artifacts and dependencies
.tool-versionsasdf tool versions (Zig, Kit)
LICENSEMIT license file
README.mdThis file
c/kit_nuklear.cC FFI wrapper and SDL renderer bridge
c/kit_nuklear.hC header for the FFI wrapper
c/nuklear.hVendored Nuklear single-header library
examples/demo.kitWidget demo with buttons, sliders, progress, checkbox, and options
examples/sdl-demo.kitSDL integration demo with input forwarding
examples/simple.kitMinimal SDL-backed Nuklear example
kit.tomlPackage manifest with metadata, native build settings, and tasks
src/nuklear.kitKit API for Nuklear context, widgets, input, and command iteration
tests/module-structure.test.kitExport and module structure tests
tests/nuklear.test.kitImport smoke test

Dependencies

No Kit package dependencies.

Native dependencies:

DependencyPurpose
SDL2Windowing and renderer integration for examples and render-sdl
SDL2_ttfFont initialization used by the C wrapper

Install native dependencies on macOS:

brew install sdl2 sdl2_ttf

Install native dependencies on Ubuntu:

sudo apt-get install libsdl2-dev libsdl2-ttf-dev

Installation

kit add gitlab.com/kit-lang/packages/kit-nuklear.git

Usage

import Kit.Nuklear as Nk
import Kit.Sdl as SDL

main = fn =>
  match SDL.init
    | Ok _ ->
      defer SDL.quit

      match SDL.create-window "Nuklear App" 640 480
        | Ok window ->
          defer SDL.destroy-window window

          match SDL.create-renderer window
            | Ok renderer ->
              defer SDL.destroy-renderer renderer

              ctx = Nk.init 65536
              defer Nk.free ctx

              Nk.input-begin ctx
              # Feed SDL events here with Nk.input-motion, Nk.input-button,
              # Nk.input-scroll, and Nk.input-key.
              Nk.input-end ctx

              flags = Int.bit-or (Nk.flag-border) (Nk.flag-title)
              if Nk.begin? ctx "Demo" 50.0 50.0 240.0 160.0 flags then
                Nk.layout-row-dynamic ctx 30.0 1
                Nk.label ctx "Hello from Nuklear" Nk.text-centered
                if Nk.button-label? ctx "Click me" then
                  println "Button clicked"
                else
                  no-op
                Nk.end ctx
              else
                Nk.end ctx

              SDL.set-draw-color renderer 30 30 30 255
              SDL.clear renderer
              Nk.render-sdl ctx renderer.ptr
              SDL.present renderer
              Nk.clear ctx
            | Err err ->
              println "Renderer error: ${err}"
        | Err err ->
          println "Window error: ${err}"
    | Err err ->
      println "SDL init error: ${err}"

main

API Overview

Context management:

  • init, free, clear

Window and layout:

  • begin?, end, window-close, window-is-closed?, window-is-hidden?
  • layout-row-dynamic, layout-row-static, layout-row-begin, layout-row-push, layout-row-end, spacing

Widgets:

  • label, label-colored, label-wrap
  • button-label?, button-color?
  • check-label?, option-label?
  • slide-float, slide-int, prog, propertyi, propertyf
  • group-begin?, group-end, tree-push?, tree-pop
  • popup-begin?, popup-close, popup-end, tooltip
  • menubar-begin, menubar-end, menu-begin-label?, menu-item-label?, menu-close, menu-end
  • combo-begin-label?, combo-item-label?, combo-close, combo-end

Input and rendering:

  • input-begin, input-end, input-motion, input-button, input-scroll, input-key
  • render-sdl
  • command-begin, command-next, command-type for custom renderers

Constants:

  • Window flags: flag-border, flag-movable, flag-scalable, flag-closable, flag-minimizable, flag-no-scrollbar, flag-title
  • Text alignment: text-left, text-centered, text-right
  • Mouse buttons and keys: mouse-button-left, mouse-button-middle, mouse-button-right, key-shift, key-ctrl, key-del, key-enter, key-tab, key-backspace, key-up, key-down, key-left, key-right
  • Command types: cmd-nop, cmd-scissor, cmd-line, cmd-rect, cmd-rect-filled, cmd-circle, cmd-circle-filled, cmd-triangle, cmd-triangle-filled, cmd-text

Rendering Notes

Nuklear owns UI state and emits draw commands; it does not create windows or process platform events by itself. This package provides an SDL renderer helper (render-sdl) and lower-level command iteration for custom renderers.

Typical frame flow:

  1. Call input-begin
  2. Forward SDL input events into Nuklear
  3. Call input-end
  4. Build UI with begin?, layout calls, widgets, and end
  5. Render with render-sdl or iterate commands manually
  6. Call clear

Development

Running Examples

Run examples with the interpreter:

kit run examples/simple.kit
kit run examples/demo.kit
kit run examples/sdl-demo.kit

Compile examples to native binaries:

kit build examples/simple.kit && ./simple

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check examples, test):

kit dev --no-spinner

This will:

  1. Verify the native library is current
  2. Check formatting
  3. Type check src/
  4. Type check examples
  5. Run tests with coverage

Running Parity

Check interpreter/build parity for examples:

kit parity --no-spinner --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/nuklear/, making it available for import as Kit.Nuklear in other projects.

License

This package is released under the MIT License - see LICENSE for details.

The bundled c/nuklear.h library is public domain / MIT licensed by the Nuklear project.

Exported Functions & Types

init

Initialize a Nuklear context with the given memory size.

Parameters:

Returns:

PositiveInt -> Ptr

free

Free a Nuklear context and release all resources.

Ptr -> Unit

clear

Clear the command buffer. Call this at the end of each frame.

Ptr -> Unit

flag-border

Window has a visible border.

Int

flag-movable

Window can be moved by dragging the header.

Int

flag-scalable

Window can be resized by dragging the corner.

Int

flag-closable

Window has a close button.

Int

flag-minimizable

Window can be minimized.

Int

flag-no-scrollbar

Window has no scrollbar.

Int

flag-title

Window always shows the title bar.

Int

text-left

Left-aligned text.

Int

text-centered

Center-aligned text.

Int

text-right

Right-aligned text.

Int

begin?

Begin a new window. Returns true if window is visible.

Parameters:

Ptr -> NonEmptyString -> Float -> Float -> Float -> Float -> Int -> Bool

flags = Nk.flag-border ||| Nk.flag-movable ||| Nk.flag-title
if Nk.begin? ctx "My Window" 50.0 50.0 200.0 200.0 flags then
  # ... window contents ...
  Nk.end ctx

end

End the current window.

Ptr -> Unit

window-is-closed?

Check if a window has been closed.

Ptr -> NonEmptyString -> Bool

window-is-hidden?

Check if a window is hidden.

Ptr -> NonEmptyString -> Bool

window-close

Close a window by name.

Ptr -> NonEmptyString -> Unit

window-get-width

Get the current window width.

Ptr -> Float

window-get-height

Get the current window height.

Ptr -> Float

window-has-focus?

Check if the current window has focus.

Ptr -> Bool

window-is-hovered?

Check if the current window is hovered.

Ptr -> Bool

item-is-any-active?

Check if any item is currently active.

Ptr -> Bool

layout-row-dynamic

Create a dynamic row with equally sized columns.

Parameters:

    Ptr -> Float -> Int -> Unit

layout-row-static

Create a static row with fixed-width columns.

Parameters:

    Ptr -> Float -> Int -> Int -> Unit

layout-row-begin

Begin a custom row layout.

Ptr -> Int -> Float -> Int -> Unit

layout-row-push

Push a column width for custom row layout.

Ptr -> Float -> Unit

layout-row-end

End a custom row layout.

Ptr -> Unit

spacing

Add spacing columns.

Ptr -> Int -> Unit

label

Display a text label.

Parameters:

    Ptr -> String -> Int -> Unit

label-colored

Display a colored text label.

Ptr -> String -> Int -> Byte -> Byte -> Byte -> Byte -> Unit

label-wrap

Display a wrapping text label.

Ptr -> String -> Unit

button-label?

Create a button with a text label. Returns true if clicked.

Ptr -> NonEmptyString -> Bool

button-color?

Create a colored button. Returns true if clicked.

Ptr -> Byte -> Byte -> Byte -> Byte -> Bool

check-label?

Create a checkbox (toggle). Returns new state.

Parameters:

Returns:

Ptr -> String -> Bool -> Bool

option-label?

Create a radio button option. Returns true if selected.

Parameters:

    Ptr -> String -> Bool -> Bool

slide-float

Create a float slider. Returns the new value.

Parameters:

    Ptr -> Float -> Float -> Float -> Float -> Float

slide-int

Create an integer slider. Returns the new value.

Ptr -> Int -> Int -> Int -> Int -> Int

prog

Create a progress bar. Returns the new value.

Parameters:

    Ptr -> Int -> Int -> Bool -> Int

propertyi

Create an integer property (label + value + increment buttons).

Ptr -> NonEmptyString -> Int -> Int -> Int -> Int -> Float -> Int

propertyf

Create a float property.

Ptr -> NonEmptyString -> Float -> Float -> Float -> Float -> Float -> Float

group-begin?

Begin a group (scrollable sub-region). Returns true if visible.

Ptr -> NonEmptyString -> Int -> Bool

group-end

End a group.

Ptr -> Unit

tree-node

Tree node type constant.

Int

tree-tab

Tree tab type constant.

Int

minimized

Minimized state constant.

Int

maximized

Maximized state constant.

Int

tree-push?

Begin a tree node. Returns true if expanded.

Ptr -> Int -> NonEmptyString -> Int -> Bool

tree-pop

End a tree node.

Ptr -> Unit

input-begin

Begin input handling. Call before feeding input events.

Ptr -> Unit

input-end

End input handling. Call after all input events are fed.

Ptr -> Unit

input-motion

Feed mouse motion event.

Ptr -> Int -> Int -> Unit

input-button

Feed mouse button event.

Parameters:

    Ptr -> Int -> Int -> Int -> Bool -> Unit

input-scroll

Feed scroll event.

Ptr -> Float -> Float -> Unit

input-key

Feed key event.

Ptr -> Int -> Bool -> Unit

mouse-button-left

Mouse button constants.

Int

mouse-button-middle

Middle mouse button constant.

Int

mouse-button-right

Right mouse button constant.

Int

key-shift

Shift key constant.

Int

key-ctrl

Ctrl key constant.

Int

key-del

Delete key constant.

Int

key-enter

Enter key constant.

Int

key-tab

Tab key constant.

Int

key-backspace

Backspace key constant.

Int

key-up

Up arrow key constant.

Int

key-down

Down arrow key constant.

Int

key-left

Left arrow key constant.

Int

key-right

Right arrow key constant.

Int

render-sdl

Render all Nuklear commands to an SDL renderer.

Parameters:

Ptr -> Ptr -> Unit

SDL.clear renderer
Nk.render-sdl ctx renderer
SDL.present renderer

command-begin

Get the first command in the buffer. Returns null if empty.

Ptr -> Ptr

command-next

Get the next command. Returns null if no more commands.

Ptr -> Ptr -> Ptr

command-type

Get the type of a command.

Ptr -> Int

cmd-nop

No-operation command type constant.

Int

cmd-scissor

Scissor command type constant.

Int

cmd-line

Line command type constant.

Int

cmd-rect

Rectangle command type constant.

Int

cmd-rect-filled

Filled rectangle command type constant.

Int

cmd-circle

Circle command type constant.

Int

cmd-circle-filled

Filled circle command type constant.

Int

cmd-triangle

Triangle command type constant.

Int

cmd-triangle-filled

Filled triangle command type constant.

Int

cmd-text

Text command type constant.

Int

Static popup type constant.

Int

Dynamic popup type constant.

Int

popup-begin?

Begin a popup window. Returns true if visible.

Ptr -> Int -> NonEmptyString -> Int -> Float -> Float -> Float -> Float -> Bool

Close the current popup.

Ptr -> Unit

End a popup.

Ptr -> Unit

tooltip

Show a simple tooltip at current widget position.

Ptr -> String -> Unit

Begin the menubar.

Ptr -> Int

End the menubar.

Ptr -> Unit

menu-begin-label?

Begin a menu. Returns true if open.

Ptr -> String -> Int -> Float -> Float -> Bool

menu-item-label?

Create a menu item. Returns true if clicked.

Ptr -> String -> Int -> Bool

Close the current menu.

Ptr -> Unit

End a menu.

Ptr -> Unit

combo-begin-label?

Begin a combo box. Returns true if open.

Ptr -> String -> Float -> Float -> Bool

combo-item-label?

Create a combo item. Returns true if clicked.

Ptr -> String -> Int -> Bool

combo-close

Close the current combo.

Ptr -> Unit

combo-end

End a combo box.

Ptr -> Unit