Skip to content

Commit dcd8f1a

Browse files
djoweldjowel
committed
- Added button stylers
- Removed the receiver<int> from the button styler API documentation
1 parent 61a7e75 commit dcd8f1a

File tree

6 files changed

+290
-34
lines changed

6 files changed

+290
-34
lines changed

‎docs/modules/ROOT/nav.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
* xref:aspects.adoc[Design Aspects]
44
* xref:elements.adoc[Elements]
55
** xref:elements/buttons.adoc[Buttons]
6+
** xref:elements/button_stylers.adoc[Button Stylers]
67
* xref:layout.adoc[Layout]
78
** xref:layout/limits.adoc[Limits]
89
** xref:layout/sizing.adoc[Sizing]

‎docs/modules/ROOT/pages/common.adoc

+7-1
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,10 @@
2121
:Stretch-Elements: xref:layout/stretch.adoc[Stretch]
2222
:Layers: xref:layout/layers.adoc[Layers]
2323
:Layers_Semantics: xref:layout/layers.adoc#_semantics[Layer Semantics]
24-
:decks: xref:layout/decks.adoc[Decks]
24+
:Decks: xref:layout/decks.adoc[Decks]
25+
:Buttons: xref:elements/buttons.adoc[Buttons]
26+
27+
// Placeholders
28+
:Customization: Customization
29+
:Global-theme: Global theme
30+
:receiver: receiver

‎docs/modules/ROOT/pages/elements.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ include::common.adoc[]
77
The Element is the basic building block of the Elements Library. This
88
document provides an overview of the various elements available. This section
99
will focus on how elements are used, instead of how they are implemented. We
10-
will deal with the latter in the Customization section.
10+
will deal with the latter in the {Customization} section.
1111

1212
It suffices to say that elements are implemented as a hierarchy of classes,
1313
with the `element` class at the root. The `element` class provides the

‎docs/modules/ROOT/pages/elements/button_stylers.adoc

+155
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
= Stretch
2+
3+
include::../common.adoc[]
4+
5+
== Overview
6+
7+
This document provides a list of buttion stylers that can be used to style
8+
buttons in the Elements Library. The button stylers are used to define the
9+
appearance of buttons, such as colors, borders, icons and labels, and shapes.
10+
The button stylers are separate from the button classes, which handle user
11+
interactions. This separation of responsibilities allows for greater
12+
flexibility in defining the button's appearance and behavior.
13+
14+
=== Notation
15+
16+
`label` :: An object of type std::string.
17+
`bst` :: A button styler instance.
18+
`size` :: The button's relative size of type `float`.
19+
`color` :: An object of type `color`.
20+
`icon_id` :: Unicode code point of type `std::uint32_t` from the
21+
{Global-theme} `icon_font`.
22+
`margin` :: The margin in pixels of type `rect`.
23+
`r` :: The corner radius in pixels of type`float`.
24+
`tl`, `tr`, `bl`, `br` :: The corner radius in pixels for top-left, top-right,
25+
bottom-left, and bottom-right corners of type `float`.
26+
27+
=== Expressions
28+
29+
[,c++]
30+
----
31+
button_styler{label} <1>
32+
bst.size(size) <2>
33+
bst.color(color) <3>
34+
bst.active_body_color(color) <4>
35+
bst.text_color(color) <5>
36+
bst.icon(icon_id) <6>
37+
bst.icon_left() <7>
38+
bst.icon_right() <8>
39+
bst.icon_color(color) <9>
40+
bst.align_left() <10>
41+
bst.align_center() <11>
42+
bst.align_right() <12>
43+
bst.margin(margin) <13>
44+
bst.corner_radius(r) <14>
45+
bts.corner_radius(tl, tr, bl, br) <15>
46+
bts.rounded_top() <16>
47+
bts.rounded_bottom() <17>
48+
bts.rounded_left() <18>
49+
bts.rounded_right() <19>
50+
bts.rounded_top(r) <20>
51+
bts.rounded_bottom(r) <21>
52+
bts.rounded_left(r) <22>
53+
bts.rounded_right(r) <23>
54+
bts.rounded_corner_top_left(r) <24>
55+
bts.rounded_corner_top_right(r) <25>
56+
bts.rounded_corner_bottom_left(r) <26>
57+
bts.rounded_corner_bottom_right(r) <27>
58+
----
59+
60+
=== Semantics
61+
62+
<1> Creates a button styler with the given label.
63+
<2> Sets the button relative size of a button styler. A value > 1.0 makes the
64+
button larger, while a value < 1.0 makes the button smaller.
65+
<3> Sets the color of a button styler.
66+
<4> Sets the active body color of a button styler.
67+
<5> Sets the text color of a button styler.
68+
<6> Sets the icon of a button styler.
69+
<7> Sets the icon to the left of the text.
70+
<8> Sets the icon to the right of the text.
71+
<9> Sets the icon color of a button styler.
72+
<10> Aligns the text and icon to the left.
73+
<11> Aligns the text and icon to the center.
74+
<12> Aligns the text and icon to the right.
75+
<13> Sets the margin of a button styler.
76+
<14> Sets the corner radius of a button styler.
77+
<15> Sets the corner radius of a button styler for each corner.
78+
<16> Sets the top corners of a button styler to be rounded.
79+
<17> Sets the bottom corners of a button styler to be rounded.
80+
<18> Sets the left corners of a button styler to be rounded.
81+
<19> Sets the right corners of a button styler to be rounded.
82+
<20> Sets the top corners of a button styler to be rounded with a specific radius.
83+
<21> Sets the bottom corners of a button styler to be rounded with a specific radius.
84+
<22> Sets the left corners of a button styler to be rounded with a specific radius.
85+
<23> Sets the right corners of a button styler to be rounded with a specific radius.
86+
<24> Sets the top-left corner of a button styler to be rounded with a specific radius.
87+
<25> Sets the top-right corner of a button styler to be rounded with a specific radius.
88+
<26> Sets the bottom-left corner of a button styler to be rounded with a specific radius.
89+
<27> Sets the bottom-right corner of a button styler to be rounded with a specific radius.
90+
91+
All of these expressions return a button styler. Therefore, these expressions
92+
can be chained together to create a button styler with the desired
93+
appearance. The result is then passed to one of the button creation functions
94+
(see {Buttons}).
95+
96+
=== Examples
97+
98+
Make a default momentary button with label "My Button":
99+
100+
[,c++]
101+
----
102+
auto btn = momentary_button(
103+
button_styler{"My Button"}
104+
);
105+
----
106+
107+
Make a blue momentary button with label "Lock":
108+
109+
[,c++]
110+
----
111+
auto btn = momentary_button(
112+
button_styler{"Lock"}
113+
.body_color(colors::blue)
114+
);
115+
----
116+
117+
Make a momentary button with label "Rounded Left" and a `left_circled` icon,
118+
aligned to the left, with a rounded left corner of 10 pixels:
119+
120+
[,c++]
121+
----
122+
auto btn = momentary_button(
123+
button_styler{"Rounded Left"}
124+
.align_left()
125+
.icon(icons::left_circled)
126+
.icon_left()
127+
.rounded_left(10)
128+
);
129+
----
130+
131+
=== Default Button Styler
132+
133+
The basic button styler is a simple button with a text label with no icon,
134+
with these defaults:
135+
136+
[cols="1,1", options="header"]
137+
|===
138+
| Property | Default Value
139+
140+
| size | `1.0f`
141+
| body_color | {Global-theme} `default_button_color`
142+
| active_body_color | `body_color`
143+
| text_color | {Global-theme} `label_font_color`
144+
| icon | `0`
145+
| icon_placement | `icon_none`
146+
| icon_color | {Global-theme} `label_font_color`
147+
| label_alignment | `align_center`
148+
| margin | {Global-theme} `button_margin`
149+
| corner_radius | {Global-theme} `button_corner_radius`
150+
| corner_radius_top_left | `corner_radius`
151+
| corner_radius_top_right | `corner_radius`
152+
| corner_radius_bottom_left | `corner_radius`
153+
| corner_radius_bottom_right | `corner_radius`
154+
|===
155+

‎docs/modules/ROOT/pages/elements/buttons.adoc

+117-24
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ Latching buttons ::
1818
Buttons are buttons that stay on until programmatically reset.
1919

2020
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
2323
interactions, while the button styler manages the button's visual
2424
presentation. With this pattern, different stylers can be implemented for
2525
various visual representations, for instance, plain buttons, radio buttons,
@@ -93,55 +93,148 @@ The provided base types `MBase`, `TBase`, and `LBase` offer the flexibility
9393
to use custom button behavior, provided they adhere to their respective
9494
concepts.
9595

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+
96199
== Button Styler
97200

98201
NOTE: This section is an advanced topic only relevant to those who want to
99202
write custom buttons. This section may be skipped by most users.
100203

101204
The button styler is a separate element that is responsible for rendering the
102205
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.
116209

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:
120212

121213
=== button_state
122214

123215
[,c++]
124216
----
125217
struct button_state
126218
{
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;
131223
};
132224
----
133225

134226
`button_state` is struct struct for maintaining and managing the state of a
135227
button. This structure captures the various states that a button can have:
136228

137229
- `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).
139232
- `tracking`: True if the mouse button being pressed.
140233
- `enabled`: True if the button is enabled.
141234

142235

143236
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,
145238
and not adjust to state changes. This may still be useful in certain cases.
146239

147240
'''

‎lib/include/elements/element/button.hpp

+9-8
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ namespace cycfi::elements
3838
*
3939
* This structure captures the various states that a button can have:
4040
* - `value`: The button's value; 0(off) or 1(on).
41-
* - `hilite`: True if the button is highlighted.
41+
* - `hilite`: True if the button is highlighted (when the mouse is
42+
* hovering over the button).
4243
* - `tracking`: True if the mouse button being pressed.
4344
* - `enabled`: True if the button is enabled.
4445
*/
@@ -59,13 +60,13 @@ namespace cycfi::elements
5960
*
6061
* The `basic_button` class is a foundational class for creating a GUI
6162
* button. This class is a proxy which delegates the rendering of the
62-
* actual button to a button styler subject. This division of
63-
* responsibilities allows for more flexibility in dictating the
64-
* button's appearance and interaction. The `basic_button` class
65-
* handles user interactions, while the button styler manages the
66-
* button's visual presentation. With this pattern, different stylers
67-
* can be implemented for various visual representations, for instance,
68-
* plain buttons, radio buttons, slide switches, checkboxes, and more.
63+
* actual button to a button styler subject. This separation of
64+
* responsibilities provides greater flexibility in defining the
65+
* button's appearance and behavior. The `basic_button` class handles
66+
* user interactions, while the button styler manages the button's
67+
* visual presentation. With this pattern, different stylers can be
68+
* implemented for various visual representations, for instance, plain
69+
* buttons, radio buttons, slide switches, checkboxes, and more.
6970
*
7071
* The communication with the button styler is done via the
7172
* `receiver<button_state>` or a `receiver<int>` APIs. These APIs

0 commit comments

Comments
 (0)