Provides a rotary knob control for Mootools
This widget aims to provide a rotary knob control for MooTools.
A Knob object can be instantiated with a variety of options, and the library also parses the DOM for elements with class .mooknob, replacing each with an instance of the Knob control.
All knobs require user-supplied styling: details below.
Knobs can be controlled with cursor keys, mouse drags, and double clicks, and provide WIA-ARIA attributes populated from both the initial data, and computed data in real time.
Knobs can monitor and reflect a field with a value attribute.
By default, the control increments and decrements by 1. If the control receives keyboard focus, the cursor keys may be used to increment and decrement the value - by 10 if if the shift key is depressed. If the alt/meta key is depressed whilst a cursor key is pressed, the value of the control is set to its maximum or minimum, dependent on the cursor key.
The effect of mouse dragging the control is scaled using the
option scale
: that is, the number of pixels moved will be multiplied
by the value of the scale
option (or data-scale
attribute) and added
to the current value of the knob: the great the range of the knob, the smaller
the value of scale
. If you do not like the speed of the knob movement
in relation to mouse dragging, change scale
.
A control can monitor and reflect values of another element's value
fileld: such element should be supplied via the monotpr field, as described in 'Options', below.
The initial value of the control comes from either the monitor
elements' value
attribute, or the options.value
(which may come from the data-value
attribute of the element
), or from the element's value
attribute, in that order.
As seems to be usual for MooTools, no CSS is supplied. However, the Docs/index.html page contains some examples. A basic gray and round knob can be achieved without graphics if you client supports the border-radius property of CSS3:
<style>
.rotary {
border: 1px solid black;
background: silver;
text-align: center;
border-radius: 50%;
font-weight: bold;
font-size:28pt;
width: 32pt;
height: 32pt;
}
</style>
If select the addpointer option (below), the widget will contain a UTF-8 up-arrow.
The widget can be configued using the attribute of any element
which it consumes. Any option listed under the JavaScript API
can be passed as an HTML attribute, prefixed with data-
.
The range of values the widget will supports (default ±100)
can be set with the aria-valuemin
and aria-valuemax
attributes
of the element, which equate to the object's range
option array.
The initial (described above) will be placed
in the aria-valuenow
and aria-valuetext
attributes, as well as
in the value
attribute, if present, otherwise in the data-value
attribute.
For example, the following element will produce a rotary knob with
an up-arrow (↑
), an initial value of 5, and range between 0 and 10:
<span id='knob1'
data-value='5'
aria-valuemin='0'
aria-valuemax='10'
>↑</span>
The equivalent to the above HTML would be:
new Knob({
element: 'knob1',
value: 5,
range: [0, 10]
});
The following options are available. Some may be supplied as dataset- attributes when their values are literal.
element
: the DOM element to replace with this controlvalue
: (0) The iInitial value of the control. If not supplied, taken from attributes value or data-valuerange
: ([-100, 100]) The minimum and maximum values. May be supplied in HTML as aria-valuemin and aria-valuemax.scale
: (null) Multiplier applied to the number of pixels the mosue may be moved, to acheive change in thevalue
field (see Events, below). This is set automatically upon initialisation, unless the user specifies a value.keychangeby
: (1) When arrow keys control the knob, thevalue
field is increased by this factorkeychangebywithshift
: (10) Askeychangeby
, above, but for when shift is held.monitor
: A name for, or instance of, a DOM element that has avalue
field that shoudl be monitored for changes, to be reflected by this control. Intended for text input elements.monitorMs
: (250) The interval, in milliseconds, at which to check themonitor
element, if supplied. The monitor element's value (an aria-related) attribute will also be updated with changes to the control.addpointer
: (↑) By default the module (since 0.3) replaceselement
's content with an up-arrow to the element. Disable this by setting this option to null or false.forceint
: (false) Force all values to be integersdegreesoffset
: (0) Offset, in degrees, to apply to the rotation of the knob. This does not effect the value of the control, only its appearance, and can change the style of the control form a pan control to a volume control, for example. The default is 0 but this may change.completedelay
: (500) Number of milliseconds to wait for inactivity before firing theonComplete
event.
In addition to the above options, the following events are supported:
onMousedown
: fired when the knob is clickedonMouseup
: fired when the knob is released but before it is renderedonComplete
: fired when no changes have taken place for the number milliseconds defined in thecompletedelay
option.onTick
: fired as the knob is turned
The options may be passed as HTML dataset attributes by prepending data-
.
The supplied code is wrapped:
(function(){
// Supplied code here
})
The onTick
event is intended to allow the user to adjust the behaviour
of the widget, and to allow this widget to affect other objects,
using the following object fields:
x
andy
represent the position of the mouse curosr relative to the knobmovement
contains the greater of these twovalue
contains the calculated value of the knobdegrees
contains the amount by which the knob will be rotated, afteronTick
has returned, and can be set in accordance with the value in degrees, as accepted by the CSS3 Transform/rotate property.
render
: Update the control to reflect the current state of thevalue
field, which may be set by supply a single, numeric argumentattach
: Called at instantiation to attach eveents to allow the control to operatedetach
: Removes events
-
Double click support seems to miss the very minimum value of the range.
-
Considering if the knob should support more intuative dragging, dependant upon the knob's current value.
When using HTML mark-up to create a knob, why do *valuemin* and *valuemax* not work?
The acceptable range of inputs should be specified through aria-valuemin
and aria-valuemax*, not
data-valueminand
data-valuemax`.
Why are arguments all lower case, rather than camel case?
To make parsing of dataset
attributes easier: these are all forced to lower case by the browser.