doc/api.html

<!DOCTYPE html>
<html>
  <head>
    <title>JavaScript Algorithm Visualization (JSAV) API documentation</title>
    <link rel="stylesheet" href="apidoc.css" >
  </head>

<body>
<h1>Documentation for the JavaScript Algorithm Visualization API (JSAV) Version 0.7dev</h1>

<p class="note">
This documentation reflects the current status of the library.
It is a work-in-progress and subject to change!
</p>
<h1>Contents</h1>
<ol id="toc"></ol>
<h2>Loading the Required Files</h2>
<p>
The easiest way to check the required files is to look at
the examples directory and copy one of those files as a template for
your new AV.
</p> 

<p>
If done manually, the files required (in this order) are as follows.
Note that <code>[JSAV]</code> refers to the relative position of the
JSAV library directory, which depends on where you are developing from.
</p> 

<ul>
  <li>jquery.transform: <code>[JSAV]/lib/jquery.transform.light.js</code></li>
  <li>Raphael: <code>[JSAV]/lib/raphael.js</code></li>
  <li>The library: Either <code>[JSAV]/build/jsav.js</code> or
      <code>[JSAV]/build/jsav-min.js</code>.
      This must always be included.</li>
</ul>
</p>

<p>
The main jQuery library must always be loaded.
jQuery UI and jquery.transform are only needed when you use the
library to show animations, such as using the data structures or
graphical primitives and modifying them. In other words, using
any other part of the library than the messaging API. Raphael is
only needed when using graphical primitives like circles and
rectangles or when using data structures with edges.
</p>

<p>
In addition, developers must include the supporting .css file:
<code>[JSAV]/css/JSAV.css</code>
</p>

<h2>HTML Template for the Visualization</h2>

<p>
Visualizations generally include two parts:
HTML DOM elements, and JavaScript elements. 
The HTML section typical includes something like this:
</p> 

<pre>
  &lt;div id="container">
  &lt;div class="jsavcontrols">&lt;/div>
  &lt;p class="jsavoutput jsavline">&lt;/p>
  &lt;/div>
</pre>
<dl>
  <dt><code>container</code></dt>
  <dd>This is the container element for the visualization</dd>
  <dt><code>jsavcontrols</code></dt>
  <dd>The library will generate slideshow controls inside this
  element if your visualization uses the slideshow API</dd>
  <dt><code>jsavoutput</code></dt>
  <dd>The area where the messages from the
      visualization will be displayed to the user.
      Type can further be specified using either
      class <code>jsavline</code> or <code>jsavscroll</code>.
      See the Messages API for more details.</dd>
</dl>

<h2>Creating A Visualization</h2>
<p>Initializing the visualization container is simple:</p>
<pre>var av = new JSAV("container");</pre>
<p>The <code>container</code> here refers to the id attribute of the
  container element (see the HTML template above).
  Alternatively, a DOM or jQuery element can be
  used as well. So, the following are alternative ways to achieve
  the same result:</p>
<pre>var av = new JSAV(document.getElementById("container"));
var av = new JSAV(jQuery("#container"));</pre>
<p>Both alternatives accept an optional second parameter <code>options</code> 
  which should be a JavaScript object. The options that are currently 
  supported:</p>
<dl>
  <dt><code>title</code></dt>
  <dd>Title of the AV. This will be shown as the first slide of the
    slideshow.</dd><br/>
  <dt><code>animationMode</code></dt>
  <dd>Use "none" to turn off animation (slideshow) mode.</dd>
</dl>
<p>In addition to the options passed to the function, any options specified
  in a global variable <code>JSAV_OPTIONS</code> will be used. Those passed on
  initialization always override the global options.</p>
    
<h2>Slideshow Support</h2>

<p>A slideshow is created by using a series of calls to the
  <code>.step()</code> method.
  Associated with each step, you use method calls to define or show
  the appropriate data structures and UI elements along with any
  actions to take place (such as swapping elements in an array or
  highlighting an element).</p>

<h3 class="apimethod">.step()</h3>
<p>Marks that a new step in the animation will start. Basically,
   everything within one step will be animated simultaneously when
   moving backward and forward.</p>

<p>
<b>Returns:</b> A JSAV object. Thus, this method may be chained with,
for example, the <code>umsg</code> method.
</p>

<h3 class="apimethod">.recorded()</h3>
<p>
A call to this method is placed at the end of the series of
<code>.step()</code> method calls to start the slideshow.
</p>

<h3 class="apimethod">.displayInit()</h3>
<p>Marks the current state of the visualization as the state where the 
  animation will start. That is, what will be displayed initially.</p>
<p>
<b>Returns:</b> A JSAV object. Thus, this method may be chained.</p>
  

<h3 class="apimethod">.animInfo()</h3>
<p>
This will return an object that has two properties: number of slides
and and number of effects.
It might be better used when called from somewhere like the FireBug
command line than in an actual AV implementation.
It can help a developer to optimize the complexity of the slideshow.

<h3>The <code>counter</code> element</h3>
<p>
A slideshow counter showing the position in slideshow (e.g. 2/120) can
be added by including a DOM element with class <code>jsavcounter</code>
inside the <code>container</code>.
For example, you can add
<code>&lt;span class="jsavcounter">&lt;/span></code> to some DOM element
to attach the counter.
</p>

<h3>Controlling Animation Outside of JSAV</h3>
<p>Sometimes you might want to control a JSAV animation from JavaScript 
 and not through the JSAV generated UI. There are two ways to do this:</p>
 <ol>
  <li>A JSAV instance has functions <code>.begin()</code>, <code>.backward()</code>,
    <code>.forward()</code> and <code>.end()</code> that can be called to move in
    the animation.</li>
  <li>You can trigger events on the <code>container</code> element to have
    JSAV move in the animation. The events are: <code>jsav-begin</code>,
    <code>jsav-backward</code>, <code>jsav-forward</code>, and
    <code>jsav-end</code>. For example, to move a step forward in the animation, 
    one could write <code>$(".jsavcontainer").trigger("jsav-forward")</code>.
    Note, that this example moves <em>all</em> JSAV animations on the page one
    step forward.</li>
 </ol>
<h2>Messages API</h2>

<p>
The Messages API allows the user to control the contents of the output
message buffer intended for informing the user about the state of the
visualization or for providing directions.</p>

<p>
The output buffer will have been specified in the HTML section of the
document. It is defined as an empty paragraph of class
<code>jsavoutput</code>, with one of the following class options.
</p>
<p>
<code>class="jsavoutput jsavline"</code> indicates a small "line-style"
message buffer where typically each line overwrites the previous one.
</p>
<p>
<code>class="jsavoutput jsavscroll"</code> indicates a visible textbox with a
scrollbar. The textbox is only cleared when explicitly directed by a
<code>.clearumsg()</code> call.
Since this acts as a normal HTML paragraph,
optional standard parameters can be used such as
<code>readonly="readonly"</code> to make 
the textbox unwriteable by the user, or to
override the default height and width.
</p>

<h3 class="apimethod">.umsg(msg[, options])</h3>
<p>
Add the given message <code>msg</code> to the message
output. The optional <code>options</code> parameter
can be an object whose properties specify the
behavior. The <code>color</code> property is used (when
present) to change the color of the message.
Use would look something like:
</p>
<pre>
av.umsg("My message here", {"color": "blue"});
</pre>
<p>
When "line-style" message buffer is used, option
<code>"preserve": true</code> can be used to append the new message
after the previous one instead of clearing the buffer.
</p>
<p>
Since the
<code>msg</code> is output as standard HTML, the style of
the message text can also be controlled by using HTML commands.
</p>

<p>
<b>Returns:</b> A JSAV object. Thus, this method may be chained with,
for example, the <code>step</code> method.
</p>


<h3 class="apimethod">.clearumsg()</h3>
<p>Clear the contents of the output message buffer.</p>

<h2>Array Data Structure API</h2>

<p>
JSAV will ultimately provide layout support for a number of standard
data structures. Presently, arrays, trees, and lists are supported.
</p>

<h3 class="apimethod">.ds.array(element[, options]) and
.ds.array(Array[, options])</h3>
<p>
An array can be created using the .ds.array method on a JSAV instance.
It takes one parameter indicating either a DOM/jQuery Element
(ul or ol) or a JavaScript Array.
For example, to initialize and add to the visualization an array with
four elements:</p>
<pre>var arr = av.ds.array([10, 13, 99, 25]);</pre>

<p>
Array indexing begins at zero.
</p>

<p>The returned array instance is controlled through a collection of
methods explained next. Note that changes to the array contents must
go through this API (using the <code>.value</code> method),
since the array contents must be managed by
JSAV rather than by the developer.
</p>

<p>Options that the second, optional, parameter can specify:</p>
<ul>
<li>layout: Defines choices of layout (<code>bar</code> for bars, <code>vertical</code> to show the array vertically, the
    default is to show a horizontal array).</li>
