Home :: GUI :: Widgets

  1. Introduction
  2. Reference
    1. Object Variables
      1. VERSION
    2. Inherited Methods
    3. Methods
      1. constructor
      2. init
      3. buildSVG
      4. addEventListeners
      5. setMin
      6. setMax
      7. setMinmax
      8. setValue
      9. setPosition
      10. findPosition
      11. mousedown
      12. mouseup
      13. mousemove
    4. Properties
      1. x
      2. y
      3. nodes
      4. size
      5. direction
      6. callback
      7. min
      8. max
      9. value
      10. active
      11. bodyText
      12. thumbText
    1. Use
      1. Loading Slider into you SVG Document
      2. Creating a Slider
      3. Using pSVG
      4. Setting the Slider Value
    2. Example
  3. Download
  4. Known Problems
  5. History

Introduction

Dr. Stefan Goessner was kind enough to share his Slider code with the SVG community. To ease the use of multiple sliders, I created a JavaScript Slider object.

With the Slider object, you can control the following characterstics of a slider:

  1. The slider's appearance
  2. The slider's (or thumb's) position
  3. The angle at which the slider is drawn
  4. The numerical range of values used by the slider

Version 3.0 introduces many new features that are being used in the SVGUI project. I decided to present these concepts here since the SVGUI will advance at a slow pace.


Reference

Object Variables

Slider.VERSION

This number represents the current version for this implementation of the Slider object. This property can be used by scripts to check that the correct version of the object is being used.

Inherited Methods

The following methods are inherited from the Widget object.

realize(svgParentNode);

textToSVG(text);

getUserCoordinate(node, x, y);

getTransformToElement(node);

handleEvent(e);

Methods

constructor - new Slider(x, y, length, direction, callback, bodyText, thumbText);

This method creates a new Slider object.

init();

buildSVG();

addEventListeners();

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);

mouseup(e);

mousemove(e);

Properties

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.


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:

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.

slider = new Slider(
    50, 200, 100, 0,
    my_callback
);
slider.realize(svgDocument.documentElement);

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.

Here are some examples to illustrate pSVG in use.

<rect x="$x" y="$y" width="100" height="16" fill="rgb($shade,$shade,$shade)"/>

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.

Color Picker is another example using multiple sliders.


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


History

Version 3.0

  1. No longer clones DOM to create slider body and slider thumb
  2. Implemented use of pSVG to describe the slider appearance
  3. Removed Slider class property
  4. Removed class event handlers
  5. Uses Widget's event dispatcher (handleEvent) to invoke an eventListener on the active slider
  6. Default appearances are built into the Slider class
  7. 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

  1. Removed dependency on Node_Builder class
  2. 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.
  3. Default slider has a more standard look

Version 1.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.
  2. Added VERSION property
  3. Changed sliders global to object property
  4. Added min and max properties and implemented scaling with these properties
  5. Implemented direction property to support any angle
  6. Moved initialization code to it's own method to simplifiy overriding the Slider object
  7. Added rotation support to make_controls() method
  8. Added set_min(), set_max(), and set_minmax() methods
  9. Changed set_value() to support min and max properties
  10. Added set_position() to convert from the linear position on the slider to the value property
  11. Added find_position() to convert from mouse coordinates to the linear position on the slider.
  12. 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.
  13. getAttributeNS() is now coerced to a string in Find_Slider() to get around a Netscape bug.