# Yahoo! UI Library

### dial 3.3.0

Yahoo! UI Library > dial > Dial
Search:
Filters Show Private Show Protected Show Deprecated

## Class Dial - extends Widget

Create a dial to represent an input control capable of representing a series of intermediate states based on the position of the Dial's handle. These states are typically aligned to a value algorithm whereby the angle of the handle's position corresponds to a given value.

### Constructor

Dial `( config )`

Parameters:
  `config <Object>` Configuration object

### Properties

#### Dial.ATTRS - `protected static {Object}`

Static property used to define the default attribute configuration of the Widget.

#### Dial.CENTER_BUTTON_TEMPLATE - `protected {String}`

template that will contain the Dial's center button.
Default Value: <div class="[...-centerButton]"><div class="[...-resetString]">' + Y.substitute('{resetStr}', Dial.ATTRS.strings.value) + '</div></div>

#### Dial.CSS_CLASSES - `private static {Array}`

array of static constants used to identify the classname applied to the Dial DOM objects

#### Dial.HANDLE_TEMPLATE - `protected {String}`

template that will contain the Dial's handle.
Default Value: <div class="[...-handle]"><div class="[...-handleUser]" aria-labelledby="' + labelId + '" aria-valuetext="" aria-valuemax="" aria-valuemin="" aria-valuenow="" role="slider" tabindex="0"></div></div>';// title="{tooltipHandle}"

#### Dial.LABEL_TEMPLATE - `protected {String}`

template that will contain the Dial's label.
Default Value: <div>...</div>

#### Dial.MARKER_TEMPLATE - `protected {String}`

template that will contain the Dial's current angle marker.
Default Value: <div class="[...-marker] [...-marker-hidden]"><div class="[...-markerUser]"></div></div>

#### Dial.NAME - `protected static String`

The identity of the widget.
Default Value: 'dial'

#### Dial.RING_TEMPLATE - `protected {String}`

template that will contain the Dial's background ring.
Default Value: <div class="[...-ring]"><div class="[...-northMark]"></div></div>

#### Properties inherited from Plugin.Host:

`PluginHost`

#### Properties inherited from Attribute:

``

#### Properties inherited from Widget:

`_UI_ATTRS, BOUNDING_TEMPLATE, CONTENT_TEMPLATE, DEF_PARENT_NODE, DEF_UNIT, UI_EVENTS`

#### Properties inherited from Base:

`name`

### Methods

#### _afterValueChange

`protected void _afterValueChange ( e )`
calls the method to update the UI whenever the Dial value changes

Parameters:
  `e <Event>`

#### _decrMajor

`protected void _decrMajor ( )`
decrements Dial value by a major increment

#### _decrMinor

`protected void _decrMinor ( )`
decrements Dial value by a minor increment

#### _dialCenterOut

`void _dialCenterOut ( e )`
Sets the string in the object the user clicks to reset the Dial value to ""

Parameters:
  `e <DOMEvent>` the mouseover event object

#### _dialCenterOver

`void _dialCenterOver ( e )`
Sets the string in the object the user clicks to reset the Dial value

Parameters:
  `e <DOMEvent>` the mouseover event object

#### _getAngleFromValue

`protected Number _getAngleFromValue ( newVal )`
returns the handle angle associated with the current value of the Dial

Parameters:
  `newVal <Number>` the current value of the Dial

Returns: `Number`
  the angle associated with the current Dial value

#### _getValueFromAngle

`protected Number _getValueFromAngle ( angle )`
returns the value of the Dial calculated from the current handle angle

Parameters:
  `angle <Number>` the current angle of the Dial's handle

Returns: `Number`
  the current Dial value corresponding to the handle position

#### _handleDrag

`protected void _handleDrag ( e )`
handles the user dragging the handle around the Dial, calculates the angle, checks for wrapping around top center, handles exceeding min or max values

Parameters:
  `e <DOMEvent>` the drag event object

#### _handleDragEnd

`protected void _handleDragEnd ( )`
handles the end of a user dragging the handle, animates the handle returning to resting position.

#### _handleDragStart

`protected void _handleDragStart ( e )`
handles the user starting to drag the handle around the Dial

Parameters:
  `e <DOMEvent>` the drag event object

#### _incrMajor

`protected void _incrMajor ( )`
increments Dial value by a major increment

#### _incrMinor

`protected void _incrMinor ( )`
increments Dial value by a minor increment

#### _onDirectionKey

