guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::entities::Badge Class Reference

A small colored pill showing a count or a short label, or a plain status dot (react-native-paper Badge). More...

#include <headers/guillaume/entities/badge.hpp>

Inheritance diagram for guillaume::entities::Badge:
Collaboration diagram for guillaume::entities::Badge:

Classes

class  Builder
 Configures Badge widgets and registers them in the scene's entity registry. More...

Public Types

using Variant = components::Badge::Variant
Public Types inherited from guillaume::entities::SurfaceBase< components::Animation, components::Badge >
using Children
Public Types inherited from guillaume::ecs::Entity
using Identifier = std::size_t
 The key under which an entity's components are stored. Systems and components refer to entities by this value.
using Signature = std::bitset<128>
 A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits).

Public Member Functions

 ~Badge (void) override
 Destructor.
Badge & setVariant (Variant variant)
 Change the size class of the badge. Resizes at once.
Variant getVariant (void) const
 Get the size class of the badge.
Badge & setLabel (const std::string &label)
 Change the text shown in the badge. Restyles at once.
Badge & setSize (float size)
 Override the height of the variant (Paper size). Resizes at once.
Badge & clearSize (void)
 Drop the height override and use the height of the variant again. Resizes at once.
float getSize (void) const
 Get the height the badge is drawn with.
Badge & setContainerColor (const utility::graphic::Color32Bit &color)
 Override the fill color of the pill. Restyles at once.
Badge & setContentColor (const utility::graphic::Color32Bit &color)
 Override the color of the label. Restyles at once.
Badge & setVisible (bool visible)
 Show or hide the badge with a 150 ms fade (Paper visible).
bool isVisible (void) const
 Get the visibility the badge is fading to.
float getOpacity (void) const
 Get the current opacity of the fade.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Animation, components::Badge >
 ~SurfaceBase (void) override=default
 Default destructor.
SurfaceBase & setPose (const utility::graphic::PoseF &pose)
 Move the surface.
SurfaceBase & setColor (const utility::graphic::Color32Bit &color)
 Set the fill color (Color component).
SurfaceBase & setBorderRadius (float radius)
 Set the radius of the four corners (Borders component).
SurfaceBase & setSurfaceConfig (const SurfaceConfig &config)
 Apply every field of a configuration at once.
SurfaceConfig getSurfaceConfig (void) const
 Read the current configuration back from the components.
SurfaceBase & setChildren (const Children &children)
 Choose the children this surface arranges, in order.
std::vector< ecs::Entity::Identifier > getChildren (void) const
 Get the children this surface arranges.
Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
 ParentEntityFiller (ComponentRegistry &componentRegistry)
 Create the entity, its listed components and its components::Hierarchy. It owns no child yet.
virtual ~ParentEntityFiller (void)=default
 Destroy the entity object and release the children it owns; components stay in the registry (see EntityRegistry::removeEntity).
Public Member Functions inherited from guillaume::ecs::Entity
 Entity (void)
 Create an entity with a fresh identifier, an empty signature, no parent and no component.
virtual ~Entity (void)=default
 Destroy the entity object.
Entity::Identifier getIdentifier (void) const noexcept
 Get the identifier of the entity.
Entity::Signature getSignature (void) const noexcept
 Get the set of component types the entity declares.
void setSignature (const Signature &signature)
 Replace the signature of the entity.
std::int32_t getLayer (void) const noexcept
 Get the depth of the entity in the tree.
Entity & setParent (std::shared_ptr< Entity > parent)
 Attach the entity under another one, or detach it.
std::vector< Identifier > releaseComponents (void)
 Drop the entity's place in the tree and all its components.
std::shared_ptr< Entity > getParent (void) const noexcept
 Get the parent entity.
Public Member Functions inherited from guillaume::ecs::EntityRegistry
 EntityRegistry (void)=default
 Create a registry.
virtual ~EntityRegistry (void)=default
 Virtual destructor.
void addEntity (std::shared_ptr< Entity > entity)
 Make this registry own an entity, so that it stays alive and systems visit it.