<li>indexed: Boolean to determine if array indices are shown or not.</li>
<li>visible: Boolean to determine if initially the array is shown or
      not. Default true.</li>
<li>center: Boolean to determine if array should be automatically centered
  within its container. Defaults to true.</li>
  <li>left/top/right/bottom: Values to determine the absolute position of the array relative to its container.</li>
  <li>relativeTo: A JSAV data structure object or DOM element that this structure should be positioned relative to.
      If this option is specified, left and top options will change structure's position relative to the relativeTo
      element. Note, that the element pointed by relativeTo needs to be visible.</li>
  <li>anchor: Defines which position on the element being positioned to align with the target element. Should be in 
      format <code>horizontal vertical</code>. Possible horizontal values are "left", "center", "right" and vertical values "top", "center", "bottom". Defaults to <code>center center</code>. Only has an effect if relativeTo is
      specified.</li>
  <li>myAnchor: Similar to anchor, but the position on this element. Defaults to <code>center center</code>. Only 
      has an effect if relativeTo is specified.</li>
  <li>relativeIndex: If relativeTo points to a JSAV array, this option can be used to position this structure relative
      to an index in that array. Only has an effect if relativeTo is specified.</li>
</ul>

<h3 class="apimethod">.clone()</h3>
<p>
Create and return a clone of an array.
The clone will remain invisible until the <code>show</code>
method is called on it.
</p>

<h3 class="apimethod">.css(indices, cssPropertyName)</h3>
<p>Returns the value of CSS property <code>cssPropertyName</code> for the first 
  index matching the <code>indices</code> parameter. Parameter <code>indices</code> 
  can be a number, array, <code>true</code>, or function like for
  the <code>highlight</code> method.</p>


<h3 class="apimethod">.css(indices, css)</h3>
<p>
Apply the given CSS properties to the specified <code>indices</code>.
Parameter <code>indices</code> can be a number, array,
<code>true</code>, or function like for the <code>highlight</code>
method.
When <code>indices</code> is <code>true</code>, then <code>css</code>
is applied to all elements of the array.
The argument <code>css</code> should be an object with property
name-and-value pairs.
For example, to make positions 0 and 4 have green color and lightgray
background:
</p>
<pre>
arr.css([0, 4], {"color": "green", "background-color": "#eee"});
</pre>

<p>
<b>Returns:</b> a JSAV array object. Thus, this method can be chained.
</p>

<h3 class="apimethod">.css(cssPropertyName)</h3>
<p>Returns the value of CSS property <code>cssPropertyName</code> for the array.</p>

<h3 class="apimethod">.css(css)</h3>
<p>
Apply the given CSS properties to the array element.
The argument <code>css</code> should be an object with property
name-and-value pairs. For example, to move the array 20 pixels to the right:
</p>
<pre>
arr.css({"left": "+=20px"});
</pre>

<h3 class="apimethod">.hide()</h3>
<p>
Make the array invisible.
</p>

<h3 class="apimethod">.highlight()</h3>
<p>
Call to <code>highlight</code> without any parameters will highlight
all elements in the array.
Note that this will only apply the color and background-color of CSS class 
<code>jsavhighlight</code> to the array elements.
It is up to the author to make sure the loaded CSS files include such
styling.
</p>

<p>
<b>Returns:</b> a JSAV array object. Thus, this method can be chained.
</p>

<h3 class="apimethod">.highlight(number)</h3>
<p>
Highlight the given index number.
</p>

<h3 class="apimethod">.highlight(indexlist)</h3>
<p>
Highlight the indices in the given <code>indexlist</code>.
For example, the following would highlight array positions 1, 2, and 5.
</p>
<pre>arr.highlight([1, 2, 5]);</pre>

<h3 class="apimethod">.highlight(function)</h3>
<p>
Highlights all the indices that the passed function returns true.
For example, to highlight all even indices:</p> 
<pre>arr.highlight(function(index) { return index%2==0; });</pre>

<h3 class="apimethod">.highlight(boolean)</h3>
<p>
If the given boolean value is <code>true</code>, all the indices are highlighted. 
If <code>false</code>, none are.
For example, to highlight all indices:</p> 
<pre>arr.highlight(true);</pre>

<h3 class="apimethod">.show()</h3>
<p>
Make the array visible.
</p>

<h3 class="apimethod">.size()</h3>
<p>
Returns the size of the array.
For the array defined in the array creation example above,
the following would return 4:
</p>
<pre>arr.size();</pre>
    
<h3 class="apimethod">.swap(index1, index2)</h3>
<p>Swaps the contents (and graphics state) of the two array positions.</p>
    
<h3 class="apimethod">.unhighlight(indices)</h3>
<p>
Removes the highlight from the given <code>indices</code>.
There are corresponding versions of this function with parameters like
for highlight.
</p>

<p>
<b>Returns:</b> a JSAV array object. Thus, this method can be chained.
</p>

<h3 class="apimethod">.value(index)</h3>
<p>Returns the value of the element at the given index.</p>
    
<h3 class="apimethod">.value(index, newValue)</h3>
<p>
Sets the value of the element at the given index to the given value.
</p>

<h3 class="apimethod">.toggleLine(index, [options])</h3>
<p>Toggles a marker line above a given array index for bar layout. For other layouts, does nothing. Options that can be passed:</p>
<ul>
  <li><code>markStyle</code>: Style of the "ball" as an object of CSS property/value pairs. Default style is first applied, then the given style. Passing <code>null</code> will disable the ball altogether.</li>
  <li><code>lineStyle</code>: Style of the line. Works similarly to <code>markStyle</code>.</li>
  <li><code>startIndex</code>: Index in the array where the line will start. Default 0.</li>
  <li><code>endIndex</code>: Index in the array where the line will end, inclusive. Defaults to last index of the array.</li>
</ul>
<h3 class="apimethod">.isEmpty()</h3>
<p>Returns true if the array is empty.</p>
<h3 class="apimethod">.addClass(index, className, [options])</h3>
<p>Adds the CSS class <code>className</code> to given indices and animates the changes. Like for
  the rest of array methods, <code>index</code> can be a number, array of numbers, or a function.</p>
<h3 class="apimethod">.removeClass(index, className, [options])</h3>
<p>Removes the CSS class <code>className</code> to given indices and animates the changes. Like for
  the rest of array methods, <code>index</code> can be a number, array of numbers, or a function.</p>
<h3 class="apimethod">.toggleClass(index, className, [options])</h3>
<p>Toggles the CSS class <code>className</code> to given indices and animates the changes. Like for
  the rest of array methods, <code>index</code> can be a number, array of numbers, or a function.</p>
<h3 class="apimethod">.hasClass(index, className, [options])</h3>
<p>Return true/false based on if the given index has the CSS class <code>className</code>. Parameter
  <code>index</code> should be a number.</p>

<h3 class="apitopic">Events</h3>
<p>There are functions to attach event handlers for the array elements. The events that can be
  listened for are: click, dblclick, mousedown, mousemove, mouseup, mouseenter, and mouseleave. 
  See <a href="http://api.jquery.com/category/events/">jQuery documentation</a> for details on 
  the events. Every event handler gets as a first parameter the index of the array element that
  the event was triggered for. The last parameter is the jQuery event object. Inside the event
  handler function, <code>this</code> will refer to the JSAV array object. </p>
<p><b>Returns:</b> a JSAV array object. Thus, this method can be chained.</p>
<p>Example to toggle arrow on click of an element:</p>
  <pre>arr.click(function(index) {
    this.toggleArrow(index);
  });</pre>
<p>Since many of the JSAV array functions take the index as the first parameter, they can be used
  as event handlers. For example, to highlight an index on mouseenter and unhighlight on mouseleave,
  you can use:</p>
  <pre>arr.mouseenter(arr.highlight).mouseleave(arr.unhighlight);</pre>
  <p>You can also pass custom arguments to the event handler function. To do this, the first argument
  to the event binding function should be an array of parameters that will be passed as parameters to
  the event handler function. This is best explained with an example:</p>
  <pre>arr.mouseenter([{"color": "red"}], arr.css).mouseleave([{"color": "black"}], arr.css);</pre>
  <p>This will use array's <code>css</code> function as the event handler and pass it another parameter
    when the event is triggered. On mouse enter, the function call will essentially be: 
    <code>arr(index, {"color": "red"}, e)</code>. Here, <code>e</code> is again the jQuery event object.</p>
<h3 class="apimethod">.on(eventName, [data,], handler)</h3>
<p>To bind other events than the ones listed above, you can use the <code>on</code> function. It takes
  as the first parameter the name of the event. Multiple events can be bound by separating their names with
  spaces. Other parameters are the same as for the shortcuts.</p>

<h3 class="apitopic">CSS control</h3>

There are various options and style effects that can be controlled via
CSS.

<h3 class="apimethod">width and height</h3>

<p>By default, array elements are at minimum 45 pixels wide and will automatically expand if the content
  is wider than that. Width and height can be controlled with the width/height CSS properties. Example:</p>

