State of a list: a column of rows, each with a headline and optional supporting text, icons or image, plus subheaders, dividers and accordions.
More...
#include <headers/guillaume/components/list.hpp>
|
| struct | Item |
| | Description of one list entry, as given by the user. More...
|
| struct | Row |
| | Identifiers of the entities built for one entry. More...
|
|
|
| List (void)=default |
| | Create the configuration of an empty single-line list.
|
|
| ~List (void)=default |
| | Default destructor.
|
| Variant | getVariant (void) const noexcept |
| | Get the number of text lines a row is meant for.
|
| List & | setVariant (Variant variant) |
| | Set the number of text lines a row is meant for.
|
| const std::vector< Item > & | getItems (void) const noexcept |
| | Get the description of every top-level entry.
|
| List & | setItems (std::vector< Item > items) |
| | Replace the entries.
|
| const Item * | findItem (const Path &path) const noexcept |
| | Find an entry from its position in the tree.
|
| const Row * | findRow (const Path &path) const noexcept |
| | Find the entities built for an entry from its position in the tree.
|
| List & | setItemDisabled (std::size_t index, bool disabled) |
| | Change the disabled flag recorded for one top-level entry.
|
| List & | setItemExpanded (std::size_t index, bool expanded) |
| | Record whether one top-level accordion shows its children.
|
| const std::vector< Row > & | getRows (void) const noexcept |
| | Get the entities built for the entries.
|
| List & | setRows (const std::vector< Row > &rows) |
| | Record the entities built for the entries.
|
| bool | isRowsDirty (void) const noexcept |
| | Tell whether the rows must be rebuilt from the entries.
|
| List & | setRowsDirty (bool dirty) |
| | Mark the rows as out of date or as up to date.
|
| bool | hasChanged (void) const |
| | Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
|
| void | setHasChanged (bool hasChanged) |
| | Raise or lower the changed flag.
|
|
| Component (void)=default |
| | Create a component that is not marked as changed.
|
|
virtual | ~Component (void)=default |
| | Virtual destructor, so components can be destroyed through the base class.
|
|
| static constexpr float | DefaultWidth = 360.0f |
| | Default width of a list, in dp.
|
| static constexpr float | IconSize = 24.0f |
| | Size of the leading and trailing icons, in dp.
|
| static constexpr const char * | CollapsedGlyph = "expand_more" |
| | Glyph name of the trailing icon of a collapsed accordion.
|
| static constexpr const char * | ExpandedGlyph = "expand_less" |
| | Glyph name of the trailing icon of an expanded accordion.
|
State of a list: a column of rows, each with a headline and optional supporting text, icons or image, plus subheaders, dividers and accordions.
The entities::List widget writes it: the entries, and one Row of entity identifiers per entry it builds. systems::List reads it every frame in the Layout phase and turns it into the list's Layout, Color and Borders, and into the Layout, Color, enabled state and accessibility state of every row and of its content.
Entries and rows are two trees that must stay in step: the Row at a given Path holds the entities built for the Item at the same Path. Replacing the entries does not rebuild the rows; the widget raises the rows-dirty flag and rebuilds them.
An entry with children is an accordion: pressing it shows or hides its children. Only top-level entries can be accordions.
- See also
- systems::List, entities::List
Definition at line 57 of file list.hpp.
◆ Path
Position of an entry in the tree: the top-level index, then one child index per nesting level. {2} is the third entry; {2, 0} is its first child.
Definition at line 159 of file list.hpp.
◆ ItemKind
What a list entry is.
| Enumerator |
|---|
| Item | Pressable row (or accordion when it has children).
|
| Subheader | Section header (titleSmall text).
|
| Divider | Horizontal divider line.
|
Definition at line 71 of file list.hpp.
◆ Variant
Number of text lines a row is meant for.
SingleLine hides the supporting text; TwoLine and ThreeLine both show it.
Definition at line 66 of file list.hpp.
◆ findItem()
| const List::Item * guillaume::components::List::findItem |
( |
const Path & | path | ) |
const |
|
noexcept |
Find an entry from its position in the tree.
- Parameters
-
| path | The index path of the entry. |
- Returns
- The entry, or nullptr when the path is empty or names no entry. The pointer is valid until the entries are replaced.
Definition at line 94 of file list.cpp.
◆ findRow()
| const List::Row * guillaume::components::List::findRow |
( |
const Path & | path | ) |
const |
|
noexcept |
Find the entities built for an entry from its position in the tree.
- Parameters
-
| path | The index path of the entry. |
- Returns
- The row, or nullptr when the path is empty or names no built row. The pointer is valid until the rows are replaced.
Definition at line 110 of file list.cpp.
◆ getItems()
| const std::vector< List::Item > & guillaume::components::List::getItems |
( |
void | | ) |
const |
|
noexcept |
Get the description of every top-level entry.
- Returns
- The entries, from top to bottom; accordion children are in Item::children.
Definition at line 77 of file list.cpp.
◆ getRows()
| const std::vector< List::Row > & guillaume::components::List::getRows |
( |
void | | ) |
const |
|
noexcept |
Get the entities built for the entries.
- Returns
- One row per built top-level entry, in entry order. Empty until the widget has built them.
Definition at line 145 of file list.cpp.
◆ getVariant()
| List::Variant guillaume::components::List::getVariant |
( |
void | | ) |
const |
|
noexcept |
Get the number of text lines a row is meant for.
- Returns
- The variant, Variant::SingleLine by default.
Definition at line 63 of file list.cpp.
◆ isRowsDirty()
| bool guillaume::components::List::isRowsDirty |
( |
void | | ) |
const |
|
noexcept |
Tell whether the rows must be rebuilt from the entries.
- Returns
- True when the entries changed since the rows were built. True for a new component.
Definition at line 159 of file list.cpp.
◆ setItemDisabled()
| List & guillaume::components::List::setItemDisabled |
( |
std::size_t | index, |
|
|
bool | disabled ) |
Change the disabled flag recorded for one top-level entry.
To update the row on screen too, call systems::List::setItemDisabled. Marks the component changed only when the flag differs.
- Parameters
-
| index | The top-level entry index, starting at 0. An index out of range is ignored. |
| disabled | True to disable the entry. |
- Returns
- This component, for chaining.
Definition at line 126 of file list.cpp.
◆ setItemExpanded()
| List & guillaume::components::List::setItemExpanded |
( |
std::size_t | index, |
|
|
bool | expanded ) |
Record whether one top-level accordion shows its children.
To update the rows on screen too, call systems::List::setExpanded. Marks the component changed only when the flag differs.
- Parameters
-
| index | The top-level entry index, starting at 0. An index out of range, or an entry without children, is ignored. |
| expanded | True to show the children. |
- Returns
- This component, for chaining.
Definition at line 135 of file list.cpp.
◆ setItems()
| List & guillaume::components::List::setItems |
( |
std::vector< Item > | items | ) |
|
Replace the entries.
The press handlers are always replaced. The component is marked changed only when the texts, icons, kinds or flags differ (children included), because handlers cannot be compared. The rows are left as they are: whoever owns the row entities rebuilds them.
- Parameters
-
| items | The new entries, from top to bottom. |
- Returns
- This component, for chaining.
Definition at line 82 of file list.cpp.
◆ setRows()
| List & guillaume::components::List::setRows |
( |
const std::vector< Row > & | rows | ) |
|
Record the entities built for the entries.
Marks the component changed only when the rows differ.
- Parameters
-
| rows | One row per top-level entry, in entry order. |
- Returns
- This component, for chaining.
Definition at line 150 of file list.cpp.
◆ setRowsDirty()
| List & guillaume::components::List::setRowsDirty |
( |
bool | dirty | ) |
|
Mark the rows as out of date or as up to date.
The widget raises the flag when it replaces the entries and lowers it once it has rebuilt the row entities. Marks the component changed only when the flag differs.
- Parameters
-
| dirty | True when the rows must be rebuilt. |
- Returns
- This component, for chaining.
Definition at line 164 of file list.cpp.
◆ setVariant()
| List & guillaume::components::List::setVariant |
( |
Variant | variant | ) |
|
Set the number of text lines a row is meant for.
Marks the component changed only when the variant differs.
- Parameters
-
- Returns
- This component, for chaining.
Definition at line 68 of file list.cpp.
◆ CollapsedGlyph
| const char* guillaume::components::List::CollapsedGlyph = "expand_more" |
|
staticconstexpr |
Glyph name of the trailing icon of a collapsed accordion.
Definition at line 168 of file list.hpp.
◆ DefaultWidth
| float guillaume::components::List::DefaultWidth = 360.0f |
|
staticconstexpr |
Default width of a list, in dp.
Definition at line 162 of file list.hpp.
◆ ExpandedGlyph
| const char* guillaume::components::List::ExpandedGlyph = "expand_less" |
|
staticconstexpr |
Glyph name of the trailing icon of an expanded accordion.
Definition at line 171 of file list.hpp.
◆ IconSize
| float guillaume::components::List::IconSize = 24.0f |
|
staticconstexpr |
Size of the leading and trailing icons, in dp.
Definition at line 165 of file list.hpp.
The documentation for this class was generated from the following files: