Skip to content

Commit 0faeaa2

Browse files
committed
Dials docs
1 parent 078585b commit 0faeaa2

File tree

3 files changed

+129
-1
lines changed

3 files changed

+129
-1
lines changed

docs/modules/ROOT/nav.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
** xref:elements/buttons.adoc[Buttons]
66
** xref:elements/button_stylers.adoc[Button Stylers]
77
** xref:elements/labels.adoc[Labels]
8+
** xref:elements/dials.adoc[Dials]
89
* xref:layout.adoc[Layout]
910
** xref:layout/limits.adoc[Limits]
1011
** xref:layout/sizing.adoc[Sizing]

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

-1
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,6 @@ namespace concepts
5959
`TBase`:: Type that conforms to the ToggleButton concept.
6060
`LBase`:: Type that conforms to the LatchingButton concept.
6161

62-
6362
=== Expressions
6463

6564
[cols="2,3", options="header"]
+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
= Dials
2+
3+
include::../common.adoc[]
4+
5+
== Overview
6+
7+
Dials are used to adjust a value within a range. Dials in the Elements Library are stylable with separate elements for behavior and appearance. The `basic_dial` class is the base class for dials. This class delegates the rendering to a dial styler subject. This separation of responsibilities provides greater flexibility in defining the dial's appearance and behavior. The dial class handles user interactions, while the dial styler manages the dial's visual presentation. With this pattern, different stylers can be implemented for various visual representations.
8+
9+
=== Declaration
10+
11+
[source,c++]
12+
----
13+
class basic_dial; // Base class for dials
14+
----
15+
16+
=== Notation
17+
18+
`styler`:: Styler instance that conforms to the Element concept.
19+
20+
=== Expressions
21+
22+
[cols="2,3", options="header"]
23+
|===
24+
| Expression | Semantics
25+
26+
a|
27+
[source,c++]
28+
----
29+
dial(styler);
30+
----
31+
a|
32+
* Creates a dial with the given styler element.
33+
34+
|===
35+
36+
== On Change
37+
38+
Dials include and `on_change` callable object that is invoked when the dial's value changes.
39+
40+
=== Notation
41+
42+
`d`:: Dial instance.
43+
`f`:: Callable object with signature `void(double pos)`.
44+
45+
=== Expressions
46+
47+
[cols="2,3", options="header"]
48+
|===
49+
| Expression | Semantics
50+
51+
a|
52+
[source,c++]
53+
----
54+
d.on_change = f;
55+
----
56+
a|
57+
* Assigns a callable object to the dial's `on_change` member.
58+
* The callable object is invoked when the dial's value changes.
59+
* The pos value is normalized to the range [0, 1].
60+
|===
61+
62+
The client provides a callback function, typically a C++ lambda, that will be called when the dial's value changes. The callback function receives a normalized value in the range [0, 1].
63+
64+
The type of the `on_change` member is:
65+
66+
[source,c++]
67+
----
68+
std::function<void(double pos)>
69+
----
70+
71+
=== Example
72+
73+
[source,c++]
74+
----
75+
d.on_change =
76+
[](double pos)
77+
{
78+
std::cout << "Dial position: " << pos << std::endl;
79+
};
80+
----
81+
82+
== Value
83+
84+
The value of a dial is a `double`, normalized to the range [0, 1] and is used to determine the dial's position. The value of the `dial` can be set programmatically via the `{receiver}<double>` API.
85+
86+
NOTE: {receiver}<T> is mixin class that provides a common interface for
87+
setting and querying the values of type `T` via virtual member
88+
functions, `value()` and `value(val)`.
89+
90+
=== Notation
91+
92+
`d`:: A Dial instance.
93+
`val`:: A double value.
94+
95+
=== Expressions
96+
97+
[cols="2,3", options="header"]
98+
|===
99+
| Expression | Semantics
100+
101+
a|
102+
[source,c++]
103+
----
104+
d.value(val);
105+
----
106+
a|
107+
* Sets the value of the dial to `val`.
108+
109+
a|
110+
[source,c++]
111+
----
112+
d.value();
113+
----
114+
a|
115+
* Returns the value of the dial.
116+
|===
117+
118+
119+
== Dial Styler
120+
121+
NOTE: This section is an advanced topic only relevant to those who want to customize the appearance of dials. This section may be skipped by most users.
122+
123+
TODO: Add dial styler documentation.
124+
125+
'''
126+
127+
_Copyright (c) 2014-2024 Joel de Guzman. All rights reserved._
128+
_Distributed under the {mit_license}_

0 commit comments

Comments
 (0)