Documentation

Requirements

To use the checkBox and radioButtonGroup object, your project needs to meet the following requirements:

• it is recommended that the svg root element has a viewBox attribute set (e.g. viewBox="0 0 1024 768")
• you need to link to the following scripts in your SVG header to use the checkBox and radioButtonGroup: helper_functions.js, timer.js and checkbox_and_radiobutton.js; 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 empty svg group element with a unique id in an appropriate position of your document tree to hold the graphics of the checkBox and radioButtonGroup object (e.g. <g "radioButtonsQuality" />), one can put multiple checkBoxes or radioButtons in the same group
• you need to initialize the checkBox and radioButtonGroup object as described below

Features

• this script comes with a simple checkBox object and a radioButtonGroup object that is dependant on the checkBox object
• you can use your own symbols for the checkBox and radioButtonGroup geometry
• you can provide checkBox or radioButton labels
• checkBoxes can be checked/unchecked and removed

Dependencies on external functions

1. checkbox_and_radiobutton.js:
   • all of the objects and functions in this file are necessary
2. timer.js:
   • all of the objects and functions in this file are necessary
3. helper_functions.js:
   • all the global variables at the top of the file

Constructor for checkbox object

The following constructor function creates a checkbox:

var myCheckbox = new checkBox(id,parentNode,x,y,checkboxId,checkcrossId,checkedStatus,labelText,textStyles,labelDistance,labelYOffset,radioButtonGroup,functionToCall);

Example:

//labeltext styles
var labeltextStyles = {"font-family":"Arial,Helvetica","fill":"dimgray","font-size":15};
//now create a new checkBox instance
var myCheckbox = new checkBox("landcover","checkboxes",110,100,"checkBoxRect","checkBoxCross",true,"Landcover",labeltextStyles,12,5.5,undefined,getLayerInfo);

The arguments are the following:

1. id (String):
   unique id that identifies the checkBox instance
2. parentNode (String or node reference):
   unique id or node reference that identifies the parentNode (usually a group node) where the checkBox geometry can be appended
3. x (number, in viewBox coordinates):
   the center x where the checkBox symbol should be placed
4. y (number, in viewBox coordinates):
   the center y where the checkBox symbol should be placed
5. checkboxId (String):
   a string representing a unique id to the checkBox symbol definition (usually in the <defs/> section)
6. checkcrossId (String):
   a string representing a unique id to the checkCross or checkMark symbol definition (usually in the <defs/> section); while the checkBox symbol is always visible, the checkCross or checkMark symbol is hidden or visible to indicate the checkBox status
7. checkedStatus (Boolean, true|false):
   a boolean value indicated whether the checkbox should be checked or not
8. labelText (String):
   a String containing the label text to be displayed right of the checkBox symbols. Can be an empty String "" or undefined if you don't want a label
9. textStyles (Array of literals with presentation attributes):
   an array literal containing the presentation attributes of the label text; could include CSS classes; should at least include a "font-size" attribute; example: var labeltextStyles = {"font-family":"Arial,Helvetica","fill":"dimgray","font-size":15};
10. labelDistance (number, in viewBox coordinates):
    the distance between the center of the checkBox symbol and the labelText
11. labelYOffset (number, in viewBox coordinates):
    the yOffset from the center of the checkBox symbol and the bottom of the labelText
12. radioButtonGroup (radioButtonGroup object):
    the radioButtonGroup object where the checkBox belongs to. If this is a standalone checkBox that does not belong to a radioButtonGroup just specify undefined
13. functionToCall (function, object or undefined):
    callBack function that will be fired after the checkBox was pressed or toggled. The return parameters are the following: id (string), checkedStatus (boolean) and labelText (String) In case of an object, the method .checkBoxChanged() of the given object is fired with the same parameters as listed above. The callBack function is executed with a slight delay (200ms) to allow the checkBox or radioButton to change its display state before executing the callback function. This value can be changed in the init() method of the checkBox object.

Methods of the checkBox object

• .check(FireFunction):
  checks/activates a checkBox, the parameter FireFunction is of type boolean and indicates whether the callBack function should be fired or not
• .uncheck(FireFunction):
  unchecks/deactivates a checkBox, the parameter FireFunction is of type boolean and indicates whether the callBack function should be fired or not
• .remove():
  removes all checkBox geometries
• .setLabelText(labelText):
  changes the labelText of a checkBox, parameter is of type String

Useful Properties of the checkBox object

• .checkedStatus:
  indicates whether a checkbox is checked or not. Data type is a boolean (true|false)
• .id:
  the id of the checkBox. Data type is a String.
• .labelText:
  the labelText of the checkBox. Data type is a String.

Tip: if you don't like the y-offset of the text label in relation to the checkBox symbol, open the file checkbox_and_radiobutton.js and adopt the line this.label.setAttributeNS(null,"y",(this.y + this.textStyles["font-size"] * 0.3));. Most likely it should be enough to adopt the factor of 0.3 to some other value.

