knobRot.js demonstration


Introduction:

I present you with a jQuery plugin that turns ordinary text fields into rotary knobs. As you will soon see, the heavy lifting provided by this plugin makes it very simple to get any knob-related problem sorted.

Basic Knob:

This is a rotary knob with a value range between -100 and 100. It is center detented (that means it snaps) to 0, with a sensitivity of -10 to 10 for the snapping. There are 64 frames in the knob image - the code works out all the hard stuff. The only other code I needed was a simple input text field, and a line of CSS defining the background image the knob should use.

Go ahead, click it and drag.

	$('#basic-knob').knobRot();
			

Basic Knob - Horizontal:

This is the same as before - but notice that you now drag from side to side. The mouse cursor changes appropriately, saving you the hassle of dealing with cross-browser event bubbling nightmares.

	$('#basic-knob-horizontal').knobRot({dragVertical: false});
			

Hover and drag-state effects:

If you use a sprite sheet stacked vertically with normal, hover and drag state graphics, you can automatically create hover and dragging effects (the plug-in adds a 'dragging' class to help with this)...

	$('#circle-knob').knobRot({
		'classes': ['circle'],
		'frameCount': 69,
		'detent': true,
		'detentThreshold': 5,
		'minimumValue': -60,
		'maximumValue': 60
	});				
			

Discrete steps:

Here is another one. This is restricted to only 5 steps, in a range of 1 to 5. Even though this particular knob has 45 frames in its animation, the plugin is working out how to map calculated values to frame numbers, saving you from having to do the tedious math.

If you look at the settings, you may also notice that the drag multiplier is set to 0.02. This is because the range is reduced, so you need to reduce the amount each pixel of dragging adds to the value otherwise the knob will spin too quickly.

		
	$('#black-knob').knobRot({
		'classes': ['black'],
		'frameWidth': 66,
		'frameHeight': 66,
		'frameCount': 45,
		'detent': false,
		'discreteSteps': true,
		'stepCount': 5,
		'minimumValue': 1,
		'maximumValue': 5,
		'dragMultiplier': 0.02
	});				
			

Spawn a swarm of knobs:


Simply by adding some text fields and calling the following code, you can add a swarm of knobs to your page.

		
	$('.knob-swarm').knobRot({
		'classes': ['circle'],
		'frameCount': 69,
		'detent': true,
		'detentThreshold': 5,
		'minimumValue': -60,
		'maximumValue': 60
	});							
			

How to get the graphics:

You can use KnobMan to generate the button graphics. Export your knob as a horizontal strip of frames (click for an example with hover and drag variants.)

Plugin source code

To get the source code, or if you have any questions, feature requests or bug reports feel free contact me via my GitHub Account. My blog is back this way.

Full settings list

These are all of the available settings. They should be fairly self-explanatory, ask for support over at github if you have any issues

	// The default class - over-ride this for different knob styles
	classes: ['rot-knob'],
			
	// The number of frames in the knob image				
	frameCount: 64,
	
	// The dimensions of the source frame in PX				
	frameWidth: 64,
	frameHeight: 64,				
				
	// The value range				
	minimumValue: -100,
	maximumValue: 100,				
				
	// If detent is true, detentValue specifies the snap value				
	// detentThreshold specifies the value range either side that
	// will 'snap' to the detentValue
	detent: true,	
	detentValue: 0,
	detentThreshold: 10,
	
	// If the knob has a discrete number of steps, how many?
	// Discrete steps can be used for things like a switch you can drag
	// on or off, etc.				
	discreteSteps: false,
	stepCount: 2,
	
	// If dragVertical is false, horizontal dragging modifies the value				
	dragVertical: true,
	
	// Invert the direction of the change
	invertDirection: false,				

	// The speed at which the knob value changes when dragged 
	// Higher numbers equal faster drag speed				
	dragMultiplier: 1,							

	// The FPS of the knob animation
	animationFPS: 25,
	
	// Whether or not to hide the associated input element
	hideInput: false,
	
	// Whether or not to hide the real value field
	hideRealValue: true,				
	
	// If isToggle is true, rather than dragging to change the value
	// you simply click to toggle between max and min - all other settings
	// to do with detenting and steps will be ignored - step count will
	// be forced to true
	// Not yet implemented
	isToggle: true				
		

Events

Each knob will fire custom events. Currently, these are in an early stage of development but they are scheduled to be improved soon.

The available events are as follows:

Event name Description Parameters
knobdragstart Triggered when the user starts dragging a knob.
knobrefresh Triggered when the knob value requires a refresh.
knobdrag Triggered during knob drag.
knobmouseover Triggered when a knob mouseover event occurs (not triggered if currently dragging).
knobmouseout Triggered when a knob mouseout event occurs.
knobready Triggered when a knob is fully initialised and all of its events and mappings are set up.
knobenterdetent Triggered when the knob detents, or snaps to its center value.
knobleavedetent Triggered when the knob leaves its center value.
knobvaluemin Triggered when the knob meets or exceeds its minimum limit.
knobvaluemax Triggered when the knob meets or exceeds its maximum limit.
knobframechange Triggered when the frame changes. 1: Knob Data Object | 2: Old Frame | 3: New Frame

Functions

The following functions are available after a knob is initialised:

To return the value of the specified knob:
$('myselector').knobRot('get')
To set the value of the specified knob, or knobs (will work with a collection):
$('myselector').knobRot('set', value)

Credits

Other than the use of jQuery and KnobMan, all of the work here is my own. It's free for you guys to use however you want, though some feedback would be nice if you do use it. Check out my blog "Domitable" for more cool stuff.