Skip to main content

TimeFormatterComponent.ixx File

Component that formats time values for UI display. More...

Included Headers​

#include <format> #include <string> #include <helios.engine.modules.ui.layout.types.TimeDisplayMode>

Namespaces Index​

namespacehelios
namespaceengine

Main engine module aggregating core infrastructure and game systems. More...

namespacemodules

Domain-specific components and systems. More...

namespaceui

User interface components and systems for game entities. More...

namespacelayout

Layout primitives for UI positioning and value formatting. More...

namespacecomponents

Layout-related UI components. More...

Classes Index​

classTimeFormatterComponent

Component that formats elapsed or remaining time into a display string. More...

Description​

Component that formats time values for UI display.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file TimeFormatterComponent.ixx
3 * @brief Component that formats time values for UI display.
4 */
5module;
6
7#include <format>
8#include <string>
9
10export module helios.engine.modules.ui.layout.components.TimeFormatterComponent;
11
12import helios.engine.modules.ui.layout.types.TimeDisplayMode;
13
14using namespace helios::engine::modules::ui::layout::types;
15
16export namespace helios::engine::modules::ui::layout::components {
17
18 /**
19 * @brief Component that formats elapsed or remaining time into a display string.
20 *
21 * Holds a format string compatible with std::vformat and a TimeDisplayMode.
22 * The format string receives two integer arguments: minutes and seconds.
23 *
24 * @see TimeDisplayMode
25 * @see GameTimer2UiTextUpdateSystem
26 */
27 class TimeFormatterComponent {
28
29 /**
30 * @brief The format string used by std::vformat (expects minutes, seconds).
31 */
32 std::string format_;
33
34 /**
35 * @brief Label displayed instead of "00:00" when remaining time reaches zero.
36 */
37 std::string elapsedLabel_;
38
39 /**
40 * @brief True if an elapsed label has been configured.
41 */
42 bool hasElapsedLabel_ = false;
43
44 /**
45 * @brief True if the output should be empty when remaining time reaches zero.
46 */
47 bool hideWhenZero_ = false;
48
49 /**
50 * @brief The active display mode (elapsed or remaining).
51 *
52 * Declared mutable because format() may fall back to Elapsed when
53 * duration is zero.
54 */
55 mutable TimeDisplayMode displayMode_ = TimeDisplayMode::Elapsed;
56
57
58 public:
59
60 /**
61 * @brief Sets the format string and display mode.
62 *
63 * @param format A std::vformat-compatible string (e.g. "{:02d}:{:02d}").
64 * @param displayMode The display mode to use. Defaults to Elapsed.
65 */
66 void setFormat(std::string format, const TimeDisplayMode displayMode = TimeDisplayMode::Elapsed) {
67 format_ = std::move(format);
68 displayMode_ = displayMode;
69 }
70
71 /**
72 * @brief Formats the given time values into a display string.
73 *
74 * If duration is zero, the display mode falls back to Elapsed.
75 *
76 * @param elapsed Elapsed time in seconds.
77 * @param duration Total duration in seconds. Zero disables Remaining mode.
78 *
79 * @return The formatted time string.
80 */
81 std::string format(const float elapsed, const float duration = 0) const {
82
83 const auto effectiveDisplayMode = duration == 0 ? TimeDisplayMode::Elapsed : displayMode_;
84
85
86 switch (effectiveDisplayMode) {
87 case TimeDisplayMode::Elapsed: {
88 const auto minutes = static_cast<unsigned int>(std::max(0.0f, elapsed)) / 60;
89 const auto seconds = static_cast<unsigned int>(std::max(0.0f, elapsed)) % 60;
90 return std::vformat(format_, std::make_format_args(minutes, seconds));
91 }
92
93 case TimeDisplayMode::Remaining: {
94
95 const auto minutes = static_cast<unsigned int>(std::max(0.0f, duration - elapsed)) / 60;
96 const auto seconds = static_cast<unsigned int>(std::max(0.0f, duration - elapsed)) % 60;
97
98 if (hideWhenZero_ && std::max(0.0f, duration - elapsed) <= 0.0f) {
99 return "";
100 }
101
102 if (hasElapsedLabel_ && std::max(1.0f, duration - elapsed) <= 1.0f) {
103 return elapsedLabel_;
104 }
105
106
107 return std::vformat(format_, std::make_format_args(minutes, seconds));
108
109 }
110 }
111
112 std::unreachable();
113 }
114
115 /**
116 * @brief Sets the label shown in place of "00:00" when remaining time reaches zero.
117 *
118 * In Remaining mode, once the remaining time drops to one second or below,
119 * this label is returned by format() instead of the numeric output.
120 * Implicitly enables the elapsed label.
121 *
122 * @param label The label string to display (e.g. "TIME UP").
123 */
124 void setElapsedLabel(std::string label) {
125 elapsedLabel_ = std::move(label);
126 hasElapsedLabel_ = true;
127 }
128
129 /**
130 * @brief Returns the elapsed label.
131 *
132 * @return The configured elapsed label string.
133 */
134 std::string elapsedLabel() {
135 return elapsedLabel_;
136 }
137
138 /**
139 * @brief Returns whether an elapsed label is configured.
140 *
141 * @return True if an elapsed label has been set.
142 */
143 bool hasElapsedLabel() const {
144 return hasElapsedLabel_;
145 }
146
147 /**
148 * @brief Sets whether to hide the output when remaining time reaches zero.
149 *
150 * @param hideWhenZero True to return an empty string at zero remaining time.
151 */
152 void setHideWhenZero(const bool hideWhenZero) noexcept {
153 hideWhenZero_ = hideWhenZero;
154 }
155
156 /**
157 * @brief Returns whether the output is hidden at zero remaining time.
158 *
159 * @return True if hidden when zero.
160 */
161 bool hideWhenZero() const {
162 return hideWhenZero_;
163 }
164
165
166
167 };
168
169
170}

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.