DIR : /home/kozerus/public_html/pn/uize/site-source/js/Uize/Widget/Bar.js

/home/kozerus/public_html/pn/uize/site-source/js/Uize/Widget

/*______________
|       ______  |   U I Z E    J A V A S C R I P T    F R A M E W O R K
|     /      /  |   ---------------------------------------------------
|    /    O /   |    MODULE : Uize.Widget.Bar Class
|   /    / /    |
|  /    / /  /| |    ONLINE : http://www.uize.com
| /____/ /__/_| | COPYRIGHT : (c)2005-2016 UIZE
|          /___ |   LICENSE : Available under MIT License or GNU General Public License
|_______________|             http://www.uize.com/license.html
*/

/* Module Meta Data
	type: Class
	importance: 5
	codeCompleteness: 100
	docCompleteness: 25
*/

/*?
	Introduction
		The =Uize.Widget.Bar= class implements a widget for displaying numerical values using a bar, with full and empty indicators and an optional value knob.

		*DEVELOPERS:* `Chris van Rensburg`, `Bryan Hsueh`

		This module supports both horizontally and vertically oriented bars.
*/

Uize.module ({
	name:'Uize.Widget.Bar',
	required:[
		'Uize.Dom.Basics',
		'Uize.Dom.Pos'
	],
	builder:function (_superclass) {
		'use strict';

		var
			/*** Variables for Scruncher Optimization ***/
				_undefined,
				_Uize_Dom_Basics = Uize.Dom.Basics,
				_Uize_Dom_Pos = Uize.Dom.Pos
		;

		/*** Private Instance Methods ***/
			function _conformValue (_value) {
				var
					m = this,
					_minValue = m._minValidValue == _undefined ? m._minValue : m._minValidValue,
					_increments = m._increments
				;
				return (
					Uize.constrain (
						_increments ? (_minValue + Math.round ((_value - _minValue) / _increments) * _increments) : _value,
						_minValue,
						m._maxValidValue == _undefined ? m._maxValue : m._maxValidValue
					)
				);
			}

			function _updateUi () {
				var m = this;

				function _updateDimsObj (_name,_node) {
					var
						_dimsObjects = m._dimsObjects || (m._dimsObjects = {}),
						_newDimsObject = _Uize_Dom_Pos.getDimensions (_node)
					;
					if (!_dimsObjects [_name] || (_newDimsObject.width && _newDimsObject.height))
						_dimsObjects [_name] = _newDimsObject
					;
					return _dimsObjects [_name];
				}

				if (m.isWired) {
					var
						_orientationNo = m._orientationNo,
						_trackDimsObj = _updateDimsObj ('track',m._trackNode),
						_trackDims = [_trackDimsObj.width,_trackDimsObj.height],
						_knobNode = m._knobNode,
						_knobDimsObj = _updateDimsObj ('knob',_knobNode),
						_knobDims = [_knobDimsObj.width,_knobDimsObj.height],
						_scaleFunc = m._scaleFunc,
						_minValueScaled = _scaleFunc (m._minValue),
						_maxValueScaled = _scaleFunc (m._maxValue),
						_valueScaled = _scaleFunc (m._value),
						_knobVirtualPos = Math.round (
							(_valueScaled - _minValueScaled) /
							(_maxValueScaled - _minValueScaled) * (_trackDims [_orientationNo] - _knobDims [_orientationNo])
						),
						_knobPos = _orientationNo ? _trackDims [1] - _knobDims [1] - _knobVirtualPos : _knobVirtualPos,
						_knobCenter = Math.round (_knobPos + _knobDims [_orientationNo] / 2),
						_value = Uize.isNumber (m._decimalPlacesToDisplay)
							? m._value.toFixed (m._decimalPlacesToDisplay)
							: m._value
					;
					if (_knobNode) {
						_knobNode.style [_orientationNo ? 'top' : 'left'] = _knobPos + 'px';
						_knobNode.title = _value;
					}
					m._fullNode &&
						_Uize_Dom_Basics.setClipRect (
							m._fullNode,
							_orientationNo ? _knobCenter : 0,
							_orientationNo ? _trackDims [0] : _knobCenter,
							_trackDims [1],
							0
						)
					;
					m._emptyNode &&
						_Uize_Dom_Basics.setClipRect (
							m._emptyNode,
							0,
							_trackDims [0],
							_orientationNo ? _knobCenter : _trackDims [1],
							_orientationNo ? 0 : _knobCenter
						)
					;
					m._valueNode &&
						_Uize_Dom_Basics.setInnerHtml (
							m._valueNode,
							Uize.isNumber (m._decimalPlacesToDisplay)
								? m._value.toFixed (m._decimalPlacesToDisplay)
								: m._value
						)
					;
				}
			}

			function _conformValueAndUpdateUi () {
				var m = this;
				m.set ({_value:_conformValue.call (m,m._value)});
				_updateUi.call (m);
			}

		return _superclass.subclass ({
			instanceMethods:{
				updateUi:_updateUi,

				wireUi:function () {
					var m = this;
					if (!m.isWired) {
						m._trackNode = m.getNode ('track');
							/*?
								DOM Nodes
									track
										The =track= DOM node acts as a "guide" in which a bar's knob is to move. This node should be transparent when using the optional =full= and =empty= DOM nodes, in order for those nodes to be visible to the user. When not using those nodes, the track image can be set in the CSS style for this node or can be a child node.

										NOTES
										- this DOM node is required
							*/
						m._knobNode = m.getNode ('knob');
							/*?
								DOM Nodes
									knob
										The =knob= DOM node acts as an indicator for a bar's current value and - for sliders - is wired up for drag-and-drop and provides the user a way to change the value. This node must be a child node of the =track= DOM node.

										NOTES
										- this DOM node is required
							*/
						m._fullNode = m.getNode ('full');
							/*?
								DOM Nodes
									full
										The optional =full= DOM node acts as an indicator for the "full" side of a bar. For vertical bars, the full side is on the bottom side of the knob. For horizontal bars, the full side is on the left side of the knob.

										To display correctly, this node should occupy the same space in the layout as the optional =empty= DOM node and must have the same dimension on the axis of the knob's motion (i.e. height for vertical bars, and width for horizontal bars) as the =track= DOM node. It's not necessary that this node occupy the same space in the layout as the =track= DOM node - the full/empty indicators could be off to the side, outside of the bar's track. However, in many cases you'll see bars with the full/empty indicators right over the track.

										NOTES
										- this DOM node is optional
										- compare to the =empty= DOM node
							*/
						m._emptyNode = m.getNode ('empty');
							/*?
								DOM Nodes
									empty
										The optional =empty= DOM node acts as an indicator for the "empty" side of a bar. For vertical bars, the empty side is on the top side of the knob. For horizontal bars, the empty side is on the right side of the knob.

										To display correctly, this node should occupy the same space in the layout as the optional =full= DOM node and must have the same dimension on the axis of the knob's motion (i.e. height for vertical bars, and width for horizontal bars) as the =track= DOM node. It's not necessary that this node occupy the same space in the layout as the =track= DOM node - the full/empty indicators could be off to the side, outside of the bar's track. However, in many cases you'll see bars with the full/empty indicators right over the track.

										NOTES
										- this DOM node is optional
										- compare to the =full= DOM node
							*/
						m._valueNode = m.getNode ('value');
							/*?
								DOM Nodes
									value
										The optional =value= DOM node provides a convenient way to display a bar's current value. When this node is present, its innerHTML will be set to the bar's value, every time it changes.

										NOTES
										- this DOM node is optional
							*/

						_superclass.doMy (m,'wireUi');
					}
				}
			},

			stateProperties:{
				_decimalPlacesToDisplay:'decimalPlacesToDisplay',
					/*?
						State Properties
							decimalPlacesToDisplay
								[DOCUMENT]
					*/
				_increments:{
					name:'increments',
					onChange:_conformValueAndUpdateUi,
					value:1
					/*?
						State Properties
							increments
								[DOCUMENT]
					*/
				},
				// if set, this is the min valid value, otherwise, use minValue
				_minValidValue:{
					name:'minValidValue',
					onChange:_conformValueAndUpdateUi
					/*?
						State Properties
							minValidValue
								[DOCUMENT]
					*/
				},
				_minValue:{
					name:'minValue',
					onChange:_conformValueAndUpdateUi,
					value:0
					/*?
						State Properties
							minValue
								[DOCUMENT]
					*/
				},
				// if set, this is the max valid value, otherwise, use maxValue
				_maxValidValue:{
					name:'maxValidValue',
					onChange:_conformValueAndUpdateUi
					/*?
						State Properties
							maxValidValue
								[DOCUMENT]
					*/
				},
				_maxValue:{
					name:'maxValue',
					onChange:_conformValueAndUpdateUi,
					value:100
					/*?
						State Properties
							maxValue
								[DOCUMENT]
					*/
				},
				_orientation:{
					name:'orientation',
					value:'vertical'
					/*?
						State Properties
							orientation
								[DOCUMENT]
					*/
				},
				_orientationNo:{
					derived:'orientation: orientation == "vertical" ? 1 : 0',
					onChange:_updateUi
				},
				// this function can show the value in differe scale: eg, log(x+1), 1-1/x, x^2, etc.
				_scaleFunc:{
					name:'scaleFunc',
					value:Uize.returnX
					/*?
						State Properties
							scaleFunc
								[DOCUMENT]
					*/
				},
				_value:{
					name:'value',
					conformer:_conformValue,
					onChange:_updateUi,
					value:0
					/*?
						State Properties
							value
								[DOCUMENT]
					*/
				}
			}
		});
	}
});