
        JSGraph JavaScript Library

        Copyright 2007, James Melanson
                        james_melanson@yahoo.ca
        
                        jsgraph.js  V1.03       January 3rd, 2007

        All Rights Reserved.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

        What this means is:

          1.) If you are creating free software that is distributed for free,
              you can use this library for free.

          2.) If you are going to use this library in an application you will
              be selling OR are creating the application for a Commercial
              application OR are creating the application for which you are
              receiving compensation (money, product or employment), then 
              you must purchase a Commercial License for this library for
              US$25. Contact me at the email above for more details.

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  CONTENTS OF ReadMe FILE:
  
  1.)  Overview

  2.)  Implementation
       i    What files to use.
       ii   Linking to the files.
       iii  Instantiating the JSGraph object
             a.) Loading the JSGraph Object.
       iv   Instantiating multiple JSGraph objects
       v    Specifying the size of the Y-Axis and X-Axis
       vi   Adding a background colour or image
       vii  Adding Tick Marks
       viii Adding Trellis Lines
       ix   Adding Axis Text
             a.) Nudging Y-Axis Text

  3.)  Bar Graph
       i    Specifying orientation of Bar graph
       ii   Adding Bars
             a.) Adding Shadows
             b.) Over value plus "+" sign

       iii  After load methods
             a.) Modifying Bar Length
             b.) Hidding/Unhiding a bar

  4.)  Line Plot Graph
       i    Adding plot points

  5.)  Pie Chart
       i    Adding pie slice


  6.)  Full Property & Method List
  7.)  Adding a visual legend
  8.)  Samples of instantion, property assignment and working sliders
  9.)  Debugging
  10.) Support


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  OVERVIEW

  JSGraph is a JavaScript library to simplify the implementation of visual "bar graphs"
  on a web page.

  Creating graphs from scratch are a lengthy and time consuming process requiring
  hand coding HTML skill OR graphics skills. This library was created so that you
  can put a bar graph on your web page in minutes AND modify it in seconds!

  There are example files in this zip file that will show you both horizontal and vertical
  bar graphs as well as an example of a dynamic implementation.

  This Library has been written to work in IE, Opera, Firefox and Netscape. I have
  no access to an Apple to test it so feedback would be appreciated.

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - WHAT FILES TO USE

  The file that you need to implement this with your web page is:

  jsgraph.js

  If you are developing locally, on your desktop, simply save the file to the same
  project folder as the page you are implementing the graph on.

  For live implementation, FTP the file in ASCII mode (not Binary) to the web server.

  The browsers that this library supports are:

  Opera 7+
  IE 5.5+ (Possibly some builds of IE5.0)
  Firefox 1.5+
  Netscape 7.0

  The library was developed in Opera and then ported to work in the other browsers.

  Known Issues:

    --Over value "plus" feature obscures the NW and NE shadow in horizontal mode.


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - LINKING TO THE FILES

  The JSGraph library file has been written to support the four browsers above. There
  are no browser specific files.

  The code below shows you how to link to the file. Remember that this code MUST
  come before any other references to the JSGraph object you will be creating.

  Inside the <head></head> tags of the web page you are implementing the graph on,
  copy and past the following code inside the snippet blocks:

  [-- Start Snippet --]

<script language="JavaScript" src="jsgraph.js"></script>

  [--  End Snippet --]


  If you are calling the library file from a different folder, make sure you change the "src"
  attribute to a relative path or full URL.

  **It would be preferable that you paste the above code BEFORE ANY OTHER IN-LINE JAVASCRIPT.

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - INSTANTIATING THE JSGRAPH OBJECT

  After implementing the above, we now move on to instantiating (creating) the graph object.

  The following line of code is what we use to create the graph object:

                    var objHandle = new JSGraph();

  The above code should appear inside your <head></head> tags within JavaScript tags. In any case,
  this code MUST appear on the physical page BEFORE you attempt to load the slider and before you
  assign any properties or call any methods.

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - INSTANTIATING THE JSGRAPH OBJECT - LOADING THE JSGRAPH OBJECT

  This is how you place the code on your page, after setting the properties, that will actually
  cause the graph to appear.

  This call to load the graph MUST appear between the <body></body> tags and it MUST be contained
  within <DIV></DIV> tags.

  [-- Start Snippet --]

