Methods

x is a number that defines the x position of the upper-lefthand corner of the slider

y is a number that defines the y position of the upper-lefthand corner of the slider

length is a number that determines the width or height of the slider. If the slider is horizontal, then length represents the width of the control. If the slider is vertical, then length represents the height of the control.

direction is a number that designates the angle, in degrees, at which the Slider object is to be drawn.

callback is a function reference which will be called each time the slider changes value. This parameter is optional.

bodyText is a string that uses pSVG to describe the appearance of the slider's body. This parameter is optional.

thumbText is a string that uses pSVG to describe the appearance of the slider's thumb. This parameter is optional.

init();

init() initialized all properties for this object. This method overrides the init method in the Widget object. The overridden method is called by init().

buildSVG();

buildSVG() converts the bodyText and thumbText properties to their equivalent SVG Document Fragments. These fragments are then added to the current SVG document.

This method overrides the abstract method in the Widget object.

addEventListeners();

addEventListeners() attaches all events listeners to the top-most slider node. These event listeners implement the dragging fuctionality of the Slider object.

This method overrides the abstract method in the Widget object.

setMin(min);

setMin() sets the lowest value to be used by the Slider object. If the current value property is smaller than the min parameter, then the value property is changed to the min parameter. The thumb position will be updated as necessary. The Slider object allows the min property to be greater than the max property. This effectively swaps the ending values of the Slider object.

min is a number that represents the smallest value used by the Slider object

setMax(max);

setMax() sets the highest value to be used by the Slider object. If the current value property is larger than the max parameter, then the value property is changed to the max parameter. The thumb position will be updated as necessary. The Slider object allows the max property to be less than the min property. This effectively swaps the ending values of the Slider object.

max is a number which represents the largest value used by the Slider object

setMinmax(min, max);

setMinmax() sets both the min and max properites of the Slider object. See setMin() and setMax() for further details.

setValue(value, call_callback);

setValue() sets the value property to the value parameter. The thumb's position is updated to the proper location for the passed value. If call_callback is true and the callback property are defind, then the callback function is called with the current value.

value is a number to which the value property will be set

call_callback is a boolean flag which determines if the callback function will be called by setValue().

setPosition(position, call_callback);

setPosition() sets the value property based on the position parameter. The thumb's position is updated to the proper location for the passed value. If call_callback is true and the callback property are defind, then the callback function is called with the current value. This function is used internally to convert the mouse coordinate to the correct value. There should be no need to use this function.

position is a number which represents the distance from the origin of the slider. This number is converted to the equivalent slider value.

call_callback is a boolean flag which determines if the callback function will be called by setValue().

findPosition(e);

findPosition() determines how far the user's mouse position is from the origin of the slider. The current implementation of this function allows for the Slider object to be rotated to any angle.

mousedown(e);

mousedown() is an event handler that is called when the mouse button is pressed over the slider graphics. This method activates the slider.

e is the event object passed by the mousedown event.

mouseup(e);

moueup() is an event handler that is called when the mouse button is released over the slider graphics. This method deactivates the slider.

e is the event object passed generated my the mouseup event.

mousemove(e);

mousemove() is an event handler that is called when the mouse is moved over the slider graphics. If the slider is active, this method calls set_value().

e is the event object passed generated my the mousemove event.

Properties

x is the x coordinate of the upper-lefthand corner of the slider. This property is inherited from the Widget object

y is the y coordinate of the upper-lefthand corner of the slider. This property is inherited from the Widget object

nodes is an object that is inherited from the Widget object. The properties of this object are used to reference key SVG DOM nodes. Slider defines the following nodes:

nodes.parent is the parent node of the slider graphics. This can be used to delete the slider from the SVG document.

nodes.body is a reference to the body node of the slider.

nodes.thumb is a reference to the thumb node of the slider.

size is the length of the slider dependent on the direction of the slider

direction is the angle at which the slider is drawn.

callback is function reference that will be called (optionally) when setValue() is called.

min is the minimum value of the slider. Note that min can be larger than max to effectively swap the end values of the slider

max is the maximum value of the slider. Note that max can be smaller than min to effectively swap the end values of the slider.

value is a number representing the current value of the slider

active is a boolean used to determine if the current slider is active. This is used internally only.

Use

Loading Slider into your SVG document

In order to use the Slider object in your SVG file, you will need to insert a <script> element inside of your <svg> element. As an example, if slider.js.gz is in the same directory as your SVG document, then you would include the Slider object with the following text:

<script xlink:href="slider.js.gz" />

Please note that the gzip file, slider.js.gz, contains all supporting files that are need to use the Slider object.

Creating a Slider

In order to create a new Slider object, you need to know the following: the upper-lefthand corner of the slider, the length of the slider, a callback function, the parent node of the slider graphics. The following section will discuss how to customize the appearance of your Slider.

