Documentation

Requirements

To use the scrollbar, your project needs to meet the following requirements:

• the svg root element needs to have a viewBox attribute set (e.g. viewBox="0 0 1100 700")
• you need to link to the following scripts in your SVG header to use the scrollbar: mapApp.js, helper_functions.js and scrollbar.js; please note, that not all of the functions in these files are needed. The depencies are listed below. This example also makes use of the button.js script.
• you need to include the global variable "myMapApp" of type "mapApp" into one of your js files, (e.g. var myMapApp = new mapApp(false,undefined);)
• you need to create an svg group element with a unique id in an appropriate position of your document tree to hold the graphics of the scrollbar (e.g. <g id="scrollbar1" />)
• it is recommended to place a background rectangle behind your SVG application to receive events on the root element level, e.g. loosing focus and calling the callback function when clicking outside of the scrollbar
• you need to initialize the scrollbar as described below

Features

• scrollbars can be horizontal or vertical
• they also work within a group that has a transform attribute set
• scrollbars, scrollers and scroll buttons can be individually styled to a certain extent by passing presentation attributes
• scroll buttons can be placed at both sides of the scrollbar, at just one side, or not at all
• scrollbars can be changed by using the scroller, the button or the scrollbar itself
• scrollbars can be scripted from other functions or objects
• scrollbars call callback functions with different event types as argument
• scripts may query the current scrollbar value at any time
• scrollbars may be hidden/shown
• scrollbars can be removed after creation

Dependencies on external functions

1. scrollbar.js:
   • all of the objects and functions in this file are necessary
2. mapApp.js:
   • all of the objects and functions in this file are necessary
3. timer.js:
   • all of the objects and functions in this file are necessary
4. helper_functions.js:
   • all the global variables at the top of the file
   • function getTransformToRootElement()

Constructor

The following constructor function creates the scrollbar:

var scrollbar = new scrollbar(id,parentNode,x,y,width,height,startValue,endValue,initialHeightPerc,initialOffset,scrollStep,scrollButtonLocations,scrollbarStyles,scrollerStyles,triangleStyles,highlightStyles,functionToCall) {
Example:
//first the scrollbar styles
var scrollbarStyles = {"fill":"whitesmoke","stroke":"dimgray","stroke-width":1};
var scrollerStyles = {"fill":"lightgray","stroke":"dimgray","stroke-width":1};
var triangleStyles = {"fill":"dimgray"};
var highlightStyles = {"fill":"dimgray","stroke":"dimgray","stroke-width":1};
myMapApp.scrollbars["sb1horiz"] = new scrollbar("sb1horiz","scrollbars1",50.5,250.5,899,15,scrolledObject1.maxX,scrolledObject1.minX,0.2495,0,0.005,"top_bottom",scrollbarStyles,scrollerStyles,triangleStyles,highlightStyles,scrolledObject1);

The arguments are the following:

1. id (String):
   unique id for the scrollbar
2. parentNode (String or node reference):
   group id or node reference to the parent group that will contain the scrollbar geometry
3. x (number, in viewBox coordinate system):
   x-coordinate of the scrollbar (upper left corner)
4. y (number, in viewBox coordinate system):
   y-coordinate of the scrollbar (upper left corner)
5. width (number, in viewBox coordinate system):
   width of the scrollbar (this includes the scroll buttons)
6. height (number, in viewBox coordinate system):
   height of the scrollbar (this includes the scroll buttons)
7. startValue (number, float):
   the start value of the scrollbar (at the left or top of the scrollbar)
8. endValue (number, float):
   the end value of the scrollbar (at the right or bottom of the scrollbar)
9. initialHeightPerc (number, percentage, float):
   the width of the scroller rectangle in relation to the scrollbar rectangle. This width indicates how much of the scrollable content is currently visible. The value should be between 0 and 1, typically smaller than 1 (otherwise you wouldn't have to scroll)
10. initialOffset (number, percentage, float):
    the initial (left or top) position of the scroller in relation to the scrollbar rectangle. The value must be between 0 and 1.
11. scrollStep (number, percentage, float):
    the step (percentage value of the whole scrollbar width or height) that the scroller should move when one of the scroll buttons is clicked. The same value, multiplied by 10 is used to scroll when clicking directly in the scrollbar
12. scrollButtonLocations (string, with an underbar as separator):
    this parameter indicates where the scroll buttons should be located in relation to the scrollbar. The separator is an underbar (_). Valid values are the following: "top_bottom", "bottom_bottom", "top_top" or "none_none". Other values generate an error. In case of an horizontal scrollbar, "top" translates into "left" and "bottom" into "right"
13. scrollbarStyles (array of literals with presentation attributes):
    an array literal containing the presentation attributes of the scrollbar rectangle; could include CSS classes; example: var {"fill":"whitesmoke","stroke":"dimgray","stroke-width":1};
14. scrollerStyles (array of literals with presentation attributes):
    an array literal containing the presentation attributes of the scroller rectangle; could include CSS classes; example: var scrollerStyles = {"fill":"lightgray","stroke":"dimgray","stroke-width":1}; note that the same presentation attributes are also used for the scroll buttons.
15. triangleStyles (array of literals with presentation attributes):
    an array literal containing the presentation attributes of the triangles in the scroller buttons; could include CSS classes; example: var triangleStyles = {"fill":"dimgray"};
16. highlightStyles (array of literals with presentation attributes):
    an array literal containing the presentation attributes of the active scroller rectangle and the active scroll buttons; could include CSS classes; these presentation attributes are applied when the scroller, scrollbar or the scrollbuttons are pressed; example: var highlightStyles = {"fill":"dimgray","stroke":"dimgray","stroke-width":1};
17. functionToCall (function or object or undefined):
    callBackFunction: you can pass a function, object or undefined. In the case of function and object the parameters returned are: id of the scrollbar (string), the changetype (string ("scrollStart"|"scrollChange"|"scrollEnd"|"scrolledStep")), current absolute value of the scrollbar (number, float) and the current percentage value of the scrollbar (number, float): In case of an object, it calls the method .scrollbarChanged(). In case of an undefined value, no callBack function is executed. The changetype values mean the following: scrollStart (the user just started scrolling, pressed the scroller rectangle), scrollChange (the user is actively scrolling while pressing/dragging the scroller rectangle), scrollEnd (the user released the scroller rectangle and stopped scrolling), scrolledStep (the user just scrolled stepwise pressing either the scroll buttons or the scrollbar).

Methods

• .getValue():
  returns the absolute and relative current value of the scrollbar, the values can be used as follows: var values = myScrollbar.getValue(); alert(values.abs+","+values.perc);
• .scrollToValue(value):
  sets the scrollbar to the specified absolute value of the scrollbar (number, float). Note that the specified value does not relate to the coordinate system of the SVG file but to the range given with .startValue and .endValue. The specified value must be within the range of the specified start and end value.
• .scrollToPercent(value):
  sets the scrollbar to the specified percent value of the scrollbar (number, float). The specified value must be within the range 0 and 1.
• .hide():
  hides the scrollbar by setting the display attribute of the parentGroup to "hidden"
• .show():
  shows the scrollbar by setting the display attribute of the parentGroup to "inherit"
• .remove():
  removes the scrollbar geometry by removing the parentGroup from its parent node

Known issues

• In the given example, there is a problem in Batik and Firefox 1.5/2.0 because content nested within an svg element, but outside the viewBox coordinate system is still receptive to events in these viewers. Note that this is not a bug in the scrollbar object but a problem of these viewers. Bug reports are already issued for these viewers. As a temporary workaround one could use a clipPath rectangle until the problem is fixed.

Planned future methods

• .removeScrollbar()
• .repos(x,y,width,height)
• .changeScrollerWidth(newWidthPerc)

Version history

• 0.9 (2006-10-12): initial version
• 0.9.1 (2006-10-30): added methods .show(), .hide() and .remove()

Credits

• Kevin Lindsey (tutorials on his website)