1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<div class="intro" style="min-height:181px;">
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff Conniff <img src="{{{componentAssets}}}/images/dial_drag.png" alt="Screenshot of the Dial widget" style="border: 1px solid #bfbfbf; float:right; height:146px; margin: 0 0 8px 8px; width:154px;">
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff Conniff The Dial widget is a circular value input control. It's like a real-world, analog volume control dial, but with much finer UI control.
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff Conniff Have you ever needed a slider with a 2000 unit range, wanted 1 unit accuracy, but didn't have 2000 pixels of real estate for a slider?
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff Conniff The Dial widget is made for cases like this.
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff Conniff The user sets the value of the dial by dragging its handle or clicking on the ring.
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff{{>getting-started}}
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<h2>Using the Dial Widget</h2>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<h3>Anatomy of a Dial</h3>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<h4>Dom Structure</h4>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff The major parts of the Dial are:
11b60db4a3348a5dc24ea483146dcbfb01e2f3edJeff Conniff <li>Ring</li>
11b60db4a3348a5dc24ea483146dcbfb01e2f3edJeff Conniff <li>Marker</li>
11b60db4a3348a5dc24ea483146dcbfb01e2f3edJeff Conniff <li>User-draggable handle</li>
11b60db4a3348a5dc24ea483146dcbfb01e2f3edJeff Conniff <li>Reset button</li>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff The ring is the background element and container of the other elements.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff The marker is always displayed at a fixed but configurable distance from the dial center.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff Its position around the dial indicates the current value as the user drags the handle or clicks
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff Conniff on the ring to adjust the value.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff When not being dragged, the handle occupies the same space as the marker, and the marker is not displayed.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff When the keyboard is used for input, the marker is not displayed.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff The reset button restores the dial to the initial configuration value.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <p>A label string and a value string are dislayed above the dial.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <p>Like other form controls, Dials are inline elements.</p>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <img src="{{{componentAssets}}}/images/dial_anatomy.png" alt="illustration of the parts of a Dial">
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<h3>Markup Structure</h3>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <p>The final rendered Dial has the markup structure shown below:</p>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<div id="demo">
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <div class="yui3-widget yui3-dial">
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <div class="yui3-dial-content">
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <div class="yui3-dial-label" id="[custom YUI gen id for screen reader]">
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <span class="yui3-dial-label-string">My label</span>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <span class="yui3-dial-value-string">30</span>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <div class="yui3-dial-ring">
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <div class="yui3-dial-north-mark"></div>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <div class="yui3-dial-marker yui3-dial-marker-hidden"></div>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <div class="yui3-dial-center-button">
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <div class="yui3-dial-reset-str"></div>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <div class="yui3-dial-handle yui3-dd-draggable" title="Drag to set value" tabindex="0" role="slider" aria-valuenow="30" aria-valuemin="-220" aria-valuemax="220" aria-valuetext="30" aria-labelledby="[custom YUI gen id for screen reader]"></div>
320497661e5086dc0705ca9cc3cb6ccfd7ced2e8Jeff Conniff<h3>Instantiating the Dial</h3>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff The only markup required to instantiate a `Dial` is an HTML tag into which the widget will be rendered.
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<div id="demo"></div>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <p>`Dial` extends the `Widget` class, following the same pattern
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff as any widget constructor, accepting a configuration object to
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff set the initial configuration for the widget.</p>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <p>Some commonly used configuration attributes are shown below.</p>
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff ConniffYUI().use('dial', function(Y) {
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff var dial = new Y.Dial({
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff stepsPerRevolution:100,
320497661e5086dc0705ca9cc3cb6ccfd7ced2e8Jeff Conniff After creating and configuring the new `Dial`,
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff Call the `render` method on your `Dial` object, passing it
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff the `selector` of a container object.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff This renders it in the container and makes it usable.
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff Conniffvar dial = new Y.Dial();
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<h4>Attributes</h4>
7672ad7af50c02c6b92a851d4418ed0c7722ed14Jeff Conniff <p>The following configuration attributes are provided to define default values for each Dial widget:</p>
7672ad7af50c02c6b92a851d4418ed0c7722ed14Jeff Conniff <th>Attribute</th>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <th>Description</th>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <th>Default</th>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`min`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>Minimum input value allowed</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`-220`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`max`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>Maximum input value allowed</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`220`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`diameter`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>Diameter of the dial control in pixels</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`100`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`centerButtonDiameter`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>The diameter of the center button. This value is a percentage of the diameter of the Dial widget.</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`0.5`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`markerDiameter`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>The diameter of the marker that follows the angle of the handle as it is dragged. This value is a percentage of the diameter of the Dial widget.</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`0.1`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`handleDiameter`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>The diameter of the handle that sets the Dial value. This value is a percentage of the diameter of the Dial widget.</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`0.2`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`value`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>The initial value which will set the UI display</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`0`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`minorStep`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>Value is incremented/decremented by this value on arrow key press.</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`1`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`majorStep`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>Value is incremented/decremented by this value on page up/down key press.</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`10`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`stepsPerRevolution`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>One revolution of the dial adds/subtracts this many value units.</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`100`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`decimalPlaces`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>Number of digits to the right of decimal point to retain in the value.</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`0`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`strings`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>Display text strings are isolated in object literals and are handled through YUI's Internationalization utility.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff See the examples for ways to replace these strings.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`{label:'My label', resetStr:'Reset', tooltipHandle:'Drag to set value'}`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`handleDistance`</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>This is the distance from the center of the dial to the center of the marker and handle when at rest. This value is a percentage of the radius of the Dial widget.</td>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <td>`0.75`</td>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<h4>Setting and Constraining the Dial Value</h4>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<h5>Setting and Getting Dial Values</h5>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<p>Like any input element, the most important thing about a Dial is its `value`.
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff`value` is managed as an attribute.</p>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff// Specify value at construction
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniffvar dial = new Y.Dial({
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff// Get and set the value as an attribute
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniffvar val = dial.get('value');
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniffdial.set('value',val + 10);
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<h5>Constraining Dial Values</h5>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<p>A Dial's `value` is constrained between the configured `min` and `max` attribute values.
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff ConniffValues outside this range are treated as the closer of `min` or `max`.</p>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<p>Configuring values for `max` and `min` that are respectively larger or smaller than the configured
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff`stepsPerRevolution` or `-stepsPerRevolution` can be used to configure a Dial to allow the user to drag the handle more than 360°.
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff ConniffBy this means, a `Dial` can be configured to "go around and around," allowing a very large range of values.</p>
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff ConniffYUI().use("dial", function(Y) {
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff var dial = new Y.Dial({
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff stepsPerRevolution:100,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff<h5>Sync the UI If the Dial Was Rendered off the DOM</h5>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <p>If a Dial is rendered off the DOM, you must call the Dial's `syncUI()` method after attaching it to the DOM
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff in order for the handle to be placed correctly.
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff When off DOM, the dimensional information necessary to place the handle is unavailable.</p>
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff <p>The core structural CSS for the Dial is shown below. Widths and heights of elements
5cdd1d5bb84599836fa8ad9e8ced04ff5bceabccJeff Conniff are computed based on the "diameter" configuration property.</p>
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff/* VML implementation for IE */
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff behavior: url(#default#VML);
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff display: inline-block;
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff zoom: 1; *display: inline; /* IE < 8: fake inline-block */
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff position:relative;
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff display:-moz-inline-stack;
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff display:inline-block;
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff *display:inline;
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-content,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-ring{
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff position:relative;
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-handle,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-marker,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-center-button,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-reset-string,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-handle-vml,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-marker-vml,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-center-button-vml,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-ring-vml v\:oval,
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-center-button-vml v\:oval
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff position:absolute;
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-dial-center-button-vml v\:oval {
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff font-size:1px;
2ce1b062532c7895a7093b67252dbaf239fbe6a7Jeff Conniff.yui3-skin-sam .yui3-dial-hidden {
fe0e87d09da3f6bc93c56f8cf194455b06039fd4Jeff Conniff filter:alpha(opacity=0);