|
guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
|
This guide documents breaking API changes and how to update existing code, newest first. The first group is unreleased; the rest shipped up to 2026.3.1.
Before: every entity had a Builder and a Director; presets were called as director.makeButton(builder, parent, ...), and scenes fetched directors with getDirectorManager().getDirector<X::Director>().
After: the presets are Builder members with the same names and the same remaining arguments: builder.makeButton(parent, ...). X::Director, ecs::EntityDirector, ecs::EntityDirectorManager and Scene::getDirectorManager() are removed.
Update: Drop the director variable and the builder argument:
Before: enum Phase : size_t, implicitly convertible to an integer.
After: enum class Phase : std::size_t. ecs::Phase::Event and the other enumerators are spelled the same; code that used a phase as an array index or printed it needs static_cast<std::size_t>(phase).
Before: Application<MyScene, MyScene> app(resources); followed by app.setEngine(std::move(engine));. The default scene had to be repeated in the scene list, and calling run() before setEngine() dereferenced a null engine.
After: Application<MyScene> app(resources, std::move(engine));. The first template argument is the default scene and every scene is listed once (Application<Home, Settings>); a repeated scene type no longer compiles. A null engine throws std::invalid_argument. setEngine() is gone.
Update: Pass the engine to the constructor and remove the duplicated default scene from the template arguments.
Application::pollEvents(), update(), clear() and present() were removed: they only forwarded to the engine and were not used by run(). Call routine() to run one frame.
Before: engine-backed systems were constructed from a std::unique_ptr<utility::Engine> &.
After: they take a utility::Engine &. SceneManager also takes the engine by reference in its constructor; SceneManager::setEngine() is gone.
Update: Pass *engine when constructing a system yourself.
Before: switchToScene<T>() only changed the active scene type.
After: it calls onExit() on the current scene and onEnter() on the new one, like a transition requested with Scene::goToScene<T>().
Core systems are registered by systems::registerCoreSystems() (guillaume/systems/core_systems.hpp). Include the header of any system you reference directly.
getShapeRadius(), getStateLayerAlpha(), getElevationToken(), getMotionDuration(), getActiveTypescale() and getActiveScheme() now read getActiveTheme() instead of defaultTheme. Behavior is unchanged until you call setActiveTheme(). getActiveColor(role) replaces the getActiveScheme().getColor(role).getColor() chain.
Before: every entity had a Builder and a Director; presets were called as director.makeButton(builder, parent, ...), and scenes fetched directors with getDirectorManager().getDirector<X::Director>().
After: the presets are Builder members with the same names and the same remaining arguments: builder.makeButton(parent, ...). X::Director, ecs::EntityDirector, ecs::EntityDirectorManager and Scene::getDirectorManager() are removed.
Update: Drop the director variable and the builder argument:
Before: Application<MyScene, MyScene> app(resources); followed by app.setEngine(std::move(engine));. The default scene had to be repeated in the scene list, and calling run() before setEngine() dereferenced a null engine.
After: Application<MyScene> app(resources, std::move(engine));. The first template argument is the default scene and every scene is listed once (Application<Home, Settings>); a repeated scene type no longer compiles. A null engine throws std::invalid_argument. setEngine() is gone.
Update: Pass the engine to the constructor and remove the duplicated default scene from the template arguments.
Application::pollEvents(), update(), clear() and present() were removed: they only forwarded to the engine and were not used by run(). Call routine() to run one frame.
Before: engine-backed systems were constructed from a std::unique_ptr<utility::Engine> &.
After: they take a utility::Engine &. SceneManager also takes the engine by reference in its constructor; SceneManager::setEngine() is gone.
Update: Pass *engine when constructing a system yourself.
Before: switchToScene<T>() only changed the active scene type.
After: it calls onExit() on the current scene and onEnter() on the new one, like a transition requested with Scene::goToScene<T>().
Core systems are registered by systems::registerCoreSystems() (guillaume/systems/core_systems.hpp). Include the header of any system you reference directly.
getShapeRadius(), getStateLayerAlpha(), getElevationToken(), getMotionDuration(), getActiveTypescale() and getActiveScheme() now read getActiveTheme() instead of defaultTheme. Behavior is unchanged until you call setActiveTheme(). getActiveColor(role) replaces the getActiveScheme().getColor(role).getColor() chain.
Before: getEntity<EntityType>(id) threw std::runtime_error when the entity was not found or was not of the expected type.
After: getEntity<EntityType>(id) returns nullptr when the entity is not found or is not of the expected type. It also returns nullptr for Entity::InvalidIdentifier.
Update: Check the returned pointer for nullptr instead of wrapping the call in a try/catch.
Before: getActiveScene() returned std::unique_ptr<Scene>&, exposing mutable ownership of an internal unique_ptr.
After: getActiveScene() returns a Scene*. Callers must not delete the returned pointer; the scene manager retains ownership.
Update: Most call sites that used -> continue to work unchanged. If you stored the result as std::unique_ptr<Scene>&, change it to Scene*.
Before: subscribe<EventType>(const Listener &listener).
After: subscribe<EventType>(Listener listener) (moved into the bus).
Update: Existing call sites that pass a lambda or std::function continue to work unchanged.
Before: getSystemsByPhase(phase) used std::map::at, throwing std::out_of_range for an invalid phase.
After: getSystemsByPhase(phase) returns an empty vector for a valid phase with no systems, and throws std::out_of_range only for an invalid phase value.
Update: No change required for valid phases.
Before: Entity was abstract; derived entities had to implement initialize() and update().
After: Both have default no-op implementations. Derived entities may still override them.
Before: A widget was built in two steps: construct it, then call initialize() (the entity registry did it when the entity was added) so it could create its children.
After: Constructors are private. create() takes the same arguments and returns the widget fully built. Entity::initialize() no longer exists and EntityRegistry::addEntity() no longer calls anything on the entity.
Update:
Before: ecs::System::routine called update() on an entity whose components had changed, then on its parent. Library widgets restyled and re-arranged themselves there.
After: Systems are the only place behavior lives. Every library widget is a facade without fields; its rules are static functions of a system named after it (systems::Checkbox::apply, systems::Button::release, ...), run every frame in the Layout phase and callable on an identifier. Entity::update() no longer exists, and neither does the unused components::Parent (use components::Hierarchy).
Update:
Update: No change required; existing overrides continue to work.
Several trivial getters (e.g. Entity::getIdentifier, Entity::getSignature, Entity::getLayer, Entity::getParent, System::getPhase, System::getSignature) are now noexcept. This is source-compatible.
Identifier generation is now thread-safe. No source change is required.
The Panel, Container and Layout entities are gone. entities::View is the layout container: it keeps the surface behavior (pose, color, border radius) and delegates child arrangement to components::Layout + systems::Layout.
View::Builder exposes:
The geometry is produced by systems::Layout, a core system of the Layout phase. It positions the children and writes the resulting size back to the view's components::Bound. There is no margin: nest a View or adjust the pose instead.
Update: Replace the old container with View and its builder presets:
Several defaults changed to match react-native-paper v5. See docs/THEMING.md for the token layer.