Documentation

Requirements

To use the button 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 button or switchbutton: helper_functions.js, timer.js and button.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 button object (e.g. <g "textbutton1" />)
• you need to initialize the button object as described below in the constructor section

Features

• the button comes in two incarnations: a regular button and a switchbutton. The latter is a subclass of the button object and allows to switch/indicate state (pressed|unpressed)
• can be either a textbutton or imagebutton
• buttons states can be changed from other functions
• buttons can be hidden or shown
• buttons can be activated and deactivated (greyed out)
• for text buttons one can get or reset the button text value

Dependencies on external functions

1. button.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

The following constructor function creates the button or switchbutton:

var myButton = new button(id,parentNode,functionToCall,buttonType,buttonText,buttonSymbolId,x,y,width,height,textStyles,buttonStyles,shadeLightStyles,shadeDarkStyles,shadowOffset); or
var myButton = new switchbutton(id,parentNode,functionToCall,buttonType,buttonText,buttonSymbolId,x,y,width,height,textStyles,buttonStyles,shadeLightStyles,shadeDarkStyles,shadowOffset);

Example:
//first a few styles
var buttonTextStyles = {"font-family":"Arial,Helvetica","fill":"navy","font-size":12};
var buttonStyles = {"fill":"lightsteelblue"};
var shadeLightStyles = {"fill":"white"};
var shadeDarkStyles = {"fill":"navy"};
//now create a new button instance
var textbutton1 = new button("textbutton1","textbutton1",buttonPressed,"rect","Click me",undefined,100,100,100,30,buttonTextStyles,buttonStyles,shadeLightStyles,shadeDarkStyles,1);
or
var buttonMoveVertex = new switchbutton("buttonMoveVertex","buttonMoveVertex",imageButtonPressed,"rect",undefined,"moveVertex",300,150,20,20,buttonTextStyles,buttonStyles,shadeLightStyles,shadeDarkStyles,1);

The arguments are the following:

1. id (String):
   id of the button
2. parentNode (String or node reference):
   group id or node reference to the parent group that will contain the button geometry
3. functionToCall (function, object or undefined):
   callBack function that will be fired after button was pressed or toggled. The return parameters vary according to the button type:
   • for a text button: groupId (string), evt (object), buttonText (string)
   • for an image button: groupId (string), evt (object)
   • for a text switchbutton: groupId (string), evt (object), buttonState (boolean), buttonText (string)
   • for an image switch button: groupId (string), evt (object), buttonState (boolean)
   In case of an object, the method .buttonPressed() 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 button to change its display state before executing the callback function. This value can be changed in the init() method of the button object.
4. buttonType (string):
   valid values are "rect" or "ellipse"
5. buttonText (string or undefined):
   the string of the buttonText to be displayed or the value undefined in case of an image button, if you want multiline buttons, use \n as a newline separator.
6. buttonSymbolId (string):
   the id (string) of the button symbol or undefined for text buttons
7. x (number):
   the left side of the button
8. y (number):
   the top side of the button
9. width (number):
   the button width/li>
10. height (number):
    the button height
11. textStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the button text; could include CSS classes; should at least include a "font-size" attribute; example: var buttonTextStyles = {"font-family":"Arial,Helvetica","fill":"navy","font-size":12};
12. buttonStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the button rectangle or ellipse; could include CSS classes; should at least include a "fill" attribute; example: var buttonStyles = {"fill":"lightsteelblue"};, Note if you want rounded rectangles you can add the attributes "rx" and "rx" here.
13. shadeLightStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the button lighter shadow, simulating the button 3d effect behind the button rectangle or ellipse; could include CSS classes; should at least include a "fill" attribute; example: var shadeLightStyles = {"fill":"white"};, Note if you want rounded rectangles you can add the attributes "rx" and "rx" here.
14. shadeDarkStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the button darker shadow, simulating the button 3d effect behind the button rectangle or ellipse; could include CSS classes; should at least include a "fill" attribute; example: var shadeDarkStyles = {"fill":"navy"};, Note if you want rounded rectangles you can add the attributes "rx" and "rx" here.
15. shadowOffset (number):
    a number describing the shadow offset behind the button, simulating the button 3d effect

Note, if you want to change the y-offset value of the text in a textbutton you can do so in the method .createButton() - watch out for comment //create text element. Likewise you can change the dy offset for multiline textbuttons in the for loop creating the tspan elements.

Methods

• .deactivate():
  deactivates (greys out) a button by placing an insensitive transparent rect or ellipse above the button
• .activate():
  activates a button if it was deactivated
• .hideButton():
  hides a button using the display="none" attribute
• .showButton():
  shows a button using the display="inherit" attribute
• .removeButton():
  removes button including all geometry. The existing button reference isn't usable anymore, after this method.
• .getTextValue():
  get the button text value, works only for text buttons
• .setTextValue(string):
  sets the button text value, works only for text buttons, parameter is a string
• .getSwitchValue():
  works only for switch buttons, returns a true or false parameter to see if button is pressed or not
• .setSwitchValue(onOrOff,fireFunction):
  works only for switch buttons, parameters are two boolean values (true|false) indicating if the button should be pressed or released. The second parameter controls whether the callBack function should be activated or not
• .moveTo(x,y):
  moves the button to a different position. The given parameters are of type number (in viewBox coordinates) and define the new x and y position of the upper left corner of the button
• .resize(width,height):
  moves the button to a different position. The given parameters are of type number (in viewBox coordinates) and define the new width and height of the button

Useful Properties

• .activated:
  indicates whether a button is active or not (greyed out). Data type is a boolean (true|false)

Version history

• 1.0 (2006-02-08): initial version
• 1.0.1 (2006-03-13): changed parameters of constructor (styling system): now an array of literals containing presentation attributes. This allows for more flexibility in Styling. Added check for number of arguments.
• 1.0.2 (2006-07-07): added the option to create multiline textbuttons, changed the behaviour of the y placement of the text in the button
• 1.1 (2006-07-12): added .resize(width,height) and .moveTo(x,y) methods, added new constructor parameter parentNode, fixed a bug from version 1.0.2 in the method .setTextValue()
• 1.1.1 (2006-10-23): fixed an error with vertical positioning of button texts (thanks Bruce and Virgis); changed DOM hierarchy slightly. Every button now has its own group "this.parentGroup". This is necessary to hide and show a button. This group should not be shared by other SVG elements, unless on purpose; adopted .resize() and .moveTo() methods to make use of the corrected function this.createButtonTexts();
• 1.1.2 (2006-10-26): corrected a bug where type conversion in buttonText was missing when buttonText was of type number
• 1.1.3 (2006-10-30): corrected a bug where the .deactivate() method did not work properly when called after the method .setTextValue(); added support for rx and ry attribute in this.deActivateRect

Credits

• Bruce Rindahl and Virgis Globis for reporting errors on the vertical positioning of text within text buttons, and for sending bug fixes
• Olaf Schnabel for suggesting a bugfix where type conversion was missing when button text was of type number