<pre>
.jsavarray .jsavindex {
  width: 60px;
}
</pre>
<p>Note, that JSAV has specified <code>min-width</code> for array indices to be 45 pixels. If you want to
  make the indices smaller than that, you will also need to specify the <code>min-width</code> property. For 
  example, to make indices 20px wide:<p>
<pre>
.jsavarray .jsavindex {
  width: 20px;
  min-width: 20px;
}
</pre>
<p>If you change the height of array elements, you should probably also change the line-height of the text inside. Example:</p>
<pre>
.jsavarray .jsavindex {
  height: 20px;
  min-height: 20px;
  line-height: 20px
}
</pre>

<h3 class="apitopic">Extending the Array</h3>
<p class="todo">
Example of extending to provide .opacity(indices, value) function as a
shortcut to set the opacity of indices.
</p> 


<h2>Tree Data Structure API</h2>

<p>
Currently, JSAV supports two types of trees: common tree and binary tree. The structures form a "class" hierarchy: Tree &larr; Binary Tree and TreeNode &larr; BinaryTreeNode.
</p>

<h3 class="apimethod">.ds.tree([options]) and .ds.bintree([options])</h3>
<p>These functions of a JSAV instance initialize a new tree or binary tree. The returned tree instance is controlled through a collection of methods explained next.</p>

<p>Options that the optional parameter can specify:</p>
<ul>
<li>layout: Defines choices of layout (currently only the default layout is supported).</li>
<li>visible: Boolean to determine if initially the tree is shown or
      not. Default true.</li>
<li>center: Boolean to determine if tree should be automatically centered
  within its container. Defaults to true.</li>
  <li>left/top/right/bottom: Values to determine the absolute position of the tree relative to its container.</li>
  <li>nodegap: Number to specify how big the gap between nodes in the tree should be. Defaults to 40.</li>
  <li>relativeTo: A JSAV data structure object or DOM element that this structure should be positioned relative to.
      If this option is specified, left and top options will change structure's position relative to the relativeTo
      element. Note, that the element pointed by relativeTo needs to be visible.</li>
  <li>anchor: Defines which position on the element being positioned to align with the target element. Should be in 
      format <code>horizontal vertical</code>. Possible horizontal values are "left", "center", "right" and vertical values "top", "center", "bottom". Defaults to <code>center center</code>. Only has an effect if relativeTo is
      specified.</li>
  <li>myAnchor: Similar to anchor, but the position on this element. Defaults to <code>center center</code>. Only 
      has an effect if relativeTo is specified.</li>
  <li>relativeIndex: If relativeTo points to a JSAV array, this option can be used to position this structure relative
      to an index in that array. Only has an effect if relativeTo is specified.</li>
</ul>

<h3 class="apimethod">.css(propertyName)</h3>
<p>Returns the value for the given CSS property. This function exists for all trees, nodes, and edges.</p>

<h3 class="apimethod">.css(propertyName, value)</h3>
<p>Animates the value of the given CSS property to value. This function exists for all trees, nodes, and edges.</p>
<h3 class="apimethod">.css({map})</h3>
<p>Animates values of the CSS properties in the map to the given values. This function exists for all trees, nodes, and edges. For example</p>
<pre>
  tree.css({color: "green", "font-size": "20px"});
</pre>
<p>would animate the color and font-size properties of the tree.</p>

<h3 class="apimethod">.id([newId])</h3>
<p>Returns the ID of the structure. If optional parameter <var>newId</var> is given, sets the ID of the structure. The given ID should be unique. This function exists for all trees, nodes, and edges.</p>

<h3 class="apimethod">.root([node])</h3>
<p>Returns the root of this tree. If the optional <var>node</var> parameter is given, the root of the tree is set. This function exists for all trees.</p>

<h3 class="apimethod">.newNode(value)</h3>
<p>Creates a new node that can be added to this tree. "Subclasses" override this to create nodes suited for the tree, so this method should be used when creating new nodes. This function exists for all trees.</p>

<h3 class="apimethod">.height()</h3>
<p>Returns the height of the tree. This function exists for all trees</p>

<h3 class="apimethod">.layout()</h3>
<p>This function (re)calculates the layout for the tree. Note, that the library does not do this automatically. That means that after changing the tree, you should call this manually at the end of each animation step. This function exists for all trees.</p>

<h3 class="apimethod">.hide([options])</h3>
<p>Make the tree invisible. This function exists for all trees. It recursively hides all the nodes and edges in the tree as well unless
option <code>recursive</code> is set to <code>false</code>.</p>
<h3 class="apimethod">.show([options])</h3>
<p>Make the tree visible.This function exists for all trees. It recursively shows all the nodes and edges in the tree as well unless
option <code>recursive</code> is set to <code>false</code>.</p>

<h3 class="apimethod">.addClass(className, [options])</h3>
<p>Adds the CSS class <code>className</code> to the tree and animates the changes.</p>

<h3 class="apimethod">.removeClass(className, [options])</h3>
<p>Removes the CSS class <code>className</code> from the tree and animates the changes.</p>

<h3 class="apimethod">.toggleClass(className, [options])</h3>
<p>Toggles the CSS class <code>className</code> to the tree and animates the changes.</p>

<h3 class="apimethod">.hasClass(className, [options])</h3>
<p>Return true/false based on if the tree has the CSS class <code>className</code>.</p>


<h3 class="apitopic">Events</h3>
<p>There are functions to attach event handlers for the nodes and edges in the tree. The events 
  that can be
  listened for are: click, dblclick, mousedown, mousemove, mouseup, mouseenter, and mouseleave. 
  See <a href="http://api.jquery.com/category/events/">jQuery documentation</a> for details on 
  the events. Every event handler gets as a parameter the jQuery event object. Inside the event
  handler function, <code>this</code> will refer to the JSAV node or edge object. </p>
  <p>The function takes another, optional, parameter options that should be an object. It can be 
  used to specify whether
  the event handler is for nodes or edges. By default, it is attached to only nodes.
  <p><b>Returns:</b> a JSAV tree object. Thus, this method can be chained.</p>
  <p>For example, to highlight an node on mouseenter and unhighlight on mouseleave,
  you can use:</p>
  <pre>tree.mouseenter(function() { this.highlight(); })
    .mouseleave(function() { this.unhighlight(); });</pre>
  <p>To attach a handler to edges, you can do:</p>
  <pre>tree.mouseenter(yourEventHandler, {edge: true});</pre>
  <p>Similarly to arrays, you can also pass custom data to the handler. For example, 
    <code>bt.click({"color": "blue"}, JSAV.utils._helpers.css);</code> would call the <code>css</code>
    function with the given parameter. </p>
<h3 class="apimethod">.on(eventName, [data,], handler, options)</h3>
<p>To bind other events than the ones listed above, you can use the <code>on</code> function. It takes
  as the first parameter the name of the event. Multiple events can be bound by separating their names with
  spaces. Other parameters are the same as for the shortcuts.</p>
  

<h2>Tree Node API</h2>
<p>The following functions exist for both tree nodes and binary tree nodes.</p>
<h3 class="apimethod">.value([newValue])</h3>
<p>Returns the value stored in this node. If the optional <var>newValue</var> parameter is given, the value is set to the given value.</p>
<h3 class="apimethod">.parent([newParent])</h3>
<p>Returns the parent node of this node. If the optional <var>newParent</var> parameter is given, the parent node is set.</p>
<h3 class="apimethod">.edgeToParent([newEdge])</h3>
<p>Returns the edge that connects this node to its parent. If the optional <var>newEdge</var> parameter is given, the edge to parent is set.</p>
<h3 class="apimethod">.edgeToChild(pos)</h3>
<p>Returns the edge that connects this node to its child at <var>pos</var>. Returns <code>undefined</code> is no such child exists.</p>
<h3 class="apimethod">.child(pos)</h3>
<p>Returns the <var>pos</var>:th child of this node.</p>
<h3 class="apimethod">.child(pos, node [,options])</h3>
<p>Sets the <var>pos</var>:th child to the given value. The <var>node</var> can be a value or a node of correct type to the node. If value <code>null</code> is given as <code>node</code>, the child at that position is removed. Note, that this also hides the removed node and the edge.</p>
<p>The optional third argument <code>options</code> should be an object. The following option(s) are supported:</p>
<ul>
  <li><code>edgeLabel</code>: specify a label shown on the edge connecting the new node to its parent.</li>
</ul>
<h3 class="apimethod">.addChild(node [,options])</h3>
<p>Adds a child node to this node. The <var>node</var> can be a value or a node of correct type to the node.
  The <code>options</code> parameter works like above.</p>
<h3 class="apimethod">.remove([options])</h3>
<p>Removes the node from its parent.</p>
<h3 class="apimethod">.hide([options])</h3>
<p>Hides the node and the edge connecting it to the parent node. Also recursively hides all child nodes unless 
option <code>recursive</code> is set to <code>false</code>.</p>
<h3 class="apimethod">.show([options])</h3>
<p>Shows the node and the edge connecting it to the parent node. Also recursively shows all child nodes unless 
option <code>recursive false</code> is set to <code>false</code>. Note, that if the tree is not visible, showing nodes will not have
any effect until the tree is set visible by calling show.</p>

