@@ -18,8 +18,8 @@ Latching buttons ::
18
18
Buttons are buttons that stay on until programmatically reset.
19
19
20
20
These classes delegate the rendering to a button styler subject. This
21
- division of responsibilities allows for more flexibility in dictating the
22
- button's appearance and interaction . The button classes handle user
21
+ separation of responsibilities provides greater flexibility in defining the
22
+ button's appearance and behavior . The button classes handle user
23
23
interactions, while the button styler manages the button's visual
24
24
presentation. With this pattern, different stylers can be implemented for
25
25
various visual representations, for instance, plain buttons, radio buttons,
@@ -93,55 +93,148 @@ The provided base types `MBase`, `TBase`, and `LBase` offer the flexibility
93
93
to use custom button behavior, provided they adhere to their respective
94
94
concepts.
95
95
96
+ == On Click
97
+
98
+ Buttons include an `on_click` callable object, which is called whenever the
99
+ button is clicked.
100
+
101
+ === Notation
102
+
103
+ `btn`:: A Button instance.
104
+ `f` :: A callback function with the signature `void(bool state)`.
105
+
106
+ === Expression
107
+
108
+ [,c++]
109
+ ----
110
+ btn.on_click = f;
111
+ ----
112
+
113
+ === Semantics
114
+
115
+ The type of the `on_click` callable object is:
116
+
117
+ [,c++]
118
+ ----
119
+ std::function<void(bool state))
120
+ ----
121
+
122
+ The client provides a callback function, typically a c++ lambda, that will be
123
+ called when the button is clicked. The `state` argument indicates whether the
124
+ button is ON (`true`) or OFF (`false`).
125
+
126
+ . The `on_click` callback is called at the trailing edge of the click, just
127
+ before release.
128
+
129
+ . Momentary and latching buttons will always have a state of `true` when
130
+ its `on_click` callback is called.
131
+
132
+ . Toggle buttons will will have a state that alternates between `true` and
133
+ `false` with each click.
134
+
135
+ === Example
136
+
137
+ [,c++]
138
+ ----
139
+ btn.on_click = [](bool state)
140
+ {
141
+ std::cout << "Button clicked: " << state << std::endl;
142
+ };
143
+ ----
144
+
145
+ == Enable/Disable
146
+
147
+ Buttons can be enabled or disabled. When disabled, the button will not
148
+ respond to user clicks and, if the button styler handles it, will render
149
+ differently to indicate that it is disabled.
150
+
151
+ === Notation
152
+
153
+ `btn` :: A Button instance.
154
+ `state` :: A boolean value indicating whether the button is enabled or disabled.
155
+
156
+ === Expression
157
+
158
+ [,c++]
159
+ ----
160
+ btn.enable(state) <1>
161
+ btn.is_enabled() <2>
162
+ ----
163
+
164
+ === Semantics
165
+
166
+ <1> Pass `true` to the `state` argument to enable the button, or
167
+ `false` to disable it. When disabled, the button will not respond
168
+ to clicks.
169
+ <2> Returns `true` if the button is enabled, and `false` otherwise.
170
+
171
+ == Value
172
+
173
+ The value of a button is a boolean that indicates whether the button is ON
174
+ (`true`) or OFF (`false`). The value of a button can be set programmatically
175
+ via the `{receiver}<bool>` API.
176
+
177
+ NOTE: {receiver}<T> is mixin class that provides a common interface for
178
+ setting and querying the values of type `T` via virtual member
179
+ functions, `value()` and `value(val)`.
180
+
181
+ === Notation
182
+
183
+ `btn` :: A Button instance.
184
+ `val` :: A boolean value.
185
+
186
+ === Expression
187
+
188
+ [,c++]
189
+ ----
190
+ btn.value(val) <1>
191
+ btn.vauel() <2>
192
+ ----
193
+
194
+ === Semantics
195
+
196
+ <1> Sets the value of the button to `val`.
197
+ <2> Returns the current value of the button.
198
+
96
199
== Button Styler
97
200
98
201
NOTE: This section is an advanced topic only relevant to those who want to
99
202
write custom buttons. This section may be skipped by most users.
100
203
101
204
The button styler is a separate element that is responsible for rendering the
102
205
button. The communication with the button styler is done via the
103
- `receiver<button_state>` or a `receiver<int>` APIs. These APIs provide a
104
- means to update the button styler about changes in button's state to allow
105
- the styler to adjust the visual representation accordingly.
106
-
107
- If the button styler follows a `receiver<int>` API, it will receive in
108
- integer with these possible values:
109
-
110
- ----
111
- 0: value=false, hilite=false
112
- 1: value=false, hilite=true
113
- 2: value=true, hilite=false
114
- 3: value=true, hilite=true
115
- ----
206
+ `{receiver}<button_state>` API. This API provides a means to update the button
207
+ styler about changes in button's state to allow the styler to adjust the
208
+ visual representation accordingly.
116
209
117
- If the button styler follows a `receiver<button_state>` API, it will receive
118
- a `button_state` when the button's state changes. This has a richer API
119
- compared to the former, allowing more nuanced button rendering:
210
+ If the button styler is as a subclass of `{receiver}<button_state>` API, it
211
+ will receive a `button_state` when the button's state changes:
120
212
121
213
=== button_state
122
214
123
215
[,c++]
124
216
----
125
217
struct button_state
126
218
{
127
- bool value : 1 = false;
128
- bool hilite : 1 = false;
129
- bool tracking : 1 = false;
130
- bool enabled : 1 = true;
219
+ bool value : 1 = false;
220
+ bool hilite : 1 = false;
221
+ bool tracking : 1 = false;
222
+ bool enabled : 1 = true;
131
223
};
132
224
----
133
225
134
226
`button_state` is struct struct for maintaining and managing the state of a
135
227
button. This structure captures the various states that a button can have:
136
228
137
229
- `value`: The button's value; 0(off) or 1(on).
138
- - `hilite`: True if the button is highlighted.
230
+ - `hilite`: True if the button is highlighted (when the mouse is
231
+ hovering over the button).
139
232
- `tracking`: True if the mouse button being pressed.
140
233
- `enabled`: True if the button is enabled.
141
234
142
235
143
236
NOTE: The button styler is just an element and does not have to follow the
144
- `receiver` API. If that's the case, then the button rendering will be static,
237
+ `{ receiver} ` API. If that's the case, then the button rendering will be static,
145
238
and not adjust to state changes. This may still be useful in certain cases.
146
239
147
240
'''
0 commit comments