mirror of
https://github.com/scratchfoundation/paper.js.git
synced 2025-01-01 02:38:43 -05:00
Clean up documentation for Project#getItems() / Item#getItems().
This commit is contained in:
Jürg Lehni
parent
82b988327d
commit
c25548031b
2 changed files with 28 additions and 208 deletions
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
},
|
||||
|
||||
/**
|
||||
|
|
|
|||
Loading…
Reference in a new issue