Splitted function `select` into `getSelection` and `setSelection`

docs/timeline.html

@@ -552,6 +552,12 @@ var options = {
     </td>
   </tr>
 
+  <tr>
+    <td>getSelection()</td>
+    <td>ids</td>
+    <td>Get an array with the ids of the currently selected items.</td>
+  </tr>
+
   <tr>
     <td>on(event, callback)</td>
     <td>none</td>
@@ -564,13 +570,6 @@ var options = {
     <td>Remove an event listener created before via function <code>on(event, callback)</code>.</td>
   </tr>
 
-  <tr>
-    <td>select([ids])</td>
-    <td>ids</td>
-    <td>Select or deselect items, or get current selection. Returns an array with the ids of the currently selected items.
-    </td>
-  </tr>
-
   <tr>
     <td>setGroups(groups)</td>
     <td>none</td>
@@ -598,6 +597,13 @@ var options = {
     </td>
   </tr>
 
+  <tr>
+    <td>setSelection([ids])</td>
+    <td>none</td>
+    <td>Select or deselect items. Currently selected items will be unselected.
+    </td>
+  </tr>
+
 </table>
 
 

examples/timeline/06_event_listeners.html

@@ -20,7 +20,7 @@
   <script type="text/javascript">
     var container = document.getElementById('visualization');
     var items = [
-      {ida: 1, content: 'item 1', start: '2013-04-20'},
+      {id: 1, content: 'item 1', start: '2013-04-20'},
       {id: 2, content: 'item 2', start: '2013-04-14'},
       {id: 3, content: 'item 3', start: '2013-04-18'},
       {id: 4, content: 'item 4', start: '2013-04-16', end: '2013-04-19'},

src/timeline/Timeline.js

@@ -350,13 +350,22 @@ Timeline.prototype.getItemRange = function getItemRange() {
 };
 
 /**
- * Select or deselect items, or get current selection.
- * Returns the currently selected items
- * @param {Array} [ids] An array with zero or more ids of the items to be selected.
+ * Set selected items by their id. Replaces the current selection
+ * Unknown id's are silently ignored.
+ * @param {Array} [ids] An array with zero or more id's of the items to be
+ *                      selected. If ids is an empty array, all items will be
+ *                      unselected.
+ */
+Timeline.prototype.setSelection = function setSelection (ids) {
+  if (this.content) this.content.setSelection(ids);
+};
+
+/**
+ * Get the selected items by their id
  * @return {Array} ids  The ids of the selected items
  */
-Timeline.prototype.select = function select(ids) {
-  return this.content ? this.content.select(ids) : [];
+Timeline.prototype.getSelection = function getSelection() {
+  return this.content ? this.content.getSelection() : [];
 };
 
 /**
@@ -406,9 +415,10 @@ Timeline.prototype._onSelectItem = function (event) {
   var item = this._itemFromTarget(event);
 
   var selection = item ? [item.id] : [];
-  selection = this.select(selection);
+  this.setSelection(selection);
+
   this._trigger('select', {
-    items: selection
+    items: this.getSelection()
   });
 
   event.stopPropagation();
@@ -427,7 +437,8 @@ Timeline.prototype._onMultiSelectItem = function (event) {
     // do nothing...
     return;
   }
-  selection = this.select(); // current selection
+
+  selection = this.getSelection(); // current selection
   var index = selection.indexOf(item.id);
   if (index == -1) {
     // item is not yet selected -> select it
@@ -437,10 +448,10 @@ Timeline.prototype._onMultiSelectItem = function (event) {
     // item is already selected -> deselect it
     selection.splice(index, 1);
   }
+  this.setSelection(selection);
 
-  selection = this.select(selection);
   this._trigger('select', {
-    items: selection
+    items: this.getSelection()
   });
 
   event.stopPropagation();

src/timeline/component/Group.js

@@ -76,12 +76,22 @@ Group.prototype.setItems = function setItems(items) {
 };
 
 /**
- * Change the item selection, and/or get currently selected items
- * @param {Array} [ids] An array with zero or more ids of the items to be selected.
+ * Set selected items by their id. Replaces the current selection.
+ * Unknown id's are silently ignored.
+ * @param {Array} [ids] An array with zero or more id's of the items to be
+ *                      selected. If ids is an empty array, all items will be
+ *                      unselected.
+ */
+Group.prototype.setSelection = function setSelection(ids) {
+  if (this.itemset) this.itemset.setSelection(ids);
+};
+
+/**
+ * Get the selected items by their id
  * @return {Array} ids  The ids of the selected items
  */
-Group.prototype.select = function select(ids) {
-  return this.itemset ? this.itemset.select(ids) : [];
+Group.prototype.getSelection = function getSelection() {
+  return this.itemset ? this.itemset.getSelection() : [];
 };
 
 /**

src/timeline/component/GroupSet.js

@@ -150,11 +150,32 @@ GroupSet.prototype.getGroups = function getGroups() {
 };
 
 /**
- * Change the item selection, and/or get currently selected items
- * @param {Array} [ids] An array with zero or more ids of the items to be selected.
+ * Set selected items by their id. Replaces the current selection.
+ * Unknown id's are silently ignored.
+ * @param {Array} [ids] An array with zero or more id's of the items to be
+ *                      selected. If ids is an empty array, all items will be
+ *                      unselected.
+ */
+GroupSet.prototype.setSelection = function setSelection(ids) {
+  var selection = [],
+      groups = this.groups;
+
+  // iterate over each of the groups
+  for (var id in groups) {
+    if (groups.hasOwnProperty(id)) {
+      var group = groups[id];
+      group.setSelection(ids);
+    }
+  }
+
+  return selection;
+};
+
+/**
+ * Get the selected items by their id
  * @return {Array} ids  The ids of the selected items
  */
-GroupSet.prototype.select = function select(ids) {
+GroupSet.prototype.getSelection = function getSelection() {
   var selection = [],
       groups = this.groups;
 
@@ -162,7 +183,7 @@ GroupSet.prototype.select = function select(ids) {
   for (var id in groups) {
     if (groups.hasOwnProperty(id)) {
       var group = groups[id];
-      selection = selection.concat(group.select(ids));
+      selection = selection.concat(group.getSelection());
     }
   }
 

src/timeline/component/ItemSet.js

@@ -112,11 +112,13 @@ ItemSet.prototype.setRange = function setRange(range) {
 };
 
 /**
- * Change the item selection, and/or get currently selected items
- * @param {Array} [ids] An array with zero or more ids of the items to be selected.
- * @return {Array} ids  The ids of the selected items
+ * Set selected items by their id. Replaces the current selection
+ * Unknown id's are silently ignored.
+ * @param {Array} [ids] An array with zero or more id's of the items to be
+ *                      selected. If ids is an empty array, all items will be
+ *                      unselected.
  */
-ItemSet.prototype.select = function select(ids) {
+ItemSet.prototype.setSelection = function setSelection(ids) {
   var i, ii, id, item, selection;
 
   if (ids) {
@@ -152,11 +154,14 @@ ItemSet.prototype.select = function select(ids) {
       this.requestRepaint();
     }
   }
-  else {
-    selection = this.selection.concat([]);
-  }
+};
 
-  return selection;
+/**
+ * Get the selected items by their id
+ * @return {Array} ids  The ids of the selected items
+ */
+ItemSet.prototype.getSelection = function getSelection() {
+  return this.selection.concat([]);
 };
 
 /**