diff --git a/cocos2d/core/value-types/CCAffineTransform.js b/cocos2d/core/value-types/CCAffineTransform.js index cd9bf1f429..29facd289a 100644 --- a/cocos2d/core/value-types/CCAffineTransform.js +++ b/cocos2d/core/value-types/CCAffineTransform.js @@ -25,9 +25,12 @@ ****************************************************************************/ /** - *

cc.AffineTransform class represent an affine transform matrix. It's composed basically by translation, rotation, scale transformations.
+ * !#en + * cc.AffineTransform class represent an affine transform matrix. It's composed basically by translation, rotation, scale transformations.
* Please do not use its constructor directly, use cc.affineTransformMake alias function instead. - *

+ * !#zh + * cc.AffineTransform 类代表一个仿射变换矩阵。它基本上是由平移旋转,缩放转变所组成。
+ * 请不要直接使用它的构造,请使用 cc.affineTransformMake 函数代替。 * @class AffineTransform * @param {Number} a * @param {Number} b @@ -47,7 +50,8 @@ cc.AffineTransform = function (a, b, c, d, tx, ty) { }; /** - * Create a cc.AffineTransform object with all contents in the matrix + * !#en Create a cc.AffineTransform object with all contents in the matrix. + * !#zh 用在矩阵中的所有内容创建一个 cc.AffineTransform 对象。 * @method affineTransformMake * * @param {Number} a @@ -63,7 +67,8 @@ cc.affineTransformMake = function (a, b, c, d, tx, ty) { }; /** - * Clone a cc.AffineTransform object from the specified transform + * !#en Clone a cc.AffineTransform object from the specified transform. + * !#zh 克隆指定的 cc.AffineTransform 对象。 * @method affineTransformClone * * @param {AffineTransform} t @@ -74,7 +79,8 @@ cc.affineTransformClone = function (t) { }; /** - * Apply the affine transformation on a point. + * !#en Apply the affine transformation on a point. + * !#zh 应用 Point 到仿射变换矩阵上。 * @method pointApplyAffineTransform * * @param {Vec2|Number} point - or x. @@ -100,7 +106,8 @@ cc._pointApplyAffineTransform = function (x, y, t) { //it will remove. }; /** - * Apply the affine transformation on a size. + * !#en Apply the affine transformation on a size. + * !#zh 应用 Size 到仿射变换矩阵上。 * @method sizeApplyAffineTransform * * @param {Size} size @@ -112,9 +119,14 @@ cc.sizeApplyAffineTransform = function (size, t) { }; /** - *

Create a identity transformation matrix:
+ * !#en + * Create a identity transformation matrix:
* [ 1, 0, 0,
- * 0, 1, 0 ]

+ * 0, 1, 0 ] + * !#zh + * 创建一个恒等变换矩阵:
+ * [ 1, 0, 0,
+ * 0, 1, 0 ] * * @method affineTransformMakeIdentity * @return {AffineTransform} @@ -123,10 +135,11 @@ cc.affineTransformMakeIdentity = function () { return {a: 1.0, b: 0.0, c: 0.0, d: 1.0, tx: 0.0, ty: 0.0}; }; -/** - *

Create a identity transformation matrix:
+/* + * Create a identity transformation matrix:
* [ 1, 0, 0,
- * 0, 1, 0 ]

+ * 0, 1, 0 ] + * * * @method affineTransformIdentity * @return {AffineTransform} @@ -138,7 +151,8 @@ cc.affineTransformIdentity = function () { }; /** - * Apply the affine transformation on a rect. + * !#en Apply the affine transformation on a rect. + * !#zh 应用 Rect 到仿射变换矩阵上。 * * @method rectApplyAffineTransform * @param {Rect} rect @@ -188,7 +202,8 @@ cc._rectApplyAffineTransformIn = function(rect, anAffineTransform){ }; /** - * Create a new affine transformation with a base transformation matrix and a translation based on it. + * !#en Create a new affine transformation with a base transformation matrix and a translation based on it. + * !#zh 创建一个基础变换矩阵,并在此基础上平移了新的仿射变换。 * * @method affineTransformTranslate * @param {AffineTransform} t - The base affine transform object. @@ -208,7 +223,8 @@ cc.affineTransformTranslate = function (t, tx, ty) { }; /** - * Create a new affine transformation with a base transformation matrix and a scale based on it. + * !#en Create a new affine transformation with a base transformation matrix and a scale based on it. + * !#zh 创建一个基础变换矩阵,并在此基础上进行了 Scale 仿射变换。 * @method affineTransformScale * @param {AffineTransform} t - The base affine transform object. * @param {Number} sx - The scale on x axis. @@ -220,7 +236,8 @@ cc.affineTransformScale = function (t, sx, sy) { }; /** - * Create a new affine transformation with a base transformation matrix and a rotation based on it. + * !#en Create a new affine transformation with a base transformation matrix and a rotation based on it. + * !#zh 创建一个基础变换矩阵,并在此基础上进行了 Rotation 仿射变换。 * @method affineTransformRotate * @param {AffineTransform} aTransform - The base affine transform object. * @param {Number} anAngle - The angle to rotate. @@ -239,8 +256,12 @@ cc.affineTransformRotate = function (aTransform, anAngle) { }; /** + * !#en * Concatenate a transform matrix to another and return the result:
* t' = t1 * t2 + * !#zh 拼接变换矩阵到另一个,并返回结果:
+ * t' = t1 * t2 + * * @method affineTransformConcat * @param {AffineTransform} t1 - The first transform object. * @param {AffineTransform} t2 - The transform object to concatenate. @@ -256,9 +277,13 @@ cc.affineTransformConcat = function (t1, t2) { }; /** + * !#en * Concatenate a transform matrix to another
* The results are reflected in the first matrix.
* t' = t1 * t2 + * !#zh + * 拼接变换矩阵到另一个,将结果反射在第一矩阵。
+ * t' = t1 * t2 * @method affineTransformConcatIn * @param {AffineTransform} t1 - The first transform object. * @param {AffineTransform} t2 - The transform object to concatenate. @@ -276,7 +301,8 @@ cc.affineTransformConcatIn = function (t1, t2) { }; /** - * Return true if an affine transform equals to another, false otherwise. + * !#en Return true if an affine transform equals to another, false otherwise. + * !#zh 如果仿射变换等于另一个返回 true,否则为 false * @method affineTransformEqualToTransform * @param {AffineTransform} t1 * @param {AffineTransform} t2 @@ -287,7 +313,8 @@ cc.affineTransformEqualToTransform = function (t1, t2) { }; /** - * Get the invert transform of an AffineTransform object. + * !#en Get the invert transform of an AffineTransform object. + * !#zh 获取反向仿射变换的对象 * @method affineTransformInvert * @param {AffineTransform} t * @return {AffineTransform} The inverted transform object. diff --git a/cocos2d/core/value-types/CCColor.js b/cocos2d/core/value-types/CCColor.js index 686c7fb6ff..155f9ef666 100644 --- a/cocos2d/core/value-types/CCColor.js +++ b/cocos2d/core/value-types/CCColor.js @@ -29,12 +29,20 @@ var JS = require('../platform/js'); var Color = (function () { /** + * !#en * Representation of RGBA colors. * * Each color component is a floating point value with a range from 0 to 255. * * You can also use the convenience method {{#crossLink "cc/color:method"}}cc.color{{/crossLink}} to create a new Color. * + * !#zh + * RGBA 颜色表示。 + * + * 每个 Color 的取值范围在 0 到 255 之间。 + * + * 您也可以使用便捷的方法 {{#crossLink "cc/color:method"}}cc.color{{/crossLink}} 来创建一个新的 Color。 + * * @class Color * @extends ValueType */ @@ -64,66 +72,88 @@ var Color = (function () { var DefaultColors = { // color: [r, g, b, a] /** + * !#en TODO + * !#zh 白色 * @property WHITE * @type {Color} * @static */ WHITE: [255, 255, 255, 255], /** + * !#en TODO + * !#zh 黑色 * @property BLACK * @type {Color} * @static */ BLACK: [0, 0, 0, 255], /** + * !#en TODO + * !#zh 透明 * @property TRANSPARENT * @type {Color} * @static */ TRANSPARENT:[0, 0, 0, 0], /** + * !#en TODO + * !#zh 灰色 * @property GRAY * @type {Color} * @static */ GRAY: [127.5, 127.5, 127.5], /** + * !#en TODO + * !#zh 红色 * @property RED * @type {Color} * @static */ RED: [255, 0, 0], /** + * !#en TODO + * !#zh 绿色 * @property GREEN * @type {Color} * @static */ GREEN: [0, 255, 0], /** + * !#en TODO + * !#zh 蓝色 * @property BLUE * @type {Color} * @static */ BLUE: [0, 0, 255], /** + * !#en TODO + * !#zh 黄色 * @property YELLOW * @type {Color} * @static */ YELLOW: [255, 235, 4], /** + * !#en TODO + * !#zh 橙色 * @property ORANGE * @type {Color} * @static */ ORANGE: [255, 127, 0], /** + * !#en TODO + * !#zh 青色 * @property CYAN * @type {Color} * @static */ CYAN: [0, 255, 255], /** + * !#en TODO + * !#zh 洋红色(品红色) * @property MAGENTA * @type {Color} * @static @@ -140,18 +170,31 @@ var Color = (function () { } /** - * Clone a new color from the current color. + * !#en Clone a new color from the current color. + * !#zh 克隆当前颜色。 * @method clone * @return {Color} Newly created color. + * @example + * var color = cc.Color.WHITE; + * var newColor = color.clone(); + * cc.log(newColor); */ Color.prototype.clone = function () { return new Color(this.r, this.g, this.b, this.a); }; /** + * !#en TODO + * !#zh 当前颜色与指定颜色是否相等。 * @method equals * @param {Color} other * @return {Boolean} + * @example + * var color1 = cc.Color.WHITE; + * var color2 = cc.Color.WHITE; + * cc.log(color1.equals(color2)); // return true; + * color2 = cc.Color.RED; + * cc.log(color2.equals(color1)); // return false; */ Color.prototype.equals = function (other) { return other && @@ -162,11 +205,14 @@ var Color = (function () { }; /** + * !#en TODO + * !#zh 插值 * @method lerp * @param {Color} to * @param {number} ratio - the interpolation coefficient. * @param {Color} [out] - optional, the receiving vector. * @return {Color} + * @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCColor/lerp.js} */ Color.prototype.lerp = function (to, ratio, out) { out = out || new Color(); @@ -182,8 +228,13 @@ var Color = (function () { }; /** + * !#en TODO + * !#zh 输出字符串格式。 * @method toString * @return {String} + * @example + * var color = cc.Color.WHITE; + * color.toString(); // return "rgba(255, 255, 255, 255)" */ Color.prototype.toString = function () { return "rgba(" + @@ -195,36 +246,56 @@ var Color = (function () { }; /** + * !#en TODO + * !#zh 设置 Color 中的 R 属性。 * @method setR * @param {Number} red - the new Red component. * @return {Color} this color. + * @example + * var color = cc.Color.BLACK; + * color.setR(255); // return Color {r: 255, g: 0, b: 0, a: 255} */ Color.prototype.setR = function (red) { this.r = red; return this; }; /** + * !#en TODO + * !#zh 设置 Color 中的 G 属性。 * @method setG * @param {Number} green - the new Green component. * @return {Color} this color. + * @example + * var color = cc.Color.BLACK; + * color.setG(255); // return Color {r: 0, g: 255, b: 0, a: 255} */ Color.prototype.setG = function (green) { this.g = green; return this; }; /** + * !#en TODO + * !#zh 设置 Color 中的 B 属性。 * @method setB * @param {Number} blue - the new Blue component. * @return {Color} this color. + * @example + * var color = cc.Color.BLACK; + * color.setB(255); // return Color {r: 0, g: 0, b: 255, a: 255} */ Color.prototype.setB = function (blue) { this.b = blue; return this; }; /** + * !#en TODO + * !#zh 设置 Color 中的 A (透明度) 属性。 * @method setA * @param {Number} alpha - the new Alpha component. * @return {Color} this color. + * @example + * var color = cc.Color.BLACK; + * color.setA(0); // return Color {r: 0, g: 0, b: 0, a: 0} */ Color.prototype.setA = function (alpha) { this.a = alpha; @@ -232,9 +303,12 @@ var Color = (function () { }; /** + * !#en TODO + * !#zh 转换为 CSS 格式。 * @method toCSS * @param {String} opt - "rgba", "rgb", "#rgb" or "#rrggbb". * @return {String} + * @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCColor/toCSS.js} */ Color.prototype.toCSS = function ( opt ) { if ( opt === 'rgba' ) { @@ -258,8 +332,14 @@ var Color = (function () { }; /** - * Clamp this color to make all components between 0 to 1. + * !#en Clamp this color to make all components between 0 to 1. + * !#zh 限制颜色数值,在 0 到 255 之间。 * @method clamp + * @example + * var color = cc.Color.BLACK; + * cc.log(color); // return Color {r: 0, g: 0, b: 0, a: 255}; + * color.r = 1000; // return Color {r: 1000, g: 0, b: 0, a: 255}; + * color.clamp(); // return Color {r: 255, g: 0, b: 0, a: 255}; */ Color.prototype.clamp = function () { this.r = cc.clampf(this.r, 0, 255); @@ -269,10 +349,15 @@ var Color = (function () { }; /** + * !#en TODO + * !#zh 读取 16 进制。 * @method fromHEX * @param {String} hexString * @return {Color} * @chainable + * @example + * var color = cc.Color.BLACK; + * color.fromHEX("#FFFF33"); // return Color {r: 255, g: 255, b: 51, a: 255}; */ Color.prototype.fromHEX = function (hexString) { var hex = parseInt(((hexString.indexOf('#') > -1) ? hexString.substring(1) : hexString), 16); @@ -283,9 +368,15 @@ var Color = (function () { }; /** + * !#en TODO + * !#zh 转换为 16 进制。 * @method toHEX * @param {String} fmt - "#rgb" or "#rrggbb". * @return {String} + * @example + * var color = cc.Color.BLACK; + * color.toHEX("#rgb"); // return "000"; + * color.toHEX("#rrggbb"); // return "000000"; */ Color.prototype.toHEX = function ( fmt ) { var hex = [ @@ -312,9 +403,13 @@ var Color = (function () { }; /** - * Convert to 24bit rgb value. + * !#en Convert to 24bit rgb value. + * !#zh 转换为 24bit 的RGB值。 * @method toRGBValue * @return {Number} + * @example + * var color = cc.Color.YELLOW; + * color.toRGBValue(); // return 16771844; */ Color.prototype.toRGBValue = function () { return (cc.clampf(this.r, 0, 255) << 16) + @@ -323,12 +418,17 @@ var Color = (function () { }; /** + * !#en TODO + * !#zh 读取 HSV(色彩模型)格式。 * @method fromHSV * @param {Number} h * @param {Number} s * @param {Number} v * @return {Color} * @chainable + * @example + * var color = cc.Color.YELLOW; + * color.fromHSV(0, 0, 1); // return Color {r: 255, g: 255, b: 255, a: 255}; */ Color.prototype.fromHSV = function ( h, s, v ) { var rgb = Color.hsv2rgb( h, s, v ); @@ -339,8 +439,13 @@ var Color = (function () { }; /** + * !#en TODO + * !#zh 转换为 HSV(色彩模型)格式。 * @method toHSV * @return {Object} - {h: number, s: number, v: number}. + * @example + * var color = cc.Color.YELLOW; + * color.toHSV(); // return Object {h: 0.1533864541832669, s: 0.9843137254901961, v: 1}; */ Color.prototype.toHSV = function () { return Color.rgb2hsv( this.r, this.g, this.b ); @@ -350,11 +455,15 @@ var Color = (function () { })(); /** + * !#en TODO + * !#zh RGB 转换为 HSV。 * @method rgb2hsv * @param {Number} r - red, must be [0, 255]. * @param {Number} g - red, must be [0, 255]. * @param {Number} b - red, must be [0, 255]. * @return {Object} - {h: number, s: number, v: number}. + * @example + * cc.Color.rgb2hsv(255, 255, 255); // return Object {h: 0, s: 0, v: 1}; */ Color.rgb2hsv = function ( r, g, b ) { r = r / 255; @@ -379,11 +488,15 @@ Color.rgb2hsv = function ( r, g, b ) { }; /** + * !#en TODO + * !#zh HSV 转换为 RGB。 * @method hsv2rgb * @param {Number} h * @param {Number} s * @param {Number} v * @return {Object} - {r: number, g: number, b: number}}, rgb will be in [0, 255]. + * @example + * cc.Color.hsv2rgb(0, 0, 1); // return Object {r: 255, g: 255, b: 255}; */ Color.hsv2rgb = function ( h, s, v ) { var rgb = { r: 0, g: 0, b: 0 }; @@ -456,15 +569,20 @@ cc.Color = Color; */ /** + * !#en * The convenience method to create a new {{#crossLink "Color/Color:method"}}cc.Color{{/crossLink}} * Alpha channel is optional. Default value is 255. + * + * !#zh + * 通过该方法来创建一个新的 {{#crossLink "Color/Color:method"}}cc.Color{{/crossLink}} + * Alpha 通道是可选的。默认值是 255。 + * * @method color * @param {Number} [r=0] * @param {Number} [g=0] * @param {Number} [b=0] * @param {Number} [a=255] * @return {Color} - * * @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCColor/color.js} */ cc.color = function color (r, g, b, a) { @@ -482,22 +600,29 @@ cc.color = function color (r, g, b, a) { // Functional style API, for backward compatibility /** - * returns true if both ccColor3B are equal. Otherwise it returns false. + * !#en returns true if both ccColor3B are equal. Otherwise it returns false. + * !#zh 如果两个 Color 相等返回 true。否则返回 false。 * @method colorEqual * @param {Color} color1 * @param {Color} color2 * @return {Boolean} true if both ccColor3B are equal. Otherwise it returns false. + * @example + * cc.log(cc.colorEqual(cc.Color.RED, cc.Color.RED)); // return true; */ cc.colorEqual = function (color1, color2) { return color1.r === color2.r && color1.g === color2.g && color1.b === color2.b; }; /** + * !#en * convert a string of color for style to Color. - * e.g. "#ff06ff" to : cc.color(255,6,255) + * e.g. "#ff06ff" to : cc.color(255,6,255)。 + * !#zh 16 进制转换 Color。 * @method hexToColor * @param {String} hex * @return {Color} + * @example + * cc.hexToColor("#FFFF33"); // return Color {r: 255, g: 255, b: 51, a: 255}; */ cc.hexToColor = function (hex) { hex = hex.replace(/^#?/, "0x"); @@ -509,11 +634,16 @@ cc.hexToColor = function (hex) { }; /** + * !#en * convert Color to a string of color for style. * e.g. cc.color(255,6,255) to : "#ff06ff" + * !#zh Color 转换为 16进制。 * @method colorToHex * @param {Color} color * @return {String} + * @example + * var color = new cc.Color(255, 6, 255) + * cc.colorToHex(color); // return #ff06ff; */ cc.colorToHex = function (color) { var hR = color.r.toString(16), hG = color.g.toString(16), hB = color.b.toString(16); diff --git a/cocos2d/core/value-types/CCEnum.js b/cocos2d/core/value-types/CCEnum.js index 1484d2b2f5..b3f5fda4f5 100644 --- a/cocos2d/core/value-types/CCEnum.js +++ b/cocos2d/core/value-types/CCEnum.js @@ -26,33 +26,20 @@ // enum /** - * Define an enum type. If a enum item has a value of -1, it will be given an Integer number according to it's order in the list. Otherwise it will use the value specified by user who writes the enum definition. + * !#en + * Define an enum type.
+ * If a enum item has a value of -1, it will be given an Integer number according to it's order in the list.
+ * Otherwise it will use the value specified by user who writes the enum definition. + * + * !#zh + * 定义一个枚举类型。
+ * 如果枚举项具有值-1,它会根据它的顺序列表给出一个整数。
+ * 否则,它会使用用户指定定义的枚举值。 + * * @method Enum * @param {object} obj - a JavaScript literal object containing enum names and values * @return {object} the defined enum type - * - * @example - Texture.WrapMode = cc.Enum({ - Repeat: -1, - Clamp: -1 -}); - // Texture.WrapMode.Repeat == 0 - // Texture.WrapMode.Clamp == 1 - // Texture.WrapMode[0] == "Repeat" - // Texture.WrapMode[1] == "Clamp" - - var FlagType = cc.Enum({ - Flag1: 1, - Flag2: 2, - Flag3: 4, - Flag4: 8, -}); - var AtlasSizeList = cc.Enum({ - 128: 128, - 256: 256, - 512: 512, - 1024: 1024, -}); + * @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCEnum/Enum.js} */ cc.Enum = function (obj) { diff --git a/cocos2d/core/value-types/CCPointExtension.js b/cocos2d/core/value-types/CCPointExtension.js index c7cdb2a1ee..74ba21de2d 100644 --- a/cocos2d/core/value-types/CCPointExtension.js +++ b/cocos2d/core/value-types/CCPointExtension.js @@ -32,189 +32,251 @@ */ /** - * smallest such that 1.0+FLT_EPSILON != 1.0 - * @constant - * @type Number + * !#en smallest such that 1.0+FLT_EPSILON != 1.0. + * !#zh 它是满足 1.0+FLT_EPSILON != 1.0 的最小的正数。 + * @property POINT_EPSILON + * @type {Number} + * @static */ var POINT_EPSILON = parseFloat('1.192092896e-07F'); /** - * Returns opposite of point. + * !#en Returns opposite of point. + * !#zh 返回相反的指定坐标点。 * @method pNeg * @param {Vec2} point * @return {Vec2} + * @example + * cc.pNeg(cc.v2(10, 10));//-- return Vec2 {x: -10, y: -10}; */ cc.pNeg = function (point) { return cc.p(-point.x, -point.y); }; /** - * Calculates sum of two points. + * !#en Calculates sum of two points. + * !#zh 返回指定两个向量之间的总和。 * @method pAdd * @param {Vec2} v1 * @param {Vec2} v2 * @return {Vec2} - * @examples {@link utils/api/engine/docs/cocos2d/core/support/pAdd.js} + * @example + * cc.pAdd(cc.v2(1, 1), cc.v2(2, 2));//-- return Vec2 {x: 3, y: 3}; */ cc.pAdd = function (v1, v2) { return cc.p(v1.x + v2.x, v1.y + v2.y); }; /** - * Calculates difference of two points. + * !#en Calculates difference of two points. + * !#zh 返回指定两个向量之间的差值。 * @method pSub * @param {Vec2} v1 * @param {Vec2} v2 * @return {Vec2} + * @example + * cc.pSub(cc.v2(20, 20), cc.v2(5, 5)); //-- return Vec2 {x: 15, y: 15}; */ cc.pSub = function (v1, v2) { return cc.p(v1.x - v2.x, v1.y - v2.y); }; /** - * Returns point multiplied by given factor. + * !#en Returns point multiplied by given factor. + * !#zh 返回向量的指定倍数。 * @method pMult * @param {Vec2} point * @param {Number} floatVar * @return {Vec2} + * @example + * cc.pMult(cc.v2(5, 5), 4); // return Vec2 {x: 20, y: 20}; */ cc.pMult = function (point, floatVar) { return cc.p(point.x * floatVar, point.y * floatVar); }; /** - * Calculates midpoint between two points. + * !#en Calculates midpoint between two points. + * !#zh 两个向量之间的中心点。 * @method pMidpoint * @param {Vec2} v1 * @param {Vec2} v2 * @return {Vec2} + * @example + * cc.pMidpoint(cc.v2(10, 10), cc.v2(5, 5)); // return Vec2 {x: 7.5, y: 7.5}; */ cc.pMidpoint = function (v1, v2) { return cc.pMult(cc.pAdd(v1, v2), 0.5); }; /** - * Calculates dot product of two points. + * !#en Calculates dot product of two points. + * !#zh 两个向量之间进行点(积)乘。 * @method pDot * @param {Vec2} v1 * @param {Vec2} v2 * @return {Number} + * @example + * cc.pDot(cc.v2(20, 20), cc.v2(5, 5)); // return 200; */ cc.pDot = function (v1, v2) { return v1.x * v2.x + v1.y * v2.y; }; /** - * Calculates cross product of two points. + * !#en Calculates cross product of two points. + * !#zh 两个向量之间进行叉(积)乘。 * @method pCross * @param {Vec2} v1 * @param {Vec2} v2 * @return {Number} + * @example + * cc.pCross(cc.v2(20, 20), cc.v2(5, 5)); // return 0; */ cc.pCross = function (v1, v2) { return v1.x * v2.y - v1.y * v2.x; }; /** - * Calculates perpendicular of v, rotated 90 degrees counter-clockwise -- cross(v, perp(v)) greater than 0 + * !#en Calculates perpendicular of v, rotated 90 degrees counter-clockwise -- cross(v, perp(v)) greater than 0. + * !#zh 将指定向量逆时针旋转 90 度并返回。 * @method pPerp * @param {Vec2} point * @return {Vec2} + * @example + * cc.pPerp(cc.v2(20, 20)); // return Vec2 {x: -20, y: 20}; */ cc.pPerp = function (point) { return cc.p(-point.y, point.x); }; /** - * Calculates perpendicular of v, rotated 90 degrees clockwise -- cross(v, rperp(v)) smaller than 0 + * !#en Calculates perpendicular of v, rotated 90 degrees clockwise -- cross(v, rperp(v)) smaller than 0. + * !#zh 将指定向量顺时针旋转 90 度并返回。 * @method pRPerp * @param {Vec2} point * @return {Vec2} + * @example + * cc.pRPerp(cc.v2(20, 20)); // return Vec2 {x: 20, y: -20}; */ cc.pRPerp = function (point) { return cc.p(point.y, -point.x); }; /** - * Calculates the projection of v1 over v2. + * !#en Calculates the projection of v1 over v2. + * !#zh 投影,v1 在后 v2 上的投影。 * @method pProject * @param {Vec2} v1 * @param {Vec2} v2 * @return {Vec2} + * @example + * var v1 = cc.v2(20, 20); + * var v2 = cc.v2(5, 5); + * cc.pProject(v1, v2); // return Vec2 {x: 20, y: 20}; */ cc.pProject = function (v1, v2) { return cc.pMult(v2, cc.pDot(v1, v2) / cc.pDot(v2, v2)); }; /** - * Rotates two points. + * !#en Rotates two points. + * !#zh 旋转指定的 2 个向量。 * @method pRotate * @param {Vec2} v1 * @param {Vec2} v2 * @return {Vec2} + * @example + * var v1 = cc.v2(20, 20); + * var v2 = cc.v2(5, 5); + * cc.pRotate(v1, v2); // return Vec2 {x: 0, y: 200}; */ cc.pRotate = function (v1, v2) { return cc.p(v1.x * v2.x - v1.y * v2.y, v1.x * v2.y + v1.y * v2.x); }; /** - * Unrotates two points. + * !#en Unrotates two points. + * !#zh 未旋转指定的 2 个向量。 * @method pUnrotate * @param {Vec2} v1 * @param {Vec2} v2 * @return {Vec2} + * @example + * var v1 = cc.v2(20, 20); + * var v2 = cc.v2(5, 5); + * cc.pUnrotate(v1, v2); // return Vec2 {x: 200, y: 0}; */ cc.pUnrotate = function (v1, v2) { return cc.p(v1.x * v2.x + v1.y * v2.y, v1.y * v2.x - v1.x * v2.y); }; /** - * Calculates the square length of a cc.Vec2 (not calling sqrt() ) + * !#en Calculates the square length of a cc.Vec2 (not calling sqrt() ). + * !#zh 返回指定向量长度的平方。 * @method pLengthSQ * @param {Vec2} v * @return {Number} + * @example + * cc.pLengthSQ(cc.v2(20, 20)); // return 800; */ cc.pLengthSQ = function (v) { return cc.pDot(v, v); }; /** - * Calculates the square distance between two points (not calling sqrt() ) + * !#en Calculates the square distance between two points (not calling sqrt() ). + * !#zh 返回指定 2 个向量之间的距离平方。 * @method pDistanceSQ * @param {Vec2} point1 * @param {Vec2} point2 * @return {Number} + * @example + * var point1 = cc.v2(20, 20); + * var point2 = cc.v2(5, 5); + * cc.pDistanceSQ(point1, point2); // return 450; */ cc.pDistanceSQ = function(point1, point2){ return cc.pLengthSQ(cc.pSub(point1,point2)); }; /** - * Calculates distance between point an origin + * !#en Calculates distance between point an origin. + * !#zh 返回指定向量的长度. * @method pLength * @param {Vec2} v * @return {Number} + * @example + * cc.pLength(cc.v2(20, 20)); // return 28.284271247461902; */ cc.pLength = function (v) { return Math.sqrt(cc.pLengthSQ(v)); }; /** - * Calculates the distance between two points + * !#en Calculates the distance between two points. + * !#zh 返回指定 2 个向量之间的距离。 * @method pDistance * @param {Vec2} v1 * @param {Vec2} v2 * @return {Number} + * @example + * var v1 = cc.v2(20, 20); + * var v2 = cc.v2(5, 5); + * cc.pDistance(v1, v2); // return 21.213203435596427; */ cc.pDistance = function (v1, v2) { return cc.pLength(cc.pSub(v1, v2)); }; /** - * Returns point multiplied to a length of 1. + * !#en Returns this vector with a magnitude of 1. + * !#zh 返回一个长度为 1 的标准化过后的向量。 * @method pNormalize * @param {Vec2} v * @return {Vec2} + * @example + * cc.pNormalize(cc.v2(20, 20)); // return Vec2 {x: 0.7071067811865475, y: 0.7071067811865475}; */ cc.pNormalize = function (v) { var n = cc.pLength(v); @@ -222,32 +284,47 @@ cc.pNormalize = function (v) { }; /** - * Converts radians to a normalized vector. + * !#en Converts radians to a normalized vector. + * !#zh 将弧度转换为一个标准的向量,返回坐标 x = cos(a) , y = sin(a)。 * @method pForAngle * @param {Number} a * @return {Vec2} + * @example + * cc.pForAngle(20); // return Vec2 {x: 0.40808206181339196, y: 0.9129452507276277}; */ cc.pForAngle = function (a) { return cc.p(Math.cos(a), Math.sin(a)); }; /** - * Converts a vector to radians. + * !#en Converts a vector to radians. + * !#zh 返回指定向量转换后的弧度。 * @method pToAngle * @param {Vec2} v * @return {Number} + * @example + * cc.pToAngle(cc.v2(20, 20)); // return 0.7853981633974483; */ cc.pToAngle = function (v) { return Math.atan2(v.y, v.x); }; /** - * Clamp a value between from and to. + * !#en Clamp a value between from and to. + * !#zh + * 返回指定限制区域后的数值。
+ * 数值大于 max_inclusive 则返回 max_inclusive。
+ * 数值小于 min_inclusive 则返回 min_inclusive。
+ * 否则返回自身。 * @method clampf * @param {Number} value * @param {Number} min_inclusive * @param {Number} max_inclusive * @return {Number} + * @example + * var v1 = cc.clampf(20, 0, 20); // return 20; + * var v2 = cc.clampf(-1, 0, 20); // return 0; + * var v3 = cc.clampf(10, 0, 20); // return 10; */ cc.clampf = function (value, min_inclusive, max_inclusive) { if (min_inclusive > max_inclusive) { @@ -259,73 +336,110 @@ cc.clampf = function (value, min_inclusive, max_inclusive) { }; /** - * Clamp a value between 0 and 1. + * !#en Clamp a value between 0 and 1. + * !#zh 返回一个范围在 0 ~ 1 之间的指定数值。 * @method clamp01 * @param {Number} value * @return {Number} + * @example + * var v1 = cc.clampf(20); //-- return 1; + * var v2 = cc.clampf(-1); //-- return 0; + * var v3 = cc.clampf(0.5); //-- return 0.5; */ cc.clamp01 = function (value) { return value < 0 ? 0 : value < 1 ? value : 1; }; /** - * Clamp a point between from and to. + * !#en Clamp a point between from and to. + * !#zh + * 返回指定限制区域后的向量。
+ * 向量大于 max_inclusive 则返回 max_inclusive。
+ * 向量小于 min_inclusive 则返回 min_inclusive。
+ * 否则返回自身。 * @method pClamp * @param {Vec2} p - * @param {Number} min_inclusive - * @param {Number} max_inclusive + * @param {Vec2} min_inclusive + * @param {Vec2} max_inclusive * @return {Vec2} + * @example + * var min_inclusive = cc.v2(0, 0); + * var max_inclusive = cc.v2(20, 20); + * var v1 = cc.pClamp(cc.v2(20, 20), min_inclusive, max_inclusive); // return Vec2 {x: 20, y: 20}; + * var v2 = cc.pClamp(cc.v2(0, 0), min_inclusive, max_inclusive); // return Vec2 {x: 0, y: 0}; + * var v3 = cc.pClamp(cc.v2(10, 10), min_inclusive, max_inclusive); // return Vec2 {x: 10, y: 10}; */ cc.pClamp = function (p, min_inclusive, max_inclusive) { return cc.p(cc.clampf(p.x, min_inclusive.x, max_inclusive.x), cc.clampf(p.y, min_inclusive.y, max_inclusive.y)); }; /** - * Quickly convert cc.Size to a cc.Vec2. + * !#en Quickly convert cc.Size to a cc.Vec2. + * !#zh 快速转换 cc.size 为 cc.vec2。 * @method pFromSize * @param {Size} s * @return {Vec2} + * @example + * cc.pFromSize(new cc.size(20, 20)); //-- return Vec2 {x: 20, y: 20}; */ cc.pFromSize = function (s) { return cc.p(s.width, s.height); }; /** + * !#en * Run a math operation function on each point component
* Math.abs, Math.fllor, Math.ceil, Math.round. - * + * !#zh 通过运行指定的数学运算函数来计算指定的向量。 * @method pCompOp * @param {Vec2} p * @param {Function} opFunc * @return {Vec2} - * @example {@link utils/api/engine/docs/cocos2d/core/support/pCompOp.js} + * @example + * cc.pCompOp(cc.p(-10, -10), Math.abs); // return Vec2 {x: 10, y: 10}; */ cc.pCompOp = function (p, opFunc) { return cc.p(opFunc(p.x), opFunc(p.y)); }; /** - * Linear Interpolation between two points a and b. - * alpha == 0 ? a - * alpha == 1 ? b - * otherwise a value between a..b - * + * !#en + * Linear Interpolation between two points a and b.
+ * alpha == 0 ? a
+ * alpha == 1 ? b
+ * otherwise a value between a..b. + * !#zh + * 两个点 A 和 B 之间的线性插值。
+ * alpha == 0 ? a
+ * alpha == 1 ? b
+ * 否则这个数值在 a ~ b 之间。 * @method pLerp * @param {Vec2} a * @param {Vec2} b * @param {Number} alpha * @return {Vec2} + * @example + * cc.pLerp(cc.v2(20, 20), cc.v2(5, 5), 0.5); // return Vec2 {x: 12.5, y: 12.5}; */ cc.pLerp = function (a, b, alpha) { return cc.pAdd(cc.pMult(a, 1 - alpha), cc.pMult(b, alpha)); }; /** + * !#en TODO + * !#zh + * 进行向量之间的模糊判断。
+ * 判断 2 个向量是否在指定数值的范围之内,如果在则返回 true,反之则返回 false。 * @method pFuzzyEqual * @param {Vec2} a * @param {Vec2} b * @param {Number} variance * @return {Boolean} if points have fuzzy equality which means equal with some degree of variance. + * @example + * var a = cc.v2(20, 20); + * var b = cc.v2(5, 5); + * var b1 = cc.pFuzzyEqual(a, b, 10); // return false; + * var b2 = cc.pFuzzyEqual(a, b, 18); // return true; */ cc.pFuzzyEqual = function (a, b, variance) { if (a.x - variance <= b.x && b.x <= a.x + variance) { @@ -336,17 +450,22 @@ cc.pFuzzyEqual = function (a, b, variance) { }; /** - * Multiplies a nd b components, a.x*b.x, a.y*b.y. + * !#en Multiplies a nd b components, a.x*b.x, a.y*b.y. + * !#zh 组件 a 和 b 向量之间的相乘, a.x * b.x, a.y * b.y。 * @method pCompMult * @param {Vec2} a * @param {Vec2} b * @return {Vec2} + * @example + * cc.pCompMult(acc.v2(20, 20), cc.v2(5, 5)); // return Vec2 {x: 100, y: 100}; */ cc.pCompMult = function (a, b) { return cc.p(a.x * b.x, a.y * b.y); }; /** + * !#en TODO + * !#zh 返回两个向量方向之间带正负号的弧度。 * @method pAngleSigned * @param {Vec2} a * @param {Vec2} b @@ -362,6 +481,8 @@ cc.pAngleSigned = function (a, b) { }; /** + * !#en TODO + * !#zh 获取当前向量与指定向量之间的弧度角。 * @method pAngle * @param {Vec2} a * @param {Vec2} b @@ -374,7 +495,8 @@ cc.pAngle = function (a, b) { }; /** - * Rotates a point counter clockwise by the angle around a pivot. + * !#en Rotates a point counter clockwise by the angle around a pivot. + * !#zh 返回指定向量逆时针旋转围绕轴心的角度点。 * @method pRotateByAngle * @param {Vec2} v - v is the point to rotate * @param {Vec2} pivot - pivot is the pivot, naturally @@ -391,13 +513,16 @@ cc.pRotateByAngle = function (v, pivot, angle) { }; /** + * !#en * A general line-line intersection test * indicating successful intersection of a line
* note that to truly test intersection for segments we have to make
* sure that s & t lie within [0..1] and for rays, make sure s & t > 0
* the hit point is p3 + t * (p4 - p3);
* the hit point also is p1 + s * (p2 - p1); - * + * !#zh + * 返回 A 为起点 B 为终点线段 1 所在直线和 C 为起点 D 为终点线段 2 所在的直线是否相交,
+ * 如果相交返回 true,反之则为 false,参数 retP 是返回交点在线段 1、线段 2 上的比例。 * @method pLineIntersect * @param {Vec2} A - A is the startpoint for the first line P1 = (p1 - p2). * @param {Vec2} B - B is the endpoint for the first line P1 = (p1 - p2). @@ -439,7 +564,8 @@ cc.pLineIntersect = function (A, B, C, D, retP) { }; /** - * ccpSegmentIntersect return YES if Segment A-B intersects with segment C-D. + * !#en ccpSegmentIntersect return YES if Segment A-B intersects with segment C-D. + * !#zh 返回线段 A - B 和线段 C - D 是否相交。 * @method pSegmentIntersect * @param {Vec2} A * @param {Vec2} B @@ -456,7 +582,8 @@ cc.pSegmentIntersect = function (A, B, C, D) { }; /** - * ccpIntersectPoint return the intersection point of line A-B, C-D. + * !#en ccpIntersectPoint return the intersection point of line A-B, C-D. + * !#zh 返回线段 A - B 和线段 C - D 的交点。 * @method pIntersectPoint * @param {Vec2} A * @param {Vec2} B @@ -479,7 +606,8 @@ cc.pIntersectPoint = function (A, B, C, D) { }; /** - * check to see if both points are equal. + * !#en check to see if both points are equal. + * !#zh 检查指定的 2 个向量是否相等。 * @method pSameAs * @param {Vec2} A - A ccp a * @param {Vec2} B - B ccp b to be compared @@ -497,7 +625,8 @@ cc.pSameAs = function (A, B) { // High Perfomance In Place Operationrs --------------------------------------- /** - * sets the position of the point to 0. + * !#en sets the position of the point to 0. + * !#zh 设置指定向量归 0。 * @method pZeroIn * @param {Vec2} v */ @@ -507,7 +636,8 @@ cc.pZeroIn = function(v) { }; /** - * copies the position of one point to another. + * !#en copies the position of one point to another. + * !#zh v1 向量等于 v2 向量的值。 * @method pIn * @param {Vec2} v1 * @param {Vec2} v2 @@ -518,7 +648,8 @@ cc.pIn = function(v1, v2) { }; /** - * multiplies the point with the given factor (inplace). + * !#en multiplies the point with the given factor (inplace). + * !#zh 向量乘于指定倍数。 * @method pMultIn * @param {Vec2} point * @param {Number} floatVar @@ -529,7 +660,8 @@ cc.pMultIn = function(point, floatVar) { }; /** - * subtracts one point from another (inplace). + * !#en subtracts one point from another (inplace). + * !#zh v1 向量减等于 v2 向量的值。 * @method pSubIn * @param {Vec2} v1 * @param {Vec2} v2 @@ -540,7 +672,8 @@ cc.pSubIn = function(v1, v2) { }; /** - * adds one point to another (inplace). + * !#en adds one point to another (inplace). + * !#zh v1 向量加等于 v2 向量的值。 * @method pAddIn * @param {Vec2} v1 * @param {Vec2} v2 @@ -551,7 +684,8 @@ cc.pAddIn = function(v1, v2) { }; /** - * normalizes the point (inplace). + * !#en normalizes the point (inplace). + * !#zh 规范化 v 向量,设置 v 向量长度为 1。 * @method pNormalizeIn * @param {Vec2} v */ diff --git a/cocos2d/core/value-types/CCRect.js b/cocos2d/core/value-types/CCRect.js index 5bdba66970..c3b88a34e1 100644 --- a/cocos2d/core/value-types/CCRect.js +++ b/cocos2d/core/value-types/CCRect.js @@ -27,14 +27,18 @@ var ValueType = require('./CCValueType'); var JS = require('../platform/js'); /** - * A 2D rectangle defined by x, y position and width, height. - * + * !#en A 2D rectangle defined by x, y position and width, height. + * !#zh 通过 X,Y 位置和宽度,高度定义的 2D 矩形。 * @class Rect * @extends ValueType */ /** + * !#en * Constructor of cc.Rect class. * see {{#crossLink "cc/rect:method"}} cc.rect {{/crossLink}} for convenience method. + * !#zh + * CC Rect类构造函数。可以通过 {{#crossLink "cc/rect:method"}} cc.rect {{/crossLink}} 简便方法进行创建。 + * * @method Rect * @param {Number} [x=0] * @param {Number} [y=0] @@ -58,12 +62,15 @@ JS.extend(Rect, ValueType); require('../platform/CCClass').fastDefine('cc.Rect', Rect, ['x', 'y', 'width', 'height']); /** - * Creates a rectangle from two coordinate values. + * !#en Creates a rectangle from two coordinate values. + * !#zh 根据指定 2 个向量创建出一个矩形区域。 * @static * @method fromMinMax * @param {Vec2} v1 * @param {Vec2} v2 * @return {Rect} + * @example + * cc.Rect.fromMinMax(cc.v2(10, 10), cc.v2(20, 20)); // return Rect {x: 10, y: 10, width: 10, height: 10}; */ Rect.fromMinMax = function (v1, v2) { var min_x = Math.min(v1.x, v2.x); @@ -75,12 +82,23 @@ Rect.fromMinMax = function (v1, v2) { }; /** - * Checks if rect contains. + * !#en Checks if rect contains. + * !#zh + * 判断 2 个矩形是否有包含。
+ * 返回 1 为 a 包含 b,如果 -1 为 b 包含 a, + * 0 这则都不包含。 * @static * @method contain * @param a {Rect} Rect a * @param b {Rect} Rect b * @return {Number} The contains result, 1 is a contains b, -1 is b contains a, 0 is no contains. + * @example + * var a = new cc.rect(0, 0, 10, 10); + * var b = new cc.rect(5, 5, 5, 5); + * var c = new cc.rect(20, 20, 10, 10); + * cc.Rect.contain(a, b); // return 1; + * cc.Rect.contain(b, a); // return -1; + * cc.Rect.contain(a, c); // return 0; */ Rect.contain = function _Contain (a, b) { if (a.x <= b.x && @@ -103,17 +121,28 @@ Rect.contain = function _Contain (a, b) { var proto = Rect.prototype; /** + * !#en TODO + * !#zh 克隆一个新的 Rect。 * @method clone * @return {Rect} + * @example + * var a = new cc.rect(0, 0, 10, 10); + * a.clone();// return Rect {x: 0, y: 0, width: 10, height: 10} */ proto.clone = function () { return new Rect(this.x, this.y, this.width, this.height); }; /** + * !#en TODO + * !#zh 是否等于指定的矩形。 * @method equals * @param {Rect} other * @return {Boolean} + * @example + * var a = new cc.rect(0, 0, 10, 10); + * var b = new cc.rect(0, 0, 10, 10); + * a.equals(b);// return true; */ proto.equals = function (other) { return other && @@ -124,11 +153,22 @@ proto.equals = function (other) { }; /** + * !#en TODO + * !#zh Rect 的线性插值。 * @method lerp * @param {Rect} to * @param {Number} ratio - the interpolation coefficient. * @param {Rect} [out] - optional, the receiving vector. * @return {Rect} + * @example + * var a = new cc.rect(0, 0, 10, 10); + * var b = new cc.rect(50, 50, 100, 100); + * update (dt) { + * // method 1; + * var c = a.lerp(b, dt * 0.1); + * // method 2; + * a.lerp(b, dt * 0.1, c); + * } */ proto.lerp = function (to, ratio, out) { out = out || new Rect(); @@ -144,8 +184,13 @@ proto.lerp = function (to, ratio, out) { }; /** + * !#en TODO + * !#zh Rect 用字符串表示。 * @method toString * @return {String} + * @example + * var a = new cc.rect(0, 0, 10, 10); + * a.toString();// return "(0.00, 0.00, 10.00, 10.00)"; */ proto.toString = function () { return '(' + this.x.toFixed(2) + ', ' + this.y.toFixed(2) + ', ' + this.width.toFixed(2) + @@ -153,6 +198,8 @@ proto.toString = function () { }; /** + * !#en TODO + * !#zh 矩形的左坐标。 * @property xMin * @type {Number} */ @@ -165,6 +212,8 @@ Object.defineProperty(proto, 'xMin', { }); /** + * !#en TODO + * !#zh 矩形的顶坐标。 * @property yMin * @type {Number} */ @@ -177,6 +226,8 @@ Object.defineProperty(proto, 'yMin', { }); /** + * !#en TODO + * !#zh 矩形的右坐标。 * @property xMax * @type {Number} */ @@ -186,6 +237,8 @@ Object.defineProperty(proto, 'xMax', { }); /** + * !#en TODO + * !#zh 矩形的底坐标。 * @property yMax * @type {Number} */ @@ -195,6 +248,8 @@ Object.defineProperty(proto, 'yMax', { }); /** + * !#en TODO + * !#zh 矩形的中心点。 * @property center * @type {Number} */ @@ -210,6 +265,8 @@ Object.defineProperty(proto, 'center', { }); /** + * !#en TODO + * !#zh 矩形的大小。 * @property {Size} size */ Object.defineProperty(proto, 'size', { @@ -223,38 +280,55 @@ Object.defineProperty(proto, 'size', { }); /** + * !#en TODO + * !#zh 当前矩形与指定矩形是否相交。 * @method intersects * @param {Rect} rect * @type {Boolean} + * @example + * var a = new cc.rect(0, 0, 10, 10); + * var b = new cc.rect(0, 0, 20, 20); + * a.intersects(b);// return true */ proto.intersects = function (rect) { return cc.rectIntersectsRect(this, rect); }; /** + * !#en TODO + * !#zh 当前矩形是否包含指定坐标点。 * Returns true if the point inside this rectangle. * @method contains * @param {Vec2} point * @type {Boolean} + * @example + * var a = new cc.rect(0, 0, 10, 10); + * var b = new cc.v2(0, 5); + * a.contains(b);// return true */ proto.contains = function (point) { - return (this.x <= point.x && - this.x + this.width >= point.x && - this.y <= point.y && - this.y + this.height >= point.y); + return (this.x < point.x && + this.x + this.width > point.x && + this.y < point.y && + this.y + this.height > point.y); }; /** - * Returns true if the other rect totally inside this rectangle. + * !#en Returns true if the other rect totally inside this rectangle. + * !#zh 当前矩形是否包含指定矩形。 * @method containsRect * @param {Rect} rect * @type {Boolean} + * @example + * var a = new cc.rect(0, 0, 10, 10); + * var b = new cc.rect(0, 0, 20, 20); + * a.containsRect(b);// return true */ proto.containsRect = function (rect) { - return (this.x <= rect.x && - this.x + this.width >= rect.x + rect.width && - this.y <= rect.y && - this.y + this.height >= rect.y + rect.height); + return (this.x < rect.x && + this.x + this.width > rect.x + rect.width && + this.y < rect.y && + this.y + this.height > rect.y + rect.height); }; cc.Rect = Rect; @@ -264,14 +338,19 @@ cc.Rect = Rect; */ /** + * !#en * The convenience method to create a new Rect. * see {{#crossLink "Rect/Rect:method"}}cc.Rect{{/crossLink}} + * !#zh + * 该方法用来快速创建一个新的矩形。{{#crossLink "Rect/Rect:method"}}cc.Rect{{/crossLink}} * @method rect * @param {Number[]|Number} [x=0] * @param {Number} [y=0] * @param {Number} [w=0] * @param {Number} [h=0] * @return {Rect} + * @example + * var a = new cc.rect(0 , 0, 10, 0); */ cc.rect = function rect (x, y, w, h) { return new Rect(x, y, w, h); @@ -281,11 +360,18 @@ cc.rect = function rect (x, y, w, h) { // Functional style API, for backward compatibility /** - * Check whether a rect's value equals to another. + * !#en Check whether a rect's value equals to another. + * !#zh 检查一个矩形的值是否等于另一个。 * @method rectEqualToRect * @param {Rect} rect1 * @param {Rect} rect2 * @return {Boolean} + * @example + * var a = new cc.rect(0, 0, 10, 10); + * var b = new cc.rect(0, 0, 5, 5); + * cc.rectEqualToRect(a, b); // return false; + * var c = new cc.rect(0, 0, 5, 5); + * cc.rectEqualToRect(b, c); // return true; */ cc.rectEqualToRect = function (rect1, rect2) { return rect1 && rect2 && (rect1.x === rect2.x) && (rect1.y === rect2.y) && (rect1.width === rect2.width) && (rect1.height === rect2.height); @@ -296,11 +382,18 @@ cc._rectEqualToZero = function(rect){ }; /** - * Check whether the rect1 contains rect2. + * !#en Check whether the rect1 contains rect2. + * !#zh + * 检查 rect1 矩形是否包含 rect2 矩形。
+ * 注意:如果要允许 rect1 和 rect2 的边界重合,应该用 cc.rectOverlapsRect * @method rectContainsRect * @param {Rect} rect1 * @param {Rect} rect2 * @return {Boolean} + * @example + * var a = new cc.rect(0, 0, 20, 20); + * var b = new cc.rect(10, 10, 20, 20); + * cc.rectContainsRect(a, b); // return true; */ cc.rectContainsRect = function (rect1, rect2) { if (!rect1 || !rect2) @@ -311,70 +404,99 @@ cc.rectContainsRect = function (rect1, rect2) { }; /** - * Returns the rightmost x-value of a rect. + * !#en Returns the rightmost x-value of a rect. + * !#zh 返回指定矩形的最右边的 x 值。 * @method rectGetMaxX * @param {Rect} rect * @return {Number} The rightmost x value. + * @example + * var a = new cc.rect(10, 0, 20, 20); + * cc.rectGetMaxX(a); // return 30; */ cc.rectGetMaxX = function (rect) { return (rect.x + rect.width); }; /** - * Return the midpoint x-value of a rect. + * !#en Return the midpoint x-value of a rect. + * !#zh 返回指定矩形的中心点的 x 值。 * @method rectGetMidX * @param {Rect} rect * @return {Number} The midpoint x value. + * @example + * var a = new cc.rect(10, 0, 20, 20); + * cc.rectGetMidX(a); // return 20; */ cc.rectGetMidX = function (rect) { return (rect.x + rect.width / 2.0); }; /** - * Returns the leftmost x-value of a rect. + * !#en Returns the leftmost x-value of a rect. + * !#zh 返回指定矩形的最左边的 x 值。 * @method rectGetMinX * @param {Rect} rect * @return {Number} The leftmost x value. + * @example + * var a = new cc.rect(10, 0, 20, 20); + * cc.rectGetMinX(a); // return 10; */ cc.rectGetMinX = function (rect) { return rect.x; }; /** - * Return the topmost y-value of a rect. + * !#en Return the topmost y-value of a rect. + * !#zh 返回一个矩形的最上面的 y 值。 * @method rectGetMaxY * @param {Rect} rect * @return {Number} The topmost y value. + * @example + * var a = new cc.rect(0, 10, 20, 20); + * cc.rectGetMaxY(a); // return 30; */ cc.rectGetMaxY = function (rect) { return(rect.y + rect.height); }; /** - * Return the midpoint y-value of `rect'. + * !#en Return the midpoint y-value of `rect'. + * !#zh 返回指定矩形的中心点的 y 值。 * @method rectGetMidY * @param {Rect} rect * @return {Number} The midpoint y value. + * @example + * var a = new cc.rect(0, 10, 20, 20); + * cc.rectGetMidY(a); // return 20; */ cc.rectGetMidY = function (rect) { return rect.y + rect.height / 2.0; }; /** - * Return the bottommost y-value of a rect. + * !#en Return the bottommost y-value of a rect. + * !#zh 返回一个矩形的最下面的 y 值。 * @method rectGetMinY * @param {Rect} rect * @return {Number} The bottommost y value. + * @example + * var a = new cc.rect(0, 10, 20, 20); + * cc.rectGetMinY(a); // return 10; */ cc.rectGetMinY = function (rect) { return rect.y; }; /** - * Check whether a rect contains a point. + * !#en Check whether a rect contains a point. + * !#zh 检查一个矩形是否包含某个坐标点。 * @method rectContainsPoint * @param {Rect} rect * @param {Vec2} point * @return {Boolean} + * @example + * var a = new cc.rect(0, 10, 20, 20); + * var b = cc.v2(0, 10, 10, 10); + * cc.rectContainsPoint(a, b); // return true; */ cc.rectContainsPoint = function (rect, point) { return (point.x >= cc.rectGetMinX(rect) && point.x <= cc.rectGetMaxX(rect) && @@ -382,11 +504,16 @@ cc.rectContainsPoint = function (rect, point) { }; /** - * Check whether a rect intersect with another. + * !#en Check whether a rect intersect with another. + * !#zh 检查一个矩形是否与另一个相交。 * @method rectIntersectsRect * @param {Rect} rectA * @param {Rect} rectB * @return {Boolean} + * @example + * var a = new cc.rect(0, 10, 20, 20); + * var b = new cc.rect(0, 10, 10, 10); + * cc.rectIntersectsRect(a, b); // return true; */ cc.rectIntersectsRect = function (ra, rb) { var maxax = ra.x + ra.width, @@ -397,11 +524,16 @@ cc.rectIntersectsRect = function (ra, rb) { }; /** - * Check whether a rect overlaps another. + * !#en Check whether a rect overlaps another. + * !#zh 检查一个矩形是否重叠另一个。 * @method rectOverlapsRect * @param {Rect} rectA * @param {Rect} rectB * @return {Boolean} + * @example + * var a = new cc.rect(0, 10, 20, 20); + * var b = new cc.rect(0, 10, 10, 10); + * cc.rectOverlapsRect(a, b); // return true; */ cc.rectOverlapsRect = function (rectA, rectB) { return !((rectA.x + rectA.width < rectB.x) || @@ -411,11 +543,16 @@ cc.rectOverlapsRect = function (rectA, rectB) { }; /** - * Returns the smallest rectangle that contains the two source rectangles. + * !#en Returns the smallest rectangle that contains the two source rectangles. + * !#zh 返回一个包含两个指定矩形的最小矩形。 * @method rectUnion * @param {Rect} rectA * @param {Rect} rectB * @return {Rect} + * @example + * var a = new cc.rect(0, 10, 20, 20); + * var b = new cc.rect(0, 10, 10, 10); + * cc.rectUnion(a, b); // return Rect {x: 0, y: 10, width: 20, height: 20}; */ cc.rectUnion = function (rectA, rectB) { var rect = cc.rect(0, 0, 0, 0); @@ -427,11 +564,16 @@ cc.rectUnion = function (rectA, rectB) { }; /** - * Returns the overlapping portion of 2 rectangles. + * !#en Returns the overlapping portion of 2 rectangles. + * !#zh 返回 2 个矩形重叠的部分。 * @method rectUnion * @param {Rect} rectA * @param {Rect} rectB * @return {Rect} + * @example + * var a = new cc.rect(0, 10, 20, 20); + * var b = new cc.rect(0, 10, 10, 10); + * cc.rectIntersection(a, b); // return Rect {x: 0, y: 10, width: 10, height: 10}; */ cc.rectIntersection = function (rectA, rectB) { var intersection = cc.rect( diff --git a/cocos2d/core/value-types/CCSize.js b/cocos2d/core/value-types/CCSize.js index 21b736bcf1..9acf29f62a 100644 --- a/cocos2d/core/value-types/CCSize.js +++ b/cocos2d/core/value-types/CCSize.js @@ -27,8 +27,18 @@ var ValueType = require('./CCValueType'); var JS = require('../platform/js'); /** - * cc.Size is the class for size object, please do not use its constructor to create sizes, use {{#crossLink "cc/size:method"}}{{/crossLink}} alias function instead. - * It will be deprecated soon, please use cc.Vec2 instead + * !#en + * cc.Size is the class for size object,
+ * please do not use its constructor to create sizes,
+ * use {{#crossLink "cc/size:method"}}{{/crossLink}} alias function instead.
+ * It will be deprecated soon, please use cc.Vec2 instead. + * + * !#zh + * cc.Size 是 size 对象的类。
+ * 请不要使用它的构造函数创建的 size,
+ * 使用 {{#crossLink "cc/size:method"}}{{/crossLink}} 别名函数。
+ * 它不久将被取消,请使用cc.Vec2代替。 + * * @class Size */ /** @@ -49,7 +59,8 @@ JS.extend(Size, ValueType); require('../platform/CCClass').fastDefine('cc.Size', Size, ['width', 'height']); /** - * return a Size object with width = 0 and height = 0. + * !#en return a Size object with width = 0 and height = 0. + * !#zh 返回与宽度 = 0 和高度 = 0 Size 的对象。 * @property ZERO * @type {Size} * @default new Size(0, 0) @@ -62,17 +73,27 @@ JS.get(Size, 'ZERO', function () { var proto = Size.prototype; /** + * !#en TODO + * !#zh 克隆 size 对象。 * @method clone * @return {Size} + * @example + * var a = new cc.size(10, 10); + * a.clone();// return Size {width: 0, height: 0}; */ proto.clone = function () { return new Size(this.width, this.height); }; /** + * !#en TODO + * !#zh 当前 size 对象是否等于指定 size 对象。 * @method equals * @param {Size} other * @return {Boolean} + * @example + * var a = new cc.size(10, 10); + * a.equals(new cc.size(10, 10));// return true; */ proto.equals = function (other) { return other && @@ -81,11 +102,22 @@ proto.equals = function (other) { }; /** + * !#en TODO + * !#zh Rect 的线性插值。 * @method lerp * @param {Rect} to * @param {Number} ratio - the interpolation coefficient. * @param {Size} [out] - optional, the receiving vector. * @return {Size} + * @example + * var a = new cc.size(10, 10); + * var b = new cc.rect(50, 50, 100, 100); + * update (dt) { + * // method 1; + * var c = a.lerp(b, dt * 0.1); + * // method 2; + * a.lerp(b, dt * 0.1, c); + * } */ proto.lerp = function (to, ratio, out) { out = out || new Size(); @@ -97,19 +129,27 @@ proto.lerp = function (to, ratio, out) { }; /** + * !#en TODO + * !#zh Size 用字符串表示。 * @method toString * @return {String} + * @example + * var a = new cc.size(10, 10); + * a.toString();// return "(10.00, 10.00)"; */ proto.toString = function () { return '(' + this.width.toFixed(2) + ', ' + this.height.toFixed(2) + ')'; }; /** - * Helper function that creates a cc.Size. + * !#en + * Helper function that creates a cc.Size.
* Please use cc.p or cc.v2 instead, it will soon replace cc.Size. - * + * !#zh + * 创建一个 cc.Size 帮助函数。
+ * 请使用 cc.p 或者是 cc.v2 代替,将很快取代 cc.Size。 * @method size - * @param {Number|Size} w - width or a size object + * @param {Number|Size} w - width or a size object * @param {Number} h - height * @return {Size} * @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCSize/size.js} @@ -119,11 +159,18 @@ cc.size = function (w, h) { }; /** - * Check whether a point's value equals to another. + * !#en Check whether a point's value equals to another. + * !#zh 检查 size 对象是否等于另一个。 * @method sizeEqualToSize * @param {Size} size1 * @param {Size} size2 * @return {Boolean} + * @example + * var a = new cc.size(10, 10); + * var b = new cc.size(10, 10); + * cc.sizeEqualToSize(a, b);// return true; + * var b = new cc.size(5, 10); + * cc.sizeEqualToSize(a, b);// return false; */ cc.sizeEqualToSize = function (size1, size2) { return (size1 && size2 && (size1.width === size2.width) && (size1.height === size2.height)); diff --git a/cocos2d/core/value-types/CCTypes.js b/cocos2d/core/value-types/CCTypes.js index 6af48d93ec..e731cbecb0 100644 --- a/cocos2d/core/value-types/CCTypes.js +++ b/cocos2d/core/value-types/CCTypes.js @@ -25,7 +25,8 @@ ****************************************************************************/ /** - * the device accelerometer reports values for each axis in units of g-force. + * !#en the device accelerometer reports values for each axis in units of g-force. + * !#zh 设备重力传感器传递的各个轴的数据。 * @class Acceleration * @constructor */ @@ -45,7 +46,8 @@ cc.Acceleration = function (x, y, z, timestamp) { }; /** - * Blend Function used for textures. + * !#en Blend Function used for textures. + * !#zh 用于纹理的混合函数。 * @class BlendFunc * @Constructor */ @@ -187,7 +189,9 @@ cc.blendFuncDisable = cc.BlendFunc._disable; * @constructor */ /** - * @method FontDefinition + * !#en TODO + * !#zh 定义字体基本属性的结构体。 + * @method FontDefinition * @param {Object} properties - (OPTIONAL) Allow inline FontDefinition * @return {FontDefinition} */ diff --git a/cocos2d/core/value-types/CCValueType.js b/cocos2d/core/value-types/CCValueType.js index 1436a7d754..f327a009cc 100644 --- a/cocos2d/core/value-types/CCValueType.js +++ b/cocos2d/core/value-types/CCValueType.js @@ -26,7 +26,8 @@ var JS = require('../platform/js'); /** - * The base class of all value types. + * !#en The base class of all value types. + * !#zh 所有 value 类型的基类。 * @class ValueType * @constructor */ @@ -46,7 +47,8 @@ JS.mixin(ValueType.prototype, { }, /** - * Compares this object with the other one. + * !#en Compares this object with the other one. + * !#zh 当前对象是否等于指定对象。 * @method equals * @param {ValueType} other * @return {Boolean} @@ -57,6 +59,8 @@ JS.mixin(ValueType.prototype, { }, /** + * !#en TODO + * !#zh 用字符串表示。 * @method toString * @return {string} */ @@ -65,8 +69,12 @@ JS.mixin(ValueType.prototype, { }, /** + * !#en * Linearly interpolates between this value to to value by ratio which is in the range [0, 1]. * When ratio = 0 returns this. When ratio = 1 return to. When ratio = 0.5 returns the average of this and to. + * !#zh + * 线性插值。
+ * 当 ratio = 0 返回此。当 ratio = 1 返回。当 ratio = 0.5 返回平均值的这个和。 * @method lerp * @param {ValueType} to - the to value * @param {number} ratio - the interpolation coefficient diff --git a/cocos2d/core/value-types/CCVec2.js b/cocos2d/core/value-types/CCVec2.js index a6cc5ad046..1d453873b7 100644 --- a/cocos2d/core/value-types/CCVec2.js +++ b/cocos2d/core/value-types/CCVec2.js @@ -28,16 +28,20 @@ var JS = require('../platform/js'); var FireClass = require('../platform/CCClass'); /** - * Representation of 2D vectors and points. + * !#en Representation of 2D vectors and points. + * !#zh 代表 2D 向量和 points。 * * @class Vec2 * @extends ValueType * @constructor */ - /** +/** + * !#en * Constructor * see {{#crossLink "cc/vec2:method"}}cc.v2{{/crossLink}} or {{#crossLink "cc/p:method"}}cc.p{{/crossLink}} + * !#zh + * 构造函数,可查看 {{#crossLink "cc/vec2:method"}}cc.v2{{/crossLink}} 或者 {{#crossLink "cc/p:method"}}cc.p{{/crossLink}} * @method Vec2 * @param {number} [x=0] * @param {number} [y=0] @@ -67,6 +71,8 @@ JS.mixin(Vec2.prototype, { }, /** + * !#en TODO + * !#zh 设置。 * @method set * @param {Vec2} newValue - !#en new value to set. !#zh 要设置的新值 * @return {Vec2} returns this @@ -79,6 +85,8 @@ JS.mixin(Vec2.prototype, { }, /** + * !#en TODO + * !#zh 当前的向量是否与指定的向量相等。 * @method equals * @param {Vec2} other * @return {Boolean} @@ -88,6 +96,8 @@ JS.mixin(Vec2.prototype, { }, /** + * !#en TODO + * !#zh 用字符串表示。 * @method toString * @return {string} */ @@ -99,6 +109,8 @@ JS.mixin(Vec2.prototype, { }, /** + * !#en TODO + * !#zh 向量线性插值。 * @method lerp * @param {Vec2} to * @param {number} ratio - the interpolation coefficient @@ -115,11 +127,15 @@ JS.mixin(Vec2.prototype, { }, /** - * Adds this vector. If you want to save result to another vector, use add() instead. + * !#en Adds this vector. If you want to save result to another vector, use add() instead. + * !#zh 当前向量加等于指定的向量。如果你想保存结果到另一个向量,使用 add() 代替。 * @method addSelf * @param {Vec2} vector * @return {Vec2} returns this * @chainable + * @example + * var v = cc.v2(10, 10); + * v.addSelf(cc.v2(5, 5));// return Vec2 {x: 15, y: 15}; */ addSelf: function (vector) { this.x += vector.x; @@ -128,11 +144,17 @@ JS.mixin(Vec2.prototype, { }, /** - * Adds two vectors, and returns the new result. + * !#en Adds two vectors, and returns the new result. + * !#zh 当前向量与指定向量进行加法运算,并返回新结果。 * @method add * @param {Vec2} vector * @param {Vec2} [out] - optional, the receiving vector * @return {Vec2} the result + * @example + * var v = cc.v2(10, 10); + * v.add(cc.v2(5, 5)); // return Vec2 {x: 15, y: 15}; + * var v1; + * v.add(cc.v2(5, 5), v1); // return Vec2 {x: 15, y: 15}; */ add: function (vector, out) { out = out || new Vec2(); @@ -142,11 +164,15 @@ JS.mixin(Vec2.prototype, { }, /** - * Subtracts one vector from this. If you want to save result to another vector, use sub() instead. + * !#en Subtracts one vector from this. If you want to save result to another vector, use sub() instead. + * !#zh 当前向量减等于指定的向量。如果你想保存结果到另一个向量,可使用 sub() 代替。 * @method subSelf * @param {Vec2} vector * @return {Vec2} returns this * @chainable + * @example + * var v = cc.v2(10, 10); + * v.subSelf(cc.v2(5, 5));// return Vec2 {x: 5, y: 5}; */ subSelf: function (vector) { this.x -= vector.x; @@ -155,11 +181,17 @@ JS.mixin(Vec2.prototype, { }, /** - * Subtracts one vector from this, and returns the new result. + * !#en Subtracts one vector from this, and returns the new result. + * !#zh 当前向量与指定向量进行减法运算,并返回新结果。 * @method sub * @param {Vec2} vector * @param {Vec2} [out] - optional, the receiving vector * @return {Vec2} the result + * @example + * var v = cc.v2(10, 10); + * v.sub(cc.v2(5, 5)); // return Vec2 {x: 5, y: 5}; + * var v1; + * v.sub(cc.v2(5, 5), v1); // return Vec2 {x: 5, y: 5}; */ sub: function (vector, out) { out = out || new Vec2(); @@ -169,11 +201,15 @@ JS.mixin(Vec2.prototype, { }, /** - * Multiplies this by a number. If you want to save result to another vector, use mul() instead. + * !#en Multiplies this by a number. If you want to save result to another vector, use mul() instead. + * !#zh 当前向量进行 num 倍数的乘法运算。如果你想结果保存到另一个向量,可使用 mul() 代替。 * @method mulSelf * @param {number} num * @return {Vec2} returns this * @chainable + * @example + * var v = cc.v2(10, 10); + * v.mulSelf(5);// return Vec2 {x: 50, y: 50}; */ mulSelf: function (num) { this.x *= num; @@ -182,11 +218,17 @@ JS.mixin(Vec2.prototype, { }, /** - * Multiplies by a number, and returns the new result. + * !#en Multiplies by a number, and returns the new result. + * !#zh 当前向量与指定向量进行乘法运算,并返回新结果。 * @method mul * @param {number} num * @param {Vec2} [out] - optional, the receiving vector * @return {Vec2} the result + * @example + * var v = cc.v2(10, 10); + * v.mul(5); // return Vec2 {x: 50, y: 50}; + * var v1; + * v.mul(5, v1); // return Vec2 {x: 50, y: 50}; */ mul: function (num, out) { out = out || new Vec2(); @@ -196,11 +238,15 @@ JS.mixin(Vec2.prototype, { }, /** - * Multiplies two vectors. + * !#en Multiplies two vectors. + * !#zh 当前向量与指定向量进行相乘。 * @method scaleSelf * @param {Vec2} vector * @return {Vec2} returns this * @chainable + * @example + * var v = cc.v2(10, 10); + * v.scaleSelf(cc.v2(5, 5));// return Vec2 {x: 50, y: 50}; */ scaleSelf: function (vector) { this.x *= vector.x; @@ -209,11 +255,17 @@ JS.mixin(Vec2.prototype, { }, /** - * Multiplies two vectors, and returns the new result. + * !#en Multiplies two vectors, and returns the new result. + * !#zh 当前向量与指定向量进行相乘,并返回新的结果。 * @method scale * @param {Vec2} vector * @param {Vec2} [out] - optional, the receiving vector * @return {Vec2} the result + * @example + * var v = cc.v2(10, 10); + * v.scale(cc.v2(5, 5)); // return Vec2 {x: 50, y: 50}; + * var v1; + * v.scale(cc.v2(5, 5), v1); // return Vec2 {x: 50, y: 50}; */ scale: function (vector, out) { out = out || new Vec2(); @@ -223,11 +275,15 @@ JS.mixin(Vec2.prototype, { }, /** - * Divides by a number. If you want to save result to another vector, use div() instead. + * !#en Divides by a number. If you want to save result to another vector, use div() instead. + * !#zh 当前向量与指定向量进行相除。如果你想结果保存到另一个向量,可使用 div() 代替。 * @method divSelf * @param {Vec2} vector * @return {Vec2} returns this * @chainable + * @example + * var v = cc.v2(10, 10); + * v.divSelf(5); // return Vec2 {x: 2, y: 2}; */ divSelf: function (num) { this.x /= num; @@ -236,11 +292,17 @@ JS.mixin(Vec2.prototype, { }, /** - * Divides by a number, and returns the new result. + * !#en Divides by a number, and returns the new result. + * !#zh 当前向量与指定向量进行相除,并返回新的结果。 * @method div * @param {Vec2} vector * @param {Vec2} [out] - optional, the receiving vector * @return {Vec2} the result + * @example + * var v = cc.v2(10, 10); + * v.div(5); // return Vec2 {x: 2, y: 2}; + * var v1; + * v.div(5, v1); // return Vec2 {x: 2, y: 2}; */ div: function (num, out) { out = out || new Vec2(); @@ -250,10 +312,14 @@ JS.mixin(Vec2.prototype, { }, /** - * Negates the components. If you want to save result to another vector, use neg() instead. + * !#en Negates the components. If you want to save result to another vector, use neg() instead. + * !#zh 当前向量进行取反。如果你想结果保存到另一个向量,可使用 neg() 代替。 * @method negSelf * @return {Vec2} returns this * @chainable + * @example + * var v = cc.v2(10, 10); + * v.negSelf(); // return Vec2 {x: -10, y: -10}; */ negSelf: function () { this.x = -this.x; @@ -262,10 +328,15 @@ JS.mixin(Vec2.prototype, { }, /** - * Negates the components, and returns the new result. + * !#en Negates the components, and returns the new result. + * !#zh 当前向量进行取反,并返回新的结果。 * @method neg * @param {Vec2} [out] - optional, the receiving vector * @return {Vec2} the result + * @example + * var v = cc.v2(10, 10); + * var v1; + * v.neg(v1); // return Vec2 {x: -10, y: -10}; */ neg: function (out) { out = out || new Vec2(); @@ -275,48 +346,68 @@ JS.mixin(Vec2.prototype, { }, /** - * Dot product + * !#en Dot product + * !#zh 当前向量与指定向量进行点(积)乘。 * @method dot * @param {Vec2} [vector] * @return {number} the result + * @example + * var v = cc.v2(10, 10); + * v.dot(cc.v2(5, 5)); // return 100; */ dot: function (vector) { return this.x * vector.x + this.y * vector.y; }, /** - * Cross product + * !#en Cross product + * !#zh 当前向量与指定向量进行点乘叉(积)乘。 * @method cross * @param {Vec2} [vector] * @return {number} the result + * @example + * var v = cc.v2(10, 10); + * v.cross(cc.v2(5, 5)); // return 0; */ cross: function (vector) { return this.y * vector.x - this.x * vector.y; }, /** - * Returns the length of this vector. + * !#en Returns the length of this vector. + * !#zh 返回该向量的长度。 * @method mag * @return {number} the result + * @example + * var v = cc.v2(10, 10); + * v.mag(); // return 14.142135623730951; */ mag: function () { return Math.sqrt(this.x * this.x + this.y * this.y); }, /** - * Returns the squared length of this vector. + * !#en Returns the squared length of this vector. + * !#zh 返回该向量的长度平方。 * @method magSqr * @return {number} the result + * @example + * var v = cc.v2(10, 10); + * v.magSqr(); // return 200; */ magSqr: function () { return this.x * this.x + this.y * this.y; }, /** - * Make the length of this vector to 1. + * !#en Make the length of this vector to 1. + * !#zh 让这个向量的长度为1。 * @method normalizeSelf * @return {Vec2} returns this * @chainable + * @example + * var v = cc.v2(10, 10); + * v.normalizeSelf(); // return Vec2 {x: 0.7071067811865475, y: 0.7071067811865475}; */ normalizeSelf: function () { var magSqr = this.x * this.x + this.y * this.y; @@ -336,12 +427,22 @@ JS.mixin(Vec2.prototype, { }, /** - * Returns this vector with a magnitude of 1. - * + * !#en + * Returns this vector with a magnitude of 1.
+ *
* Note that the current vector is unchanged and a new normalized vector is returned. If you want to normalize the current vector, use normalizeSelf function. + * !#zh + * 返回向量的长度为 1。
+ *
+ * 注意,当前向量不变,并返回一个新的标准化向量。如果你想来标准化当前向量,可使用 normalizeSelf 函数。 * @method normalize * @param {Vec2} [out] - optional, the receiving vector * @return {Vec2} result + * @example + * var v = cc.v2(10, 10); + * v.normalize(); // return Vec2 {x: 0.7071067811865475, y: 0.7071067811865475}; + * var v1; + * v.normalize(v1); // return Vec2 {x: 0.7071067811865475, y: 0.7071067811865475}; */ normalize: function (out) { out = out || new Vec2(); @@ -352,7 +453,8 @@ JS.mixin(Vec2.prototype, { }, /** - * Get angle in radian between this and vector + * !#en Get angle in radian between this and vector. + * !#zh 获取当前向量与指定向量之间的弧度角。 * @method angle * @param {Vec2} vector * @return {number} from 0 to Math.PI @@ -373,7 +475,8 @@ JS.mixin(Vec2.prototype, { }, /** - * Get angle in radian between this and vector with direction + * !#en Get angle in radian between this and vector with direction. + * !#zh 获取当前向量与指定向量之间的弧度和方向向量。 * @method signAngle * @param {Vec2} vector * @return {number} from -MathPI to Math.PI @@ -388,7 +491,8 @@ JS.mixin(Vec2.prototype, { }, /** - * rotate + * !#en rotate + * !#zh 旋转 * @method rotate * @param {number} radians * @param {Vec2} [out] - optional, the receiving vector @@ -402,7 +506,8 @@ JS.mixin(Vec2.prototype, { }, /** - * rotate self + * !#en rotate self + * !#zh 旋转自身 * @method rotateSelf * @param {number} radians * @return {Vec2} returns this @@ -429,7 +534,8 @@ JS.mixin(Vec2.prototype, { // static /** - * return a Vec2 object with x = 1 and y = 1 + * !#en return a Vec2 object with x = 1 and y = 1. + * !#zh 返回 x = 1 和 y = 1 的 Vec2 对象。 * @property ONE * @type Vec2 * @static @@ -439,7 +545,8 @@ JS.get(Vec2, 'ONE', function () { }); /** - * return a Vec2 object with x = 0 and y = 0 + * !#en return a Vec2 object with x = 0 and y = 0. + * !#zh 返回 x = 0 和 y = 0 的 Vec2 对象。 * @property ZERO * @type Vec2 * @static @@ -449,7 +556,8 @@ JS.get(Vec2, 'ZERO', function () { }); /** - * return a Vec2 object with x = 0 and y = 1 + * !#en return a Vec2 object with x = 0 and y = 1. + * !#zh 返回 x = 0 和 y = 1 的 Vec2 对象。 * @property up * @type Vec2 * @static @@ -459,7 +567,8 @@ JS.get(Vec2, 'UP', function () { }); /** - * return a Vec2 object with x = 1 and y = 0 + * !#en return a Vec2 object with x = 1 and y = 0. + * !#zh 返回 x = 1 和 y = 0 的 Vec2 对象。 * @property RIGHT * @type Vec2 * @static @@ -476,18 +585,25 @@ cc.Vec2 = Vec2; /** - * The convenience method to create a new {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}. + * !#en The convenience method to create a new {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}. + * !#zh 通过该简便的函数进行创建 {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}} * @method v2 * @param {Number|Object} [x=0] * @param {Number} [y=0] * @return {Vec2} + * @example + * var v1 = cc.v2(); + * var v2 = cc.v2(0, 0); + * var v3 = cc.v2(v2); + * var v4 = cc.v2({x: 100, y: 100}); */ cc.v2 = function v2 (x, y) { return new Vec2(x, y); }; /** - * The convenience method to creates a new {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}. + * !#en The convenience method to creates a new {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}. + * !#zh 通过该简便的函数进行创建 {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}} * @method p * @param {Number|Object} [x=0] a Number or a size object * @param {Number} [y=0] @@ -504,7 +620,8 @@ cc.p = cc.v2; // Functional style API, for backward compatibility /** - * Check whether a point's value equals to another + * !#en Check whether a point's value equals to another. + * !#zh 检查向量的值是否等于另一个 * @method pointEqualToPoint * @param {Vec2} point1 * @param {Vec2} point2 diff --git a/docs/cocos2d/core/support/pAdd.js b/docs/cocos2d/core/support/pAdd.js deleted file mode 100644 index a1f5e8d7a3..0000000000 --- a/docs/cocos2d/core/support/pAdd.js +++ /dev/null @@ -1,4 +0,0 @@ ------------------ -cc.pAdd( cc.p(1,1), cc.p(2,2) ); // preferred cocos2d way
-cc.pAdd( cc.p(1,1), cc.p(2,2) ); // also ok but more verbose
-cc.pAdd( cc.cpv(1,1), cc.cpv(2,2) ); // mixing chipmunk and cocos2d (avoid)

diff --git a/docs/cocos2d/core/support/pCompOp.js b/docs/cocos2d/core/support/pCompOp.js deleted file mode 100644 index 9facaccb9f..0000000000 --- a/docs/cocos2d/core/support/pCompOp.js +++ /dev/null @@ -1,3 +0,0 @@ --------------- -//For example: let's try to take the floor of x,y -var p = cc.pCompOp(cc.p(10,10),Math.abs); diff --git a/docs/cocos2d/core/value-types/CCColor/color.js b/docs/cocos2d/core/value-types/CCColor/color.js index 86c4819aa4..ebba3138fb 100644 --- a/docs/cocos2d/core/value-types/CCColor/color.js +++ b/docs/cocos2d/core/value-types/CCColor/color.js @@ -1,7 +1,7 @@ ----------------------- // 1. All channels seperately as parameters -var color1 = cc.color(255, 255, 255, 255); +var color1 = cc.Color(255, 255, 255, 255); // 2. Convert a hex string to a color -var color2 = cc.color("#000000"); +var color2 = cc.Color("#000000"); // 3. An color object as parameter -var color3 = cc.color({r: 255, g: 255, b: 255, a: 255}); +var color3 = cc.Color({r: 255, g: 255, b: 255, a: 255}); diff --git a/docs/cocos2d/core/value-types/CCColor/lerp.js b/docs/cocos2d/core/value-types/CCColor/lerp.js new file mode 100644 index 0000000000..8692f31c83 --- /dev/null +++ b/docs/cocos2d/core/value-types/CCColor/lerp.js @@ -0,0 +1,12 @@ +// Converts a white color to a black one trough time. +var oldColor = cc.Color.WHITE; +// Method 2 +update: function (dt) { + var outColor = oldColor.lerp(Color.BLACK, dt * 0.1); + cc.log(outColor); +} +// Method 2 +update: function (dt) { + oldColor.lerp(Color.white, dt * 0.1, outColor); + cc.log(outColor); +} \ No newline at end of file diff --git a/docs/cocos2d/core/value-types/CCColor/toCSS.js b/docs/cocos2d/core/value-types/CCColor/toCSS.js new file mode 100644 index 0000000000..6415aa54c7 --- /dev/null +++ b/docs/cocos2d/core/value-types/CCColor/toCSS.js @@ -0,0 +1,6 @@ +var color = cc.Color.BLACK; +color.toCSS(); // return "#000"; +color.toCSS("rgba"); // return "rgba(0,0,0,1.00)"; +color.toCSS("rgb"); // return "rgba(0,0,0)"; +color.toCSS("#rgb"); // return "#000"; +color.toCSS("#rrggbb"); // return "#000000"; \ No newline at end of file diff --git a/docs/cocos2d/core/value-types/CCEnum/Enum.js b/docs/cocos2d/core/value-types/CCEnum/Enum.js new file mode 100644 index 0000000000..78918c5d18 --- /dev/null +++ b/docs/cocos2d/core/value-types/CCEnum/Enum.js @@ -0,0 +1,23 @@ +Texture.WrapMode = cc.Enum({ + Repeat: -1, + Clamp: -1 +}); + +// Texture.WrapMode.Repeat == 0 +// Texture.WrapMode.Clamp == 1 +// Texture.WrapMode[0] == "Repeat" +// Texture.WrapMode[1] == "Clamp" + +var FlagType = cc.Enum({ + Flag1: 1, + Flag2: 2, + Flag3: 4, + Flag4: 8, +}); + +var AtlasSizeList = cc.Enum({ + 128: 128, + 256: 256, + 512: 512, + 1024: 1024, +}); \ No newline at end of file diff --git a/docs/cocos2d/core/value-types/CCSize/size.js b/docs/cocos2d/core/value-types/CCSize/size.js index d61e901452..d7fba0c2d7 100644 --- a/docs/cocos2d/core/value-types/CCSize/size.js +++ b/docs/cocos2d/core/value-types/CCSize/size.js @@ -1,4 +1,3 @@ ------ var size1 = cc.size(); var size2 = cc.size(100,100); var size3 = cc.size(size2);