bool removeEntity (Entity::Identifier identifier)
 Remove an entity, with its children and all their components.
void clearEntities (void)
 Remove every entity owned by this registry, with everything they own and all their components.
const std::vector< std::shared_ptr< Entity > > & getEntities (void) const
 Get the entities this registry owns directly.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void)
 List every entity of this registry and of the registries nested in it, level by level.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void) const
 List every entity of this registry and of the registries nested in it, level by level (const overload).
template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > getEntity (Entity::Identifier identifier)
 Find an entity owned directly by this registry, by identifier.
template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > getEntity (Entity::Identifier identifier) const
 Find an entity owned directly by this registry, by identifier (const overload).
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature) const
 List the entities that have every component type of a signature, from the root down.
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const
 List the entities that have every component type of a signature, in the order chosen by a traveler.

Static Public Member Functions

template<typename... Arguments>
static std::shared_ptr< Badge > create (Arguments &&...arguments)
 Build a badge without registering it in an entity registry.
Static Public Member Functions inherited from guillaume::ecs::Entity
template<InheritFromComponent... ComponentTypes>
static Signature getSignatureFromTypes (void)
 Build the signature that has exactly the bits of the given component types.

Additional Inherited Members

Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity
Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::Animation, components::Badge >
 SurfaceBase (ecs::ComponentRegistry &registry, const SurfaceConfig &config)
 Create the entity with its components and apply a configuration.
void applyGeometry (void)
 Arrange the layout children now with systems::Layout::apply.
Protected Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
ComponentRegistry & getComponentRegistry (void)
 Get the registry that stores this entity's components.
Protected Member Functions inherited from guillaume::ecs::ParentEntity
std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) override
 Give access to the list of entities this entity owns directly.
const std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) const override
 Give read access to the list of entities this entity owns directly.
Protected Member Functions inherited from guillaume::ecs::Entity
void attachHierarchy (ComponentRegistry &componentRegistry)
 Give the entity a components::Hierarchy in a registry and add that component to its signature.
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.

Detailed Description

A small colored pill showing a count or a short label, or a plain status dot (react-native-paper Badge).

Its state lives in components::Badge (variant, label, size and color overrides, visibility and fade opacity); systems::Badge sizes and colors the pill and styles its label each frame, in the Layout phase. components::Animation drives the 150 ms fade played when the visibility changes. The class itself holds no field: its setters write the component and restyle at once. The label is a Text child owned by the badge.

Badge::Builder builder(getComponentRegistry(), getEntityRegistry());
auto badge = builder.makeBadge(parent, "3", Badge::Variant::Large);
badge->setLabel("4");
badge->setVisible(false);
Configures Badge widgets and registers them in the scene's entity registry.
Definition badge.hpp:96

Badge::create(registry, config, variant, label) builds the same widget, label included, without registering it in an entity registry.

Watch out:

  • The label child is created only at construction, and only when the variant is not Dot and the label is not empty. A badge built without it never shows text: setLabel() and setVariant() update an existing label child but do not create one.
  • The height is the size of the variant (6, 16 or 20 dp) or the override of setSize(). The width is the height, or more when the label is wider: the label width plus 3 dp on each side.
  • systems::Badge overwrites the fill color, the corner radius, the padding, the spacing and the fixed size every frame. Use setContainerColor() and setSize(); SurfaceBase::setColor() and SurfaceBase::setBorderRadius() do not last.
  • The default colors are the Error and OnError roles of the active theme.
See also
components::Badge, systems::Badge, SurfaceBase

Definition at line 84 of file badge.hpp.

Member Typedef Documentation

◆ Variant

Size class of the badge: Dot (6 dp, no label), Small (16 dp) or Large (20 dp).

Definition at line 89 of file badge.hpp.

Constructor & Destructor Documentation

◆ ~Badge()

guillaume::entities::Badge::~Badge ( void )
override

Destructor.

Definition at line 100 of file badge.cpp.

