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

Documentation: reorder functions, add group titles and todos.

Browse source
This commit is contained in:
Jonathan Puckey 2011-05-27 13:28:13 +02:00
parent 397d3676ed
commit ca3230c1ad
12 changed files with 259 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
src/basic/Point.js
View file

@ -30,6 +30,14 @@ var Point = this.Point = Base.extend({
* @class The Point object represents a point in the two dimensional space
* of the Paper.js project. It is also used to represent two dimensional
* vector objects.
*
* Sample code:
* <pre>
* // Create a point at x: 10, y: 5
* var point = new Point(10, 5);
* console.log(point.x); // 10
* console.log(point.y); // 5
* </pre>
*/
initialize: function(arg0, arg1) {
if (arg1 !== undefined) {

88
src/basic/Rectangle.js
View file

@ -115,7 +115,7 @@ var Rectangle = this.Rectangle = Base.extend({
return this;
},
/*
/**
* The top-left point of the rectangle
*
* @type Point
@ -132,7 +132,7 @@ var Rectangle = this.Rectangle = Base.extend({
return this;
},
/*
/**
* The size of the rectangle
*
* @type Size
@ -222,6 +222,7 @@ var Rectangle = this.Rectangle = Base.extend({
*
* @type number
* @bean
* @ignore
*/
getCenterX: function() {
return this.x + this.width * 0.5;
@ -237,6 +238,7 @@ var Rectangle = this.Rectangle = Base.extend({
*
* @type number
* @bean
* @ignore
*/
getCenterY: function() {
return this.y + this.height * 0.5;
@ -248,6 +250,8 @@ var Rectangle = this.Rectangle = Base.extend({
},
/**
* {@grouptitle Corner and Center Point Positions}
*
* The center point of the rectangle.
*
* @type Point
@ -265,6 +269,62 @@ var Rectangle = this.Rectangle = Base.extend({
// DOCS: Rectangle#topLeft, Rectangle#topRight etc.
/**
* The top-left point of the rectangle.
*
* @name Rectangle#topLeft
* @type Point
*/
/**
* The top-right point of the rectangle.
*
* @name Rectangle#topRight
* @type Point
*/
/**
* The bottom-left point of the rectangle.
*
* @name Rectangle#bottomLeft
* @type Point
*/
/**
* The bottom-right point of the rectangle.
*
* @name Rectangle#bottomRight
* @type Point
*/
/**
* The left-center point of the rectangle.
*
* @name Rectangle#leftCenter
* @type Point
*/
/**
* The top-center point of the rectangle.
*
* @name Rectangle#topCenter
* @type Point
*/
/**
* The right-center point of the rectangle.
*
* @name Rectangle#rightCenter
* @type Point
*/
/**
* The bottom-center point of the rectangle.
*
* @name Rectangle#bottomCenter
* @type Point
*/
// DOCS: Rectangle#equals
/**
* @param {Rectangle} rect
@ -283,6 +343,18 @@ var Rectangle = this.Rectangle = Base.extend({
return this.width == 0 || this.height == 0;
},
/**
* @return {string} A string representation of this rectangle.
*/
toString: function() {
var format = Base.formatNumber;
return '{ x: ' + format(this.x)
+ ', y: ' + format(this.y)
+ ', width: ' + format(this.width)
+ ', height: ' + format(this.height)
+ ' }';
},
/**
* {@grouptitle Geometric Tests}
*
@ -391,18 +463,6 @@ var Rectangle = this.Rectangle = Base.extend({
return Rectangle.create(x1, y1, x2 - x1, y2 - y1);
},
/**
* @return {string} A string representation of this rectangle.
*/
toString: function() {
var format = Base.formatNumber;
return '{ x: ' + format(this.x)
+ ', y: ' + format(this.y)
+ ', width: ' + format(this.width)
+ ', height: ' + format(this.height)
+ ' }';
},
statics: {
// See Point.create()
create: function(x, y, width, height) {

50
src/basic/Size.js
View file

@ -27,6 +27,14 @@ var Size = this.Size = Base.extend({
* @param {number} height the height
*
* @class The Size object represents the size of something.
*
* Sample code:
* <pre>
* // Create a size that is 10pt wide and 5pt height
* var size = new Size(10, 5);
* console.log(size.width); // 10
* console.log(size.height); // 5
* </pre>
*/
initialize: function(arg0, arg1) {
if (arg1 !== undefined) {
@ -54,6 +62,15 @@ var Size = this.Size = Base.extend({
}
},
/**
* @return {string} A string representation of the size.
*/
toString: function() {
var format = Base.formatNumber;
return '{ width: ' + format(this.width)
+ ', height: ' + format(this.height) + ' }';
},
/**
* The width of the size
*
@ -254,9 +271,9 @@ var Size = this.Size = Base.extend({
*
* @example
* var size = new Size(5, 10);
* print(size == new Size(5, 10)); // true
* print(size == new Size(1, 1)); // false
* print(size != new Size(1, 1)); // true
* console.log(size == new Size(5, 10)); // true
* console.log(size == new Size(1, 1)); // false
* console.log(size != new Size(1, 1)); // true
*
* @param {Size}
* @return {boolean}
@ -267,6 +284,7 @@ var Size = this.Size = Base.extend({
},
/**
* {@grouptitle Tests}
* Checks if this size has both the width and height set to 0.
*
* @return {boolean} true if both width and height are 0, false otherwise.
@ -285,15 +303,6 @@ var Size = this.Size = Base.extend({
return isNaN(this.width) || isNaN(this.height);
},
/**
* @return {string} A string representation of the size.
*/
toString: function() {
var format = Base.formatNumber;
return '{ width: ' + format(this.width)
+ ', height: ' + format(this.height) + ' }';
},
statics: {
/** @lends Size */
@ -306,6 +315,12 @@ var Size = this.Size = Base.extend({
* Returns a new size object with the smallest {@link #width} and
* {@link #height} of the supplied sizes.
*
* @example
* var size1 = new Size(10, 100);
* var size2 = new Size(200, 5);
* var minSize = Size.min(size1, size2);
* console.log(minSize); // { width: 10.0, height: 5.0 }
*
* @static
* @param {Size} size1
* @param {Size} size2
@ -321,6 +336,12 @@ var Size = this.Size = Base.extend({
* Returns a new size object with the largest {@link #width} and
* {@link #height} of the supplied sizes.
*
* @example
* var size1 = new Size(10, 100);
* var size2 = new Size(200, 5);
* var maxSize = Size.max(size1, size2);
* console.log(maxSize); // { width: 200.0, height: 100.0 }
*
* @static
* @param {Size} size1
* @param {Size} size2
@ -336,6 +357,11 @@ var Size = this.Size = Base.extend({
* Returns a size object with random {@link #width} and {@link #height}
* values between {@code 0} and {@code 1}.
*
* @example
* var maxSize = new Size(100, 100);
* var randomSize = Size.random();
* var size = maxSize * randomSize;
*
* @returns {Size} The newly created size object
* @static
*/

7
src/item/Layer.js
View file

@ -22,7 +22,8 @@ var Layer = this.Layer = Group.extend({
// DOCS: improve constructor code example.
/**
* Creates a new Layer item and places it at the end of the
* {@link Project#layers} array.
* {@link Project#layers} array. The newly created layer will be activated,
* so all newly created items will be placed within it.
*
* @example
* var layer = new Layer();
@ -69,14 +70,14 @@ var Layer = this.Layer = Group.extend({
: this._project.layers[this._index - 1] || null;
},
// DOCS: improve Layer#activate() example.
/**
* Activates the layer.
*
* @example
* var layer = new Layer();
* layer.name = 'new layer';
* layer.activate();
* console.log(project.activeLayer.name) // 'new layer'
* console.log(project.activeLayer == layer); // true
*/
activate: function() {
this._project.activeLayer = this;

4
src/item/PathStyle.js
View file

@ -54,7 +54,8 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
* {@link Item#style}. This is a convenient way to define a style once and
* apply it to a series of items:
*
* @example
* Sample Code:
* <pre>
* var circleStyle = {
* fillColor: new RGBColor(1, 0, 0),
* strokeColor: new GrayColor(1),
@ -63,6 +64,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
*
* var path = new Path.Circle(new Point(50, 50), 50);
* path.style = circleStyle;
* </pre>
*/
initialize: function(style) {
// Note: This relies on bean setters that get implicetly

104
src/item/Raster.js
View file

@ -202,57 +202,6 @@ var Raster = this.Raster = Item.extend({
this.getContext().drawImage(image, point.x, point.y);
},
/**
* Gets the color of a pixel in the raster.
*
* @name Raster#getPixel^2
* @function
* @param x the x offset of the pixel in pixel coordinates
* @param y the y offset of the pixel in pixel coordinates
* @return {RGBColor} the color of the pixel
*/
/**
* Gets the color of a pixel in the raster.
* @param point the offset of the pixel as a point in pixel coordinates
* @return {RGBColor} the color of the pixel
*/
getPixel: function(point) {
point = Point.read(arguments);
var pixels = this.getContext().getImageData(point.x, point.y, 1, 1).data,
channels = new Array(4);
for (var i = 0; i < 4; i++)
channels[i] = pixels[i] / 255;
return RGBColor.read(channels);
},
/**
* Sets the color of the specified pixel to the specified color.
*
* @name Raster#setPixel^2
* @function
* @param x the x offset of the pixel in pixel coordinates
* @param y the y offset of the pixel in pixel coordinates
* @param color the color that the pixel will be set to
*/
/**
* Sets the color of the specified pixel to the specified color.
* @param point the offset of the pixel as a point in pixel coordinates
* @param color the color that the pixel will be set to
*/
setPixel: function(point, color) {
var hasPoint = arguments.length == 2;
point = Point.read(arguments, 0, hasPoint ? 1 : 2);
color = Color.read(arguments, hasPoint ? 1 : 2);
var ctx = this.getContext(),
imageData = ctx.createImageData(1, 1),
alpha = color.getAlpha();
imageData.data[0] = color.getRed() * 255;
imageData.data[1] = color.getGreen() * 255;
imageData.data[2] = color.getBlue() * 255;
imageData.data[3] = alpha != null ? alpha * 255 : 255;
ctx.putImageData(imageData, point.x, point.y);
},
/**
* Calculates the average color of the image within the given path,
* rectangle or point. This can be used for creating raster image
@ -325,8 +274,61 @@ var Raster = this.Raster = Item.extend({
return total ? Color.read(channels) : null;
},
/**
* {@grouptitle Pixels}
* Gets the color of a pixel in the raster.
*
* @name Raster#getPixel^2
* @function
* @param x the x offset of the pixel in pixel coordinates
* @param y the y offset of the pixel in pixel coordinates
* @return {RGBColor} the color of the pixel
*/
/**
* Gets the color of a pixel in the raster.
* @param point the offset of the pixel as a point in pixel coordinates
* @return {RGBColor} the color of the pixel
*/
getPixel: function(point) {
point = Point.read(arguments);
var pixels = this.getContext().getImageData(point.x, point.y, 1, 1).data,
channels = new Array(4);
for (var i = 0; i < 4; i++)
channels[i] = pixels[i] / 255;
return RGBColor.read(channels);
},
/**
* Sets the color of the specified pixel to the specified color.
*
* @name Raster#setPixel^2
* @function
* @param x the x offset of the pixel in pixel coordinates
* @param y the y offset of the pixel in pixel coordinates
* @param color the color that the pixel will be set to
*/
/**
* Sets the color of the specified pixel to the specified color.
* @param point the offset of the pixel as a point in pixel coordinates
* @param color the color that the pixel will be set to
*/
setPixel: function(point, color) {
var hasPoint = arguments.length == 2;
point = Point.read(arguments, 0, hasPoint ? 1 : 2);
color = Color.read(arguments, hasPoint ? 1 : 2);
var ctx = this.getContext(),
imageData = ctx.createImageData(1, 1),
alpha = color.getAlpha();
imageData.data[0] = color.getRed() * 255;
imageData.data[1] = color.getGreen() * 255;
imageData.data[2] = color.getBlue() * 255;
imageData.data[3] = alpha != null ? alpha * 255 : 255;
ctx.putImageData(imageData, point.x, point.y);
},
// DOCS: document Raster#createData
/**
* {@grouptitle Image Data}
* @param {Size} size
* @return {ImageData}
*/

28
src/path/Path.js
View file

@ -929,6 +929,8 @@ var Path = this.Path = PathItem.extend({
// DOCS: document moveTo
/**
* {@grouptitle Postscript Style Drawing Commands}
*
* @param {Point} point
*/
moveTo: function(point) {
@ -990,7 +992,7 @@ var Path = this.Path = PathItem.extend({
);
},
// DOCS: document curveTo
// DOCS: document Path#curveTo
/**
* @param {Point} through
* @param {Point} to
@ -1012,6 +1014,11 @@ var Path = this.Path = PathItem.extend({
this.quadraticCurveTo(handle, to);
},
// DOCS: document Path#arcTo
/**
* @param {Point} to
* @param {boolean} [clockwise=true]
*/
arcTo: function(to, clockwise) {
// Get the start point:
var current = getCurrentSegment(this),
@ -1095,12 +1102,22 @@ var Path = this.Path = PathItem.extend({
this._add(segments);
},
// DOCS: document Path#lineBy
/**
* @param {Point} vector
*/
lineBy: function(vector) {
vector = Point.read(arguments);
var current = getCurrentSegment(this);
this.lineTo(current._point.add(vector));
},
// DOCS: document Path#curveBy
/**
* @param {Point} throughVector
* @param {Point} toVector
* @param {number} [parameter=0.5]
*/
curveBy: function(throughVector, toVector, parameter) {
throughVector = Point.read(throughVector);
toVector = Point.read(toVector);
@ -1109,6 +1126,11 @@ var Path = this.Path = PathItem.extend({
parameter);
},
// DOCS: document Path#arcBy
/**
* @param {Point} throughVector
* @param {Point} toVector
*/
arcBy: function(throughVector, toVector) {
throughVector = Point.read(throughVector);
toVector = Point.read(toVector);
@ -1116,6 +1138,10 @@ var Path = this.Path = PathItem.extend({
this.arcBy(current.add(throughVector), current.add(toVector));
},
/**
* Closes the path. When closed, Paper.js connects the first and last
* segments.
*/
closePath: function() {
this.setClosed(true);
}

8
src/path/Segment.js
View file

@ -45,7 +45,7 @@ var Segment = this.Segment = Base.extend({
* @constructor
*
* @class The Segment object represents a part of a path which is
* described by the {@link Path##segments} array. Every segment of a
* described by the {@link Path#segments} array. Every segment of a
* path corresponds to an anchor point (anchor points are the path handles
* that are visible when the path is selected).
*/
@ -214,7 +214,8 @@ var Segment = this.Segment = Base.extend({
* {@grouptitle Sibling Segments}
*
* The next segment in the {@link Path#segments} array that the segment
* belongs to.
* belongs to. If the segments belongs to a closed path, the first segment
* is returned for the last segment of the path.
*
* @type Segment
* @bean
@ -227,7 +228,8 @@ var Segment = this.Segment = Base.extend({
/**
* The previous segment in the {@link Path#segments} array that the
* segment belongs to.
* segment belongs to. If the segments belongs to a closed path, the last
* segment is returned for the first segment of the path.
*
* @type Segment
* @bean

45
src/project/Symbol.js
View file

@ -22,25 +22,6 @@ var Symbol = this.Symbol = Base.extend({
/**
* Creates a Symbol item.
*
* Sample code:
* @example
* var circlePath = new Path.Circle(new Point(100, 100), 50);
* circlePath.fillColor = 'red';
*
* var circleSymbol = new Symbol(circlePath);
* circleSymbol.name = 'Circle';
*
* // The original item is still contained in the document:
* circlePath.remove();
*
* // The symbol can now also be accessed
* // through project.symbols:
* console.log(project.symbols['Circle']);
*
* // To place instances of the symbol in the document:
* var placedCircle = new PlacedSymbol(circleSymbol);
* placedCircle.position = new Point(150, 150);
*
* @param {Item} item the source item which is copied as the definition of
* the symbol
*
@ -53,6 +34,21 @@ var Symbol = this.Symbol = Base.extend({
* around complex objects, since internal properties such as segment
* lists and gradient positions don't need to be updated with every
* transformation.
*
* Sample code:
* <pre>
* var circlePath = new Path.Circle(new Point(100, 100), 50);
* circlePath.fillColor = 'red';
*
* var circleSymbol = new Symbol(circlePath);
*
* // The original item is still contained in the document:
* circlePath.remove();
*
* // To place instances of the symbol in the document:
* var placedCircle = new PlacedSymbol(circleSymbol);
* placedCircle.position = new Point(150, 150);
* </pre>
*/
initialize: function(item) {
this.project = paper.project;
@ -60,7 +56,16 @@ var Symbol = this.Symbol = Base.extend({
this.setDefinition(item);
},
// TODO: remove()
// TODO: Symbol#remove()
// TODO: Size#name (accessible by name through project#symbols)
/**
* The project that this symbol belongs to.
*
* @type Project
* @readonly
* @name Symbol#project
*/
/**
* The symbol definition.

16
src/text/ParagraphStyle.js
View file

@ -21,10 +21,6 @@ var ParagraphStyle = this.ParagraphStyle = Base.extend({
* ParagraphStyle objects don't need to be created directly. Just pass an
* object to {@link TextItem#paragraphStyle}, it will be converted to a
* ParagraphStyle object internally.
*
* Currently, the ParagraphStyle object may seem a bit empty, with just the
* {@link #justification} property. Yet, we have lots in store for Paper.js
* when it comes to typography. Please stay tuned.
*
* @constructs ParagraphStyle
* @param {object} style
@ -32,13 +28,19 @@ var ParagraphStyle = this.ParagraphStyle = Base.extend({
* @constructs ParagraphStyle
*
* @class The ParagraphStyle object represents the paragraph style of a text
* item ({@link TextItem#paragraphStyle})
* item ({@link TextItem#paragraphStyle}).
*
* @example
* Currently, the ParagraphStyle object may seem a bit empty, with just the
* {@link #justification} property. Yet, we have lots in store for Paper.js
* when it comes to typography. Please stay tuned.
*
* Sample code:
* <pre>
* var text = new PointText(new Point(0,0));
* text.fillColor = 'black';
* text.content = 'Hello world.';
* text.paragraphStyle.justification = 'center';
* </pre>
*/
initialize: function(style) {
Base.initialize(this, style, {
@ -51,7 +53,7 @@ var ParagraphStyle = this.ParagraphStyle = Base.extend({
*
* @name ParagraphStyle#justification
* @default 'left'
* @type string
* @type String('left', 'right', 'center')
*/
statics: {

14
src/text/PointText.js
View file

@ -22,12 +22,6 @@ var PointText = this.PointText = TextItem.extend({
/**
* Creates a point text item
*
* @example
* var text = new PointText(new Point(50, 100));
* text.paragraphStyle.justification = 'center';
* text.content = 'The contents of the point text';
* text.fillColor = 'black';
*
* @param {Point} point the position where the text will start
*
* @constructs PointText
@ -36,6 +30,14 @@ var PointText = this.PointText = TextItem.extend({
* project which starts from a certain point and extends by the amount of
* characters contained in it.
*
* Sample code:
* <pre>
* var text = new PointText(new Point(50, 100));
* text.paragraphStyle.justification = 'center';
* text.content = 'The contents of the point text';
* text.fillColor = 'black';
* </pre>
*
* @extends TextItem
* @extends Item
*/

6
src/tool/Tool.js
View file

@ -35,7 +35,8 @@ var Tool = this.Tool = Base.extend({
* {@link #onMouseDrag}, {@link #onMouseUp}) or a keyboard handler
* function ({@link #onKeyDown}, {@link #onKeyUp}).
*
* @example
* Example code:
* <pre>
* var path;
*
* // Only execute onMouseDrag when the mouse
@ -52,6 +53,7 @@ var Tool = this.Tool = Base.extend({
* // Add a point to the path every time the mouse is dragged
* path.lineTo(event.point);
* }
* </pre>
*/
initialize: function(handlers, scope) {
this._scope = scope;
@ -194,6 +196,8 @@ var Tool = this.Tool = Base.extend({
// DOCS: document Tool#onKeyDown
/**
* {@grouptitle Keyboard Event Handlers}
*
* @name Tool#onKeyDown
* @property
* @type function