Constructor for radioButtonGroup object

The following constructor function creates a radioButtonGroup:

var myRadioButtons = radioButtonGroup(id,functionToCall);
Subsequently one has to create two or more checkBox object instances and hand over the radioButtonGroup instance to the checkBox (parameter radioButtonGroup) to tell it that it belongs to the radioButtonGroup. Note that in most cases one should not specify a callBack function (functionToCall) on a checkBox belonging to a radioButtonGroup, since the radioButtonGroup has its own callBack function.

Example:

//labeltext styles
var labeltextStyles = {"font-family":"Arial,Helvetica","fill":"dimgray","font-size":15};
//now create a new radioButtonGroup instance
var radioGroupBandwidth = new radioButtonGroup("radioGroupBandwidth",setBandwidth);
//the following three checkboxes are added to the radio button group stored in the object instance 'radioGroup'
var cbHighQuality = new checkBox("highbandwidth","radioButtonsBandwidth",660,100,"radioBorder","radioPoint",true,"High Bandwidth",labeltextStyles,12,5.5,radioGroupBandwidth,undefined);
var cbLowQuality = new checkBox("mediumbandwidth","radioButtonsBandwidth",660,120,"radioBorder","radioPoint",false,"Medium Bandwidth",labeltextStyles,12,5.5,radioGroupBandwidth,undefined);	
var cbLowQuality = new checkBox("lowbandwidth","radioButtonsBandwidth",660,140,"radioBorder","radioPoint",false,"Low Bandwidth",labeltextStyles,12,5.5,radioGroupBandwidth,undefined);		

The arguments are the following:

1. id (String):
   unique id that identifies the checkBox instance
2. functionToCall (function, object or undefined):
   callBack function that will be fired after the checkBox was pressed or toggled. The return parameters are the following: id (String), selectedId (String) and labelText (String). In case of an object, the method .radioButtonChanged() of the given object is fired with the same parameters as listed above. The callBack function is executed with a slight delay (200ms) to allow the checkBox or radioButton to change its display state before executing the callback function. This value can be changed in the init() method of the checkBox object.

Methods of the radioButtonGroup object

• .selectById(cbId,fireFunction):
  selects the radioButton with the specified id. The first parameter is the checkBox/radioButton id (String), the second parameter FireFunction is of type boolean and indicates whether the callBack function of the radioButtonGroup should be fired or not
• .selectByLabelname(labelName,fireFunction):
  selects the radioButton with the specified labelText. The first parameter is the checkBox/radioButton labelText (String), the second parameter FireFunction is of type boolean and indicates whether the callBack function of the radioButtonGroup should be fired or not
• .addCheckBox(checkBoxObj):
  adds an additional checkBox object to the radioButtonGroup. Normally, this method isn't necessary for the user, because one usually allocates a checkBox to the radioButtonGroup upon checkBox creation. However, this method allows to add a checkBox to a radioButtonGroup after it was created. The parameter is of type checkBox, a checkBox instance.
• .moveTo(x,y):
  allows to move an existing checkbox or radio button. As with creation, the reference point is the center of the symbol instance of the checkbox or radio button. Parameters (x and y) are numbers in viewBox coordinates.
• .remove():
  Removes all checkbox or radiobutton geometries. This method takes no arguments. For some reasons Internet Explorer and ASV seem to crash when reloading a page after this method was called. If someone finds out the cause, please let me know and I'll fix it. Thanks.

Useful Properties of the radioButtonGroup object

• .selectedId:
  the id of the currently checked (active) checkBox in a radioButtonGroup. Data type is a String.
• .selectedIndex:
  the index of the currently checked (active) checkBox. The order is the order of the checkBoxes added to the radioButtonGroup. Data type is a number (zero based).
• .id:
  the id of the checkBox. Data type is a String.
• .checkBoxes:
  an array with references to the checkBoxes belonging to this radioButtonGroup. Datatype is an Array of checkBoxes.

Version history

• 1.0 (2006-03-13): initial version
• 1.1 (2006-03-13): text labels are now clickable (thanks to Guy Morton); added method .moveTo() to move checkbox to a different location; introduced new constructor parameter labelYOffset to allow more flexible placement of the text label
• 1.1.1 (2007-02-06): added cursor pointer to the text label and use element representing the checkBox
• 1.1.2 (2007-04-19): bug fix: this.selectedIndex was not correctly initialized in method addCheckBox of the radioButtonGroup object
• 1.1.3 (2007-08-09): bug fix: the method .remove() was slightly modified (using removeEventListener) for avoiding a crash related to the method after reloading the SVG file

Credits

• Guy Morton for providing a fix to allow users toggle a checkBox or radioButton by clicking on text labels
• Bruce Rindahl for providing the bugfix described in 1.1.2
• Simon Shutter for providing a fix for the ASV in IE crash when reloading the SVG file after calling the .remove() method on a checkbox