Member Function Documentation

◆ clearSize()

Badge & guillaume::entities::Badge::clearSize ( void )

Drop the height override and use the height of the variant again. Resizes at once.

Returns
Reference to this badge for chaining.

Definition at line 146 of file badge.cpp.

Here is the call graph for this function:

◆ create()

template<typename... Arguments>
std::shared_ptr< Badge > guillaume::entities::Badge::create ( Arguments &&... arguments)
inlinestatic

Build a badge without registering it in an entity registry.

The arguments are forwarded to the private constructor: (registry, config, variant, label). It then calls build(), which creates the label child when the badge shows one.

Template Parameters
ArgumentsThe constructor argument types.
Parameters
argumentsThe constructor arguments, as listed above.
Returns
The new badge. The caller owns it; the badge owns its label.

Definition at line 179 of file badge.hpp.

Here is the caller graph for this function:

◆ getOpacity()

float guillaume::entities::Badge::getOpacity ( void ) const

Get the current opacity of the fade.

Returns
The opacity, from 0 (hidden) to 1 (fully shown). It multiplies the alpha of the fill and label colors.

Definition at line 187 of file badge.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getSize()

float guillaume::entities::Badge::getSize ( void ) const

Get the height the badge is drawn with.

Returns
The override of setSize() when there is one, the height of the variant otherwise, in dp.

Definition at line 104 of file badge.cpp.

Here is the call graph for this function:

◆ getVariant()

Badge::Variant guillaume::entities::Badge::getVariant ( void ) const

Get the size class of the badge.

Returns
The variant stored in components::Badge.

Definition at line 118 of file badge.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ isVisible()

bool guillaume::entities::Badge::isVisible ( void ) const

Get the visibility the badge is fading to.

Returns
True when the badge is shown or fading in, false when it is hidden or fading out. A new badge is visible.

Definition at line 180 of file badge.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setContainerColor()

Badge & guillaume::entities::Badge::setContainerColor ( const utility::graphic::Color32Bit & color)

Override the fill color of the pill. Restyles at once.

Parameters
colorThe new fill color (RGBA). Without an override the Error color of the active theme is used.
Returns
Reference to this badge for chaining.

Definition at line 155 of file badge.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setContentColor()

Badge & guillaume::entities::Badge::setContentColor ( const utility::graphic::Color32Bit & color)

Override the color of the label. Restyles at once.

Parameters
colorThe new label color (RGBA). Without an override the OnError color of the active theme is used.
Returns
Reference to this badge for chaining.

Definition at line 164 of file badge.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setLabel()

Badge & guillaume::entities::Badge::setLabel ( const std::string & label)

Change the text shown in the badge. Restyles at once.

The text only shows when the badge was built with a label child (see the class description).

Parameters
labelThe new label.
Returns
Reference to this badge for chaining.

Definition at line 125 of file badge.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setSize()

Badge & guillaume::entities::Badge::setSize ( float size)

Override the height of the variant (Paper size). Resizes at once.

The label font size follows: it is half the height.

Parameters
sizeThe badge height, in dp. Must be positive.
Returns
Reference to this badge for chaining.
Exceptions
std::invalid_argumentIf size is zero or negative.

Definition at line 134 of file badge.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setVariant()

Badge & guillaume::entities::Badge::setVariant ( Variant variant)

Change the size class of the badge. Resizes at once.

It does not create or remove the label child.

Parameters
variantDot (6 dp), Small (16 dp) or Large (20 dp).
Returns
Reference to this badge for chaining.

Definition at line 109 of file badge.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setVisible()

Badge & guillaume::entities::Badge::setVisible ( bool visible)

Show or hide the badge with a 150 ms fade (Paper visible).

The fade starts from the current opacity, so it can be reversed midway. Passing the current visibility does nothing. A hidden badge is fully transparent but keeps its place in a layout.

Parameters
visibleTrue to fade the badge in, false to fade it out.
Returns
Reference to this badge for chaining.

Definition at line 173 of file badge.cpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files: