From f2f522d77ad87d4dace9c3c91eaa0a2199eb676e Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Wed, 5 Apr 2017 15:52:49 -0700 Subject: [PATCH] Miscellaneous comment cleanup --- core/block.js | 8 +++++--- core/block_drag_surface.js | 8 ++++---- core/block_svg.js | 22 ++++++++++++++-------- core/rendered_connection.js | 36 +++++++++++++++++++++++------------- core/touch.js | 19 +++++++++++++++---- 5 files changed, 61 insertions(+), 32 deletions(-) diff --git a/core/block.js b/core/block.js index c42322e1b..81280a6af 100644 --- a/core/block.js +++ b/core/block.js @@ -119,6 +119,8 @@ Blockly.Block = function(workspace, prototypeName, opt_id) { this.comment = null; /** + * The block's position in workspace units. (0, 0) is at the workspace's + * origin; scale does not change this value. * @type {!goog.math.Coordinate} * @private */ @@ -1445,7 +1447,7 @@ Blockly.Block.prototype.setMutator = function(/* mutator */) { /** * Return the coordinates of the top-left corner of this block relative to the - * drawing surface's origin (0,0). + * drawing surface's origin (0,0), in workspace units. * @return {!goog.math.Coordinate} Object with .x and .y properties. */ Blockly.Block.prototype.getRelativeToSurfaceXY = function() { @@ -1454,8 +1456,8 @@ Blockly.Block.prototype.getRelativeToSurfaceXY = function() { /** * Move a block by a relative offset. - * @param {number} dx Horizontal offset. - * @param {number} dy Vertical offset. + * @param {number} dx Horizontal offset, in workspace units. + * @param {number} dy Vertical offset, in workspace units. */ Blockly.Block.prototype.moveBy = function(dx, dy) { goog.asserts.assert(!this.parentBlock_, 'Block has parent.'); diff --git a/core/block_drag_surface.js b/core/block_drag_surface.js index 942dfa3b9..2c37ed6d7 100644 --- a/core/block_drag_surface.js +++ b/core/block_drag_surface.js @@ -112,10 +112,10 @@ Blockly.BlockDragSurfaceSvg.prototype.setBlocksAndShow = function(blocks) { }; /** - * Translate and scale the entire drag surface group to keep in sync with the - * workspace. - * @param {number} x X translation - * @param {number} y Y translation + * Translate and scale the entire drag surface group to the given position, to + * keep in sync with the workspace. + * @param {number} x X translation in workspace coordinates. + * @param {number} y Y translation in workspace coordinates. * @param {number} scale Scale of the group. */ Blockly.BlockDragSurfaceSvg.prototype.translateAndScaleGroup = function(x, y, scale) { diff --git a/core/block_svg.js b/core/block_svg.js index d8edb1097..418804083 100644 --- a/core/block_svg.js +++ b/core/block_svg.js @@ -99,10 +99,12 @@ goog.inherits(Blockly.BlockSvg, Blockly.Block); /** * Height of this block, not including any statement blocks above or below. + * Height is in workspace units. */ Blockly.BlockSvg.prototype.height = 0; /** * Width of this block, including any connected value blocks. + * Width is in workspace units. */ Blockly.BlockSvg.prototype.width = 0; @@ -324,8 +326,10 @@ Blockly.BlockSvg.prototype.setParent = function(newParent) { /** * Return the coordinates of the top-left corner of this block relative to the - * drawing surface's origin (0,0). - * @return {!goog.math.Coordinate} Object with .x and .y properties. + * drawing surface's origin (0,0), in workspace units. + * This does not change with workspace scale. + * @return {!goog.math.Coordinate} Object with .x and .y properties in + * workspace coordinates. */ Blockly.BlockSvg.prototype.getRelativeToSurfaceXY = function() { var x = 0; @@ -358,8 +362,8 @@ Blockly.BlockSvg.prototype.getRelativeToSurfaceXY = function() { /** * Move a block by a relative offset. - * @param {number} dx Horizontal offset. - * @param {number} dy Vertical offset. + * @param {number} dx Horizontal offset in workspace units. + * @param {number} dy Vertical offset in workspace units. */ Blockly.BlockSvg.prototype.moveBy = function(dx, dy) { goog.asserts.assert(!this.parentBlock_, 'Block has parent.'); @@ -375,8 +379,8 @@ Blockly.BlockSvg.prototype.moveBy = function(dx, dy) { /** * Transforms a block by setting the translation on the transform attribute * of the block's SVG. - * @param {number} x The x coordinate of the translation. - * @param {number} y The y coordinate of the translation. + * @param {number} x The x coordinate of the translation in workspace units. + * @param {number} y The y coordinate of the translation in workspace units. */ Blockly.BlockSvg.prototype.translate = function(x, y) { this.getSvgRoot().setAttribute('transform', @@ -879,8 +883,10 @@ Blockly.BlockSvg.prototype.showContextMenu_ = function(e) { /** * Move the connections for this block and all blocks attached under it. * Also update any attached bubbles. - * @param {number} dx Horizontal offset from current location. - * @param {number} dy Vertical offset from current location. + * @param {number} dx Horizontal offset from current location, in workspace + * units. + * @param {number} dy Vertical offset from current location, in workspace + * units. * @private */ Blockly.BlockSvg.prototype.moveConnections_ = function(dx, dy) { diff --git a/core/rendered_connection.js b/core/rendered_connection.js index 6425dcdfc..47de4a67d 100644 --- a/core/rendered_connection.js +++ b/core/rendered_connection.js @@ -38,15 +38,22 @@ goog.require('Blockly.Connection'); */ Blockly.RenderedConnection = function(source, type) { Blockly.RenderedConnection.superClass_.constructor.call(this, source, type); + + /** + * Workspace units, (0, 0) is top left of block. + * @type {!goog.math.Coordinate} + * @private + */ this.offsetInBlock_ = new goog.math.Coordinate(0, 0); }; goog.inherits(Blockly.RenderedConnection, Blockly.Connection); /** - * Returns the distance between this connection and another connection. + * Returns the distance between this connection and another connection in + * workspace units. * @param {!Blockly.Connection} otherConnection The other connection to measure * the distance to. - * @return {number} The distance between connections. + * @return {number} The distance between connections, in workspace units. */ Blockly.RenderedConnection.prototype.distanceFrom = function(otherConnection) { var xDiff = this.x_ - otherConnection.x_; @@ -102,8 +109,8 @@ Blockly.RenderedConnection.prototype.bumpAwayFrom_ = function(staticConnection) /** * Change the connection's coordinates. - * @param {number} x New absolute x coordinate. - * @param {number} y New absolute y coordinate. + * @param {number} x New absolute x coordinate, in workspace coordinates. + * @param {number} y New absolute y coordinate, in workspace coordinates. */ Blockly.RenderedConnection.prototype.moveTo = function(x, y) { // Remove it from its old location in the database (if already present) @@ -120,8 +127,8 @@ Blockly.RenderedConnection.prototype.moveTo = function(x, y) { /** * Change the connection's coordinates. - * @param {number} dx Change to x coordinate. - * @param {number} dy Change to y coordinate. + * @param {number} dx Change to x coordinate, in workspace units. + * @param {number} dy Change to y coordinate, in workspace units. */ Blockly.RenderedConnection.prototype.moveBy = function(dx, dy) { this.moveTo(this.x_ + dx, this.y_ + dy); @@ -129,9 +136,9 @@ Blockly.RenderedConnection.prototype.moveBy = function(dx, dy) { /** * Move this connection to the location given by its offset within the block and - * the coordinate of the block's top left corner. - * @param {!goog.math.Coordinate} blockTL The coordinate of the top left corner - * of the block. + * the location of the block's top left corner. + * @param {!goog.math.Coordinate} blockTL The location of the top left corner + * of the block, in workspace coordinates. */ Blockly.RenderedConnection.prototype.moveToOffset = function(blockTL) { this.moveTo(blockTL.x + this.offsetInBlock_.x, @@ -140,8 +147,8 @@ Blockly.RenderedConnection.prototype.moveToOffset = function(blockTL) { /** * Set the offset of this connection relative to the top left of its block. - * @param {number} x The new relative x. - * @param {number} y The new relative y. + * @param {number} x The new relative x, in workspace units. + * @param {number} y The new relative y, in workspace units. */ Blockly.RenderedConnection.prototype.setOffsetInBlock = function(x, y) { this.offsetInBlock_.x = x; @@ -170,6 +177,7 @@ Blockly.RenderedConnection.prototype.tighten_ = function() { /** * Find the closest compatible connection to this connection. + * All parameters are in workspace units * @param {number} maxLimit The maximum radius to another connection. * @param {number} dx Horizontal offset between this connection's location * in the database and the current location (as a result of dragging). @@ -294,7 +302,8 @@ Blockly.RenderedConnection.prototype.hideAll = function() { /** * Check if the two connections can be dragged to connect to each other. * @param {!Blockly.Connection} candidate A nearby connection to check. - * @param {number} maxRadius The maximum radius allowed for connections. + * @param {number} maxRadius The maximum radius allowed for connections, in + * workspace units. * @return {boolean} True if the connection is allowed, false otherwise. */ Blockly.RenderedConnection.prototype.isConnectionAllowed = function(candidate, @@ -353,7 +362,8 @@ Blockly.RenderedConnection.prototype.respawnShadow_ = function() { /** * Find all nearby compatible connections to this connection. * Type checking does not apply, since this function is used for bumping. - * @param {number} maxLimit The maximum radius to another connection. + * @param {number} maxLimit The maximum radius to another connection, in + * workspace units. * @return {!Array.} List of connections. * @private */ diff --git a/core/touch.js b/core/touch.js index b73615148..566bd3665 100644 --- a/core/touch.js +++ b/core/touch.js @@ -189,6 +189,20 @@ Blockly.Touch.shouldHandleEvent = function(e) { Blockly.Touch.checkTouchIdentifier(e); }; +/** + * Get the touch identifier from the given event. If it was a mouse event, the + * identifier is the string 'mouse'. + * @param {!Event} e Mouse event or touch event. + * @return {string} The touch identifier from the first changed touch, if + * defined. Otherwise 'mouse'. + */ +Blockly.Touch.getTouchIdentifierFromEvent = function(e) { + return (e.changedTouches && e.changedTouches[0] && + e.changedTouches[0].identifier != undefined && + e.changedTouches[0].identifier != null) ? + e.changedTouches[0].identifier : 'mouse'; +}; + /** * Check whether the touch identifier on the event matches the current saved * identifier. If there is no identifier, that means it's a mouse event and @@ -202,10 +216,7 @@ Blockly.Touch.shouldHandleEvent = function(e) { * saved identifier. */ Blockly.Touch.checkTouchIdentifier = function(e) { - var identifier = (e.changedTouches && e.changedTouches[0] && - e.changedTouches[0].identifier != undefined && - e.changedTouches[0].identifier != null) ? - e.changedTouches[0].identifier : 'mouse'; + var identifier = Blockly.Touch.getTouchIdentifierFromEvent(e); // if (Blockly.touchIdentifier_ )is insufficient because android touch // identifiers may be zero.