<div id="GraphHolder" style="position:absolute;top:100px;left:100px;">
<script language="JavaScript">
<!--
objHandle.makeGraph();
//-->
</script>
</div>

  [--  End  Snippet --]

  Note that this division has CSS positioning attributes. You can change the positioning to
  relative and drop the top and left values and it will flow with the page content. However,
  I strongly recommend you play around with the "top" and "left" values and find the correct
  placement for your slider.

  After adding the code we have talked about in the above three sections and saving your HTML
  file, all you have to do is call it in your browser to see the graph showing ONLY it's
  X-Axis and Y-Axis with their default settings. This will help you position the DIV element
  that is holding the call to load the graph object.

  VERY IMPORTANT: IT IS RECOMMENDED THAT YOU PLACE THIS METHOD AT THE BOTTOM OF YOUR HTML PAGE
                  SO THAT IT COMES AFTER ANY HTML ELEMENTS THAT IT MAY NEED TO REFERENCE. IT
                  MUST COME BEFORE THE CLOSING BODY TAG.

  At this time, have a look at "JSGraph_screenshot.png" to see important points about the
  layout of the graph that you will need to understand for the following sections.

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - INSTANTIATING MULTIPLE JSGRAPH OBJECTS

  This JavaScript library takes and OOP-ish approach to the graph creation and management.
  The benefit of this to you is that you can have multiple graphs on one page and have
  them operate independantly of one another.

  For each of the graphs, you can specify a completley separate set of properties and access
  their methods individually.

  To have more than one graph on the page, simply instantiate each new graph with a
  different handle name. For example, if I was creating a financial page where user could
  view graphs on "Cost To Income Ratio", "Yield vs. Earnings" and "Yearly Income Growth"
  then I would instantiate the objects inside JavaScript tags inside the <head></head>
  tags of the page like this:

<script language="JavaScript1.2">
<!--
var ctir_graph = new JSGraph();
var yve_graph = new JSGraph();
var yig_graph = new JSGraph();
//-->
</script>


  I would now set properties and access methods individusally for each graph simply by
  refering to the handle for the slider in question (ctir_graph, yve_graph, yig_graph are the
  object handles).

  Having instantiated the objects, I would then load the graphs down in the page like this:


<div id="holder1" style="position:absolute;top:100px;left:100px;">
<script language="JavaScript1.2">
<!--
ctir_graph.makeGraph();
//-->
</script>
</div>

<div id="holder2" style="position:absolute;top:100px;left:140px;">
<script language="JavaScript1.2">
<!--
yve_graph.makeGraph();
//-->
</script>
</div>