`protected void _onDirectionKey ( e )`
sets the Dial's value in response to key events. Left and right keys are in a separate method in case an implementation wants to increment values but needs left and right arrow keys for other purposes.

Parameters:
  `e <Event>` the key event

#### _onLeftRightKey

`protected void _onLeftRightKey ( e )`
sets the Dial's value in response to left or right key events

Parameters:
  `e <Event>` the key event

#### _renderCenterButton

`protected void _renderCenterButton ( )`
renders the DOM object for the Dial's center

#### _renderHandle

`protected void _renderHandle ( )`
renders the DOM object for the Dial's user draggable handle

#### _renderLabel

`protected void _renderLabel ( )`
renders the DOM object for the Dial's label

#### _renderMarker

`protected void _renderMarker ( )`
renders the DOM object for the Dial's background marker which tracks the angle of the user dragging the handle

#### _renderRing

`protected void _renderRing ( )`
renders the DOM object for the Dial's background ring

#### _resetDial

`protected void _resetDial ( )`
resets Dial value to the orignal initial value.

#### _setBorderRadius

`private void _setBorderRadius ( )`
Sets -webkit-border-radius to 50% of width/height of the ring, handle-user, marker-user, and center-button. This is needed for iOS 3.x. The objects render square if the radius is > 50% of the width/height

#### _setLabelString

`protected void _setLabelString ( str )`
sets the visible UI label string

Parameters:
  `str <String>`

#### _setNodeToFixedRadius

`protected Array _setNodeToFixedRadius ( obj , typeArray )`
returns the XY of the fixed position, handleDist, from the center of the Dial (resting position) The XY also represents the angle related to the current value If typeArray is true, [X,Y] is returned. If typeArray is false, the XY of the node passed is set.

Parameters:
  `obj <Node>`
  `typeArray <Boolean>` true returns an array [X,Y]

Returns: `Array`
  an array of [XY] is optionally returned

#### _setResetString

`protected void _setResetString ( str )`
sets the visible UI label string

Parameters:
  `str <String>`

#### _setTimesWrapedFromValue

`private void _setTimesWrapedFromValue ( val )`
Sets _timesWrapped based on Dial value to net integer revolutions the user dragged the handle around the Dial

Parameters:
  `val <Number>` current value of the Dial

#### _setTooltipString

`protected void _setTooltipString ( str )`
sets the tooltip string in the Dial's handle

Parameters:
  `str <String>`

#### _setVMLSizes

`protected void _setVMLSizes ( )`
sets the sizes of ring, center-button, marker and handle VML ovals in pixels. Needed only in some IE versions that ignore percent style sizes/offsets. so these must be set in pixels. Normally these are set in % of the ring.

#### _setXYResetString

`protected void _setXYResetString ( )`
places the centerbutton's reset string in the center of the button based on the size of the string object

#### _uiSetValue

`protected void _uiSetValue ( val )`
Updates the UI display value of the Dial to reflect the value passed in. Makes all other needed UI display changes

Parameters:
  `val <Number>` value of the Dial

#### _validateValue

`protected void _validateValue ( val )`
value attribute default validator. Verifies that the value being set lies between the min/max value

Parameters:
  `val <Number>` value of the Dial

#### bindUI

`protected void bindUI ( )`
Creates the Y.DD.Drag instance used for the handle movement and binds Dial interaction to the configured value model.

#### renderUI

`protected void renderUI ( )`
creates the DOM structure for the Dial.

#### syncUI

`void syncUI ( )`
Synchronizes the DOM state with the attribute settings.

#### Methods inherited from EventTarget:

`_getType, _monitor, _parseType, addTarget, after, before, bubble, detach, detachAll, fire, getEvent, getTargets, on, once, parseType, publish, removeTarget, subscribe, unsubscribe, unsubscribeAll`

#### Methods inherited from Attribute:

`_addAttrs, _addLazyAttr, _defAttrChangeFn, _fireAttrChange, _getAttr, _getAttrCfg, _getAttrInitVal, _getAttrs, _getStateVal, _isLazyAttr, _normAttrVals, _protectAttrs, _set, _setAttr, _setAttrs, _setAttrVal, _setStateVal, addAttr, addAttrs, attrAdded, get, getAttrs, modifyAttr, removeAttr, reset, set, setAttrs`

#### Methods inherited from Widget:

