Documentation

Requirements

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

• it is required that the svg root element has a viewBox (e.g. viewBox="0 0 1024 768"), width and height attribute set.
• you need to link to the following scripts in your SVG file header to use the colourPicker: helper_functions.js, mapApp.js, colourPicker.js and slider.js. For the example to run, you'll also need the button.js and timer.js scripts; please note, that not all of the functions in these files are needed. The depencies to functions in the file "helper_functions.js" are listed below.
• 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 colourPicker object (e.g. <g id="colourPicker" />)
• 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 sliders/colourPicker
• you need to initialize the colourPicker object as described below in the constructor section

Features

• HSV colour picker, hue slider is compulsary
• optional value and saturation sliders
• optional transparency/opacity slider
• hue range can be restricted
• colour picker displays RGBA and HSVA values
• stroke and fill colours can be set individually
• colour picker can be resized and moved
• colour values can be queried and set from other js functions

Dependencies on external functions

1. colourPicker.js:
   • all of the objects and functions in this file are necessary
2. slider.js:
   • all of the objects and functions in this file are necessary
3. mapApp.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()
   • function leftOfTest()
   • function intersect2lines()
   • function toPolarDist()
   • function toPolarDir()
   • function rgb2hsv()
   • function hsv2rgb()

Constructor

The following constructor function creates the colourPicker:

var myColourPicker = colourPicker(id,parentNode,x,y,width,height,bgstyles,textstyles,sliderSymbId,satSliderVisible,valSliderVisible,alphaSliderVisible,colValTextVisible,fillVisible,strokeVisible,startHue,endHue,nrStopVals,fillStartColor,strokeStartColor,functionToCall);

Example:
//first some colour picker styles
var cpBgStyles = {"fill":"gainsboro"};
var cpTextStyles = {"font-family":"Arial,Helvetica","font-size":12,"fill":"dimgray"};
myMapApp.colourPickers["myColourPicker1"] = new colourPicker("colourPicker1","colourPickers",200,400,300,120,cpBgStyles,cpTextStyles,"sliderSymbol",true,true,true,true,true,true,0,360,7,"0,255,0,1","0,0,0,0.7",undefined);

The arguments are the following:

1. id (String):
   id of the colourPicker
2. parentNode (String or node reference):
   group id or node reference to the parent group that will contain the colourPicker geometry
3. x (number, float (in viewBox coordinates)):
   the left side of the colour picker box
4. y (number, float (in viewBox coordinates)):
   the top of the colour picker box
5. width (number, float (in viewBox coordinates)):
   the width of the colour picker box
6. height (number, float (in viewBox coordinates)):
   the height of the colour picker box
7. bgStyles (Array of literals with presentation attributes):
   an array literal containing the presentation attributes of the colourPicker background box; could include CSS classes; example: var cpBgStyles = {"fill":"gainsboro"};
8. textStyles (Array of literals with presentation attributes):
   an array literal containing the presentation attributes of the colourPicker text elements; could include CSS classes; should at least include a "font-size" attribute; example: var cpTextStyles = {"font-family":"Arial,Helvetica","font-size":12,"fill":"dimgray"};
9. sliderSymbId (string):
   the id (string) of the slider symbol
10. satSliderVisible (boolean (true|false)):
    determines whether the saturation slider will be visible
11. valSliderVisible (boolean (true|false)):
    determines whether the value slider will be visible
12. alphaSliderVisible (boolean (true|false)):
    determines whether the alpha/transparency/opacity slider will be visible
13. colValTextVisible (boolean (true|false)):
    determines whether the text indicating the current RGBA and HSV color values will be visible
14. fillVisible (boolean (true|false)):
    determines whether the rectangle representing the fill colour should be visible
15. strokeVisible (boolean (true|false)):
    determines whether the rectangle representing the stroke colour should be visible
16. startHue (number, float):
    a value between 0 and 360 representing the start hue value in degrees of the hue slider
17. endHue (number, float):
    a value between 0 and 360 representing the end hue value in degrees of the hue slider, the endHue value should be higher than the startHue value
18. nrStopVals (number, integer):
    the number of stop values for the hue gradient definition, a value of 5 means 7 stop value: the start stop value, 5 in between stop values and the end stop value, the stop values are linearly interpolated between the startHue and endHue value
19. fillStartColor (string):
    a string containing the RGBA start values for the fill color, should be comma separated, the color values are integers between 0 and 255, the alpha value should be between 0 and 1; example: "0,255,0,1"
20. strokeStartColor (string):
    a string containing the RGBA start values for the stroke color, should be comma separated, the color values are integers between 0 and 255, the alpha value should be between 0 and 1; example: "0,255,0,1"
21. functionToCall (function, object or undefined):
    callBack function that will be fired after a color was changed: the return values are id of the colourPicker, and values, an object literal containing the values of the colourPicker. Values can be extracted like the following: values.fill.green or values.stroke.alpha or values.stroke.hue.

Note, if you want to change some appearance issues (e.g. positioning of elements), you can do so in the method .createColourpicker. Just be sure not to introduce any logical/functionality changes, only appearance changes.

Methods

• .getValues():
  returns the current values of the colourPicker. Values are returned in an object literal structure. Values can be extracted like the following: values.fill.green or values.stroke.alpha or values.stroke.hue.
• .setRGBAColour(colourType,red,green,blue,alpha,fireFunction):
  where colourType is of type string and can either be fill or stroke, red is of type number (integer, range 0-255), green is of type number (integer, range 0-255), blue is of type number (integer, range 0-255), alpha is of type number (float, range 0-1) and fireFunction is of type boolean (true|false) and indicates of the associated callBack function should be fired after changing the colour values.
• .hide():
  hides the colourPicker by setting the display attribute of the group containing the colourPicker to none
• .show():
  shows the colourPicker by setting the display attribute of the group containing the colourPicker to inherit
• .moveTo(x,y):
  moves the colourPicker to a different position. The x and y parameters are of type number (float) in viewBox coordinates.
• .resize(width,height):
  resizes the colourPicker. The width and height parameters are of type number (float) in viewBox coordinates. Please make sure that the width and height values aren't too small, or you'll get very strange effects.

Version history

• 1.0 (2006-02-26): initial version