Dial

Screenshot of the Dial widget 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.

The user sets the value of the dial by dragging its handle or clicking on the ring.

Getting Started

To include the source files for Dial and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.8.0/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

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

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Anatomy of a Dial

Dom Structure

The major parts of the Dial are:

Ring
Marker
User-draggable handle
Reset button

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.

A label string and a value string are dislayed above the dial.

Like other form controls, Dials are inline elements.

Markup Structure

The final rendered Dial has the markup structure shown below:

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

Instantiating the Dial

Note: be sure to add the yui3-skin-sam classname to the page's <body> element or to a parent element of the widget in order to apply the default CSS skin. See Understanding Skinning.

<body class="yui3-skin-sam"> <!-- You need this skin class -->

The only markup required to instantiate a Dial is an HTML tag into which the widget will be rendered.

<div id="demo"></div>

Dial extends the Widget class, following the same pattern as any widget constructor, accepting a configuration object to set the initial configuration for the widget.

Some commonly used configuration attributes are shown below.

YUI().use('dial', function(Y) {
    var dial = new Y.Dial({
        min:-220,
        max:220,
        stepsPerRevolution:100,
        value: 30,
    });
});

After creating and configuring the new Dial, Call the render method on your Dial object, passing it the selector of a container object. This renders it in the container and makes it usable.

var dial = new Y.Dial();
dial.render("#demo");

Attributes

The following configuration attributes are provided to define default values for each Dial widget:

Attribute	Description	Default
`min`	Minimum input value allowed	`-220`
`max`	Maximum input value allowed	`220`
`diameter`	Diameter of the dial control in pixels	`100`
`centerButtonDiameter`	The diameter of the center button. This value is a percentage of the diameter of the Dial widget.	`0.5`
`markerDiameter`	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.	`0.1`
`handleDiameter`	The diameter of the handle that sets the Dial value. This value is a percentage of the diameter of the Dial widget.	`0.2`
`value`	The initial value which will set the UI display	`0`
`minorStep`	Value is incremented/decremented by this value on arrow key press.	`1`
`majorStep`	Value is incremented/decremented by this value on page up/down key press.	`10`
`stepsPerRevolution`	One revolution of the dial adds/subtracts this many value units.	`100`
`decimalPlaces`	Number of digits to the right of decimal point to retain in the value.	`0`
`strings`	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.	`{label:'My label', resetStr:'Reset', tooltipHandle:'Drag to set value'}`
`handleDistance`	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.	`0.75`

Setting and Constraining the Dial Value

Setting and Getting Dial Values

Like any input element, the most important thing about a Dial is its value. value is managed as an attribute.

// 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);

Constraining Dial Values

A Dial's value is constrained between the configured min and max attribute values. Values outside this range are treated as the closer of min or max.

Configuring values for max and min that are respectively larger or smaller than the configured stepsPerRevolution or -stepsPerRevolution can be used to configure a Dial to allow the user to drag the handle more than 360°. By this means, a Dial can be configured to "go around and around," allowing a very large range of values.

YUI().use("dial", function(Y) {

    var dial = new Y.Dial({
        min:-520,
        max:720,
        stepsPerRevolution:100,
        value: 30,
    });
    dial.render("#demo");

});

Sync the UI If the Dial Was Rendered off the DOM

If a Dial is rendered off the DOM, you must call the Dial's syncUI() 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.

CSS

The core structural CSS for the Dial is shown below. Widths and heights of elements are computed based on the "diameter" configuration property.

/* 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);
}