<h3 class="apimethod">.addClass(className, [options])</h3>
<p>Adds the CSS class <code>className</code> to the node and animates the changes.</p>

<h3 class="apimethod">.removeClass(className, [options])</h3>
<p>Removes the CSS class <code>className</code> from the node and animates the changes.</p>

<h3 class="apimethod">.toggleClass(className, [options])</h3>
<p>Toggles the CSS class <code>className</code> of the node and animates the changes.</p>

<h3 class="apimethod">.hasClass(className, [options])</h3>
<p>Return true/false based on if the node has the CSS class <code>className</code>.</p>

<h2>Binary Tree Node API</h2>
<h3 class="apimethod">.left([node [, options]])</h3>
<p>Returns the left child or undefined if node has no left child. If optional parameter <var>node</var> is given, sets the left child. The parameter can be a value or a binary tree node. If value <code>null</code> is given as <code>node</code>, the left child is removed. Note, that this also hides the removed node and the edge.
The additional <code>options</code> parameter works like for <code>.child(...)</code> above. </p>
<h3 class="apimethod">.right([node [,options]])</h3>
<p>Returns the right child or undefined if node has no right child. If optional parameter <var>node</var> is given, sets the right child. The parameter can be a value or a binary tree node. Passing <code>null</code> as node works similarly to the left function. The additional <code>options</code> parameter works like for <code>.child(...)</code> above.</p>
<h3 class="apimethod">.edgeToLeft()</h3>
<p>Returns the edge that connects this node to its left child. Returns <code>undefined</code> is node has no left child.</p>
<h3 class="apimethod">.edgeToRight()</h3>
<p>Returns the edge that connects this node to its right child. Returns <code>undefined</code> is node has no right child.</p>
  
<h2>Edge structure API</h2>
<h3 class="apimethod">.start([node])</h3>
<p>Returns the start node of this edge. If the optional <var>node</var> parameter is given, sets the start node of this edge.</p>
<h3 class="apimethod">.end([node])</h3>
<p>Returns the end node of this edge. If the optional <var>node</var> parameter is given, sets the end node of this edge.</p>
<h3 class="apimethod">.label()</h3>
<p>Returns the label attached to this edge.</p>
<h3 class="apimethod">.label(newLabel)</h3>
<p>Sets the value of the label attached to this edge.</p>


<h2>Linked List API</h2>
<h3 class="apimethod">.ds.list([options])</h3>
<p>This function of a JSAV instance initializes an empty linked list. Options that the optional parameter can specify:</p>
<ul>
  <li>layout: Defines choices of layout (currently only the default layout is supported).</li>
  <li>visible: Boolean to determine if initially the list is shown or not. Default true.</li>
  <li>center: Boolean to determine if list should be automatically centered within its container. Defaults to true.</li>
  <li>left/top/right/bottom: Values to determine the absolute position of the list relative to its container.</li>
  <li>nodegap: Number to specify how big the gap between nodes in the list should be. Defaults to 40.</li>
  <li>relativeTo: A JSAV data structure object or DOM element that this structure should be positioned relative to.
      If this option is specified, left and top options will change structure's position relative to the relativeTo
      element. Note, that the element pointed by relativeTo needs to be visible.</li>
  <li>anchor: Defines which position on the element being positioned to align with the target element. Should be in 
      format <code>horizontal vertical</code>. Possible horizontal values are "left", "center", "right" and vertical values "top", "center", "bottom". Defaults to <code>center center</code>. Only has an effect if relativeTo is
      specified.</li>
  <li>myAnchor: Similar to anchor, but the position on this element. Defaults to <code>center center</code>. Only 
      has an effect if relativeTo is specified.</li>
  <li>relativeIndex: If relativeTo points to a JSAV array, this option can be used to position this structure relative
      to an index in that array. Only has an effect if relativeTo is specified.</li>
</ul>
<p>The returned list instance is controlled through a collection of methods explained next. In addition, the list has the common functions such as <code>.id()</code>, <code>.css(...)</code>, <code>.show()</code>, and <code>.hide()</code>.</p>

<h3 class="apimethod">.first() and last()</h3>
<p>Returns the first or last node in the list. If there are no nodes in the list, returns undefined.</p>
<h3 class="apimethod">.addFirst([value]) and .addFirst([node])</h3>
<p>Adds the given <code>value</code> or <code>node</code> as the first item in the list. Returns the list, so calls can be chained.</p>
<h3 class="apimethod">.addLast([value]) and .addLast([node])</h3>
<p>Adds the given <code>value</code> or <code>node</code> as the last item in the list. Returns the list, so calls can be chained.</p>
<h3 class="apimethod">.add(index, [value or node])</h3>
<p>Adds the given <code>value</code> or <code>node</code> to be the <code>index</code>th item in the list. The first item in the list has index 0. Returns the list, so calls can be chained.</p>
<h3 class="apimethod">.get(index)</h3>
<p>Returns the node at <code>index</code>. First item has index 0. If no such index exists, returns <code>undefined</code>.</p>
<h3 class="apimethod">.removeFirst() and .removeLast()</h3>
<p>Removes the first or last node in the list. Returns the removed node.</p>
<h3 class="apimethod">.remove(index)</h3>
<p>Removes the node at <code>index</code> in the list. First item has index 0. Returns the removed node.</p>
<h3 class="apimethod">.size()</h3>
<p>Returns the size of the list.</p>
<h3 class="apimethod">.layout([options])</h3>
<p>Positions the nodes and edges is the list.</p>
<h3 class="apimethod">.newNode(value [, options])</h3>
<p>Returns a new node that can be added to the list.</p>

<h3 class="apimethod">.addClass(className, [options])</h3>
<p>Adds the CSS class <code>className</code> to the list and animates the changes.</p>

<h3 class="apimethod">.removeClass(className, [options])</h3>
<p>Removes the CSS class <code>className</code> from the list and animates the changes.</p>

<h3 class="apimethod">.toggleClass(className, [options])</h3>
<p>Toggles the CSS class <code>className</code> of the list and animates the changes.</p>

<h3 class="apimethod">.hasClass(className, [options])</h3>
<p>Return true/false based on if the list has the CSS class <code>className</code>.</p>

<h3 class="apitopic">Events</h3>
<p>There are functions to attach event handlers for the nodes and edges in the list. The events 
  that can be listened for are: click, dblclick, mousedown, mousemove, mouseup, mouseenter, and mouseleave.
  See the tree documentation for details.</p>

<h2>Linked List Node API</h2>
<p>A node in a list has the same functions as a tree node: <code>.value([newValue])</code>, <code>.highlight()/unhighlight()</code>, <code>.show()/.hide()</code>, and <code>.css(...)</code>. In addition, it has the following functions.</p>
<h3 class="apimethod">.next()</h3>
<p>Returns the next node in the linked list. If no next, returns null.</p>
<h3 class="apimethod">.next([node [, options]])</h3>
<p>Sets the next node to be the passed <code>node</code>. The optional second argument <code>options</code> should be an object. The following option(s) are supported:</p>
<ul>
  <li><code>edgeLabel</code>: specify a label shown on the edge connecting the node to the next.</li>
</ul>

<h3 class="apimethod">.edgeToNext()</h3>
<p>Returns the JSAV Edge object that points to the next item in the list.</p>

<h3 class="apimethod">.addClass(className, [options])</h3>
<p>Adds the CSS class <code>className</code> to the node and animates the changes.</p>

<h3 class="apimethod">.removeClass(className, [options])</h3>
<p>Removes the CSS class <code>className</code> from the node and animates the changes.</p>

<h3 class="apimethod">.toggleClass(className, [options])</h3>
<p>Toggles the CSS class <code>className</code> of the node and animates the changes.</p>

<h3 class="apimethod">.hasClass(className, [options])</h3>
<p>Return true/false based on if the node has the CSS class <code>className</code>.</p>


<h2>Graph API</h2>
<h3 class="apimethod">.ds.graph([options])</h3>
<p>This function of a JSAV instance initializes an empty graph. Options that the optional parameter can specify:</p>
<ul>
  <li>layout: Defines choices of layout (currently only the default layout is supported).</li>
  <li>visible: Boolean to determine if initially the graph is shown or not. Default true.</li>
  <li>center: Boolean to determine if graph should be automatically centered within its container. Defaults to true.</li>
  <li>left/top/right/bottom: Values to determine the absolute position of the graph relative to its container.</li>
  <li>relativeTo: A JSAV data structure object or DOM element that this structure should be positioned relative to.
      If this option is specified, left and top options will change structure's position relative to the relativeTo
      element. Note, that the element pointed by relativeTo needs to be visible.</li>
  <li>anchor: Defines which position on the element being positioned to align with the target element. Should be in 
      format <code>horizontal vertical</code>. Possible horizontal values are "left", "center", "right" and vertical values "top", "center", "bottom". Defaults to <code>center center</code>. Only has an effect if relativeTo is
      specified.</li>
  <li>myAnchor: Similar to anchor, but the position on this element. Defaults to <code>center center</code>. Only 
      has an effect if relativeTo is specified.</li>
  <li>relativeIndex: If relativeTo points to a JSAV array, this option can be used to position this structure relative
      to an index in that array. Only has an effect if relativeTo is specified.</li>
  <li>width: Width of the graph, in pixels. Defaults to 400.</li>
  <li>height: Height of the graph, in pixels. Defaults to 200.</li>
  <li>directed: Wether or not this graph is directed.</li>