<div id="holder3" style="position:absolute;top:100px;left:180px;">
<script language="JavaScript1.2">
<!--
yig_graph.makeGraph();
//-->
</script>
</div>

  This would layout three graphs, appearing beside each other.


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - SPECIFYING THE SIZE OF THE Y-AXIS AND X-AXIS

  To have something other than the default axis bars (default settings are Black, 4 pixels
  wide and 200 pixels long), then you need to call an object method for each axis.

  Each of these methods accepts three arguments as described below:

  Y-AXIS (up and down bar on the left side of the graph):

        objHandle.yAxis([axis bar width],[axis length],[axis bar colour]);

            Axis Bar Width:  Specify the width of the bar as an integer, expressed as a pixel
                             size. Do NOT include the "px" at the end.

            Axis Length:     This is the height of the Y-Axis bar, expressed as a pixel size.
                             Do NOT include the "px" at the end.

            Axis Bar Colour: This accepts only a HEX value (including the # symbol)

            Sample method call:   objHandle.yAxis(6, 300, '#FF0000');

  X-AXIS (left to right at the bottom of the graph):

        objHandle.xAxis([axis bar width],[axis length],[axis bar colour]);

            **Arugments are identical for the X-AXIS


  ****** IMPORTANT - GRAPH LEFT SIDE PADDING ******

  By default, the graph has a padding of 30px on the left side of the Y-Axis bar.
  This is to give room for the tick marks and any Y-Axis text. You can adjust
  this padding dynamically by specifying a new pixel size for the padding by
  adjusting this property:

  objHandle.graphLeftPaddingOverride = 20; //Do NOT include the "px" at the end.

  IMPLEMENTATION - ADDING A BACKGROUND COLOUR OR IMAGE

  You can easily add a background colour for the graph OR specify a background image.

  To specify a background colour, call the following method with the HEX value of the
  colour as the only argument:

        objHandle.addBackground('#FFF8DC');

  If you would like to specify a background image, then simply add an image URL as
  the argument:

        objHandle.addBackground('http://www.foo.com/images/graphbg.gif');

  By default, a background image will tile to fill the area of the background. If you
  do not wish it to repeat, then add a second argument to the method of 'no-repeat'
  like this:

        objHandle.addBackground('http://www.foo.com/images/graphbg.gif', 'no-repeat');


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - ADDING TICK MARKS

  If you look at the sample image, you will see that the Tick Marks are the small
  lines that run along the outside of the axis bars to aid in a visual representation
  of the graph bars value.

  You can add Tick Marks to one axis, both axis or neither axis. By default, Tick Marks
  do not show up.

  To add Tick Marks you can call one or both of the following methods with the specified
  arguments:

    Y-AXIS TICK MARKS:

        objHandle.yAddTicks([spacing],[colour],[size]);

            Spacing: The spacing is the pixel count between each Tick along the axis.
                     This is expressed as an integer value and does NOT include the "px".

            Colour:  This is the colour of the Tick Marks. It is set as a HEX value
                     including the "#" symbol. Usually set to the same colour as the
                     axis bars.

            Size:    This is the width (fatness) of the tick marks themselves. This is
                     expressed as an integer value and does NOT include the "px".

            Sample Call:   objHandle.yAddTicks(10, '#FF0000', 3);


    X-AXIS TICK MARKS:

        objHandle.xAddTicks([spacing],[colour],[size]);

            **Arguments are identical for the X-Axis Tick Marks

  The default values for Tick Marks are a spacing of 5px, Black and 2px size.

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - ADDING TRELLIS LINES

  Looking at the sample screenshot, you will see that the Trellis lines are the thin
  lines that extend across the canvass. In a Vertical Bar graph, the Trellis lines
  appear horizontally. In a Horizontal Bar graph, Trellis lines appear vertically.

  This library has the ability to either auto space lines (with no labels) or allow
  you to specify the position of the trellis lines (labels optional). The labels
  will appear beside or below the trellis line, outside the main axis line the trellis
  touches.

  To add Trellis lines, auto spacing, no labels, call the following method ONCE:

        objHandle.addTrellis([Spacing],[Size],[Colour]);

            Spacing: This is the distance, in pixels, that appear between each Trellis
                     line. The object will automatically assign the positions. This
                     value is expressed as an integer. Do NOT add the "px" value.

            Size:    This is the width of each line. Typically set to 1px width. This
                     value is expressed as an integer. Do NOT add the "px" value.

            Colour:  This is the colour of the Trellis line. It is set as a HEX value
                     including the "#" symbol. Usually set to a lighter colour in the
                     same hue as the axis bars.

            **Sample Call:   objHandle.addTrellis(20, 1, '#A9A9A9');


  To add Trellis lines, defined spacing, optional labels, call the following method
  FOR EACH TRELLIS LINE:

        objHandle.addTrellis([Spacing],[Size],[Colour],[LabelText],[LabelFont],[LabelFontSize]);

            Spacing & Size & Colour: These arguments are the same as above

            Label Text:  This is the text that will appear in the label beside or beneath
                         the Trellis line.

            Font Family: Standard HTML style font family designation.

            Font Size:   Expressed as an integer representing a pixel size for the text.
                         Do NOT include the "px" value. This value is also used in
                         calculating the label position.

            **Sample Calls:
  
                objHandle.addTrellis(40, 1, '#FF0000', 'foo1','tahoma,sans-serif',9)
                objHandle.addTrellis(80, 1, '#FF0000', 'foo2','tahoma,sans-serif',9)
                objHandle.addTrellis(120, 1, '#FF0000', 'foo3','tahoma,sans-serif',9)
                objHandle.addTrellis(160, 1, '#FF0000', 'foo4','tahoma,sans-serif',9)
                objHandle.addTrellis(200, 1, '#FF0000', 'foo5','tahoma,sans-serif',9)

  ***WARNING***
    If you choose to add Trellis with defined space (multiple calls), then you should
    not use Tick Marks and you should not use Axis Labels. They will overwrite each other.

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - ADDING AXIS TEXT

  Most graphs have a label along each axis describing what that value range represents.
  You can easily add labels to appear alongside each axis of the graph by calling the
  following methods:

  Y-AXIS LABEL:

        objHandle.yAddText([Text Value],[Font Family],[Font Colour],[Font Size]);

            Text Value:  This is the text that will appear on the axis label.

            Font Family: Standard HTML style font family designation.

            Font Colour: The colour is set as a HEX value including the "#" symbol.

            Font Size:   Expressed as an integer representing a pixel size for the text.
                         Do NOT include the "px" value.

            **Sample Call:    objHandle.yAddText('Something Here','verdana,helvetical,sans-serif','#0000FF',10);

  X-AXIS LABEL:

        objHandle.xAddText([Text Value],[Font Family],[Font Colour],[Font Size]);

            **The arguments for this method are identical.

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  IMPLEMENTATION - ADDING AXIS TEXT - NUDGING Y-AXIS TEXT

    By default the X-Axis label will center itself along the axis. This wasn't possible to
    do for the Y-Axis in a cross browser dependable format. Therefore I implemented
    the "nudge" method for the Y-Axis Text. Passing an integer value to this method will
    force the Y-Axis text down that many pixels from the top. You may have to play with it
    a bit to get it looking right. You call the method with ONE argument like this:

        objHandle.yTextNudgeDown(10);


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  BAR GRAPH - SPECIFYING ORIENTATION OF GRAPH

  The default setting for the JSGraph object is a Vertical Bar Graph. If you do not
  specify an orientation, then you will get a this most common type of bar graph.

  However, if you wish to have a Horizontal Bar Graph, then you can do this by calling
  the following JSGraph object method:
  
        objHandle.horizontalBarGraph();

  No arguments are required.

  If you want to create a Line Plot Graph, then you do not need to expressley state this.
  Your first call to the method that adds plot points will automatically convert the
  graph to a Line Plot Graph.


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  BAR GRAPH - ADDING BARS

  A graph typically has many bars on it representing your data. Bars are added to the
  graph object display by successive calls to the addBar() method with the appropriate
  arguments.

  To add a bar to the graph, call the following method and then repeat for each successive
  bar:

        objHandle.addBar([UniqueID],[Bar Length],[Bar Width],[Bar Colour]);

            Unique ID:  You must specify a unique identifier for each bar. This can be
                        as simple as "a" or more complex like "NovemberSales2006". In
                        any case, you can NOT have any blank spaces in the unique
                        identifier.

            Bar Length: This is the length of the bar from it's base point extending
                        in the orientation from the base axis. This is a value expressed
                        as an integer in pixels. Do NOT include the "px" value.

                        NOTE: The object will not allow any bar to exceed the size of the
                        axis it is running parallel to.

                        NOTE: If you pass a floating point number (i.e.: 23.25) the value
                        will be rounded up to the next whole number. So passing a value of
                        23.25 would results in the bars value being 24.

            Bar Width:  This is the width of the bar along the narrow axis. This is a
                        value expressed as an integer n pixels. Do NOT include the "px" value.
                        Typically, all bars are the same width.

            Bar Colour: The colour is set as a HEX value including the "#" symbol.

            **NOTE: The object will automatically space the bars equally along the base axis.

  Here is a sample of what the successive calls to the method would look like to add four bars
  to a graph object:

        objHandle.addBar('bar1',30,12,'#FF0000');
        objHandle.addBar('bar2',300,12,'#00FF00');
        objHandle.addBar('bar3',178,12,'#0000FF');
        objHandle.addBar('bar4',200,12,'#000000');

  Make sure you review: IMPLEMENTATION - INSTANTIATING THE JSGRAPH OBJECT - LOADING THE JSGRAPH OBJECT

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  BAR GRAPH - ADDING BARS - ADDING SHADOWS

  You can add shadows by simply specifying the direction of the light source that casts
  the shadows from the bars. The possible values are NW, NE, SW, SE (just like on a
  compass). For example, a light source of SW will cause shadows to the right of the
  bar and above the top of the bar. A light source of NE will cause shadows on the
  left side of the bar and the end of the shadow will be less than the end of the bar.

  Shadows can be used on either a Vertical Bar Graph or a Horizontal Bar Graph.

  To specify a light source, call this method with ONE of the valid source directions.
  Make sure the direction is in UPPER CASE letters:

        objHandle.lightSource('SW');

  If you do not want shadows, simply leave this method out of your description to the
  object.


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  BAR GRAPH - ADDING BARS - OVER VALUE PLUS "+" SIGN

  In no case will the object allow a graph bar to exceed the size of the parallel axis.

  However, you may want a visual cue that the value is greater than the plotted graph.

  Turning on the over value plus indicator will cause a small black plus "+" sign to
  appear at the end of the bar if the bars value is actually greater than can be
  represented on the graph. To turn on this automatic feature, simply call the
  following method with no arguments:

        objHandle.usePlus();

  **NOTE: Keep in mind that the plus sign is BLACK when assigning the colour of an
          over value bar.


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  BAR GRAPH - AFTER LOAD METHODS - MODIFYING BAR LENGTH

  After the graph has been loaded and is displayed on the web page, you can have
  the graph dynamically respond to user input. This is achieved by calling the
  following method with two arguments:


        objHandle.modifyBar([UniqueID],[New Value]);

            Unique ID: When you added the bar, you assigned it a Unique ID. You must
                       now pass that unique ID as the first argument. It must be
                       IDENTICAL and is CaSe SeNsItIvE.

            New Value: This is an integer representing the new value of the bar
                       which determines the length of the bar.

                       If you wish to pass this value as a percentage, you must
                       pre-process the percentage so that you are only passing
                       an integer value.

            **Sample Call:    objHandle.modifyBar('bar2', 173);

  NOTE: You can only call this AFTER you have called the objHandle.makeGraph method
        that loads the graph object to the page. If you attempt to call it before
        this, an error will result that will crash JavaScript on the page.

  NOTE: If you pass a floating point number (i.e.: 23.25) the value will be rounded
        up to the next whole number. So passing a value of 23.25 would results in
        the bars value being 24.


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  BAR GRAPH - AFTER LOAD METHODS - HIDDING/UNHIDING A BAR

  Another option you can access dynamically is to hide/unhide bars on the graph.
  This can help you identify certain elements of interest in response to user
  actions on the page. Please remember that when you hide a bar, you do NOT
  re-distribute the remaining bars on the page.

  To hide a bar, call the following method with one argument only:

        objHandle.hideBar([UniqueID]);

            Unique ID: When you added the bar, you assigned it a Unique ID. You must
                       now pass that unique ID as the first argument. It must be
                       IDENTICAL and is CaSe SeNsItIvE.

  To unhide a bar, call the following method with one argument only:

        objHandle.unhideBar([UniqueID]);

            **The argument is identical.

  **NOTE: View the following file in your browser: example_dynamic_graph.html
  View how the hide/un-hide works then view the source code of the file to
  see how I processed this dynamic modification.

<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  LINE PLOT GRAPH - ADDING PLOT POINTS

  Aside from Bar Graphs, you can also use this library to generate a line graph. That is,
  lines connected at plot points.

  There are some considerations using a line plot graph:

    -You should not use Tick Marks on the X-Axis if you are creating a Line Plot graph.

    -You can not use the X-Axis Label if you are using labels with the plot points.

    -Line Plot graph is always oriented vertically, you can not orient it horizontally.


  Instead of calling the addBar() method, to add plot points you use the addLinePlot()
  method:

        objHandle.addLinePlot();

  The Line Plot graph MUST have a starting point. Therefore, your VERY FIRST CALL to this
  method should only be a value along the Y-Axis of the graph for the line plot to start
  at. Typically, this will be zero:

        objHandle.addLinePlot(0);

  You can now add the rest of your plot points and lines with successive calls to this
  method. The minimum arguments for this method is the value to plot. If you specify no
  other arguments the default pen size of 1 and pen colour of Black will be used.

        objHandle.addLinePlot(somevalue);

  Here is the full definition of the arguments to addLinePlot() for successive calls:

        objHandle.addLinePlot([Value],[Pen Size],[Pen Colour], [Use Marker], [Label Text], [Label Font], [Label Colour], [Label Size]);

            Value:        This is an integer representing the value to be plotted, must be
                          less than the Y-Axis Length.

            Pen Size:     This is the size of the line that will be drawn. Typically it
                          will be a value of "1". The pen size is also used to determine
                          the size of the plot point marker, if used.

            Pen Colour:   This is the colour of both the line and the plot point marker.
                          This can be expressed as a HEX value or as a word.

            Use Marker:   A marker is a square that appears, centered on the plot point.
                          The plot point marker inherits it's colour from the Pen Colour
                          and it's width/height are three times the pen size. To use the
                          plot point marker, set this argument to "1". If you do not want
                          to use it, set the value to zero "0".

            Label Text:   You can add a text label that will appear under the X-Axis bar
                          directly beneath the plot point.

            Label Font:   Standard HTML style font family designation.

            Label Colour: This can be expressed as a HEX value or as a word.

            Label Size:   Expressed as an integer representing a pixel size for the text.
                          Do NOT include the "px" value. This value is also used in
                          calculating the label position.

  Here is an example of the calls to plot a whole graph:

        objHandle.addLinePlot(0); //Mandatory starting point on the Y-Axis
        objHandle.addLinePlot(30,1,'maroon',1,'Foo 1','tahoma,sans-serif','maroon',9);
        objHandle.addLinePlot(50,1,'maroon',1,'Foo 2','tahoma,sans-serif','maroon',9);
        objHandle.addLinePlot(178,1,'maroon',1,'Foo 3','tahoma,sans-serif','maroon',9);
        objHandle.addLinePlot(200,1,'maroon',1,'Foo 4','tahoma,sans-serif','maroon',9);
        objHandle.addLinePlot(36,1,'maroon',1,'Foo 5','tahoma,sans-serif','black',9);
        objHandle.addLinePlot(0,1,'maroon',1,'Foo 6','tahoma,sans-serif','black',9);
        objHandle.addLinePlot(127,1,'maroon',1,'Foo 7','tahoma,sans-serif','black',9);
        objHandle.addLinePlot(12,1,'maroon',1,'Foo 8','tahoma,sans-serif','black',9);
        objHandle.addLinePlot(191,1,'maroon',1,'Foo 9','tahoma,sans-serif','black',9);

  An alternate example, with variation on arguments:

        objHandle.addLinePlot(0); //Mandatory starting point on the Y-Axis
        objHandle.addLinePlot(30,1,'maroon',1);          //No label
        objHandle.addLinePlot(50,1,'maroon',1);          //No label
        objHandle.addLinePlot(178,1,'maroon');           //No plot point marker, no label.
        objHandle.addLinePlot(200,1,'maroon',0,'Foo 4'); //Default font, font colour, font size; No plot point marker
        objHandle.addLinePlot(36,1,'maroon',1,'Foo 5');  //Default font, font colour, font size
        objHandle.addLinePlot(0,1,'maroon',1,'Foo 6','tahoma,sans-serif','black',9);
        objHandle.addLinePlot(127,1,'maroon',1,'Foo 7','tahoma,sans-serif','blue',9);
        objHandle.addLinePlot(12,1,'maroon',0,'Foo 8','tahoma,sans-serif','#FF0000',9);  //No plot point marker
        objHandle.addLinePlot(191,1,'maroon',0,'Foo 9','tahoma,sans-serif','#00FF00',9); //No plot point marker


  Adding multiple lines to the graph is easy. All of the above example plots one line moving
  left to right across the graph. If you want to add a second line to your graph, then call
  the newLinePlot() method with NO arguments:

        objHandle.newLinePlot();

  After calling this method, you must begin by again adding your base plot point:

        objHandle.addLinePlot(0);

  You can now add all or your plot points for this new line with successive calls to the
  addLinePlot() method. Please be aware that labels can only be added for the FIRST line
  added to the graph. You can not add labels for following new lines. If you do include
  label information, it will be ignored. Here is a short example showing a small graph
  with four plot points and three different lines:

        objHandle.addLinePlot(0); //Mandatory starting point on the Y-Axis
        objHandle.addLinePlot(30,1,'maroon',1,'Foo 1','tahoma,sans-serif','maroon',9);
        objHandle.addLinePlot(50,1,'maroon',1,'Foo 2','tahoma,sans-serif','maroon',9);
        objHandle.addLinePlot(178,1,'maroon',1,'Foo 3','tahoma,sans-serif','maroon',9);
        objHandle.addLinePlot(200,1,'maroon',1,'Foo 4','tahoma,sans-serif','maroon',9);

        objHandle.newLinePlot();
        objHandle.addLinePlot(50); //Mandatory starting point on the Y-Axis
        objHandle.addLinePlot(30,1,'maroon',1);
        objHandle.addLinePlot(50,1,'maroon',1);
        objHandle.addLinePlot(178,1,'maroon',1);
        objHandle.addLinePlot(200,1,'maroon',1);

        objHandle.newLinePlot();
        objHandle.addLinePlot(70); //Mandatory starting point on the Y-Axis
        objHandle.addLinePlot(30,1,'maroon',1);
        objHandle.addLinePlot(50,1,'maroon',1);
        objHandle.addLinePlot(178,1,'maroon',1);
        objHandle.addLinePlot(200,1,'maroon',1);


  Make sure you review: IMPLEMENTATION - INSTANTIATING THE JSGRAPH OBJECT - LOADING THE JSGRAPH OBJECT

  **NOTE: WHILE BAR GRAPHS PERMIT A DYNAMIC RESPONSE TO USER ACTIONS, THE LINE PLOT GRAPH
          OFFERS NO DYNAMIC INTERACTIVITY OPTIONS.

  **NOTE: YOU DO NOT NEED TO SPECIFY A GRAPH TYPE OR ORIENTATION FOR A LINE PLOT GRAPH
          LIKE YOU DO WITH A BAR GRAPH. SIMPLY CALLING THE addLinePlot() METHOD WILL
          MAKE THAT SPECIFICATION FOR YOU.


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  PIE CHART

  JSgraph supports pie charts. However, they are very simple pie charts. By describing
  portions of the pie chart, pie slices, the library will create an outline circle and
  draw the pie slice lines at the appropriate points. If you specify labels, it will
  draw the labels in the correct places. While you can specify a colour for the portion
  of the circles circumference that each individual slice owns, you can not fill in
  the pie slices with colour. It's simply too memory intensive for most browsers. During
  development it kept freezing up and crashing my browsers so I abandoned the idea
  of trying to fill the pie slices.

  Still, the pie charts generated can look quite professional and give an accurate
  visual representation of the portions you are representing. It's best for you to
  try out your own pie chart and see how well it fits with your design.

  To create a pie chart, you must call the following method:

        objHandle.pieChart([Diameter]);

            Diameter:  Express the diameter of the circle in pixels.

            **Sample call:    objHandle.pieChart(200);

  
  Make sure you review: IMPLEMENTATION - INSTANTIATING THE JSGRAPH OBJECT - LOADING THE JSGRAPH OBJECT


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  PIE CHART - ADDING PIE SLICE

  A slice of the pie chart is created by describing a PERCENTAGE of the CIRCUMFERENCE of the
  circle making up the pie chart. You can specify the colour of the circumference for that
  particular slice as well as automated label information. The labels are good if you have a
  pie chart with only a few slices. If you have a lot of slices you may want to skip the
  labels and create your own legend for the slice colours.

  Note that the slices always start moving clockwise from the 12 o'clock position.

  To create a slice call the following method. To add more slices, make successive calls to
  the following method:

        objHandle.addPieSlice([Percentage of Circumference],[Slice Colour],[Label Text],[Label Font],[Label Colour],[Label Size]);

            Percentage of: This is expressed as an integer representing a portion of
            Circumference  100%. That is, all pie slice percentages should add up to
                           a value of 100. If they do not add up to 100, then a black
                           slice with no label will occupy the remainder of the
                           circumference. If the values add up to more than 100, any
                           slice starting after 100 will be ignored.

            Slice Colour:  This is the colour of both the line and the plot point marker.
                           This can be expressed as a HEX value or as a word.

            Label Text:    You can add a text label that will appear in the middle of the
                           slice circumference.

            Label Font:    Standard HTML style font family designation.

            Label Colour:  This can be expressed as a HEX value or as a word.

            Label Size:    Expressed as an integer representing a pixel size for the text.
                           Do NOT include the "px" value.

            **Sample Call:    objHandle.addPieSlice(15,'#FF0000','Label 1','tahoma,sans-serif','#FF0000',9);

  Here is what successive calls will look like:

        objHandle.addPieSlice(15,'#FF0000','Label 1 15%','tahoma,sans-serif','#FF0000',9);
        objHandle.addPieSlice(25,'#0000FF','Label 2 45%','tahoma,sans-serif','#0000FF',9);
        objHandle.addPieSlice(30,'maroon','Label 3 30%','tahoma,sans-serif','maroon',9);
        objHandle.addPieSlice(10,'green','Label 4 10%','tahoma,sans-serif','green',9);
        objHandle.addPieSlice(20,'pink','Label 5 OVER','tahoma,sans-serif','pink',9);

  Make sure you review: IMPLEMENTATION - INSTANTIATING THE JSGRAPH OBJECT - LOADING THE JSGRAPH OBJECT


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>



  FULL PROPERTY & METHOD LIST


[INSTANTIATE A NEW OBJECT]

var objHandle = new JSGraph();



[LOAD OBJECT AFTER SETTING PROPERTIES AND METHODS]

objHandle.makeGraph();



[PROPERTIES]

objHandle.graphLeftPaddingOverride = integer;



[PROPERTIES ACCESSED THROUGH METHODS]

objHandle.horizontalBarGraph();

objHandle.yAxis([axis bar width],[axis length],[axis bar colour]);
objHandle.xAxis([axis bar width],[axis length],[axis bar colour]);

objHandle.addBackground('#FFF8DC');

objHandle.yAddTicks([spacing],[colour],[size]);
objHandle.xAddTicks([spacing],[colour],[size]);

objHandle.addTrellis([Spacing],[Size],[Colour]);

objHandle.yAddText([Text Value],[Font Family],[Font Colour],[Font Size]);
objHandle.yTextNudgeDown(10);

objHandle.xAddText([Text Value],[Font Family],[Font Colour],[Font Size]);

objHandle.addBar([UniqueID],[Bar Length],[Bar Width],[Bar Colour]);

objHandle.lightSource('SW');  Possible Value are:  NW, NE, SW, SE

objHandle.usePlus();

objHandle.addLinePlot(0); //Mandatory starting plot for each line on a line plot graph

objHandle.addLinePlot([Value],[Pen Size],[Pen Colour], [Use Marker], [Label Text], [Label Font], [Label Colour], [Label Size]);

objHandle.newLinePlot();

objHandle.pieChart([Diameter]);

objHandle.addPieSlice([Percentage of Circumference],[Slice Colour],[Label Text],[Label Font],[Label Colour],[Label Size]);


[POST LOADING METHODS]

objHandle.modifyBar([UniqueID],[New Value]);

objHandle.hideBar([UniqueID]);

objHandle.unhideBar([UniqueID]);


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  ADDING A VISUAL LEGEND

  You will probably want to add a legend to your bar graph to explain what each bar references.
  Here is a simply cut and paste legend box you can use, if you don't have the time to fuss
  around creating your own.

<div id="barGraphLegend" style="position:absolute;top:300px;left:50px;margin: 0px;padding: 5px;border: 3px ridge #000000;background-color:#F5F5F5;">
  <table border="0" cellspacing="3" cellpadding="0">
    <tr><td style="width:30px;background-color:#FF0000;font-family:tahoma,sans-serif;font-size:8pt;">&nbsp;</td><td style="font-family:tahoma,sans-serif;font-size:8pt;">Bar 1 Legend</td></tr>
    <tr><td style="width:30px;background-color:#00FF00;font-family:tahoma,sans-serif;font-size:8pt;">&nbsp;</td><td style="font-family:tahoma,sans-serif;font-size:8pt;">Bar 2 Legend</td></tr>
    <tr><td style="width:30px;background-color:#0000FF;font-family:tahoma,sans-serif;font-size:8pt;">&nbsp;</td><td style="font-family:tahoma,sans-serif;font-size:8pt;">Bar 3 Legend</td></tr>
    <tr><td style="width:30px;background-color:#000000;font-family:tahoma,sans-serif;font-size:8pt;">&nbsp;</td><td style="font-family:tahoma,sans-serif;font-size:8pt;">Bar 4 Legend</td></tr>
  </table>
</div>

  Things you need to do with this:

  1.) Define the top and left position of the containing DIV element, so that it appears
      where you want it to on the page.

  2.) Modify the background-color setting to match the colours of your bars.

  3.) Modify the label for the bar.


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  SAMPLES OF INSTANTION, PROPERTY ASSIGNMENT AND WORKING SLIDERS

  Extract all the files from this archive and store them in the same folder on your computer.

  Using your browser open any of the following files in the browser of your choice:

  example_graph.html

  example_dynamic_graph.html

  example_multiple_graphs.html

  example_large_graph.html

  example_large_graph_imagebg.html

  example_large_graph_imagebg_rpt.html

  example_lineplot.html

  example_piecharts.html

  example_fourkinds_one_page.html


  After seeing how they work, you can then view the source code to examine the
  object instantiation, property settings and method useage.