`_applyParsedConfig, _applyParser, _bindAttrUI, _bindDOM, _bindUI, _createUIEvent, _defaultCB, _defRenderFn, _destroyUIEvents, _getHtmlParser, _getSrcNode, _getStrings, _getUIEventNode, _guid, _initUIEvent, _isUIEvent, _onDocFocus, _onDocMouseDown, _removeLoadingClassNames, _renderBox, _renderBoxClassNames, _renderUI, _setAttrUI, _setBB, _setBox, _setCB, _setStrings, _strSetter, _syncAttrUI, _syncUI, _uiSetDim, _uiSetDisabled, _uiSetFocused, _uiSetHeight, _uiSetTabIndex, _uiSetVisible, _uiSetWidth, _uiSizeCB, _unbindDOM, _unbindUI, _validTabIndex, bindUI, blur, destructor, disable, enable, focus, getClassName, getDefaultLocale, getSkinName, getString, getStrings, hide, initializer, render, renderer, renderUI, show, syncUI, toString`

#### Methods inherited from Base:

`_aggregateAttrs, _defDestroyFn, _defInitFn, _destroyHierarchy, _filterAttrCfs, _getAttrCfgs, _getClasses, _initHierarchy, _initHierarchyData, _preInitEventCfg, destroy, init, toString`

#### Methods inherited from Plugin.Host:

`_destroyPlugins, _initPlugins, hasPlugin, plug, unplug`

### Events

#### decimalPlacesChange

`decimalPlacesChange ( event )`
Fires when the value for the configuration attribute 'decimalPlaces' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### diameterChange

`diameterChange ( event )`
Fires when the value for the configuration attribute 'diameter' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### handleDistChange

`handleDistChange ( event )`
Fires when the value for the configuration attribute 'handleDist' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### majorStepChange

`majorStepChange ( event )`
Fires when the value for the configuration attribute 'majorStep' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### maxChange

`maxChange ( event )`
Fires when the value for the configuration attribute 'max' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### minChange

`minChange ( event )`
Fires when the value for the configuration attribute 'min' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### minorStepChange

`minorStepChange ( event )`
Fires when the value for the configuration attribute 'minorStep' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### stepsPerRevChange

`stepsPerRevChange ( event )`
Fires when the value for the configuration attribute 'stepsPerRev' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### stringsChange

`stringsChange ( event )`
Fires when the value for the configuration attribute 'strings' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### valueChange

`valueChange ( event )`
Fires when the value for the configuration attribute 'value' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### Events inherited from Widget:

`boundingBoxChange, contentBoxChange, disabledChange, focusedChange, heightChange, idChange, localeChange, renderChange, renderedChange, srcNodeChange, stringsChange, tabIndexChange, visibleChange, widget:contentUpdate, widget:render, widthChange,`

#### Events inherited from Base:

`destroy, destroyedChange, init, initializedChange,`

### Configuration Attributes

#### decimalPlaces `- {Number}`

number of decimal places of accuracy in the value
Default Value: 0

#### diameter `- writeonce {Number} the number of px in diameter`

diameter of the circular background object. Other objects scale accordingly Set this only before rendering.
Default Value: 100

#### handleDist `- {number}`

distance from the center of the dial to the resting place of the center of the handle and marker. The value is a percent of the radius of the dial.
Default Value: 0.75

#### majorStep `- {Number}`

amount to increment/decrement the dial value when the page up/down keys are pressed
Default Value: 10

#### max `- {Number}`

maximum value allowed
Default Value: 220

#### min `- {Number}`

minimum value allowed
Default Value: -220

#### minorStep `- {Number}`

amount to increment/decrement the dial value when the arrow up/down/left/right keys are pressed
Default Value: 1

#### stepsPerRev `- {Number}`

number of value increments in one 360 degree revolution of the handle around the dial
Default Value: 100

#### strings `- {Object}`

visible strings for the dial UI. This attribute is defined by the base Widget class but has an empty value. The Dial is simply providing a default value for the attribute. Gets localized strings in the current language
Default Value: {label: 'My label', resetStr: 'Reset', tooltipHandle: 'Drag to set value'}

#### value `- {Number}`

initial value of the Dial
Default Value: 0

#### Configuration attributes inherited from Widget:

`boundingBox, contentBox, disabled, focused, height, id, locale render rendered srcNode strings tabIndex visible width`

#### Configuration attributes inherited from Base:

`destroyed initialized`

Copyright © 2011 Yahoo! Inc. All rights reserved.