</ul>
<p>The returned graph instance is modified through a collection of methods explained next. In addition, the graph has the common 
  functions such as <code>.id()</code>, <code>.css(...)</code>, <code>.show()</code>, and <code>.hide()</code>.</p>

<h3 class="apimethod">.addNode(value, [options])</h3>
<p>Adds a new node with <code>value</code> to the graph. Returns the new node.</p>
<h3 class="apimethod">.removeNode(node, [options])</h3>
<p>Removes the given <code>node</code>.</p>
<h3 class="apimethod">.addEdge(fromNode, toNode, [options])</h3>
<p>Adds edge from <code>fromNode</code> to <code>toNode</code>. Returns the new edge.</p>
<h3 class="apimethod">.removeEdge(fromNode, toNode, [options])</h3>
<p>Removes edge from <code>fromNode</code> to <code>toNode</code>.</p>
<h3 class="apimethod">.hasEdge(fromNode, toNode)</h3>
<p>Returns true if the graph has an edge from <code>fromNode</code> to <code>toNode</code>.</p>
<h3 class="apimethod">.getEdge(fromNode, toNode)</h3>
<p>Returns the Edge object connecting <code>fromNode</code> and <code>toNode</code>, or <code>undefined</code> if no such edge exists.</p>
<h3 class="apimethod">.nodes()</h3>
<p>Returns an iterable array of nodes in the graph. The returned structure can be used as a normal JavaScript array. In addition, 
  it has methods <code>.next()</code> and <code>.hasNext()</code> for iterating over the values.</p>
<h3 class="apimethod">.edges()</h3>
<p>Returns an iterable array of edges in the graph. The returned structure is similar to the one returned by <code>.nodes()</code>.</p>
<h3 class="apitopic">Events</h3>
<p>There are functions to attach event handlers for the nodes and edges in the graph. The events 
  that can be listened for are: click, dblclick, mousedown, mousemove, mouseup, mouseenter, and mouseleave.
  See the tree documentation for details.</p>


<h2>Graph Node API</h2>
<p>A node in a graph has the same functions as a tree node: <code>.value([newValue])</code>, <code>.highlight()/unhighlight()</code>, <code>.show()/.hide()</code>, and <code>.css(...)</code>. In addition, it has the following functions.</p>
<h3 class="apimethod">.neighbors()</h3>
<p>Returns an iterable array of the nodes that this node is connected to.</p>
<h3 class="apimethod">.edgeTo(node)</h3>
<p>Returns the Edge object connecting this node to the given <code>node</code>. Returns <code>undefined</code> if no such edge exists.</p>
<h3 class="apimethod">.edgeFrom(node)</h3>
<p>Returns the Edge object connecting the given <code>node</code> to this node. Returns <code>undefined</code> if no such edge exists.</p>

<h2>Label API</h2>

<p>UI elements such as arrays can take a label.</p>

<h3 class="apimethod">.label(msg, options)</h3>
<p>
This is a method of the AV object.
It creates a label that is associated with some UI element of the AV
specified by the options.
Parameter <code>msg</code> is the
(initial) value for the label.
Paramter <code>options</code> include the following:
</p>
<ul>
<li> <code>{before: &lt;UI element>}</code> Set the label before element
<code>UI element</code></li>
<li> <code>{after: &lt;UI element>}</code> Set the label after element
<code>UI element</code></li>
<li> <code>{visible: &lt;boolean>}</code> Determine whether the label
is visible on creation. Defaults to true.</li>
  <li><code>{left/top/right/bottom: &lt;lengthUnit>}</code> Values to determine the absolute position of the label relative to its container.</li>
</ul>

<h3 class="apimethod">.hide()</h3>
<p>
Make the label invisible.
</p>

<h3 class="apimethod">.show()</h3>
<p>
Make the label visible.
</p>

<h3 class="apimethod">.text(msg)</h3>
<p>
Set the text for the label. If the <code>msg</code> parameter is left
out, this method will return the current text of the label.
</p>

<h3 class="apimethod">.addClass(className, [options])</h3>
<p>Adds the CSS class <code>className</code> to the label and animates the changes.</p>

<h3 class="apimethod">.removeClass(className, [options])</h3>
<p>Removes the CSS class <code>className</code> from the label and animates the changes.</p>

<h3 class="apimethod">.toggleClass(className, [options])</h3>
<p>Toggles the CSS class <code>className</code> of the label and animates the changes.</p>

