diff --git a/src/item/HitResult.js b/src/item/HitResult.js index b7904628..3d75cf33 100644 --- a/src/item/HitResult.js +++ b/src/item/HitResult.js @@ -17,7 +17,8 @@ /** * @name HitResult * - * @class + * @class A HitResult object contains information about the results of a hit + * test. * * @extends CurveLocation */ @@ -34,6 +35,61 @@ HitResult = Base.extend(/** @lends HitResult# */{ } }, + /** + * Describes the type of the hit result. For example, if you hit a segment + * point, the type would be 'segment'. + * + * @property + * @name HitResult#type + * @type String('segment', 'handle-in', 'handle-out', 'stroke', 'fill', + * 'bounds', 'center') + */ + + /** + * If the HitResult has a {@link HitResult#type} of 'bounds', this property + * describes which corner of the bounding rectangle was hit. + * + * @property + * @name HitResult#name + * @type String('top-left', 'top-right', 'bottom-left', 'bottom-right', + * 'left-center', 'top-center', 'right-center', 'bottom-center') + */ + + /** + * The item that was hit. + * + * @property + * @name HitResult#item + * @type Item + */ + + /** + * If the HitResult has a type of 'stroke', this property gives more + * information about the exact position that was hit on the path. + * + * @property + * @name HitResult#location + * @type CurveLocation + */ + + /** + * If the HitResult has a type of 'stroke', 'segment', 'handle-in' or + * 'handle-out', this property refers to the Segment that was hit or that + * is closest to the hitResult.location on the curve. + * + * @property + * @name HitResult#segment + * @type Segment + */ + + /** + * The hit point. + * + * @property + * @name HitResult#point + * @type Point + */ + statics: { /** * Merges default options into options hash for #hitTest() calls, and diff --git a/src/item/Item.js b/src/item/Item.js index 938bc79a..c8ec2c2f 100644 --- a/src/item/Item.js +++ b/src/item/Item.js @@ -682,6 +682,43 @@ var Item = this.Item = Base.extend(/** @lends Item# */{ return raster; }, + + + /** + * Perform a hit test on the item (and its children, if it is a + * {@link Group} or {@link Layer}) at the location of the specified point. + * + * The optional options object allows you to control the specifics of the + * hit test and may contain a combination of the following values: + * tolerance: {@code Number} - The tolerance of the hit test in + * points. + * type: Only hit test again a certain item + * type: {@link PathItem}, {@link Raster}, {@link TextItem}, etc. + * fill: {@code Boolean} - Hit test the fill of items. + * stroke: {@code Boolean} - Hit test the curves of path items, + * taking into account stroke width. + * segment: {@code Boolean} - Hit test for {@link Segment#point} of + * {@link Path} items. + * handles: {@code Boolean} - Hit test for the handles + * ({@link Segment#handleIn} / {@link Segment#handleOut}) of path segments. + * ends: {@code Boolean} - Only hit test for the first or last + * segment points of open path items. + * bounds: {@code Boolean} - Hit test the corners and side-centers + * of the bounding rectangle of items ({@link Item#bounds}). + * center: {@code Boolean} - Hit test the {@link Rectangle#center} + * of the bounding rectangle of items ({@link Item#bounds}). + * guide: {@code Boolean} - Hit test items that have + * {@link Item#guide} set to {@code true}. + * selected: {@code Boolean} - Only hit selected items. + * + * @param {Point} point The point where the hit test should be performed + * @param {Object} [options={ fill: true, stroke: true, segments: true, + * tolerance: 2 }] + * @param {Matrix} [matrix] + * @return {HitResult|null} A hit result object that contains more + * information about what exactly was hit or {@code null} if nothing was + * hit. + */ hitTest: function(point, options, matrix) { options = HitResult.getOptions(point, options); point = options.point; diff --git a/src/project/Project.js b/src/project/Project.js index 53764300..f432a873 100644 --- a/src/project/Project.js +++ b/src/project/Project.js @@ -181,6 +181,40 @@ var Project = this.Project = Base.extend(/** @lends Project# */{ this._selectedItems[i].setSelected(false); }, + /** + * Perform a hit test on the items contained within the project at the + * location of the specified point. + * + * The optional options object allows you to control the specifics of the + * hit test and may contain a combination of the following values: + * tolerance: {@code Number} - The tolerance of the hit test in + * points. + * type: Only hit test again a certain item + * type: {@link PathItem}, {@link Raster}, {@link TextItem}, etc. + * fill: {@code Boolean} - Hit test the fill of items. + * stroke: {@code Boolean} - Hit test the curves of path items, + * taking into account stroke width. + * segment: {@code Boolean} - Hit test for {@link Segment#point} of + * {@link Path} items. + * handles: {@code Boolean} - Hit test for the handles + * ({@link Segment#handleIn} / {@link Segment#handleOut}) of path segments. + * ends: {@code Boolean} - Only hit test for the first or last + * segment points of open path items. + * bounds: {@code Boolean} - Hit test the corners and side-centers + * of the bounding rectangle of items ({@link Item#bounds}). + * center: {@code Boolean} - Hit test the {@link Rectangle#center} + * of the bounding rectangle of items ({@link Item#bounds}). + * guide: {@code Boolean} - Hit test items that have + * {@link Item#guide} set to {@code true}. + * selected: {@code Boolean} - Only hit selected items. + * + * @param {Point} point The point where the hit test should be performed + * @param {Object} [options={ fill: true, stroke: true, segments: true, + * tolerance: true }] + * @return {HitResult|null} A hit result object that contains more + * information about what exactly was hit or {@code null} if nothing was + * hit. + */ hitTest: function(point, options) { options = HitResult.getOptions(point, options); point = options.point;