scratchfoundation/paper.js
1
0
Fork 0
mirror of https://github.com/scratchfoundation/paper.js.git synced 2025-01-19 14:10:14 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add more matching docs.

Browse source
This commit is contained in:
Jonathan Puckey 2014-04-27 23:40:43 +02:00
parent f0db48a77f
commit 12d7756892
2 changed files with 250 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
src/item/Item.js
View file

@ -1794,9 +1794,22 @@ var Item = Base.extend(Callback, /** @lends Item# */{
// The default implementation honly handles 'fill' through #_contains()
if (options.fill && this.hasFill() && this._contains(point))
return new HitResult('fill', this);
}
}, { // Now injection block for statics below
// DOCS: Item#matches
},
/**
* {@grouptitle Fetching and matching items}
*
* Check whether the item matches the properties in the specified object.
* Extended matching is possible by providing a compare function or
* regular expression. Matching points, colors only work as a comparison
* 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 Project#getItems(match)
* @param {Object} match The criteria to match against.
* @return {@true if the item matches the criteria}
*/
matches: function(match) {
// matchObject() is used to match against objects in a nested manner.
// This is useful for matching against Item#data.
@ -1843,12 +1856,37 @@ var Item = Base.extend(Callback, /** @lends Item# */{
return true;
},
// DOCS: Item#getItems
/**
* Fetch the descendants (children or children of children) of this item
* that match the properties in the specified object.
* Extended matching is possible by providing a compare function or
* regular expression. Matching points, colors only work as a comparison
* 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 Project#getItems(match)
* @param {Object} match The criteria to match against.
* @return {Item[]}
*/
getItems: function(match) {
return Item._getItems(this._children, match, true);
},
// DOCS: Item#getItem
/**
* Fetch the first descendant (child or child of child) of this item
* that matches the properties in the specified object.
* Extended matching is possible by providing a compare function or
* regular expression. Matching points, colors only work as a comparison
* 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 Project#getItem(match)
* @param {Object} match The criteria to match against.
* @return {Item}
*/
getItem: function(match) {
return Item._getItems(this._children, match, false);
},

209
src/project/Project.js
View file

@ -363,7 +363,7 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{
* fillColor: 'purple'
* });
*
* // Change the fill color of the selected path to red:
* // Select the fetched item:
* items[0].selected = true;
*
* @example {@paperscript} // Fetch items at a specific position:
@ -524,12 +524,217 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{
* }
*
* @param {Object} match The criteria to match against.
* @return {Item[]}
*/
getItems: function(match) {
return Item._getItems(this.layers, match, true);
},
// DOCS: Project#getItems
/**
* Fetch the first item contained within the project whose properties
* match the criteria in the specified object.
* Extended matching is possible by providing a compare function or
* regular expression. Matching points, colors only work as a comparison
* 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}.
*
* @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}
*/
getItem: function(match) {
return Item._getItems(this.layers, match, false);
},