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

Arranges a segmented button: a row of joined toggle buttons of which one (Single mode) or several (Multi mode) are selected. More...

#include <headers/guillaume/systems/segmented_button.hpp>

Inheritance diagram for guillaume::systems::SegmentedButton:
Collaboration diagram for guillaume::systems::SegmentedButton:

Public Member Functions

 SegmentedButton (void)
 Create the system for the Layout phase, matching entities that have a components::SegmentedButton.
 ~SegmentedButton (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Frame entry point: call apply on one segmented button.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::SegmentedButton >
 SystemFiller (Phase phase)
 Create the system and set its signature from ComponentTypes.
virtual ~SystemFiller (void)=default
 Virtual destructor.
Public Member Functions inherited from guillaume::ecs::System
 System (Phase phase)
 Create a system that runs in a given phase, with an empty signature.
virtual ~System (void)=default
 Virtual destructor.
Phase getPhase (void) const noexcept
 Get the phase of the frame in which the system runs.
Entity::Signature getSignature (void) const noexcept
 Get the component types an entity must declare to be visited by this system.
void routine (ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry, const ecs::EntityTreeTraveler &traveler)
 Run the system once over a scene: prepare(), update() on each matching entity, cleanup().
void bindComponentRegistry (ecs::ComponentRegistry &componentRegistry)
 Bind a component registry so update() can be called directly, without routine().
void unbindComponentRegistry (void)
 Drop the binding made by bindComponentRegistry().
virtual void prepare (void)
 Called once per pass, before the first update().
virtual void cleanup (void)
 Called once per pass, after the last update().

Static Public Member Functions

static void install (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Make an entity behave as a segmented button.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Lay out the row from the current selection of the buttons.
static void select (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Select a segment from code and show it at once.
static void deselect (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Deselect a segment from code and show it at once.
static void segmentChanged (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 React to the user clicking a segment.
static void setSegmentDisabled (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, bool disabled)
 Enable or disable one segment and show it at once.
static bool isSelected (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Whether a segment is selected.
static std::vector< std::size_t > selectedIndices (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 List the selected segments.

Static Public Attributes

static constexpr const char * SelectedGlyph = "check"

Additional Inherited Members

Protected Member Functions inherited from guillaume::ecs::System
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.
ecs::EntityRegistry & getEntityRegistry (void)
 Get the entity registry of the scene being processed.
const ecs::EntityRegistry & getEntityRegistry (void) const
 Get the entity registry of the scene being processed, read-only.
ecs::ComponentRegistry & getComponentRegistry (void)
 Get the component registry of the scene being processed.
const ecs::ComponentRegistry & getComponentRegistry (void) const
 Get the component registry of the scene being processed, read-only.
template<InheritFromComponent ComponentType>
bool hasComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Tell whether an entity has a component, in the bound registry.
template<InheritFromComponent ComponentType>
ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier)
 Get a component of an entity from the bound registry, to read or modify it.
template<InheritFromComponent ComponentType>
const ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Get a component of an entity from the bound registry, read-only.
template<InheritFromComponent ComponentType>
bool requireComponent (const ecs::Entity::Identifier &entityIdentifier)
 Tell whether an entity has a component, and log a warning naming the entity and the component when it does not.

Detailed Description

Arranges a segmented button: a row of joined toggle buttons of which one (Single mode) or several (Multi mode) are selected.

The segmented button entity is a horizontal layout container. Each segment is a common button child (components::Button plus components::CommonButton) built by entities::SegmentedButton and recorded by identifier in components::SegmentedButton. There is no separate selection state: a segment is selected when its button is.

// Select the second segment from code; no callback is called.
systems::SegmentedButton::select(registry, identifier, 1);
const auto selected =
static void select(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Select a segment from code and show it at once.
static std::vector< std::size_t > selectedIndices(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
List the selected segments.

All segments get the width of the widest one, and at least components::SegmentedButton::MinSegmentWidth. The list of children in the container's components::Layout is overwritten each frame.

See also
guillaume::components::SegmentedButton, guillaume::systems::CommonButton, guillaume::systems::Button

Definition at line 71 of file segmented_button.hpp.

Constructor & Destructor Documentation

◆ SegmentedButton()

guillaume::systems::SegmentedButton::SegmentedButton ( void )

Create the system for the Layout phase, matching entities that have a components::SegmentedButton.

Definition at line 58 of file segmented_button.cpp.

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

Member Function Documentation

◆ apply()

void guillaume::systems::SegmentedButton::apply ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Lay out the row from the current selection of the buttons.

In order:

  1. each button shows SelectedGlyph when selected and the icon of its segment otherwise;
  2. every button gets, as minimum width, the width of the widest one (at least components::SegmentedButton::MinSegmentWidth);
  3. the buttons become the layout children of the container and systems::Layout::apply places them in a row;
  4. the corners are joined: only the left corners of the first button and the right corners of the last one are rounded, with a radius of half the height of the container.

A button is restyled each time one of these steps changes it, so the result is visible at once. The frame calls it through update; select, deselect, segmentChanged and setSegmentDisabled call it too. Call it yourself after changing the selection of a segment's button directly.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe segmented button entity.

Definition at line 264 of file segmented_button.cpp.

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

◆ deselect()

void guillaume::systems::SegmentedButton::deselect ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Deselect a segment from code and show it at once.

The change callback is not called. In Single mode this can leave no segment selected, which a user press cannot do.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe segmented button entity.
indexThe zero-based index of the segment. The call does nothing when it is out of range.

Definition at line 180 of file segmented_button.cpp.

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

◆ install()

void guillaume::systems::SegmentedButton::install ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Make an entity behave as a segmented button.

Configures the container's components::Layout as a horizontal row packed at the start, centered across, with no spacing and no padding. Then, for every button recorded in the component: makes it a toggle, makes its click call segmentChanged with its index, enables or disables it and sets its accessibility label from the segment options at the same index, and restyles it.

Call it once the buttons exist and are recorded in the component, and again whenever the segments or their buttons change. A button identifier that is invalid or has no components::Button is skipped. It does not place anything: apply does.

Parameters
componentRegistryThe registry holding the components. The click handlers keep its address, so it must outlive the entity.
entityIdentifierThe segmented button entity. It must have a components::SegmentedButton and a components::Layout.

Definition at line 63 of file segmented_button.cpp.

Here is the call graph for this function:

◆ isSelected()

bool guillaume::systems::SegmentedButton::isSelected ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Whether a segment is selected.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe segmented button entity.
indexThe zero-based index of the segment.
Returns
True when the button of the segment is selected; false when it is not, when the index is out of range or when the segment has no button.

Definition at line 117 of file segmented_button.cpp.

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

◆ segmentChanged()

void guillaume::systems::SegmentedButton::segmentChanged ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

React to the user clicking a segment.

It is the click handler install gives each button, so it runs after systems::Button::release has already toggled the button. In Single mode it makes the clicked segment the only selected one; clicking the selected segment keeps it selected. In Multi mode the toggle stands as it is. It then calls apply and the change callback of the component with the index.

Call it directly to simulate a click in a test; unlike select, it calls the callback.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe segmented button entity.
indexThe zero-based index of the clicked segment. The call does nothing, and calls nothing, when it is out of range or the segment has no button.

Definition at line 200 of file segmented_button.cpp.

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

◆ select()

void guillaume::systems::SegmentedButton::select ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Select a segment from code and show it at once.

In Single mode every other segment is deselected; in Multi mode the others keep their state. The change callback is not called and a disabled segment can be selected this way.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe segmented button entity.
indexThe zero-based index of the segment. The call does nothing when it is out of range.

Definition at line 153 of file segmented_button.cpp.

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

◆ selectedIndices()

std::vector< std::size_t > guillaume::systems::SegmentedButton::selectedIndices ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

List the selected segments.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe segmented button entity.
Returns
The zero-based indices of the selected segments, in ascending order; empty when none is selected. In Single mode it holds at most one index after a user click.

Definition at line 133 of file segmented_button.cpp.

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

◆ setSegmentDisabled()

void guillaume::systems::SegmentedButton::setSegmentDisabled ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index,
bool disabled )
static

Enable or disable one segment and show it at once.

Records the flag in the segment options of the component, writes it to the components::StyleState of the segment's button (a disabled button ignores clicks and is drawn disabled), restyles that button and lays the row out again. The selection of the segment is kept.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe segmented button entity.
indexThe zero-based index of the segment. Out of range, nothing is changed.
disabledTrue to disable the segment, false to enable it.

Definition at line 238 of file segmented_button.cpp.

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

◆ update()

void guillaume::systems::SegmentedButton::update ( const ecs::Entity::Identifier & entityIdentifier)
overridevirtual

Frame entry point: call apply on one segmented button.

Parameters
entityIdentifierThe segmented button entity. An entity without a components::SegmentedButton is logged and skipped.

Implements guillaume::ecs::System.

Definition at line 358 of file segmented_button.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ SelectedGlyph

const char* guillaume::systems::SegmentedButton::SelectedGlyph = "check"
staticconstexpr

Name of the glyph a selected segment shows in place of its own icon.

Definition at line 76 of file segmented_button.hpp.


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