<*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  DEBUGGING

  This object library has been tested extensively in Opera 9.0, IE6.0, Firefox 1.5 and
  Netscape 8.0. If you call your page and encounter problems with the graph appearing
  or the dynamic operation, then the following suggestions will help you find the
  problem. It should work fine in Opera 6+, IE5.5+, NN7+.

  >> CHECK SYNTAX ON ALL METHODS THAT ARE CALLED. All methods MUST end in parenthesis whether or not
     arguments are passed to it. For example:

     objHandle.value(); INSTEAD OF objHandle.value;

  >> ARGUMENTS IMPROPERLY ASSIGNED FOR THEIR NATIVE TYPE. What this means is that if you
     are passing an argument as an integer, you can just type the value. If you are passing
     an argument that is a string, you must enclose that in quotes. If you are passing an
     argument as a variable, you must NOT enclose it in quotes. Here are some examples:

     objHandle.addBackground(#FFFCAD);   //This is VERY bad. JavaScript will crash in the page.
     objHandle.addBackground('#FFFCAD'); //Martha says, "This is a very good thing"
     objHandle.modifyBar('bar1','100');  //Workable, but not ideal
     objHandle.modifyBar('bar1', 100);   //Martha just launched a new magazine with your name! (Good)

     var valueFromSomewhere = '#FFFCAD';
     objHandle.addBackground('valueFromSomewhere'); //This is VERY bad. Javascript might crash but
                                                    either way, the graph object will just look
                                                    at your funny and not do anything useful.

     var valueFromSomewhere = '#FFFCAD';
     objHandle.addBackground(valueFromSomewhere);   // You Da Man!

  >> PROPERTIES IMPROPERLY ASSIGNED FOR THE VALUES NATIVE TYPE. You will only assign two of
     JavaScripts native types. They will be either "number" or "string". If you are assigning
     a NUMBER, you must NOT enclose it in quotes. If you are assigning a STRING then you MUST
     enclose it in quotes.

     Basically, if the value are assigning contains only digits (0 to 9) then it is a number.
     ANYTHING ELSE is a string. Here are some Rush Limbaugh approved examples:

     objHandle.someNiftyProperty = Red;           BAD - JavaScript crashes in the page.
     objHandle.someNiftyProperty = 'Red';         Good

     objHandle.someNiftyProperty = #FF0000;       BAD - JavaScript crashes in the page.
     objHandle.someNiftyProperty = '#FF0000';     Good

     var someColour = 'Red';
     objHandle.someNiftyProperty = 'someColour';  Not so good - JavaScript does not crash, colour does not change to Red.

     var someColour = 'Red';
     objHandle.someNiftyProperty = someColour;    Good

     objHandle.someNiftyProperty = '50';            Not so bad.
     objHandle.someNiftyProperty = 50;              Best.

     var this_width = 50;
     objHandle.someNiftyProperty = 'this_width';    Bad - Javascript will not crash, not quite sure what the object will do.

     var this_width = 50;
     objHandle.someNiftyProperty = this_width;      Perfect


  >> TYPOS ARE EASY. If you have assigned a property or argument correctly according to it's native type
     then your next check should be that you have typed all property and method names correctly. It's 
     easy to overlook. What I recommend (and this works) is to start at the bottom of the list of properties
     you have typed and work you way upwards, reading each property name backwards (from right to left). This
     will help make typo's jump out at you.

  >> WRONG OBJECT HANDLE USED. When you have more than one graph object on a page. It is quite easy to
     use the wrong object handle when setting a property or calling a method. Check your object handle name
     for the correct name AND for typo's while you are checkign your spelling on the properties and methods.

  >> BROWSER VERSION. If you are using Internet Explorer 5.0, that is probably the cause of the problems.
     Update your version of IE and try again.

  >> LOCATING THE makeGraph() METHOD. If all else fails, make sure you put this call to load the graph object
     at the very bottom of your HTML page, just BEFORE the closing </body> tag.


 <*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

  SUPPORT

  If you have run some debugging, are not using Internet Explorer 5.0 and have a headache
  from beating your head on the wall, you can contact me for assistance. I will require
  that you send me the page you are using the graph object on as well as any other
  CSS or JS files needed for the page (unless you link to them with a full URL in the
  page).

  Once I have rectified the problem, I will notify you. Payment of $40 per hour (one hour
  minimum ) is required before the solution will be released. In almost all cases, the
  solution will be within that hour.

  If I am not able to find a solution for what you are encountering then you will be
  notified and YOU WILL NOT OWE ME ANYTHING. I do not accept any payment unless I can
  provide a working solution.

  PLEASE CONTACT ME AT:      james_melanson@yahoo.ca

  Feature Requests:

  If your support issue is because a feature does not exist that you need, I will not
  support that issue. There are features I plan to implement in future versions,
  however, they are not available at this time. You can contact me to see if that
  eature is available yet, I'm always happy to answer an email.

  Upcoming Features List:

              -Conter colour bar between the end of the set bar and max value.

              -Coloured shadows.

              -Negative value support. Baseline in the middle of the graph permitting bars
               to extend above OR below the baseline.

              -Sine wave plotting.

              ***If you have a feature you would like to see added, let me know!



 <*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*><*>