<h3 class="apimethod">.hasClass(className, [options])</h3>
<p>Return true/false based on if the label has the CSS class <code>className</code>.</p>

    <h2>Variable API</h2>

    <p>Variables can be used to present undo/redo capable variables.</p>

    <h3 class="apimethod">.variable(value, [options])</h3>
    <p>
    This is a method of the AV object.
    It creates a variable that can be associated with some UI element.
    Parameter <code>value</code> is the
    (initial) value for the variable.
    Parameter <code>options</code> include the following:
    </p>
    <ul>
    <li> <code>{before: &lt;UI element>}</code> Add the variable before element
    <code>UI element</code></li>
    <li> <code>{after: &lt;UI element>}</code> Add the variable after element
    <code>UI element</code></li>
    <li> <code>{visible: &lt;boolean>}</code> Determine whether the variable
    is visible on creation. Defaults to false.</li>
    <li> <code>{name: &lt;string>}</code> Name of the variable. Can be used to 
      fetch the variable value later. </li>
    <li> <code>{label: &lt;string>}</code> Label for the variable. Will be shown 
      before the variable value. For example, label "Count =" would end up the
      variable looking like "Count = 3" in the HTML.</li>
    <li> <code>{type: &lt;string>}</code> Type of the variable. Can be boolean,
      number, or string. By default, the type is decided based on the type of the
      initial value.</li>
    <li><code>{left/top/right/bottom: &lt;lengthUnit>}</code> Values to determine the absolute position of the label relative to its container.</li>
  <li>relativeTo: A JSAV data structure object or DOM element that this structure should be positioned relative to.
      If this option is specified, left and top options will change structure's position relative to the relativeTo
      element. Note, that the element pointed by relativeTo needs to be visible.</li>
  <li>anchor: Defines which position on the element being positioned to align with the target element. Should be in 
      format <code>horizontal vertical</code>. Possible horizontal values are "left", "center", "right" and vertical values "top", "center", "bottom". Defaults to <code>center center</code>. Only has an effect if relativeTo is
      specified.</li>
  <li>myAnchor: Similar to anchor, but the position on this element. Defaults to <code>center center</code>. Only 
      has an effect if relativeTo is specified.</li>
  <li>relativeIndex: If relativeTo points to a JSAV array, this option can be used to position this structure relative
      to an index in that array. Only has an effect if relativeTo is specified.</li>
    </ul>

    <h3 class="apimethod">.hide()</h3>
    <p>
    Make the variable invisible.
    </p>

    <h3 class="apimethod">.show()</h3>
    <p>
    Make the variable visible.
    </p>

    <h3 class="apimethod">.value([val])</h3>
    <p>
    Set the value of the variable. If the <code>val</code> parameter is left
    out, this method will return the current value of the variable. The value is
    converted to the type specified when initializing the variable.
    </p>

    <h3 class="apimethod">.addClass(className, [options])</h3>
    <p>Adds the CSS class <code>className</code> to the variable and animates the changes.</p>

    <h3 class="apimethod">.removeClass(className, [options])</h3>
    <p>Removes the CSS class <code>className</code> from the variable and animates the changes.</p>

    <h3 class="apimethod">.toggleClass(className, [options])</h3>
    <p>Toggles the CSS class <code>className</code> of the variable and animates the changes.</p>

    <h3 class="apimethod">.hasClass(className, [options])</h3>
    <p>Return true/false based on if the variable has the CSS class <code>className</code>.</p>

    <h2>Pseudocode API</h2>
    <p>The pseudocode API in JSAV is intended for showing a static set of codelines that can be show/hidden and
      highlighted. There are two ways to initialize a pseudocode object in JSAV:</p>
    <h3 class="apimethod">.code(codelines[, options]) or .code([options])</h3>
    <p>Both of these are functions of a JSAV object instance. The first version takes either an array or a string 
      to be used as the lines of code. If a string is passed, it will be split on newline characters (<code>\n</code>)
      to get the codelines.</p>
    <p>The options that can be specified:</p>
    <ul>
      <li> <code>{url: &lt;string>}</code> A URL where the code should be fetched. The fetched text will be split on
        newline characters (<code>\n</code>). Note, that if the codelines parameter is given, this option is ignored. Also, same-origin
        policies in browsers might prevent this from working across domains.</li>
      <li> <code>{lineNumbers: &lt;boolean>}</code> Determine whether linenumbers should be shown. Defaults to true.</li> 
      <li> <code>{visible: &lt;boolean>}</code> Determine whether the pseudocode is visible on creation. Defaults to true.</li>
      <li> <code>{before: &lt;UI element>}</code> Add the pseudocode before element <code>UI element</code></li>
      <li> <code>{after: &lt;UI element>}</code> Add the pseudocode after element <code>UI element</code></li>
      <li> <code>{center: &lt;boolean>}</code> Boolean to determine if array should be automatically centered
  within its container. Defaults to true.</li>
      <li> <code>{startAfter: &lt;string>}</code> Only the content after the last occurrence of the specified text will be included. Only
        applied if the <code>url</code> parameter is also provided.</li>
      <li> <code>{endBefore: &lt;string>}</code> Only the content before the first occurrence of the specified text will be included. Only
        applied if the <code>url</code> parameter is also provided.</li>
      <li>relativeTo: A JSAV data structure object or DOM element that this structure should be positioned relative to.
      If this option is specified, left and top options will change structure's position relative to the relativeTo
      element. Note, that the element pointed by relativeTo needs to be visible.</li>
      <li>anchor: Defines which position on the element being positioned to align with the target element. Should be in 
      format <code>horizontal vertical</code>. Possible horizontal values are "left", "center", "right" and vertical values "top", "center", "bottom". Defaults to <code>center center</code>. Only has an effect if relativeTo is
      specified.</li>
      <li>myAnchor: Similar to anchor, but the position on this element. Defaults to <code>center center</code>. Only 
      has an effect if relativeTo is specified.</li>
      <li>relativeIndex: If relativeTo points to a JSAV array, this option can be used to position this structure relative
      to an index in that array. Only has an effect if relativeTo is specified.</li>
    </ul>
    <p>Pseudocode objects have the following functions.</p>
    <h3 class="apimethod">.highlight(indices) and .unhighlight(indices)</h3>
    <p>Highlight and unhighlight the codelines at given indices. Lines are numbered from 0, so first line could be highlighted with:</p>
    <pre>pseudo.highlight(0)</pre>
    <p>Similarly to the array (un)highlight, the <var>indices</var> parameter can be either a number, an array of numbers, or a function.</p>
    <h3 class="apimethod">.show() and .hide()</h3>
    <p>Show/hide the pseudocode object.</p>
    <h3 class="apimethod">.show(indices) and .hide(indices)</h3>
    <p>Show/hide the codelines at given indices. Again, indices can be a number, an array of numbers, or a function.</p>
    <h3 class="apimethod">.css(indices, css)</h3>
    <p>Apply the given CSS properties to the codelines at specified <code>indices</code>.
      Parameter <code>indices</code> can be a number, array, or function like for 
      the <code>highlight</code> method.
      The argument <code>css</code> should be an object with property name-and-value pairs. For example, to make
      lines 0 and 4 have green color and lightgray background:</p>
    <pre>pseudo.css([0, 4], {"color": "green", "background-color": "#eee"});</pre>
    <h3 class="apimethod">.setCurrentLine(index)</h3>
    <p>Sets the line at given <var>index</var> as the current line. Also, if another line was previously set as current, it will be
      marked as previous. If a line was also earlier marked as previous, that mark will be removed. This will help in creating a 
      visual debugger-like code stepping functionality in visualizations.</p>
    <h3 class="apimethod">.addClass(indices, className, [options])</h3>
    <p>Adds the CSS class <code>className</code> to lines at given indices and animates the changes. Like for
      the rest of pseudocode methods, <code>indices</code> can be a number, array of numbers, or a function.</p>
    <h3 class="apimethod">.removeClass(indices, className, [options])</h3>
    <p>Removes the CSS class <code>className</code> from lines at given indices and animates the changes. Like for
      the rest of pseudocode methods, <code>indices</code> can be a number, array of numbers, or a function.</p>
    <h3 class="apimethod">.toggleClass(indices, className, [options])</h3>
    <p>Toggles the CSS class <code>className</code> of lines at  given indices and animates the changes. Like for
      the rest of pseudocode methods, <code>indices</code> can be a number, array of numbers, or a function.</p>
    <h3 class="apimethod">.hasClass(index, className, [options])</h3>
    <p>Return true/false based on if the line at given index has the CSS class <code>className</code>. Parameter
      <code>index</code> should be a number.</p>


    <h2>Graphical Primitives API</h2>
    <p>JSAV supports the following graphical primitives: circle, rectangle, line,
      ellipse, polygon, polyline, and path. All these are in the JSAV.g namespace. A 
      rectangle, for example, can be initialized like follows.</p>
    <pre>var rect = av.g.rect(70, 60, 50, 40);</pre>
    <p>This would initialize a rectangle with upper-left corner at point (70, 60) that
      is 50 pixels wide and 40 pixels tall.</p>
    <p>All the graphical primitives have the following functions.</p>
    <h3 class="apimethod">.show()</h3>
    <p>Make the shape visible. Essentially the same as calling <code>.css({opacity: 1})</code>.</p>
    <h3 class="apimethod">.hide()</h3>
    <p>Make the shape invisible. Essentially the same as calling <code>.css({opacity: 0})</code>.</p>
    <h3 class="apimethod">.rotate(deg)</h3>
    <p>Rotates the object by the given amount of degrees around the center of the shape.</p>
    <h3 class="apimethod">.scale(sx, sy), .scaleX(sx), .scaleY(sy)</h3>
    <p>Scales the object by given amount. The shortcuts for X/Y scaling only
      are the same as calling <code>.scale(sx, 0)</code> and <code>.scale(0, sy)</code>. For example</p>
    <pre>rect.scale(2, 1.5)</pre>
    <p>would make the rectangle from the previous example to have width of 100 pixels and height of 60px. Note, that the position of the rectangle would also change, since the scaling is done relative to the center of the shape.</p>
    <h3 class="apimethod">.translate(dx, dy), .translateX(dx), .translateY(dy)</h3>
    <p>Translates the shape by the given amount. Again, X/Y versions are shortcuts to
      the main translation function.</p>
    <h3 class="apimethod">.css(propname)</h3>
    <p>Returns the value of the attribute with the name <code>propname</code>.</p>
    <h3 class="apimethod">.css(propname, propvalue), .css(propsObj)</h3>
    <p>Like the .css functions of the other JSAV objects, these can be used to animate
      attributes of the shape. Technically, what is changed is not CSS properties but
      attributes of the SVG element visualizing the shape. For a list of valid values,
      see <a href="http://raphaeljs.com/reference.html#Element.attr">Rapha&euml;l JS documentation</a>.</p>
      
    <h2>Circle API</h2>
    <h3 class="apimethod">jsav.g.circle(cx, cy, r[, properties])</h3>
    <p>Initializes a new circle with the given center and radius. Optional parameter <code>properties</code>,if given,  
      should be an object with key-value pairs. See <a href="http://raphaeljs.com/reference.html#Element.attr">raphael.attr</a> for valid keys and values.</p>
    <h3 class="apimethod">.center([cx, cy])</h3>
    <p>Gets or sets the center of the circle. The center is returned as an object with
      properties <code>cx</code> and <code>cy</code>.</p>
    <h3 class="apimethod">.radius([r])</h3>
    <p>Gets or sets the radius of the circle.</p>
      
    <h2>Ellipse API</h2>
    <h3 class="apimethod">jsav.g.ellipse(cx, cy, rx, ry[, properties])</h3>
    <p>Initializes a new ellipse with the given center and x and y radius. Optional parameter 
      <code>properties</code>,if given, should be an object with key-value pairs. See 
      <a href="http://raphaeljs.com/reference.html#Element.attr">raphael.attr</a> for valid keys and values.</p>
    <h3 class="apimethod">.center([cx, cy])</h3>
    <p>Same as center function of the circle.</p>
    <h3 class="apimethod">.radius([rx, ry])</h3>
    <p>Gets or sets the radius of the ellipse. The radius is returned as an object with
      properties <code>rx</code> and <code>ry</code>.</p>

    <h2>Rectangle API</h2>
    <h3 class="apimethod">jsav.g.rect(x, y, w, h[, r, properties])</h3>
    <p>Initializes a new rectangle with upper left corner at <code>x, y</code> and given width and height.
      Optional parameter <code>r</code> can be used to specify the roundness of corners.
      Optional parameter <code>properties</code>,if given, should be an object with key-value pairs. See 
      <a href="http://raphaeljs.com/reference.html#Element.attr">raphael.attr</a> for valid keys and values.</p>
    <h3 class="apimethod">.width([w])</h3>
    <p>Gets or sets the width of the rectangle.</p>
    <h3 class="apimethod">.height()</h3>
    <p>Gets or sets the height of the rectangle.</p>

    <h2>Line, Polygon, and Polyline API</h2>
    <h3 class="apimethod">jsav.g.line(x1, y1, x2, y2[, properties])</h3>
    <p>Initializes a line from point <code>x1, y1</code> to <code>x2, y2</code>. Optional parameter 
      <code>properties</code>,if given, should be an object with key-value pairs. See 
      <a href="http://raphaeljs.com/reference.html#Element.attr">raphael.attr</a> for valid keys and values.</p>

    <h3 class="apimethod">jsav.g.polyline(points[, properties]) and jsav.polygon(points[, properties])</h3>
    <p>Initializes a polyline or polygon. Parameter <code>points</code> should be an array of arrays with
      x and y coordinates. For example:</p>
    <pre>var polyline = av.g.polyline([[0, 0], [20, 20], [200, 200]], 
                                      {"stroke-width": 7, "stroke":"#ddd"});</pre>
    <p>Optional parameter 
      <code>properties</code>,if given, should be an object with key-value pairs. See 
      <a href="http://raphaeljs.com/reference.html#Element.attr">raphael.attr</a> for valid keys and values.</p>

    <h3 class="apimethod">.translatePoint(point, dx, dy)</h3>
    <p>Translates the given <code>point</code> in the (poly)line by the given amount of pixels. The point is a zero-indexed list of points used to initialize the polyline. For line, start point is index 0 and endpoint index 1.</p>

    <h3 class="apimethod">.movePoints(points)</h3>
    <p>Moves the given points to the given pixel positions. Parameter <code>points</code> should be an array of arrays with each item specifying point, px, and py.</p>

    <h2>Path API</h2>
    <h3 class="apimethod">jsav.g.path(path[, properties])</h3>
    <p>Initializes a new path element with the given <code>path</code>. The path should be defined according
      to the <a href="http://www.w3.org/TR/SVG/paths.html#PathData">SVG path string format</a>.</p>
    <h3 class="apimethod">.path()</h3>
    <p>Returns the current <code>path</code> of the object.</p>
    <h3 class="apimethod">.path(newPath)</h3>
    <p>Animates the objects path to the <code>newPath</code>.</p>

    <h2>Graphical Primitive Set</h2>
    <p>Sometimes there is a need to combine multiple graphical primitives to make up more complex shapes that can be changed simultaneously. Function <code>av.g.set()</code> can be used to create a set of graphical primitives. It has all the functions common to all graphical primitive listed above. In addition, it has one function:</p>
    <h3 class="apimethod">.push(gp)</h3>
    <p>Adds the graphical primitive gp to the set.</p>
    
    <h2>Questions API</h2>
    <p>Interactive questions can be initialized with the <code>question</code>
      function of a JSAV instance.</p>
    <h3 class="apimethod">.question(qtype, questionText, [options])</h3>
    <p>This is a method of the AV object. It initializes an interactive question
      of the given type (<code>qtype</code>). The type can be:</p>
    <ul>
      <li><code>TF</code> for a true-false type question</li>
      <li><code>MC</code> for a multiple-choice question where only one answer can be selected</li>
      <li><code>MS</code> for a multiple-select question where multiple answers can be selected and be correct</li>
    </ul>
    <p>The <code>questionText</code> parameter is the actual question shown to a student. For the question type TF, <code>options</code> parameter can contain following options.</p>
    <ul>
      <li><code>{trueLabel: &lt;string>}</code> The label shown for true option. Only for type TF. Default value True.</li>
      <li><code>{falseLabel: &lt;string>}</code> The label shown for false option. Only for type TF. Default value False.</li>
      <li><code>{correct: &lt;boolean>}</code> The correct answer, true or false.</li>
    </ul>
    <p>An example of initializing a true-false question is below.</p>
    <pre>var q = av.question("TF", "JSAV supports questions now?", {correct: true, falseLabel: "No", trueLabel: "Yes"});</pre>
    
    <p>The function returns an instance of a question. Answer choices can be added
      to this instance using the following methods.</p>
 
    <h3 class="apimethod">q.addChoice(label, [options])</h3>
    <p>This adds an answer choice to question <code>q</code>. Parameter <code>label</code> is the label shown for this answer choice. The only option at the moment is <code>correct</code> which indicates the correctness of this choice. Default value for it is false. Note, that this method does nothing for the true-false type question.</p>

    <h3 class="apimethod">q.show()</h3>
    <p>This function will show the question in the current step in the algorithm. This way, the initialization, addition of answers, and displaying the question can happen in different steps in the animation. It helps when the goal is to show students questions that require prediction of the algorithm's behavior.</p>
    <p>A complete example of a multiple-select question:</p>
    <pre>var q = av.question("MS", "Life is good?");
