From c25548031bc37d6b5c5249ab1e69183ab359bb69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrg=20Lehni?= Date: Mon, 20 Oct 2014 22:44:15 +0200 Subject: [PATCH] Clean up documentation for Project#getItems() / Item#getItems(). --- src/item/Item.js | 28 ++++-- src/project/Project.js | 208 ++--------------------------------------- 2 files changed, 28 insertions(+), 208 deletions(-) diff --git a/src/item/Item.js b/src/item/Item.js index e0d5395d..a433ee0b 100644 --- a/src/item/Item.js +++ b/src/item/Item.js @@ -1812,11 +1812,13 @@ var Item = Base.extend(Emitter, /** @lends Item# */{ * Checks whether the item matches the criteria described by the given * object, by iterating over all of its properties and matching against * their values through {@link #matches(name, compare)}. + * See {@link Project#getItems(match)} for a selection of illustrated + * examples. * - * @name #matches + * @name Item#matches * @function * - * @see Project#getItems(match) + * @see #getItems(match) * @param {Object} match the criteria to match against. * @return {@true if the item matches all the criteria} */ @@ -1827,11 +1829,13 @@ var Item = Base.extend(Emitter, /** @lends Item# */{ * partial matching (e.g. only providing the x-coordinate to match all * points with that x-value). Partial matching does work for * {@link Item#data}. + * See {@link Project#getItems(match)} for a selection of illustrated + * examples. * - * @name #matches + * @name Item#matches * @function * - * @see Project#getItems(match) + * @see #getItems(match) * @param {String} name the name of the state to match against. * @param {Object} compare the value, function or regular expression to * compare against. @@ -1899,10 +1903,12 @@ var Item = Base.extend(Emitter, /** @lends Item# */{ * of the full object, not partial matching (e.g. only providing the x- * coordinate to match all points with that x-value). Partial matching * does work for {@link Item#data}. + * See {@link Project#getItems(match)} for a selection of illustrated + * examples. * - * @see Project#getItems(match) - * @param {Object} match The criteria to match against. - * @return {Item[]} + * @see #matches(match) + * @param {Object} match the criteria to match against. + * @return {Item[]} the list of matching descendant items. */ getItems: function(match) { return Item._getItems(this._children, match); @@ -1916,10 +1922,12 @@ var Item = Base.extend(Emitter, /** @lends Item# */{ * of the full object, not partial matching (e.g. only providing the x- * coordinate to match all points with that x-value). Partial matching * does work for {@link Item#data}. + * See {@link Project#getItems(match)} for a selection of illustrated + * examples. * - * @see Project#getItem(match) - * @param {Object} match The criteria to match against. - * @return {Item} + * @see #getItems(match) + * @param {Object} match the criteria to match against. + * @return {Item} the first descendant item matching the given criteria. */ getItem: function(match) { return Item._getItems(this._children, match, true)[0] || null; diff --git a/src/project/Project.js b/src/project/Project.js index 4c1beafb..072836cf 100644 --- a/src/project/Project.js +++ b/src/project/Project.js @@ -339,6 +339,8 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{ }, /** + * {@grouptitle Fetching and matching items} + * * Fetch items contained within the project whose properties match the * criteria in the specified object. * Extended matching is possible by providing a compare function or @@ -550,8 +552,10 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{ * items[i].fillColor = 'red'; * } * - * @param {Object} match The criteria to match against. - * @return {Item[]} + * @see Item#matches(match) + * @see Item#getItems(match) + * @param {Object} match the criteria to match against. + * @return {Item[]} the list of matching items contained in the project. */ getItems: function(match) { return Item._getItems(this.layers, match); @@ -565,205 +569,13 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{ * of the full object, not partial matching (e.g. only providing the x- * coordinate to match all points with that x-value). Partial matching * does work for {@link Item#data}. + * See {@link #getItems(match)} for a selection of illustrated examples. * - * @example {@paperscript} // Fetch all selected path items: - * var path1 = new Path.Circle({ - * center: [50, 50], - * radius: 25, - * fillColor: 'black' - * }); - * - * var path2 = new Path.Circle({ - * center: [150, 50], - * radius: 25, - * fillColor: 'black' - * }); - * - * // Select path2: - * path2.selected = true; - * - * // Fetch first select path items: - * var item = project.getItem({ - * selected: true, - * class: Path - * }); - * - * // Change the fill color of the selected path to red: - * item.fillColor = 'red'; - * - * @example {@paperscript} // Fetch item with a specific fill color: - * var path1 = new Path.Circle({ - * center: [50, 50], - * radius: 25, - * fillColor: 'black' - * }); - * - * var path2 = new Path.Circle({ - * center: [150, 50], - * radius: 25, - * fillColor: 'purple' - * }); - * - * // Fetch first item with a purple fill color: - * var item = project.getItem({ - * fillColor: 'purple' - * }); - * - * // Select the fetched item: - * item.selected = true; - * - * @example {@paperscript} // Fetch item at a specific position: - * var path1 = new Path.Circle({ - * center: [50, 50], - * radius: 25, - * fillColor: 'black' - * }); - * - * var path2 = new Path.Circle({ - * center: [150, 50], - * radius: 25, - * fillColor: 'black' - * }); - * - * // Fetch path item positioned at {x: 150, y: 150}: - * var item = project.getItem({ - * position: [150, 50] - * }); - * - * // Select the fetched path: - * item.selected = true; - * - * @example {@paperscript} // Fetch item using a comparing function: - * - * // Create a circle shaped path: - * var path1 = new Path.Circle({ - * center: [50, 50], - * radius: 25, - * fillColor: 'black' - * }); - * - * // Create a circle shaped path with 50% opacity: - * var path2 = new Path.Circle({ - * center: [150, 50], - * radius: 25, - * fillColor: 'black', - * opacity: 0.5 - * }); - * - * // Fetch first item whose opacity is smaller than 1 - * var item = paper.project.getItem({ - * opacity: function(value) { - * return value < 1; - * } - * }); - * - * // Select the fetched item: - * item.selected = true; - * - * @example {@paperscript} // Fetch item using a comparing function (2): - * - * // Create a rectangle shaped path (4 segments): - * var path1 = new Path.Rectangle({ - * from: [25, 25], - * to: [75, 75], - * strokeColor: 'black', - * strokeWidth: 10 - * }); - * - * // Create a line shaped path (2 segments): - * var path2 = new Path.Line({ - * from: [125, 50], - * to: [175, 50], - * strokeColor: 'black', - * strokeWidth: 10 - * }); - * - * // Fetch first path with 2 segments: - * var item = project.getItem({ - * class: Path, - * segments: function(segments) { - * return segments.length == 2; - * } - * }); - * - * // Select the fetched path: - * item.selected = true; - * - * @example {@paperscript} // Match (nested) properties of the data property: - * - * // Create a black circle shaped path: - * var path1 = new Path.Circle({ - * center: [50, 50], - * radius: 25, - * fillColor: 'black', - * data: { - * person: { - * name: 'john', - * length: 200, - * hair: true - * } - * } - * }); - * - * // Create a red circle shaped path: - * var path2 = new Path.Circle({ - * center: [150, 50], - * radius: 25, - * fillColor: 'red', - * data: { - * person: { - * name: 'john', - * length: 180, - * hair: false - * } - * } - * }); - * - * // Fetch item whose data object contains a person - * // object whose name is john and length is 180: - * var item = paper.project.getItem({ - * data: { - * person: { - * name: 'john', - * length: 180 - * } - * } - * }); - * - * // Select the fetched item: - * item.selected = true; - * - * @example {@paperscript} // Match strings using regular expressions: - * - * // Create a path named 'aardvark': - * var path1 = new Path.Circle({ - * center: [50, 50], - * radius: 25, - * fillColor: 'black', - * name: 'aardvark' - * }); - * - * // Create a path named 'apple': - * var path2 = new Path.Circle({ - * center: [150, 50], - * radius: 25, - * fillColor: 'black', - * name: 'apple' - * }); - * - * // Fetch the first item that has a name starting with 'a': - * var item = project.getItem({ - * name: /^a/ - * }); - * - * // Change the fill color of the matched item: - * item.fillColor = 'red'; - * - * @param {Object} match The criteria to match against. - * @return {Item} + * @param {Object} match the criteria to match against. + * @return {Item} the first item in the project matching the given criteria. */ getItem: function(match) { - return Item._getItems(this.layers, match, true)[0] || null; + return Item._getItems(this.layers, match, null, null, true)[0] || null; }, /**