Implemented functions `on` and `off` to create event listeners for event `select`.

HISTORY.md

@@ -7,11 +7,10 @@ http://visjs.org
 ### Timeline
 
 - Implemented functions `on` and `off` to create event listeners for events
-  `rangechange` and `rangechanged`.
+  `rangechange`, `rangechanged`, and `select`.
 - Impelmented function `select` to get and set the selected items.
 - Items can be selected by clicking them, muti-select by holding them.
 
-
 ### Graph
 
 - Fixed longstanding bug in the force calculation, increasing simulation
@@ -25,8 +24,10 @@ http://visjs.org
 - Added local declustering to Graph, freezing the simulation of nodes outside
   of the cluster.
 - Added support for key-bindings by including mouseTrap in Graph.
-- Added node-based navigation GUI.
-- Added keyboard navigation option.
+- Added navigation controls.
+- Added keyboard navigation.
+- Implemented functions `on` and `off` to create event listeners for event
+  `select`.
 
 
 ## 2014-01-14, version 0.3.0

docs/graph.html

@@ -1384,6 +1384,33 @@ var options: {
     <th>Description</th>
   </tr>
 
+  <tr>
+    <td>getSelection()</td>
+    <td>Array of ids</td>
+    <td>Returns an array with the ids of the selected nodes.
+      Returns an empty array if no nodes are selected.
+      The selections are not ordered.
+    </td>
+  </tr>
+
+  <tr>
+    <td>on(event, callback)</td>
+    <td>none</td>
+    <td>Create an event listener. The callback function is invoked every time the event is triggered. Avialable events: <code>select</code>. The callback function is invoked as <code>callback(properties)</code>, where <code>properties</code> is an object containing event specific properties. See section <a href="#Events">Events</a> for more information.</td>
+  </tr>
+
+  <tr>
+    <td>off(event, callback)</td>
+    <td>none</td>
+    <td>Remove an event listener created before via function <code>on(event, callback)</code>. See section <a href="#Events">Events</a> for more information.</td>
+  </tr>
+
+  <tr>
+    <td>redraw()</td>
+    <td>none</td>
+    <td>Redraw the graph. Useful when the layout of the webpage changed.</td>
+  </tr>
+
   <tr>
     <td>setData(data,[disableStart])</td>
     <td>none</td>
@@ -1403,21 +1430,6 @@ var options: {
     </td>
   </tr>
 
-  <tr>
-    <td>getSelection()</td>
-    <td>Array of ids</td>
-    <td>Returns an array with the ids of the selected nodes.
-      Returns an empty array if no nodes are selected.
-      The selections are not ordered.
-    </td>
-  </tr>
-
-  <tr>
-    <td>redraw()</td>
-    <td>none</td>
-    <td>Redraw the graph. Useful when the layout of the webpage changed.</td>
-  </tr>
-
   <tr>
     <td>setSelection(selection)</td>
     <td>none</td>
@@ -1441,7 +1453,7 @@ var options: {
 
 <h2 id="Events">Events</h2>
 <p>
-  Graph fires events after one or multiple nodes are selected.
+  Graph fires events after one or multiple nodes are selected or deselected.
   The event can be catched by creating a listener.
 </p>
 
@@ -1450,13 +1462,30 @@ var options: {
 </p>
 
 <pre class="prettyprint lang-js">
-function onSelect() {
-  alert('selected nodes: ' + graph.getSelection());
+graph.on('select', function (properties) {
+  alert('selected nodes: ' + properties.nodes);
+});
+</pre>
+
+<p>
+  A listener can be removed via the function <code>off</code>:
+</p>
+
+<pre class="prettyprint lang-js">
+function onSelect (properties) {
+  alert('selected nodes: ' + properties.nodes);
 }
 
-vis.events.addListener(graph, 'select', onSelect);
+// add event listener
+graph.on('select', onSelect);
+
+// do stuff...
+
+// remove event listener
+graph.off('select', onSelect);
 </pre>
 
+
 <p>
   The following events are available.
 </p>
@@ -1470,13 +1499,14 @@ vis.events.addListener(graph, 'select', onSelect);
 
   <tr>
     <td>select</td>
-    <td>Fired after the user selects or unselects a node by clicking it,
-      or when selecting a number of nodes by dragging a selection area
-      around them. Not fired when the method <code>setSelection</code>
-      is executed. The ids of the selected nodes can be retrieved via the
-      method <code>getSelection</code>.
+    <td>Fired after the user selects or deselects a node by clicking it.
+      Not fired when the method <code>setSelection</code>is executed.
+    </td>
+    <td>
+      <ul>
+        <li><code>nodes</code>: an array with the ids of the selected nodes</li>
+      </ul>
     </td>
-    <td>none</td>
   </tr>
 </table>
 

docs/timeline.html

@@ -38,6 +38,7 @@
   </li>
   <li><a href="#Configuration_Options">Configuration Options</a></li>
   <li><a href="#Methods">Methods</a></li>
+  <li><a href="#Events">Events</a></li>
   <li><a href="#Styles">Styles</a></li>
   <li><a href="#Data_Policy">Data Policy</a></li>
 </ul>
@@ -561,13 +562,13 @@ var options = {
   <tr>
     <td>on(event, callback)</td>
     <td>none</td>
-    <td>Create an event listener. The callback function is invoked every time the event is triggered. Avialable events: <code>rangechange</code>, <code>rangechanged</code>, <code>select</code>. The callback function is invoked as <code>callback(properties)</code>, where <code>properties</code> is an object containing event specific properties.</td>
+    <td>Create an event listener. The callback function is invoked every time the event is triggered. Avialable events: <code>rangechange</code>, <code>rangechanged</code>, <code>select</code>. The callback function is invoked as <code>callback(properties)</code>, where <code>properties</code> is an object containing event specific properties. See section <a href="#Events">Events for more information</a>.</td>
   </tr>
 
   <tr>
     <td>off(event, callback)</td>
     <td>none</td>
-    <td>Remove an event listener created before via function <code>on(event, callback)</code>.</td>
+    <td>Remove an event listener created before via function <code>on(event, callback)</code>. See section <a href="#Events">Events for more information</a>.</td>
   </tr>
 
   <tr>
@@ -607,8 +608,95 @@ var options = {
 </table>
 
 
-<!-- TODO: write a section on Events -->
+<h2 id="Events">Events</h2>
+<p>
+  Timeline fires events when changing the visible window by dragging, or when
+  selecting items.
+</p>
+
+<p>
+  Here an example on how to listen for a <code>select</code> event.
+</p>
+
+<pre class="prettyprint lang-js">
+timeline.on('select', function (properties) {
+  alert('selected items: ' + properties.nodes);
+});
+</pre>
+
+<p>
+  A listener can be removed via the function <code>off</code>:
+</p>
 
+<pre class="prettyprint lang-js">
+function onSelect (properties) {
+  alert('selected items: ' + properties.nodes);
+}
+
+// add event listener
+timeline.on('select', onSelect);
+
+// do stuff...
+
+// remove event listener
+timeline.off('select', onSelect);
+</pre>
+
+
+<p>
+  The following events are available.
+</p>
+
+<table>
+  <colgroup>
+    <col style="width: 20%;">
+    <col style="width: 40%;">
+    <col style="width: 40%;">
+  </colgroup>
+
+  <tr>
+    <th>name</th>
+    <th>Description</th>
+    <th>Properties</th>
+  </tr>
+
+  <tr>
+    <td>rangechange</td>
+    <td>Fired repeatedly when the user is dragging the timeline window.
+    </td>
+    <td>
+      <ul>
+        <li><code>start</code> (Number): timestamp of the current start of the window.</li>
+        <li><code>end</code> (Number): timestamp of the current end of the window.</li>
+      </ul>
+    </td>
+  </tr>
+
+  <tr>
+    <td>rangechanged</td>
+    <td>Fired once after the user has dragging the timeline window.
+    </td>
+    <td>
+      <ul>
+        <li><code>start</code> (Number): timestamp of the current start of the window.</li>
+        <li><code>end</code> (Number): timestamp of the current end of the window.</li>
+      </ul>
+    </td>
+  </tr>
+
+  <tr>
+    <td>select</td>
+    <td>Fired after the user selects or deselects items by tapping or holding them.
+      Not fired when the method <code>setSelection</code>is executed.
+    </td>
+    <td>
+      <ul>
+        <li><code>items</code>: an array with the ids of the selected items</li>
+      </ul>
+    </td>
+  </tr>
+
+</table>
 
 
 <h2 id="Styles">Styles</h2>

examples/graph/02_random_nodes.html

@@ -94,9 +94,8 @@
       graph = new vis.Graph(container, data, options);
 
       // add event listeners
-      vis.events.addListener(graph, 'select', function(params) {
-        document.getElementById('selection').innerHTML =
-            'Selection: ' + graph.getSelection();
+      graph.on('select', function(params) {
+        document.getElementById('selection').innerHTML = 'Selection: ' + params.nodes;
       });
     }
   </script>

examples/graph/07_selections.html

@@ -51,11 +51,9 @@
   graph = new vis.Graph(container, data, options);
 
   // add event listener
-  function onSelect() {
-    document.getElementById('info').innerHTML +=
-        'selection: ' + graph.getSelection().join(', ') + '<br>';
-  }
-  vis.events.addListener(graph, 'select', onSelect);
+  graph.on('select', function(params) {
+    document.getElementById('info').innerHTML += 'selection: ' + params.nodes + '<br>';
+  });
 
   // set initial selection (id's of some nodes)
   graph.setSelection([3, 4, 5]);

examples/graph/18_fully_random_nodes_clustering.html

@@ -62,10 +62,10 @@
                 stabilize: false
             };
             graph = new vis.Graph(container, data, options);
+
             // add event listeners
-            vis.events.addListener(graph, 'select', function(params) {
-                document.getElementById('selection').innerHTML =
-                        'Selection: ' + graph.getSelection();
+            graph.on('select', function(params) {
+                document.getElementById('selection').innerHTML = 'Selection: ' + params.nodes;
             });
         }
     </script>

examples/graph/19_scale_free_graph_clustering.html

@@ -100,9 +100,8 @@
       graph = new vis.Graph(container, data, options);
 
       // add event listeners
-      vis.events.addListener(graph, 'select', function(params) {
-        document.getElementById('selection').innerHTML =
-            'Selection: ' + graph.getSelection();
+      graph.on('select', function(params) {
+        document.getElementById('selection').innerHTML = 'Selection: ' + params.nodes;
       });
     }
   </script>

examples/graph/20_navigation.html

@@ -116,9 +116,8 @@
       graph = new vis.Graph(container, data, options);
 
       // add event listeners
-      vis.events.addListener(graph, 'select', function(params) {
-        document.getElementById('selection').innerHTML =
-            'Selection: ' + graph.getSelection();
+      graph.on('select', function(params) {
+        document.getElementById('selection').innerHTML = 'Selection: ' + params.nodes;
       });
     }
   </script>

examples/timeline/01_basic.html

@@ -7,8 +7,6 @@
     body, html {
       font-family: sans-serif;
     }
-
-
   </style>
 
   <script src="../../dist/vis.js"></script>

src/graph/Graph.js

@@ -491,6 +491,33 @@ Graph.prototype.setOptions = function (options) {
   this._redraw();
 };
 
+/**
+ * Add event listener
+ * @param {String} event       Event name. Available events:
+ *                             'select'
+ * @param {function} callback  Callback function, invoked as callback(properties)
+ *                             where properties is an optional object containing
+ *                             event specific properties.
+ */
+Graph.prototype.on = function on (event, callback) {
+  var available = ['select'];
+
+  if (available.indexOf(event) == -1) {
+    throw new Error('Unknown event "' + event + '". Choose from ' + available.join());
+  }
+
+  events.addListener(this, event, callback);
+};
+
+/**
+ * Remove an event listener
+ * @param {String} event       Event name
+ * @param {function} callback  Callback function
+ */
+Graph.prototype.off = function off (event, callback) {
+  events.removeListener(this, event, callback);
+};
+
 /**
  * fire an event
  * @param {String} event   The name of an event, for example 'select'

src/graph/SelectionMixin.js

@@ -183,7 +183,9 @@ var SelectionMixin = {
     this.selectionObj = {};
 
     if (doNotTrigger == false) {
-      this._trigger('select');
+      this._trigger('select', {
+        nodes: this.getSelection()
+      });
     }
   },
 
@@ -232,7 +234,9 @@ var SelectionMixin = {
       this._removeFromSelection(node);
     }
     if (doNotTrigger == false) {
-      this._trigger('select');
+      this._trigger('select', {
+        nodes: this.getSelection()
+      });
     }
   },
 
@@ -439,7 +443,9 @@ var SelectionMixin = {
 
     if (changed && (triggerSelect == true || triggerSelect == undefined)) {
       // fire the select event
-      this._trigger('select');
+      this._trigger('select', {
+        nodes: this.getSelection()
+      });
     }
 
     return changed;
@@ -495,7 +501,9 @@ var SelectionMixin = {
 
     if (changed) {
       // fire the select event
-      this._trigger('select');
+      this._trigger('select', {
+        nodes: this.getSelection()
+      });
     }
 
     return changed;

src/util.js

@@ -671,30 +671,3 @@ util.option.asElement = function (value, defaultValue) {
 
   return value || defaultValue || null;
 };
-
-
-/**
- * Compare two numbers and return the lowest, non-negative number.
- *
- * @param {number} number1
- * @param {number} number2
- * @returns {number}        | number1 or number2, the lowest positive number. If both negative, return -1
- */
-util.getLowestPositiveNumber = function(number1,number2) {
-  if (number1 >= 0) {
-    if (number2 >= 0) {
-      return (number1 < number2) ? number1 : number2;
-    }
-    else {
-      return number1;
-    }
-  }
-  else {
-    if (number2 >= 0) {
-      return number2;
-    }
-    else {
-      return -1;
-    }
-  }
-}