q.addChoice("Of course", {correct: true});
q.addChoice("Certainly", {correct: true});
q.addChoice("No way!");
q.show();</pre>
    

<h2>Settings Dialog for AV</h2>
<p>There is a configurable settings dialog class in JSAV.utils.Settings.
  The settings objects can be instantiated with <code>new JSAV.utils.Settings(elem)</code>
  where the optional <code>elem</code> parameter specifies an element on which a
  click will open the dialog. </p>

<p>The settings used by an instance of JSAV can be specified with the <code>settings</code>
  option for the constructor. For example, <code>var av = 
  new JSAV(jQuery("#container"), {"settings": settings});</code>. If no custom settings
  are given, JSAV will automatically create a default settings panel and attach it to
  any element with class <code>jsavsettings</code> inside the container.
  No matter how the settings object is initialized,
  it can be accessed through the <code>av.settings</code>
  field.</p>

<p>A settings instance has the following functions.</p>

<h3 class="apimethod">settings.show()</h3>
<p>Shows the settings dialog.</p>

<h3 class="apimethod">settings.close()</h3>
<p>Closes the settings dialog.</p>

<h3 class="apimethod">settings.add(varname, options)</h3>
<p>Adds a component to the settings dialog. Parameter <code>varname</code> is the unique
  name of the variable for this setting which can be used later to get the value of the setting.
  Parameter <code>options</code> is an object used to specify the properties of the settings
  variable. The following options can be set:</p>
  
  <ul>
    <li>type: Type of the HTML element used for this setting. Choices are <code>select</code> and
      valid values for the text attribute of an HTML input element (such as text, email, range).</li>
    <li>label: The label displayed next to the form element of this setting.</li>
    <li>value: The initial value of the setting.</li>
    <li>options: Select options for the type select. This should be an object representing key-value pairs.
      For example, <code>"options": {"bar": "Bar layout", "array", "Array layout"}</code> would add
      two choices: Bar layout and Array layout.</li>
  </ul>
  <p>In addition to these options, when using an HTML input element (text, email) to represent the setting,
    any additional options will be set as attributes of the <code>input</code> element. For example:</p>
    <pre>settings.add("speed", {"type": "range", "value": "7", "min": 1, "max": 10, "step": 1});</pre>
  <p>Would create <code>&lt;input type="range" value="7" min="1" max="10" step="1" /></code>.</p>
    
  <p>The <code>add</code> function returns a reference to the setting. The function <code>val()</code> 
    returns the value of the setting.</p>
    

<h3 class="apimethod">settings.add(function)</h3>
<p>Adds a more customizable component to the settings dialog. The parameter should be a function
  that returns a DOM element or a jQuery object.</p>

