Entry Point

NAppGUI Overview

NAppGUI is a cross-platform C SDK for native desktop applications. In this checkout it is not just one GUI library: it is a stack of base runtime libraries, drawing and GUI layers, platform backends, optional support libraries, demos, and a resource compiler.

This page is written against commit 2b0099603323ae7a35b8ee6998d35af94f5b16c8 from 2026-03-17, version 1.6.1. All architectural statements here were verified directly against the checked-out source tree.

Relevant Source Files

README.md src/nappgui.h CMakeTargets.cmake prj/version.txt src/osapp/osapp.c src/draw2d/guictx.hxx src/gui/layout.c src/core/dbind.h prj/NAppTarget.cmake

Purpose and Scope

At the public include level, src/nappgui.h pulls in osapp/osapp.h and gui/guiall.h. That makes NAppGUI look like a single framework from the outside, but internally the codebase is split into independent libraries with explicit startup chains and dependency boundaries.

The main desktop story is: use osmain(...), build your UI with gui, let the platform-specific osgui backend provide native widgets and event integration, and optionally add encode, inet, or ogl3d when the application needs them.

Library Stack

Layer Libraries Role
Base runtime sewer, osbs, core Types, assertions, memory, streams, events, files, OS services, DBind, resource packs.
Geometry and drawing geom2d, draw2d Geometry primitives, images, fonts, drawing contexts, and the base GuiCtx interface.
Native backend osgui Platform-specific widgets, windows, menus, cursors, and control wrappers.
High-level UI gui, osapp Controls, layouts, data binding, windows, and application bootstrap/runloop integration.
Optional support encode, inet, ogl3d Encoding/serialization, HTTP transport, and platform OpenGL context management.
Build tooling tools/nrc Resource compiler used by the CMake build to generate embedded or packed assets.

One architecture detail worth keeping in mind is the dependency edge between gui and osgui. In the real CMake graph, both depend on draw2d; osapp is the layer that joins them.

Public Application Shape

The normal public bootstrap path is not a manual call sequence ending in osapp_run(). The demos use osmain(i_create, i_destroy, "", App), and osmain_imp performs the real setup: osgui_start(), gui_start(), native GuiCtx creation, current-context installation, and the internal _osapp_run(...) event loop.

That distinction matters because it explains why the public API surface is smaller than the internal startup sequence. The public application shape is intentionally narrower than the internal bootstrap path.

Cross-Cutting Systems

  • GuiCtx: backend function tables let the high-level GUI layer work without directly depending on one platform implementation.
  • Layout: recursive grid composition with a documented natural-size and expansion pass.
  • DBind: runtime type metadata plus layout/member binding for data-driven controls.
  • Resources: embedded and packed resource modes via nrc, respack, and gui_respack().
  • Events: typed listener callbacks used across UI and core subsystems.

Suggested Reading Paths

If you are new to the codebase, start with Core Architecture, then move to GuiCtx Abstraction Layer, Layout and Cell Management, and Platform Implementations.

If you need to build with the SDK or package applications, go next to Build System and Configuration. If you need widgets, go to GUI Components.