Foundations

Core Architecture

The main architectural story in NAppGUI is layered initialization plus strict separation between high-level UI composition and the native backend implementation. The result is a portable public API over real native platform code.

Relevant Source Files

CMakeTargets.cmake src/core/core.cpp src/draw2d/draw2d.c src/osgui/osgui.c src/gui/gui.c src/osapp/osapp.c src/core/event.h src/core/respack.c

Layer Model

The library graph is not accidental. Each layer introduces one kind of abstraction:

  • sewer and osbs provide low-level utilities and OS services.
  • core adds containers, streams, events, DBind, and resource packs.
  • geom2d and draw2d add geometry, imaging, fonts, and drawing contexts.
  • osgui implements native widgets and windows for one platform.
  • gui composes widgets, layouts, panels, and data binding against the abstract backend.
  • osapp owns the application lifecycle and connects the UI stack to the native event loop.

Startup Chain

Function Main Action
core_start() Starts osbs, heap, stream, and DBind; registers built-in scalar, string, and container types.
draw2d_start() Starts core, allocates font/image globals, and registers Image as a DBind binary type.
osgui_start() Starts draw2d and the platform GUI backend.
gui_start() Starts draw2d, resource packs, windows, menus, colors, notifications, and transitions.
osmain_imp() Starts osgui and gui, creates the native GuiCtx, and enters the platform runloop.

Because both gui and osgui sit on top of draw2d, the architecture avoids a direct high-level-to-native compile-time dependency.

Events and Notifications

NAppGUI uses a typed listener model rather than a string-based event bus. A Listener stores an object plus a handler, and an Event carries the event type, sender, params, and result. In debug builds the framework also tracks type names for sender, params, and result and asserts that handlers read them consistently.

This same event model is used for button clicks, window close notifications, draw callbacks, DBind object-change events, theme changes, and idle notifications.

Resources and Localization

Resource loading is built into the architecture, not bolted on. The core ResPack layer supports embedded and packed assets, while the gui layer adds high-level registration and language selection through gui_respack() and gui_language().

This is why many demos register a resource pack before constructing windows: localized strings, images, and binary assets are part of the normal application model.

Extension Libraries

The architecture also leaves room for non-UI layers:

  • encode builds on core for JSON, URL, and base64 helpers.
  • inet adds HTTP on top of encode.
  • ogl3d adds platform OpenGL context management without depending on the full GUI umbrella.