The following line creates a slider at (50,200) with a length of 100 and appends it to the top-most SVG element. The function named "my_callback" will be invoked whenever the slider's position is updated.

Using pSVG

The Slider code allows for you define the appearance of the slider body and slider thumb. This code uses a variant of SVG that is being called pSVG, which stands for parametric SVG. pSVG looks exactly like SVG; however, two new features have been introduced.

The first feature allows for you to refer to any property value that exists within the Slider object. To access the object's property, pre-pend a dollar sign, '$', to the property name.

The second feature allows for you to execute any JavaScript code. The JavaScript code is replaced with the value that it returns upon execution.

When the preceding pSVG is used, the rectangle's x value will be set to the value of the Slider's x property. Likewise the y value will be set to the value of the Slider's y value. If the slider object has a "shade" property, then this value will be used to create a shade of grey of the rectangle.

pSVG is greedy when it comes to property names. Normally, this will not be a problem. However, if you need text to immediately follow a property without any spaces, you will need to slightly modify your property reference.

<text>${direction}-wise<text>

The preceding example will replace ${direction} with the direction property from the Slider object. The curly braces isolate the name of the property reference from the surrounding text.

<rect x="$x" y="$y" width="{$width + 5}" height="{$height + 5}/>

The preceding example introduces the method used to execute a line of JavaScript. All text contained within curly braces, '{' and '}', will be eval'ed by the JavaScript interpreter. The value returned by eval'ing this statement will take the place of the curly braces and all text contained within the curly braces. It is important to note that property references, like $width in this example, will be replaced before the text is executed. Although this example simply increases the width and height by five units, any JavaScript code can be used to create the resulting SVG. The entire contents of the pSVG can be composed of JavaScript alone...as long as it returns valid SVG. For example, an application could use getUrl() to allow a server to dynamically generate the slider's SVG document fragment.

Setting the Slider Value

Sometimes it is necessary to have another function change the value of your slider object. In order to perform this function, you would use something like the following:

slider.setValue(100);

In this example, the slider thumb will be moved to the 100 position.

Example

The following example shows two Sliders used to manipulate a triangle. To see the complete details of this example, right-click (or control-click) the SVG file and View Source. Viewing the source will show you how the actual body and thumb elements are defined in the <defs> section of the SVG document.

There is a lot going on in this simple example. If you look at the source, you will see that the sliders are being added to the <g> element whose id is "world". You may notice that rotation and translation transformations are being applied to the <g> element. When the sliders are added to the <g> element, these transforms will apply to them too. The current version of the Slider object now knows how to compensate for any transform that is applied to a slider or to any of its ancestors.

Try panning and zooming the SVG image. Notice that the sliders still work as expected. The same code that compensates for transformations applied to a slider also compensates for the current zoom and pan settings.

The top-most slider's appearance has been redefined using pSVG. Please view the <defs> section to see the definitions for the slider body and the slider thumb.

Download

Slider.js - this file contains the Slider source only. You will need to download the Widget object in order for this code to function.

slider3.js.gz - this file contains all files that are needed to create and use a Slider object.

Known Problems

If you drag the mouse out of the slider, let up on the mouse, and then return to the slider, the slider will continue to update as if the mouse button is being pressed. This can be fixed by using an transparent rectangle over the entire document to capture mouse events. This will need to be added to the Widget object.

History

Version 3.0

No longer clones DOM to create slider body and slider thumb

Implemented use of pSVG to describe the slider appearance

Removed Slider class property

Removed class event handlers

Uses Widget's event dispatcher (handleEvent) to invoke an eventListener on the active slider

Default appearances are built into the Slider class

Uses methods from Widget object to compensate for any transformation that are being applied to the slider. This compensates for the current pan and zoom

Version 2.0

Removed dependency on Node_Builder class

Clones pre-existing elements from svg document to create the thumb and body of the slider. Typically, these elements are defined in the <defs> section of the svg file.

Default slider has a more standard look

Version 1.1

Changed the event handlers to global functions instead of object methods. This was due to a problem in Netscape. If it's possible to get around this problem, then I will make these object methods in the future.

Added VERSION property

Changed sliders global to object property

Added min and max properties and implemented scaling with these properties

Implemented direction property to support any angle

Moved initialization code to it's own method to simplifiy overriding the Slider object

Added rotation support to make_controls() method

Added set_min(), set_max(), and set_minmax() methods

Changed set_value() to support min and max properties

Added set_position() to convert from the linear position on the slider to the value property

Added find_position() to convert from mouse coordinates to the linear position on the slider.

Altered SliderMove and SliderClick to call find_position() which removed redundant code and added the possibility for the user to override the mouse coordinate to linear position conversion.

getAttributeNS() is now coerced to a string in Find_Slider() to get around a Netscape bug.