sdl2_basic_widgets

A (very) basic and incomplete widget library for SDL applications.

Build

The build dependencies are SDL2, SDL_ttf and fontconfig dev libs and headers. Meson is used as build system, so you'll need it too.

As the code use some C++20 features, you'll need a recent compiler which support that version of the standard.

Then, inside the project root directory, run the following commands:

$ meson build
$ meson compile -C build -j0

After that you'll have in the build directory the static library and the example programs.

API overview

The library API is divided in two main parts:

• the core, which provides some basic wrapping of SDL, SDL_ttf and fontconfig functionalities.
• the widget API built on top of the core.

Core

The main classes of the core are:

• Font: wraps TTF_Font object with the most common operations of SDL_ttf. Also provide a helper function to search system fonts by using fontconfig.
• Renderer: wraps SDL_Renderer object with common operation from the SDL 2D accelerated rendering API.
• Texture: wraps SDL_Texture object with common operations to manipulate it.

Apart from the SDL API wrappers, some generic utility functions and data types are defined:

• Color: wraps SDL_Color object and adds convenience operators overloads to operate on all color channels and/or alpha channel.
• draw.hpp: 2D drawing utilities. Currently, provides a couple of basic utility functions for software rendered textures: circle rendering and an antialising algorithm.
• math.hpp: mostly provides frequently used formulas to work with rectangles and points on a 2D coordinate system.
• concepts.hpp: a few concept definitions for used for generic programming.
• Size: representation of a 2D size. There are also a few operator overloads to operate on Size objects.

Widgets

Widgets are classes that implements the common widget interface and optionally one or more "handler" interfaces. Handlers are interfaces for event or external resources handling.

These interfaces are:

• Widget: the common base interface of every widget.
• EventHandler: base interface for event handlers.
• FocusHandler: base interface for handler having a focus notion.
• KeyboardHandler: interface for key and text input events handling.
• MouseHandler: interface for mouse events handling. Handle click and focus state changes and also introduce a notion of "pushed" state.
• FontHandler: interface for widgets using a font. Declares methods to set the widget font and set background and text color used for text rendering.
• TextureHandler: it exists but I'm thinking now that it shouldn't.

Based on these interfaces, there's implementation for a few basic widgets. Currently, the following ones are defined:

• Button: a push button.
• Caption: a caption that displays a rendered string. No multiline support.
• Input: base class for widgets using an input field.
• NumericInput an input widget for numeric values with two buttons to increase/decrease the hold value.

There are also "containers" widgets which are widget that hold a collection of widgets and manage their geometry:

• Layout: abstract class for container widgets.
• AlignedLayout: layout that is done by distributing widgets on a horizontal or vertical row.

To create widget objects, the corresponding function from widget_factory.hpp should be used. It's done this way for interface-implementation sake.

Source code organization overview

The header and source directory hierarchies is organized in the following way:

• core: C→C++ wrappers and commonly used generic functions.
• core/type: basic data types and concepts.
• w: the widget library
• w/base: the abstract widget classes.
• w/feat: handlers (optional widget features)

Widget code intent to separate public API from implementation details. For that a Widget has two classes, a pure virtual one (Widget) which is the public API and another class (WidgetImpl) that implements the interface of the first one. Unless an access to implementation details is required, the interface (pure virtual) type should be used.