<h2>Exercise API</h2>
<h3 class="apimethod">.exercise(modelSolution, reset, options)</h3>
<p>
  The exercise API is used to create interactive, automatically assessed exercises. An exercise is 
  initialized with a call to <code>av.exercise(..)</code>. The parameters for the function are:</p>
  <ul>
    <li><code>{modelSolution: &lt;function>}</code> The function to generate the model solution. The function has to return the data structures and/or variables used in grading of the exercise. The return value can be a single data structure or an array of structures.</li>
    <li><code>{reset: &lt;function>}</code> The initialization function that resets the exercise. The function has to return the data structures and/or variables used in grading of the exercise. The return value can be a single data structure or an array of structures.</li>
    </ul>
  
  <p>The function can also take several options, some of which are required. The full set of options are:</p> 
  <ul>
    <li><code>{compare: &lt;Object or Array>}</code> Specifies which properties to compare for the structures. In the example below, we set the comparison to be CSS property background-color so grading would check if the structures have same background color (that is, if they are highlighted). <strong>Required.</strong></li>
    <li><code>{feedback: &lt;string>}</code> Will change the feedback mode, possible values continuous and atend (default). See Continuous feedback below.</li>
    <li><code>{fixmode: &lt;string>}</code> Change the behavior in continuous mode, possible values are undo and fix. The default is undo.</li>
    <li><code>{feedbackSelectable: &lt;>boolean}</code> The settings dialog will not, by default, allow student to change the feedback mode. Setting this option to true enables this choice.</li>
    <li><code>{fixmodeSelectable: &lt;>boolean}</code> The settings dialog will not, by default, allow student to change the behavior in continuous feedback mode. Setting this option to true enables this choice.</li>
    <li><code>{fix: &lt;function}</code> A function that will fix the student's solution to match the current step in model solution. Before this function is called, the previous incorrect step in student's solution is undone. The function gets the model structures as a parameter. For an example, see the examples/ShellsortProficiency.html.</li>
    <li><code>{showGrade}: &lt;function>}</code> A function that can be used to customize the way the grade is shown. The function will be added to the exercise and can be called with <code>exercise.showGrade</code>. The function can access the grade information from attribute <code>this.score</code>. Example content of that attribute: <code>{total: 15, correct: 3, undo: 0, fix: 0, student: 5}</code>. Total is the total number of steps in the model solution, student the number of steps in student solution, and correct the number of correct steps. Values undo and fix show how many steps were undone/fixed in the continuous feedback mode. Note, that to make sure the grading is up to date, this function should call the <code>grade</code> function of the exercise before showing the grade.</li>
    <li><code>{modelDialog}: &lt;object>}</code> An object that can specify options for the model answer dialog. For
      the possible options, see the documentation for the JSAV.utils.dialog.</li>
  </ul>
  <p>For example, assuming <code>modelSolution</code> and <code>reset</code> are functions, the following would initialize an exercise:</p>
  <pre>
  var exercise = av.exercise(modelSolution, reset, { compare: {css: "background-color"}});
  exercise.reset();
  </pre>
  <p>See also the <a href="exercise.html">tutorial on creating an exercise</a>.</p>
  <h3 class="apimethod">exercise.showGrade()</h3>
  <p>Shows the grade of the student's current solution. The behaviour can be customized using the <code>showGrade</code> option when initializing the exercise.</p>
  
  <h3 class="apimethod">exercise.reset()</h3>
  <p>Resets the exercise.</p>
  <h3 class="apimethod">exercise.showModelAnswer()</h3>
  <p>Shows the model answer of the exercise.</p>
  <h3 class="apimethod">exercise.gradeableStep()</h3>
  <p>Marks the current step in the student's solution as a step used in grading.</p>

  <h3>Showing the Current Score and Maximum Score in Continuous Feedback Mode</h3>
  <p>If the exercise is in the continuous feedback mode, it is possible to have JSAV show
    the current score, current maximum score, and the total maximum score to student.
    This can be done by adding HTML elements <em>inside</em> the JSAV container elements.
    JSAV will search for elements with the following class attributes:</p>
  <ul>
    <li><code>jsavcurrentscore</code>: Inside this element, JSAv will update the current 
      score achieved by the student.</li>
    <li><code>jsavcurrentmaxscore</code>: The contents of this element will be updated to
      contain the maximum score thus far in the exercise.</li>
    <li><code>jsavmaxscore</code>: The maximum score available in this exercise.</li>
  </ul>
  <p>So you could use the following HTML:</p>
  <pre>&lt;p>
    Your current score is &lt;span class="jsavcurrentscore">&lt;/span> of 
    &lt;span class="jsavcurrentmaxscore">&lt;/span>. Maximum score in this exercise is
    &lt;span class="jsavmaxscore">&lt;/span>.
&lt;/p></pre>
  <p>As a shorter convenience notation, you can use <code>&lt;p class="jsavscore">&lt;p/></code>
    that will be replaced automatically by JSAV with the HTML above if the exercise is
    in continuous feedback mode. Note, that in both cases, the elements can be anything, the
    important thing is that they have the <code>class</code> attributes.</p>

<h2>Utility Functions</h2>
<p>The module <code>JSAV.utils</code> includes some utility functions
  for working with HTML pages and visualizations.</p>
<h3 class="apimethod">JSAV.utils.getQueryParameter()</h3>
<p>Returns an object containing all query parameters given for the HTML
  page. If no parameters exist, returns an empty object.</p>
  
<h3 class="apimethod">JSAV.utils.getQueryParameter(name)</h3>
<p>Returns the value of the query parameter <code>name</code>. If no such
  parameter exists, return <code>undefined</code></p>

<h3 class="apimethod">JSAV.utils.rand.numKey(min, max)</h3>
<p>Returns a random integer number between <code>min</code> (inclusive) and
  <code>max</code> (exclusive).</p>

<h3 class="apimethod">JSAV.utils.rand.numKeys(min, max, num, opts)</h3>
<p>Returns an array of <code>num</code> random integer numbers between 
  <code>min</code> (inclusive) and <code>max</code> (exclusive). Optional
  parameter <code>opts</code> is an object that can specify options:</p>
  <ul>
    <li><code>sorted</code> If set to true, the array will be sorted.</li>
    <li><code>sortfunc</code> If sorted is set to true, this option can
      be used to specify a function for sorting.</li>
  </ul>  

<h3 class="apimethod">JSAV.utils.rand.sample(arrayCollection, num)</h3>
<p>Returns an array of <code>num</code> elements randomly picked from the
  given array <code>arrayCollection</code>.</p>

<h3 class="apimethod">JSAV.utils.dialog(html, options)</h3>
<p>Shows a pop-up dialog with the given HTML as content. Returns an object
  with function <code>close()</code> that can be used to close the dialog.
  Options can include:</p>
<ul>
  <li>modal: whether the dialog is modal (default true)</li>
  <li>width (and min/maxWidth): control the width of the dialog</li>
  <li>height (and min/maxHeight): control the height of the dialog</li>
  <li>closeText: if specified, a button with this text to close the dialog
    will be added</li>
  <li>dialogClass: custom CSS classes to be added to the created component.
    Class <code>jsavdialog</code> is always added.</li>
  <li>title: title of the dialog</li>
</ul>

<h2>Animation Effects</h2>
<p>The module <code>.effects</code> offers some useful animation effects for
  AV developers.</p>
<h3 class="apimethod">.moveValue(...)</h3>
<p>Method <code>.moveValue</code> animates <em>moving</em> of a value from one structure
  to another. Structure can be an array or a tree/list node. The following parameter
  combinations are valid:</p>
<ul>
  <li><code>.moveValue(fromArray, fromIndex, toArray, toIndex)</code> Moves
    value at <code>fromIndex</code> in <code>fromArray</code> to <code>toIndex</code>
    in <code>toArray</code>. The value in <code>fromIndex</code> will be an empty
    string after this operation.</li>
  <li><code>.moveValue(fromArray, fromIndex, toNode)</code> Moves
    value at <code>fromIndex</code> in <code>fromArray</code> to <code>toNode</code>. 
    The value in <code>fromIndex</code> will be an empty
    string after this operation.</li>
  <li><code>.moveValue(fromNode, toArray, toIndex)</code> Moves
    value in <code>fromNode</code> to <code>toIndex</code>
    in <code>toArray</code>. The value in <code>fromNode</code> will be an empty
    string after this operation.</li>
  <li><code>.moveValue(fromNode, toNode)</code> Moves value in <code>fromNode</code>
    to <code>toNode</code>. The value in <code>fromNode</code> will be an empty
    string after this operation.</li>
</ul>
<p>In addition, <code>fromNode</code> and <code>toNode</code> can be an instance of
  <code>jsav.variable</code>.</p>
<p><strong>Note:</strong> both from and to structures can be the same structure.</p>

<h3 class="apimethod">.copyValue(...)</h3>
<p>Method that animates <em>copying</em> a value from one structure to another. The same
  parameter combinations are valid as for the <code>.moveValue</code> method. The only
  difference is that the source value is not removed.</p>

<h3 class="apimethod">.swapValues(...)</h3>
<p>Method that animates <em>swapping</em> a value from one structure with another. The same
  parameter combinations are valid as for the <code>.moveValue</code> method.</p>

<h2>Best Practice for Modularity</h2>

<p>
When you create a visualization, you might want to make it easy for
other people to reuse via embedding within their own pages.
Some simple steps will make this easier for them
when using a simple <code>iframe</code> tag.
The library is set up to make it natural for your visualization to
reside within the <code>container</code> element.
There is no margin or padding around the <code>container</code>, and
it has a one-pixel-wide black border.
So long as you stay within this, an <code>iframe</code> can include
your whole visualization without any disruption to the user's page.
If you would like to support mobiles, you will probably want to restrict
the full size of your <code>container</code> to at most 800 by 435 pixels.
A visualization can then be embedded with a call such as:
</p>

<pre>
&lt;iframe src="http://algoviz.org/OpenDSA/trunk/AV/shellsort.html"
   width="824" height="459" frameborder="0" marginwidth="0"
   marginheight="0" scrolling="no">
&lt;/iframe>
</pre>


  <script
     src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js">
  </script>
  <script>
  $(function() {
    // dynamically 
    var toc = $("#toc");
    $("h2").each(function(index, item) {
      $(item).html("<a name='sect" + index + "'>" + $(item).text() + "</a>");
      toc.append($("<li><a href='#sect" + index + "'>" + $(item).text() + "</a></li>"));
    });
  });
  </script>
</body>
</html>