<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Dial</title>
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic">
<link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css">
<link rel="stylesheet" href="../assets/css/main.css">
<link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
<link rel="shortcut icon" type="image/png" href="../assets/favicon.png">
<script src="../../build/yui/yui-min.js"></script>
</head>
<body>
<!--
<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
-->
<div id="doc">
<div id="hd">
<h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1>
</div>
<a href="#toc" class="jump">Jump to Table of Contents</a>
<h1>Dial</h1>
<div class="yui3-g">
<div class="yui3-u-3-4">
<div id="main">
<div class="content"><div class="intro" style="min-height:181px;">
<p>
<img src="../assets/dial/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;">
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.
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?
The Dial widget is made for cases like this.
</p>
<p>
The user sets the value of the dial by dragging its handle or clicking on the ring.
</p>
</div>
<h2 id="getting-started">Getting Started</h2>
<p>
To include the source files for Dial and its dependencies, first load
the YUI seed file if you haven't already loaded it.
</p>
<pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre>
<p>
Next, create a new YUI instance for your application and populate it with the
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
YUI will automatically load any dependencies required by the modules you
specify.
</p>
<pre class="code prettyprint"><script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('dial', function (Y) {
// Dial is available and ready for use. Add implementation
// code here.
});
</script></pre>
<p>
For more information on creating YUI instances and on the
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
documentation for the <a href="../yui/index.html">YUI Global Object</a>.
</p>
<h2 id="using-the-dial-widget">Using the Dial Widget</h2>
<h3 id="anatomy-of-a-dial">Anatomy of a Dial</h3>
<h4 id="dom-structure">Dom Structure</h4>
<p>
The major parts of the Dial are:
<ul>
<li>Ring</li>
<li>Marker</li>
<li>User-draggable handle</li>
<li>Reset button</li>
</ul>
The ring is the background element and container of the other elements.
The marker is always displayed at a fixed but configurable distance from the dial center.
Its position around the dial indicates the current value as the user drags the handle or clicks
on the ring to adjust the value.
When not being dragged, the handle occupies the same space as the marker, and the marker is not displayed.
When the keyboard is used for input, the marker is not displayed.
The reset button restores the dial to the initial configuration value.
</p>
<p>A label string and a value string are dislayed above the dial.
</p>
<p>Like other form controls, Dials are inline elements.</p>
<img src="../assets/dial/images/dial_anatomy.png" alt="illustration of the parts of a Dial">
<h3 id="markup-structure">Markup Structure</h3>
<p>The final rendered Dial has the markup structure shown below:</p>
<pre class="code prettyprint"><div id="demo">
<div class="yui3-widget yui3-dial">
<div class="yui3-dial-content">
<div class="yui3-dial-label" id="[custom YUI gen id for screen reader]">
<span class="yui3-dial-label-string">My label</span>
<span class="yui3-dial-value-string">30</span>
</div>
<div class="yui3-dial-ring">
<div class="yui3-dial-north-mark"></div>
<div class="yui3-dial-marker yui3-dial-marker-hidden"></div>
<div class="yui3-dial-center-button">
<div class="yui3-dial-reset-str"></div>
</div>
<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>
</div>
</div>
</div>
</div></pre>
<h3 id="instantiating-the-dial">Instantiating the Dial</h3>
<p>
<strong>Note:</strong> be sure to add the <code>yui3-skin-sam</code> classname to the
page's <code><body></code> element or to a parent element of the widget in order to apply
the default CSS skin. See <a href="http://yuilibrary.com/yui/docs/tutorials/skins/">Understanding Skinning</a>.
</p>
<pre class="code prettyprint"><body class="yui3-skin-sam"> <!-- You need this skin class --></pre>
<p>
The only markup required to instantiate a <code>Dial</code> is an HTML tag into which the widget will be rendered.
</p>
<pre class="code prettyprint"><div id="demo"></div></pre>
<p><code>Dial</code> extends the <code>Widget</code> class, following the same pattern
as any widget constructor, accepting a configuration object to
set the initial configuration for the widget.</p>
<p>Some commonly used configuration attributes are shown below.</p>
<pre class="code prettyprint">YUI().use('dial', function(Y) {
var dial = new Y.Dial({
min:-220,
max:220,
stepsPerRevolution:100,
value: 30,
});
});</pre>
<p>
After creating and configuring the new <code>Dial</code>,
Call the <code>render</code> method on your <code>Dial</code> object, passing it
the <code>selector</code> of a container object.
This renders it in the container and makes it usable.
</p>
<pre class="code prettyprint">var dial = new Y.Dial();
dial.render("#demo");</pre>
<h4 id="attributes">Attributes</h4>
<p>The following configuration attributes are provided to define default values for each Dial widget:</p>
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>min</code></td>
<td>Minimum input value allowed</td>
<td><code>-220</code></td>
</tr>
<tr>
<td><code>max</code></td>
<td>Maximum input value allowed</td>
<td><code>220</code></td>
</tr>
<tr>
<td><code>diameter</code></td>
<td>Diameter of the dial control in pixels</td>
<td><code>100</code></td>
</tr>
<tr>
<td><code>centerButtonDiameter</code></td>
<td>The diameter of the center button. This value is a percentage of the diameter of the Dial widget.</td>
<td><code>0.5</code></td>
</tr>
<tr>
<td><code>markerDiameter</code></td>
<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>
<td><code>0.1</code></td>
</tr>
<tr>
<td><code>handleDiameter</code></td>
<td>The diameter of the handle that sets the Dial value. This value is a percentage of the diameter of the Dial widget.</td>
<td><code>0.2</code></td>
</tr>
<tr>
<td><code>value</code></td>
<td>The initial value which will set the UI display</td>
<td><code>0</code></td>
</tr>
<tr>
<td><code>minorStep</code></td>
<td>Value is incremented/decremented by this value on arrow key press.</td>
<td><code>1</code></td>
</tr>
<tr>
<td><code>majorStep</code></td>
<td>Value is incremented/decremented by this value on page up/down key press.</td>
<td><code>10</code></td>
</tr>
<tr>
<td><code>stepsPerRevolution</code></td>
<td>One revolution of the dial adds/subtracts this many value units.</td>
<td><code>100</code></td>
</tr>
<tr>
<td><code>decimalPlaces</code></td>
<td>Number of digits to the right of decimal point to retain in the value.</td>
<td><code>0</code></td>
</tr>
<tr>
<td><code>strings</code></td>
<td>Display text strings are isolated in object literals and are handled through YUI's Internationalization utility.
See the examples for ways to replace these strings.
</td>
<td><code>{label:'My label', resetStr:'Reset', tooltipHandle:'Drag to set value'}</code></td>
</tr>
<tr>
<td><code>handleDistance</code></td>
<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>
<td><code>0.75</code></td>
</tr>
</tbody>
</table>
<h4 id="setting-and-constraining-the-dial-value">Setting and Constraining the Dial Value</h4>
<h5 id="setting-and-getting-dial-values">Setting and Getting Dial Values</h5>
<p>Like any input element, the most important thing about a Dial is its <code>value</code>.
<code>value</code> is managed as an attribute.</p>
<pre class="code prettyprint">// Specify value at construction
var dial = new Y.Dial({
value : 50
});
// Get and set the value as an attribute
var val = dial.get('value');
dial.set('value',val + 10);</pre>
<h5 id="constraining-dial-values">Constraining Dial Values</h5>
<p>A Dial's <code>value</code> is constrained between the configured <code>min</code> and <code>max</code> attribute values.
Values outside this range are treated as the closer of <code>min</code> or <code>max</code>.</p>
<p>Configuring values for <code>max</code> and <code>min</code> that are respectively larger or smaller than the configured
<code>stepsPerRevolution</code> or <code>-stepsPerRevolution</code> can be used to configure a Dial to allow the user to drag the handle more than 360°.
By this means, a <code>Dial</code> can be configured to "go around and around," allowing a very large range of values.</p>
<pre class="code prettyprint">YUI().use("dial", function(Y) {
var dial = new Y.Dial({
min:-520,
max:720,
stepsPerRevolution:100,
value: 30,
});
dial.render("#demo");
});</pre>
<h5 id="sync-the-ui-if-the-dial-was-rendered-off-the-dom">Sync the UI If the Dial Was Rendered off the DOM</h5>
<p>If a Dial is rendered off the DOM, you must call the Dial's <code>syncUI()</code> method after attaching it to the DOM
in order for the handle to be placed correctly.
When off DOM, the dimensional information necessary to place the handle is unavailable.</p>
<h3 id="css">CSS</h3>
<p>The core structural CSS for the Dial is shown below. Widths and heights of elements
are computed based on the "diameter" configuration property.</p>
<pre class="code prettyprint">/* VML implementation for IE */
v\:oval,
v\:shadow,
v\:fill {
behavior: url(#default#VML);
display: inline-block;
zoom: 1; *display: inline; /* IE < 8: fake inline-block */
}
.yui3-dial{
position:relative;
display:-moz-inline-stack;
display:inline-block;
zoom:1;
*display:inline;
}
.yui3-dial-content,
.yui3-dial-ring{
position:relative;
}
.yui3-dial-handle,
.yui3-dial-marker,
.yui3-dial-center-button,
.yui3-dial-reset-string,
.yui3-dial-handle-vml,
.yui3-dial-marker-vml,
.yui3-dial-center-button-vml,
.yui3-dial-ring-vml v\:oval,
.yui3-dial-center-button-vml v\:oval
{
position:absolute;
}
.yui3-dial-center-button-vml v\:oval {
font-size:1px;
top:0;
left:0;
}
.yui3-skin-sam .yui3-dial-hidden {
opacity:0;
filter:alpha(opacity=0);
}</pre>
</div>
</div>
</div>
<div class="yui3-u-1-4">
<div class="sidebar">
<div id="toc" class="sidebox">
<div class="hd">
<h2 class="no-toc">Table of Contents</h2>
</div>
<div class="bd">
<ul class="toc">
<li>
<a href="#getting-started">Getting Started</a>
</li>
<li>
<a href="#using-the-dial-widget">Using the Dial Widget</a>
<ul class="toc">
<li>
<a href="#anatomy-of-a-dial">Anatomy of a Dial</a>
<ul class="toc">
<li>
<a href="#dom-structure">Dom Structure</a>
</li>
</ul>
</li>
<li>
<a href="#markup-structure">Markup Structure</a>
</li>
<li>
<a href="#instantiating-the-dial">Instantiating the Dial</a>
<ul class="toc">
<li>
<a href="#attributes">Attributes</a>
</li>
<li>
<a href="#setting-and-constraining-the-dial-value">Setting and Constraining the Dial Value</a>
<ul class="toc">
<li>
<a href="#setting-and-getting-dial-values">Setting and Getting Dial Values</a>
</li>
<li>
<a href="#constraining-dial-values">Constraining Dial Values</a>
</li>
<li>
<a href="#sync-the-ui-if-the-dial-was-rendered-off-the-dom">Sync the UI If the Dial Was Rendered off the DOM</a>
</li>
</ul>
</li>
</ul>
</li>
<li>
<a href="#css">CSS</a>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="Create a Dial from existing markup on the page - a simple use case.">
<a href="dial-basic.html">Basic Dial</a>
</li>
<li data-description="Link a Dial with a text input field.">
<a href="dial-text-input.html">Dial Linked With Text Input</a>
</li>
<li data-description="Use image backgrounds to control the visual display of a Dial.">
<a href="dial-image-background.html">Dial With Image Background</a>
</li>
<li data-description="Use images to surround a Dial instance and provide additional styling.">
<a href="dial-image-surrounding.html">Dial With a Surrounding Image</a>
</li>
<li data-description="This example employs Dial to drive an interactive UI.">
<a href="dial-interactive.html">Dial With Interactive UI</a>
</li>
<li data-description="This example shows how to use Dial to animate an image sprite.">
<a href="duck.html">Image Sprite Animation with Dial</a>
</li>
</ul>
</div>
</div>
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples That Use This Component</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="Use the HSL color picker to select a new color. Then chose the color type you like best.">
<a href="../color/hsl-picker.html">HSL Color Picker</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>
<script>
YUI.Env.Tests = {
examples: [],
project: '../assets',
assets: '../assets/dial',
name: 'dial',
title: 'Dial',
newWindow: '',
auto: false
};
YUI.Env.Tests.examples.push('dial-basic');
YUI.Env.Tests.examples.push('dial-text-input');
YUI.Env.Tests.examples.push('dial-image-background');
YUI.Env.Tests.examples.push('dial-image-surrounding');
YUI.Env.Tests.examples.push('dial-interactive');
YUI.Env.Tests.examples.push('duck');
YUI.Env.Tests.examples.push('hsl-picker');
</script>
<script src="../assets/yui/test-runner.js"></script>
</body>
</html>