Abstraction Layer

GuiCtx Abstraction Layer

GuiCtx is the central architectural seam in NAppGUI. It lets the high-level gui library compose interfaces without owning the platform-specific code that draws widgets, dispatches native events, or creates windows.

Relevant Source Files

src/draw2d/guictx.hxx src/draw2d/guictx.h src/draw2d/guictx.c src/osgui/osguictx.c src/osgui/osguictx.h

Why It Exists

The top-level comment in guictx.hxx states the design directly: the GUI library knows how to compose and manage interfaces, but it does not directly draw widgets or capture platform input. Those jobs belong to a backend context object, GuiCtx.

This is why the real dependency graph is gui -> draw2d and osgui -> draw2d, not gui -> osgui.

What GuiCtx Contains

GuiCtx is implemented as a large collection of function-pointer tables and manager append helpers. The backend fills in operations for:

  • buttons, popups, edits, combos, sliders, progress bars, views, text views, web views, split views, panels, windows, menus, and common dialogs
  • global OS services such as colors, cursors, display information, transitions, and idle callbacks
  • custom control drawing hooks

The tables are indexed by internal GUI type identifiers, so the higher layers can dispatch platform work uniformly across control families.

Current Backend Implementation

The local repository ships one real backend provider: osguictx() in src/osgui/osguictx.c. That function allocates a fresh GuiCtx and wires every manager to the concrete OS wrapper functions from osgui.

On startup, osmain_imp creates this native context and installs it with guictx_set_current(...). From then on, the high-level GUI layer routes control creation, sizing, events, and window operations through the current backend.

Public Status

GuiCtx is an architectural centerpiece, but it is not presented as a standalone public subsystem. The comments explicitly say it is not currently documented separately and is considered part of the final GUI library.

In practice, this means application authors use the high-level APIs while backend maintainers or contributors work directly against GuiCtx.

Practical Implications

  • Portability: the same layout and widget logic can target Cocoa, Win32, or GTK through one call surface.
  • Isolation: platform wrappers can evolve without forcing the high-level GUI code to depend on platform headers.
  • Limits: the repo comments mention possible future alternative contexts, but this checkout only ships the native one from osgui.