Dial.js revision 95291e847f8b5eb9c289221ca612fc7b7dff8bb9
/**
* Create a circular dial value range input visualized as a draggable handle on a
* background element.
*
* @module dial
*/
var supportsVML = false;
//testVMLNode;
supportsVML = true;
}
/**
* 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.
*
* @class Dial
* @extends Widget
* @param config {Object} Configuration object
* @constructor
*/
}
// Y.Dial static properties
/**
* The identity of the widget.
*
* @property Dial.NAME
* @type String
* @default 'dial'
* @readOnly
* @protected
* @static
*/
/**
* Static property used to define the default attribute configuration of
* the Widget.
*
* @property Dial.ATTRS
* @type {Object}
* @protected
* @static
*/
/**
* minimum value allowed
*
* @attribute min
* @type {Number}
* @default -220
*/
min : {
value:-220
},
/**
* maximum value allowed
*
* @attribute max
* @type {Number}
* @default 220
*/
max : {
value:220
},
/**
* diameter of the circular background object.
* Other objects scale accordingly.
* Set this only before rendering.
*
* @attribute diameter
* @type {Number} the number of px in diameter
* @default 100
* @writeOnce
*/
diameter : {
value:100
},
/**
* diameter of the handle object which users drag to change the value.
* Dial sets the pixel dimension of the handle equal to handleDiameter * diameter.
* Set this only before rendering.
*
* @attribute handleDiameter
* @type {Number}
* @default 0.2
* @writeOnce
*/
handleDiameter : {
value:0.2
},
/**
* diameter of the marker object which follows the angle of the handle during value changes.
* Dial sets the pixel dimension of the marker equal to markerDiameter * diameter.
* Set this only before rendering.
*
* @attribute markerDiameter
* @type {Number}
* @default 0.1
* @writeOnce
*/
markerDiameter : {
value:0.1
},
/**
* diameter of the center button object.
* Dial sets the pixel dimension of the centerButton equal to centerButtonDiameter * diameter.
* Set this only before rendering.
*
* @attribute centerButtonDiameter
* @type {Number}
* @default 0.1
* @writeOnce
*/
value:0.5
},
/**
* initial value of the Dial
*
* @attribute value
* @type {Number}
* @default 0
*/
value : {
value:0,
return this._validateValue(val);
}
},
/**
*
* @attribute minorStep
* @type {Number}
* @default 1
*/
minorStep : {
value:1
},
/**
*
* @attribute majorStep
* @type {Number}
* @default 10
*/
majorStep : {
value:10
},
/**
* number of value increments in one 360 degree revolution
* of the handle around the dial
*
* @attribute stepsPerRevolution
* @type {Number}
* @default 100
*/
value:100
},
/**
* number of decimal places of accuracy in the value
*
* @attribute decimalPlaces
* @type {Number}
* @default 0
*/
decimalPlaces : {
value:0
},
/**
* 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
*
* @attribute strings
* @type {Object} the values are HTML strings
* @default {label: 'My label', resetStr: 'Reset', tooltipHandle: 'Drag to set value'}
*/
strings: {
valueFn: function () {
}
},
/**
* distance from the center of the dial to the
* center of the marker and handle, when at rest.
* The value is a percent of the radius of the dial.
*
* @attribute handleDistance
* @type {number}
* @default 0.75
*/
value:0.75
}
};
/**
* returns a properly formed yui class name
*
* @function
* @param {String} string to be appended at the end of class name
* @return
* @private
*/
function makeClassName(str) {
}
/**
* array of static constants used to identify the classname applied to the Dial DOM objects
*
* @property Dial.CSS_CLASSES
* @type {Array}
* @private
* @static
*/
Dial.CSS_CLASSES = {
};
/* Static constants used to define the markup templates used to create Dial DOM elements */
/**
* template that will contain the Dial's label.
*
* @property Dial.LABEL_TEMPLATE
* @type {HTML}
* @default <div id="' + labelId + '" class="[...-label]"><span class="[...-label-string]">{label}</span><span class="[...-value-string]"></span></div>
* @protected
*/
Dial.LABEL_TEMPLATE = '<div id="' + labelId + '" class="' + Dial.CSS_CLASSES.label + '"><span class="' + Dial.CSS_CLASSES.labelString + '">{label}</span><span class="' + Dial.CSS_CLASSES.valueString + '"></span></div>';
if(supportsVML === false){
/**
* template that will contain the Dial's background ring.
*
* @property Dial.RING_TEMPLATE
* @type {HTML}
* @default <div class="[...-ring]"><div class="[...-northMark]"></div></div>
* @protected
*/
Dial.RING_TEMPLATE = '<div class="' + Dial.CSS_CLASSES.ring + '"><div class="' + Dial.CSS_CLASSES.northMark + '"></div></div>';
/**
* template that will contain the Dial's current angle marker.
*
* @property Dial.MARKER_TEMPLATE
* @type {HTML}
* @default <div class="[...-marker] [...-marker-hidden]"><div class="[...-markerUser]"></div></div>
* @protected
*/
Dial.MARKER_TEMPLATE = '<div class="' + Dial.CSS_CLASSES.marker + ' ' + Dial.CSS_CLASSES.hidden + '"></div>';
/**
* template that will contain the Dial's center button.
*
* @property Dial.CENTER_BUTTON_TEMPLATE
* @type {HTML}
* @default <div class="[...-centerButton]"><div class="[...-resetString]">' + Y.substitute('{resetStr}', Dial.ATTRS.strings.value) + '</div></div>
* @protected
*/
Dial.CENTER_BUTTON_TEMPLATE = '<div class="' + Dial.CSS_CLASSES.centerButton + '"><div class="' + Dial.CSS_CLASSES.resetString + ' ' + Dial.CSS_CLASSES.hidden + '">{resetStr}</div></div>';
/**
* template that will contain the Dial's handle.
*
* @property Dial.HANDLE_TEMPLATE
* @type {HTML}
* @default <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}"
* @protected
*/
Dial.HANDLE_TEMPLATE = '<div class="' + Dial.CSS_CLASSES.handle + '" aria-labelledby="' + labelId + '" aria-valuetext="" aria-valuemax="" aria-valuemin="" aria-valuenow="" role="slider" tabindex="0" title="{tooltipHandle}">';
}else{ // VML case
Dial.RING_TEMPLATE = '<div class="' + Dial.CSS_CLASSES.ring + ' ' + Dial.CSS_CLASSES.ringVml + '">'+
'<v:oval strokecolor="#ceccc0" strokeweight="1px"><v:fill type=gradient color="#8B8A7F" color2="#EDEDEB" angle="45"/></v:oval>'+
'</div>'+
'';
Dial.MARKER_TEMPLATE = '<div class="' + Dial.CSS_CLASSES.markerVml + ' ' + Dial.CSS_CLASSES.hidden + '">'+
'<v:oval stroked="false">'+
'<v:fill opacity="20%" color="#000"/>'+
'</v:oval>'+
'</div>'+
'';
Dial.CENTER_BUTTON_TEMPLATE = '<div class="' + Dial.CSS_CLASSES.centerButton + ' ' + Dial.CSS_CLASSES.centerButtonVml + '">'+
'<v:oval strokecolor="#ceccc0" strokeweight="1px">'+
'<v:fill type=gradient color="#C7C5B9" color2="#fefcf6" colors="35% #d9d7cb, 65% #fefcf6" angle="45"/>'+
'<v:shadow on="True" color="#000" opacity="10%" offset="2px, 2px"/>'+
'</v:oval>'+
'<div class="' + Dial.CSS_CLASSES.resetString + ' ' + Dial.CSS_CLASSES.hidden + '">{resetStr}</div>'+
'</div>'+
'';
Dial.HANDLE_TEMPLATE = '<div class="' + Dial.CSS_CLASSES.handleVml + '" aria-labelledby="' + labelId + '" aria-valuetext="" aria-valuemax="" aria-valuemin="" aria-valuenow="" role="slider" tabindex="0" title="{tooltipHandle}">'+
'<v:oval stroked="false">'+
'<v:fill opacity="20%" color="#6C3A3A"/>'+
'</v:oval>'+
'</div>'+
'';
}
/* Dial extends the base Widget class */
/**
* creates the DOM structure for the Dial.
*
* @method renderUI
* @protected
*/
renderUI : function() {
this._renderLabel();
this._renderRing();
this._renderMarker();
this._renderCenterButton();
this._renderHandle();
// object handles
// constants
// this._dd1 = null; // expose a global for the dd of the handle so we can delegate to DD's natural behavior the mousedown on the ring
this._minValue = this.get('min'); // saves doing a .get many times, but we need to remember to update this if/when we allow changing min or max after instantiation
// variables
this._timesWrapped = 0;
// init
this._setTimesWrappedFromValue(this._originalValue);
},
/**
* 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.
* @method _setBorderRadius
* @private
*/
_setBorderRadius : function(){
});
});
});
});
},
/**
* Creates the Y.DD.Drag instance used for the handle movement and
* binds Dial interaction to the configured value model.
*
* @method bindUI
* @protected
*/
bindUI : function() {
// Looking for a key event which will fire continously across browsers while the key is held down.
keyEventSpec += "38,40,33,34,35,36";
keyLeftRightSpec += "37,39";
Y.on('mouseenter', function(){this.one('.' + Dial.CSS_CLASSES.resetString).removeClass(Dial.CSS_CLASSES.hidden);}, this._centerButtonNode);
Y.on('mouseleave', function(){this.one('.' + Dial.CSS_CLASSES.resetString).addClass(Dial.CSS_CLASSES.hidden);}, this._centerButtonNode);
// Needed to replace mousedown/up with gesturemovestart/end to make behavior on touch devices work the same.
Y.on('gesturemovestart', function(e){e.stopPropagation();}, this._centerButtonNode); //[#2530206] need to add so mousedown doesn't propagate to ring and move the handle
Y.on('gesturemovestart', Y.bind(this._handleDrag, this), this._ringNode); // [#2530206] // need to send this to the _handleDrag
Y.on('gesturemoveend', Y.bind(function(){this._handleNode.focus();}, this), this._ringNode); // [#2530206] // need to re-focus on the handle so keyboard is accessible
this._dd1 = new Y.DD.Drag({ //// [#2530206] changed global this._dd1 from just var dd1 = new Y.DD.drag so
node: this._handleNode,
on : {
}
});
Y.bind(this._dd1.addHandle(this._ringNode), this); // [#2530206] added the ring as a handle to the dd1 (the dd of the handleNode)
},
/**
* Sets _timesWrapped based on Dial value
* to net integer revolutions the user dragged the handle around the Dial
*
* @method _setTimesWrappedFromValue
* @param val {Number} current value of the Dial
* @private
*/
_setTimesWrappedFromValue : function(val){
}else{
}
},
/**
* handles the user dragging the handle around the Dial, calculates the angle,
* checks for wrapping around top center
*
* @method _handleDrag
* @param e {DOMEvent} the drag event object
* @protected
*/
_handleDrag : function(e){
var handleCenterX, // changes for [#2530206]
handleCenterY, // changes for [#2530206]
ang,
// [#2530206] The center of the handle is different relative to the XY of the mousedown event, compared to the drag:drag event.
if(e.currentTarget === this._ringNode){ // the event was emitted from mousedown on ring, so center should be the XY of mousedown.
handleCenterX = e.pageX;
handleCenterY = e.pageY;
}else{ // the event was emitted from drag:drag of handle. The center of the handle is X + radius, Y + radius
}
ang = Math.atan( (this._centerYOnPage - handleCenterY) / (this._centerXOnPage - handleCenterX) ) * (180 / Math.PI);
// [#2530206] moved down after handleCenterX and Y are defined
ang = ((this._centerXOnPage - handleCenterX) < 0) ? ang + 90 : ang + 90 + 180; // Compensate for neg angles from Math.atan
if(e.type === 'drag:drag'){ // [#2530206] Make conditional. only check/change timesWrapped if dragging, NOT on mousedown.
// check for need to set timesWrapped
}
}else{ // event was a gesturemovestart (mousedown)
newValue = this._getNewValueFromMousedown(ang);// this was added for #2530306. Handles lots of cases of min and max wrapped and not, neg and pos
}
this._handleValuesBeyondMinMax(e, newValue);
},
/**
* gets the new value when mousedown or gesturemovestart on the ringNode
*
* @method _getNewValueFromMousedown
* @param ang {number} angle where user clicked on the dial
* @return newValue {number} the new value for the dial
* @protected
*/
// range min-to-max is greater than stepsPerRevolution (one revolution)
// This makes the behavior of "the mousedown is equal to drag and release the shortest way around the dial."
this._timesWrapped = ((ang - this._prevAng) > 0) ? (this._timesWrapped - 1) : (this._timesWrapped + 1);
}// else it didn't cross a wrapping boundary
// this happens when max is set at (North), an increment of stepsPerRevolution
// because of "else if", range is <= stepsPerRevolution
this._timesWrapped --;
}
// this range includes the wrap point (north)
// because of "else if", range is <= stepsPerRevolution
if(
(ang <= (minAng + maxAng) / 2) // the angle of this click is less than the max angle, incr timesWrapped
){
this._timesWrapped ++;
}else if(
// if prev angle is < max angle and...
// the angle of this click is > min angle, decr timesWrapped
// not zero. We don't want a previously min value of zero to have its _timesWrapped decremented
){
this._timesWrapped --;
}
}else{
// min - max range doesn't include the wrap point
// range is still <= stepsPerRevolution
// This is the bisection of the min-to-max range + 180. (opposite the bisection)
if(oppositeMidRangeAngle > 180){
}else{ //oppositeMidRangeAngle <= 180
}
return newValue;
}
}
newValue = this._getValueFromAngle(ang); // This function needs the correct, current _timesWrapped value.
return newValue;
},
/**
* handles the case where the value is less than min or greater than max
*
* @method _handleValuesBeyondMinMax
* @param e {DOMEvent} the event object
* @param newValue {number} current value of the dial
* @protected
*/
// If _getValueFromAngle() is passed 0, it increments the _timesWrapped value.
// handle hitting max and min and going beyond, stops at max or min
// [#2530206] transfer the mousedown event from the _ringNode to the _handleNode drag, so we can mousedown, then continue dragging
if(e.currentTarget === this._ringNode){
// Delegate to DD's natural behavior
this._dd1._handleMouseDownEvent(e);
}
this._setTimesWrappedFromValue(this._maxValue);
this._setTimesWrappedFromValue(this._minValue);
}
},
/**
* handles the user starting to drag the handle around the Dial
*
* @method _handleDragStart
* @param e {DOMEvent} the drag event object
* @protected
*/
_handleDragStart : function(e){
},
/*
* When handle is handleDragEnd, this animates the return to the fixed dial
*/
/**
* handles the end of a user dragging the handle, animates the handle returning to
* resting position.
*
* @method _handleDragEnd
* @protected
*/
_handleDragEnd : function(){
var node = this._handleNode;
easing: 'ease-in',
}, Y.bind(function(){
//[#2530206] only hide marker if not at max or min
// more persistant user visibility of when the dial is at max or min
}
}, this)
);
},
/**
* returns the XY of the fixed position, handleDistance, 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 obj node passed in is set.
*
* @method _setNodeToFixedRadius
* @param obj {Node}
* @param typeArray {Boolean} true returns an array [X,Y]
* @protected
* @return {Array} an array of [XY] is optionally returned
*/
if(typeArray){ // just need the style for css transform left and top to animate the handle drag:end
}else{
}
},
/**
* Synchronizes the DOM state with the attribute settings.
*
* @method syncUI
*/
syncUI : function() {
// Make the marker and the resetString display so their placement and borderRadius can be calculated, then hide them again.
// We would have used visibility:hidden in the css of this class,
// but IE8 VML never returns to visible after applying visibility:hidden then removing it.
// this._markerNode.removeClass(Dial.CSS_CLASSES.hidden); // found durring [#2530206] unnecessary. see 5 lines below it is added
// this._resetString.removeClass(Dial.CSS_CLASSES.hidden); // found durring [#2530206] unnecessary. see 5 lines below it is added
this._setSizes();
this._setBorderRadius();
this._centerYOnPage = (this._ringNode.getY() + this._ringNodeRadius); // moved from _handleDragStart for [#2530206]
this._centerXOnPage = (this._ringNode.getX() + this._ringNodeRadius); // moved from _handleDragStart for [#2530206]
},
/**
* sets the sizes of ring, center-button, marker, handle, and VML ovals in pixels.
* Needed only because some IE versions
* so these must be set in pixels.
* Normally these are set in % of the ring.
*
* @method _setSizes
* @protected
*/
_setSizes : function(){
var suffix = 'px';
};
// Set these (used for trig) this way instead of relative to dia,
// in case they have borders, have images etc.
// place the centerButton
/*
Place the resetString
This seems like it should be able to be done with CSS,
But since there is also a VML oval in IE that is absolute positioned,
The resetString ends up behind the VML oval.
*/
},
/**
* renders the DOM object for the Dial's label
*
* @method _renderLabel
* @protected
*/
_renderLabel : function() {
if (!label) {
}
this._labelNode = label;
},
/**
* renders the DOM object for the Dial's background ring
*
* @method _renderRing
* @protected
*/
_renderRing : function() {
if (!ring) {
}
},
/**
* renders the DOM object for the Dial's background marker which
* tracks the angle of the user dragging the handle
*
* @method _renderMarker
* @protected
*/
_renderMarker : function() {
if (!marker) {
}
this._markerNode = marker;
},
/**
* renders the DOM object for the Dial's center
*
* @method _renderCenterButton
* @protected
*/
_renderCenterButton : function() {
if (!centerButton) {
}
this._centerButtonNode = centerButton;
},
/**
* renders the DOM object for the Dial's user draggable handle
*
* @method _renderHandle
* @protected
*/
_renderHandle : function() {
if (!handle) {
}
this._handleNode = handle;
},
/**
* sets the visible UI label HTML string
*
* @method _setLabelString
* @param str {HTML}
* @protected
* @deprecated Use DialObjName.set('strings',{'label':'My new label'}); before DialObjName.render();
*/
_setLabelString : function(str) {
},
/**
* sets the visible UI label HTML string
*
* @method _setResetString
* @param str {HTML}
* @protected
* @deprecated Use DialObjName.set('strings',{'resetStr':'My new reset string'}); before DialObjName.render();
*/
_setResetString : function(str) {
// this._setXYResetString(); // This used to recenter the string in the button. Done with CSS now. Method has been removed.
// this._resetString.setContent(''); //We no longer show/hide the reset string with setContent but by addClass and removeClass .yui3-dial-reset-string-hidden
},
/**
* sets the tooltip HTML string in the Dial's handle
*
* @method _setTooltipString
* @param str {HTML}
* @protected
* @deprecated Use DialObjName.set('strings',{'tooltipHandle':'My new tooltip'}); before DialObjName.render();
*/
_setTooltipString : function(str) {
},
/**
* 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.
*
* @method _onDirectionKey
* @param e {Event} the key event
* @protected
*/
_onDirectionKey : function(e) {
e.preventDefault();
switch (e.charCode) {
case 38: // up
this._incrMinor();
break;
case 40: // down
this._decrMinor();
break;
case 36: // home
this._resetDial();
break;
case 35: // end
this._setToMax();
break;
case 33: // page up
this._incrMajor();
break;
case 34: // page down
this._decrMajor();
break;
}
},
/**
* sets the Dial's value in response to left or right key events
*
* @method _onLeftRightKey
* @param e {Event} the key event
* @protected
*/
_onLeftRightKey : function(e) {
e.preventDefault();
switch (e.charCode) {
case 37: // left
this._decrMinor();
break;
case 39: // right
this._incrMinor();
break;
}
},
/**
* increments Dial value by a minor increment
*
* @method _incrMinor
* @protected
*/
_incrMinor : function(){
// [#2530045] .toFixed returns a string.
// Dial's value needs a number. -0 makes it a number, but removes trailing zeros.
// Added toFixed(...) again in _uiSetValue where content of yui3-dial-value-string is set.
// Removing the toFixed here, loses the feature of "snap-to" when for example, stepsPerRevolution is 10 and decimalPlaces is 0.
},
/**
* decrements Dial value by a minor increment
*
* @method _decrMinor
* @protected
*/
_decrMinor : function(){
},
/**
* increments Dial value by a major increment
*
* @method _incrMajor
* @protected
*/
_incrMajor : function(){
},
/**
* decrements Dial value by a major increment
*
* @method _decrMajor
* @protected
*/
_decrMajor : function(){
},
/**
* sets Dial value to dial's max attr
*
* @method _setToMax
* @protected
*/
_setToMax : function(){
},
/**
* sets Dial value to dial's min attr
*
* @method _setToMin
* @protected
*/
_setToMin : function(){
},
/**
* resets Dial value to the orignal initial value.
*
* @method _resetDial
* @protected
*/
_resetDial : function(e){
this._handleNode.focus();
},
/**
* returns the handle angle associated with the current value of the Dial.
* Returns a number between 0 and 360.
*
* @method _getAngleFromValue
* @param newVal {Number} the current value of the Dial
* @return {Number} the angle associated with the current Dial value
* @protected
*/
_getAngleFromValue : function(newVal){
},
/**
* returns the value of the Dial calculated from the current handle angle
*
* @method _getValueFromAngle
* @param angle {Number} the current angle of the Dial's handle
* @return {Number} the current Dial value corresponding to the handle position
* @protected
*/
_getValueFromAngle : function(angle){
if(angle < 0){
}else if(angle === 0){
angle = 360;
}
//return Math.round(value * 100) / 100;
},
/**
* calls the method to update the UI whenever the Dial value changes
*
* @method _afterValueChange
* @param e {Event}
* @protected
*/
_afterValueChange : function(e) {
this._uiSetValue(e.newVal);
},
/**
* Changes a value to have the correct decimal places per the attribute decimalPlaces
*
* @method _valueToDecimalPlaces
* @param val {Number} a raw value to set to the Dial
* @return {Number} the input val changed to have the correct decimal places
* @protected
*/
_valueToDecimalPlaces : function(val) { // [#2530206] cleaned up and better user feedback of when it's max or min.
},
/**
* Updates the UI display value of the Dial to reflect
* the value passed in.
* Makes all other needed UI display changes
*
* @method _uiSetValue
* @param val {Number} value of the Dial
* @protected
*/
_uiSetValue : function(val) { // [#2530206] cleaned up and better user feedback of when it's max or min.
this._setTimesWrappedFromValue(val);
this._setNodeToFixedRadius(this._handleNode, false);
}
this._setNodeToFixedRadius(this._markerNode, false);
if(supportsVML === true){
}
}else{ // not max or min
if(supportsVML === true){
}
if(this._handleNode.hasClass(Dial.CSS_CLASSES.dragging) === false){ // if not max || min, and not dragging handle, hide the marker
}
}
},
/**
* value attribute default validator. Verifies that
*
* @method _validateValue
* @param val {Number} value of the Dial
* @protected
*/
_validateValue: function(val) {
}
});