CodingPirates/blockly
1
0
Fork 0
mirror of https://github.com/google/blockly.git synced 2026-01-04 15:40:08 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore: Lint TsDoc. (#6353)

Browse Source 
* chore: add linting for tsdoc

* chore: don't require types on return

* chore: remove redundant fileoverview from ts

* chore: change return to returns and add some newlines

* chore: remove license tag

* chore: don't require params/return docs

* chore: remove spurious struct tags

* Revert "chore: change return to returns and add some newlines"

This reverts commit d6d8656a45.

* chore: don't auto-add param names

* chore: disable require-param bc it breaks on this

* return to returns and add line breaks

* chore: configure additional jsdoc rules

* chore: run format

* Revert "chore: remove license tag"

This reverts commit 173455588a.

* chore: allow license tag format

* chore: only require jsdoc on exported items

* chore: add missing jsdoc or silence where needed

* chore: run format

* chore: lint fixes
This commit is contained in:
Maribeth Bottorff
2022-08-23 14:27:22 -07:00
committed by GitHub
parent bb37d1b7aa
commit 037eb59b89
261 changed files with 3876 additions and 2341 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
.eslintrc.json
View File

@@ -88,8 +88,14 @@
"overrides": [{
"files": ["**/*.ts", "**/*.tsx"],
"plugins": [
"@typescript-eslint/eslint-plugin"
"@typescript-eslint/eslint-plugin",
"jsdoc"
],
"settings": {
"jsdoc": {
"mode": "typescript"
}
},
"parser": "@typescript-eslint/parser",
"parserOptions": {
"project": "./tsconfig.json",
@@ -97,11 +103,12 @@
"ecmaVersion": 2020,
"sourceType": "module"
},
"extends": ["plugin:@typescript-eslint/recommended"],
"extends": [
"plugin:@typescript-eslint/recommended",
"plugin:jsdoc/recommended"
],
"rules": {
// TS rules
// Disable JsDoc validation, since we use TsDoc.
"valid-jsdoc": ["off"],
// Blockly uses namespaces to do declaration merging in some cases.
"@typescript-eslint/no-namespace": ["off"],
// Use the updated TypeScript-specific rule.
@@ -126,7 +133,34 @@
// Temporarily disable. 3 problems.
"@typescript-eslint/no-empty-interface": ["off"],
// Temporarily disable. 34 problems.
"func-call-spacing": ["off"]
"func-call-spacing": ["off"],
// TsDoc rules (using JsDoc plugin)
// Disable built-in jsdoc verifier.
"valid-jsdoc": ["off"],
// Don't require types in params and returns docs.
"jsdoc/require-param-type": ["off"],
"jsdoc/require-returns-type": ["off"],
// params and returns docs are optional.
"jsdoc/require-param-description": ["off"],
"jsdoc/require-returns": ["off"],
// Disable for now (breaks on `this` which is not really a param).
"jsdoc/require-param": ["off"],
// Don't auto-add missing jsdoc. Only required on exported items.
"jsdoc/require-jsdoc": ["warn", {"enableFixer": false, "publicOnly": true}],
// Disable because of false alarms with Closure-supported tags.
// Re-enable after Closure is removed.
"jsdoc/check-tag-names": ["off"],
// Re-enable after Closure is removed. There shouldn't even be types in the TsDoc.
// These are "types" because of Closure's @suppress {warningName}
"jsdoc/no-undefined-types": ["off"],
"jsdoc/valid-types": ["off"],
// Disabled due to not handling `this`. If re-enabled, checkDestructured option
// should be left as false.
"jsdoc/check-param-names": ["off", {"checkDestructured": false}],
// Allow any text in the license tag. Other checks are not relevant.
"jsdoc/check-values": ["off"]
}
}]
}

204
core/block.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The class representing one block.
*/
/**
* The class representing one block.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -53,6 +50,7 @@ import type {Workspace} from './workspace.js';
/**
* Class for one block.
* Not normally called directly, workspace.newBlock() is preferred.
*
* @unrestricted
* @alias Blockly.Block
*/
@@ -78,6 +76,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Has this block been disposed of?
*
* @internal
*/
disposed = false;
@@ -184,6 +183,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* A string representing the comment attached to this block.
*
* @deprecated August 2019. Use getCommentText instead.
*/
comment: string|Comment|null = null;
@@ -214,6 +214,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* A count of statement inputs on the block.
*
* @internal
*/
statementInputCount = 0;
@@ -309,6 +310,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Dispose of this block.
*
* @param healStack If true, then try to heal any gap by connecting the next
* statement with the previous statement. Otherwise, dispose of all
* children of this block.
@@ -380,6 +382,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Unplug this block from its superior block. If this block is a statement,
* optionally reconnect the block underneath with the block on top.
*
* @param opt_healStack Disconnect child statement and reconnect stack.
* Defaults to false.
*/
@@ -395,6 +398,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Unplug this block's output from an input on another block. Optionally
* reconnect the block's parent to the only child block, if possible.
*
* @param opt_healStack Disconnect right-side block and connect to left-side
* block. Defaults to false.
*/
@@ -438,7 +442,7 @@ export class Block implements IASTNodeLocation, IDeletable {
* Since only one block can be displaced and attached to the insertion marker
* this should only ever return one connection.
*
* @return The connection on the value input, or null.
* @returns The connection on the value input, or null.
*/
private getOnlyValueConnection_(): Connection|null {
let connection = null;
@@ -459,6 +463,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Unplug this statement block from its superior block. Optionally reconnect
* the block underneath with the block on top.
*
* @param opt_healStack Disconnect child statement and reconnect stack.
* Defaults to false.
*/
@@ -486,8 +491,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Returns all connections originating from this block.
*
* @param _all If true, return all connections even hidden ones.
* @return Array of connections.
* @returns Array of connections.
* @internal
*/
getConnections_(_all: boolean): Connection[] {
@@ -512,10 +518,11 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Walks down a stack of blocks and finds the last next connection on the
* stack.
*
* @param ignoreShadows If true,the last connection on a non-shadow block will
* be returned. If false, this will follow shadows to find the last
* connection.
* @return The last next connection on the stack, or null.
* @returns The last next connection on the stack, or null.
* @internal
*/
lastConnectionInStack(ignoreShadows: boolean): Connection|null {
@@ -542,7 +549,8 @@ export class Block implements IASTNodeLocation, IDeletable {
* parent block is either the block connected to the previous connection (for
* a statement block) or the block connected to the output connection (for a
* value block).
* @return The block (if any) that holds the current block.
*
* @returns The block (if any) that holds the current block.
*/
getParent(): this|null {
return this.parentBlock_;
@@ -550,8 +558,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Return the input that connects to the specified block.
*
* @param block A block connected to an input on this block.
* @return The input (if any) that connects to the specified block.
* @returns The input (if any) that connects to the specified block.
*/
getInputWithBlock(block: Block): Input|null {
for (let i = 0, input; input = this.inputList[i]; i++) {
@@ -567,7 +576,8 @@ export class Block implements IASTNodeLocation, IDeletable {
* block has no surrounding block. A parent block might just be the previous
* statement, whereas the surrounding block is an if statement, while loop,
* etc.
* @return The block (if any) that surrounds the current block.
*
* @returns The block (if any) that surrounds the current block.
*/
getSurroundParent(): this|null {
/* eslint-disable-next-line @typescript-eslint/no-this-alias */
@@ -589,7 +599,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Return the next statement block directly connected to this block.
* @return The next statement block or null.
*
* @returns The next statement block or null.
*/
getNextBlock(): Block|null {
return this.nextConnection && this.nextConnection.targetBlock();
@@ -597,7 +608,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Returns the block connected to the previous connection.
* @return The previous statement block or null.
*
* @returns The previous statement block or null.
*/
getPreviousBlock(): Block|null {
return this.previousConnection && this.previousConnection.targetBlock();
@@ -606,7 +618,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Return the connection on the first statement input on this block, or null
* if there are none.
* @return The first statement connection or null.
*
* @returns The first statement connection or null.
* @internal
*/
getFirstStatementConnection(): Connection|null {
@@ -622,7 +635,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Return the top-most block in this block's tree.
* This will return itself if this block is at the top level.
* @return The root block.
*
* @returns The root block.
*/
getRootBlock(): this {
let rootBlock: this;
@@ -639,7 +653,8 @@ export class Block implements IASTNodeLocation, IDeletable {
* Walk up from the given block up through the stack of blocks to find
* the top block of the sub stack. If we are nested in a statement input only
* find the top-most nested block. Do not go all the way to the root block.
* @return The top block in a stack.
*
* @returns The top block in a stack.
* @internal
*/
getTopStackBlock(): this {
@@ -660,8 +675,9 @@ export class Block implements IASTNodeLocation, IDeletable {
* Includes value and statement inputs, as well as any following statement.
* Excludes any connection on an output tab or any preceding statement.
* Blocks are optionally sorted by position; top to bottom.
*
* @param ordered Sort the list if true.
* @return Array of blocks.
* @returns Array of blocks.
*/
getChildren(ordered: boolean): Block[] {
if (!ordered) {
@@ -685,6 +701,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set parent of this block to be a new block or null.
*
* @param newParent New parent block.
* @internal
*/
@@ -737,8 +754,9 @@ export class Block implements IASTNodeLocation, IDeletable {
* Includes value and statement inputs, as well as any following statements.
* Excludes any connection on an output tab or any preceding statements.
* Blocks are optionally sorted by position; top to bottom.
*
* @param ordered Sort the list if true.
* @return Flattened array of blocks.
* @returns Flattened array of blocks.
*/
getDescendants(ordered: boolean): this[] {
const blocks = [this];
@@ -753,7 +771,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get whether this block is deletable or not.
* @return True if deletable.
*
* @returns True if deletable.
*/
isDeletable(): boolean {
return this.deletable_ && !this.isShadow_ && !this.disposed &&
@@ -762,6 +781,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block is deletable or not.
*
* @param deletable True if deletable.
*/
setDeletable(deletable: boolean) {
@@ -770,7 +790,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get whether this block is movable or not.
* @return True if movable.
*
* @returns True if movable.
*/
isMovable(): boolean {
return this.movable_ && !this.isShadow_ && !this.disposed &&
@@ -779,6 +800,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block is movable or not.
*
* @param movable True if movable.
*/
setMovable(movable: boolean) {
@@ -790,7 +812,8 @@ export class Block implements IASTNodeLocation, IDeletable {
* descendants will put this block over the workspace's capacity this block is
* not duplicatable. If duplicating this block and descendants will put any
* type over their maxInstances this block is not duplicatable.
* @return True if duplicatable.
*
* @returns True if duplicatable.
*/
isDuplicatable(): boolean {
if (!this.workspace.hasBlockLimits()) {
@@ -802,7 +825,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get whether this block is a shadow block or not.
* @return True if a shadow.
*
* @returns True if a shadow.
*/
isShadow(): boolean {
return this.isShadow_;
@@ -810,6 +834,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block is a shadow block or not.
*
* @param shadow True if a shadow.
* @internal
*/
@@ -819,7 +844,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get whether this block is an insertion marker block or not.
* @return True if an insertion marker.
*
* @returns True if an insertion marker.
*/
isInsertionMarker(): boolean {
return this.isInsertionMarker_;
@@ -828,6 +854,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block is an insertion marker block or not.
* Once set this cannot be unset.
*
* @param insertionMarker True if an insertion marker.
* @internal
*/
@@ -837,7 +864,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get whether this block is editable or not.
* @return True if editable.
*
* @returns True if editable.
*/
isEditable(): boolean {
return this.editable_ && !this.disposed && !this.workspace.options.readOnly;
@@ -845,6 +873,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block is editable or not.
*
* @param editable True if editable.
*/
setEditable(editable: boolean) {
@@ -858,7 +887,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Returns if this block has been disposed of / deleted.
* @return True if this block has been disposed of / deleted.
*
* @returns True if this block has been disposed of / deleted.
*/
isDisposed(): boolean {
return this.disposed;
@@ -868,9 +898,10 @@ export class Block implements IASTNodeLocation, IDeletable {
* Find the connection on this block that corresponds to the given connection
* on the other block.
* Used to match connections between a block and its insertion marker.
*
* @param otherBlock The other block to match against.
* @param conn The other connection to match.
* @return The matching connection on this block, or null.
* @returns The matching connection on this block, or null.
* @internal
*/
getMatchingConnection(otherBlock: Block, conn: Connection): Connection|null {
@@ -889,6 +920,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set the URL of this block's help page.
*
* @param url URL string for block help, or function that returns a URL. Null
* for no help.
*/
@@ -898,6 +930,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Sets the tooltip for this block.
*
* @param newTip The text for the tooltip, a function that returns the text
* for the tooltip, or a parent object whose tooltip will be used. To not
* display a tooltip pass the empty string.
@@ -908,7 +941,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Returns the tooltip text for this block.
* @return The tooltip text for this block.
*
* @returns The tooltip text for this block.
*/
getTooltip(): string {
return Tooltip.getTooltipOfObject(this);
@@ -916,7 +950,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get the colour of a block.
* @return #RRGGBB string.
*
* @returns #RRGGBB string.
*/
getColour(): string {
return this.colour_;
@@ -924,7 +959,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get the name of the block style.
* @return Name of the block style.
*
* @returns Name of the block style.
*/
getStyleName(): string {
return this.styleName_;
@@ -932,7 +968,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get the HSV hue value of a block. Null if hue not set.
* @return Hue value (0-360).
*
* @returns Hue value (0-360).
*/
getHue(): number|null {
return this.hue_;
@@ -940,6 +977,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Change the colour of a block.
*
* @param colour HSV hue value (0 to 360), #RRGGBB string, or a message
* reference string pointing to one of those two values.
*/
@@ -951,6 +989,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set the style and colour values of a block.
*
* @param blockStyleName Name of the block style.
*/
setStyle(blockStyleName: string) {
@@ -962,6 +1001,7 @@ export class Block implements IASTNodeLocation, IDeletable {
* changes, replacing any prior onchange handler. This is usually only called
* from the constructor, the block type initializer function, or an extension
* initializer function.
*
* @param onchangeFn The callback to call when the block's workspace changes.
* @throws {Error} if onchangeFn is not falsey and not a function.
*/
@@ -979,8 +1019,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Returns the named field from a block.
*
* @param name The name of the field.
* @return Named field, or null if field does not exist.
* @returns Named field, or null if field does not exist.
*/
getField(name: string): Field|null {
if (typeof name !== 'string') {
@@ -1002,7 +1043,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Return all variables referenced by this block.
* @return List of variable ids.
*
* @returns List of variable ids.
*/
getVars(): string[] {
const vars = [];
@@ -1018,7 +1060,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Return all variables referenced by this block.
* @return List of variable models.
*
* @returns List of variable models.
* @internal
*/
getVarModels(): VariableModel[] {
@@ -1042,6 +1085,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Notification that a variable is renaming but keeping the same ID. If the
* variable is in use on this block, rerender to show the new name.
*
* @param variable The variable being renamed.
* @internal
*/
@@ -1059,6 +1103,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Notification that a variable is renaming.
* If the ID matches one of this block's variables, rename it.
*
* @param oldId ID of variable to rename.
* @param newId ID of new variable. May be the same as oldId, but with an
* updated name.
@@ -1075,8 +1120,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Returns the language-neutral value of the given field.
*
* @param name The name of the field.
* @return Value of the field or null if field does not exist.
* @returns Value of the field or null if field does not exist.
*/
getFieldValue(name: string): AnyDuringMigration {
const field = this.getField(name);
@@ -1088,6 +1134,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Sets the value of the given field for this block.
*
* @param newValue The value to set.
* @param name The name of the field to set the value of.
*/
@@ -1101,6 +1148,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block can chain onto the bottom of another block.
*
* @param newBoolean True if there can be a previous statement.
* @param opt_check Statement type or list of statement types. Null/undefined
* if any type could be connected.
@@ -1132,6 +1180,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether another block can chain onto the bottom of this block.
*
* @param newBoolean True if there can be a next statement.
* @param opt_check Statement type or list of statement types. Null/undefined
* if any type could be connected.
@@ -1163,6 +1212,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block returns a value.
*
* @param newBoolean True if there is an output.
* @param opt_check Returned type or list of returned types. Null or
* undefined if any type could be returned (e.g. variable get).
@@ -1193,6 +1243,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether value inputs are arranged horizontally or vertically.
*
* @param newBoolean True if inputs are horizontal.
*/
setInputsInline(newBoolean: boolean) {
@@ -1205,7 +1256,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get whether value inputs are arranged horizontally or vertically.
* @return True if inputs are horizontal.
*
* @returns True if inputs are horizontal.
*/
getInputsInline(): boolean {
if (this.inputsInline !== undefined) {
@@ -1232,6 +1284,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set the block's output shape.
*
* @param outputShape Value representing an output shape.
*/
setOutputShape(outputShape: number|null) {
@@ -1240,7 +1293,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get the block's output shape.
* @return Value representing output shape if one exists.
*
* @returns Value representing output shape if one exists.
*/
getOutputShape(): number|null {
return this.outputShape_;
@@ -1248,7 +1302,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get whether this block is enabled or not.
* @return True if enabled.
*
* @returns True if enabled.
*/
isEnabled(): boolean {
return !this.disabled;
@@ -1256,6 +1311,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether the block is enabled or not.
*
* @param enabled True if enabled.
*/
setEnabled(enabled: boolean) {
@@ -1270,7 +1326,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get whether the block is disabled or not due to parents.
* The block's own disabled property is not considered.
* @return True if disabled.
*
* @returns True if disabled.
*/
getInheritedDisabled(): boolean {
let ancestor = this.getSurroundParent();
@@ -1286,7 +1343,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get whether the block is collapsed or not.
* @return True if collapsed.
*
* @returns True if collapsed.
*/
isCollapsed(): boolean {
return this.collapsed_;
@@ -1294,6 +1352,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether the block is collapsed or not.
*
* @param collapsed True if collapsed.
*/
setCollapsed(collapsed: boolean) {
@@ -1306,10 +1365,11 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Create a human-readable text representation of this block and any children.
*
* @param opt_maxLength Truncate the string to this length.
* @param opt_emptyToken The placeholder string used to denote an empty field.
* If not specified, '?' is used.
* @return Text of block.
* @returns Text of block.
*/
toString(opt_maxLength?: number, opt_emptyToken?: string): string {
let text = [];
@@ -1324,8 +1384,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Whether or not to add parentheses around an input.
*
* @param connection The connection.
* @return True if we should add parentheses around the input.
* @returns True if we should add parentheses around the input.
*/
function shouldAddParentheses(connection: Connection): boolean {
let checks = connection.getCheck();
@@ -1424,9 +1485,10 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Shortcut for appending a value input row.
*
* @param name Language-neutral identifier which may used to find this input
* again. Should be unique to this block.
* @return The input object created.
* @returns The input object created.
*/
appendValueInput(name: string): Input {
return this.appendInput_(inputTypes.VALUE, name);
@@ -1434,9 +1496,10 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Shortcut for appending a statement input row.
*
* @param name Language-neutral identifier which may used to find this input
* again. Should be unique to this block.
* @return The input object created.
* @returns The input object created.
*/
appendStatementInput(name: string): Input {
return this.appendInput_(inputTypes.STATEMENT, name);
@@ -1444,9 +1507,10 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Shortcut for appending a dummy input row.
*
* @param opt_name Language-neutral identifier which may used to find this
* input again. Should be unique to this block.
* @return The input object created.
* @returns The input object created.
*/
appendDummyInput(opt_name?: string): Input {
return this.appendInput_(inputTypes.DUMMY, opt_name || '');
@@ -1455,6 +1519,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Initialize this block using a cross-platform, internationalization-friendly
* JSON description.
*
* @param json Structured data describing the block.
*/
jsonInit(json: AnyDuringMigration) {
@@ -1549,6 +1614,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Initialize the colour of this block from the JSON description.
*
* @param json Structured data describing the block.
* @param warningPrefix Warning prefix string identifying block.
*/
@@ -1569,6 +1635,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Initialize the style of this block from the JSON description.
*
* @param json Structured data describing the block.
* @param warningPrefix Warning prefix string identifying block.
*/
@@ -1587,6 +1654,7 @@ export class Block implements IASTNodeLocation, IDeletable {
* the block, including prototype values. This provides some insurance against
* mixin / extension incompatibilities with future block features. This check
* can be disabled by passing true as the second argument.
*
* @param mixinObj The key/values pairs to add to this block object.
* @param opt_disableCheck Option flag to disable overwrite checks.
*/
@@ -1613,6 +1681,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Interpolate a message description onto the block.
*
* @param message Text contains interpolation tokens (%1, %2, ...) that match
* with fields or inputs defined in the args array.
* @param args Array of arguments to be interpolated.
@@ -1654,6 +1723,7 @@ export class Block implements IASTNodeLocation, IDeletable {
* Validates that the tokens are within the correct bounds, with no
* duplicates, and that all of the arguments are referred to. Throws errors if
* any of these things are not true.
*
* @param tokens An array of tokens to validate
* @param argsCount The number of args that need to be referred to.
*/
@@ -1689,11 +1759,12 @@ export class Block implements IASTNodeLocation, IDeletable {
* Inserts args in place of numerical tokens. String args are converted to
* JSON that defines a label field. If necessary an extra dummy input is added
* to the end of the elements.
*
* @param tokens The tokens to interpolate
* @param args The arguments to insert.
* @param lastDummyAlign The alignment the added dummy input should have, if
* we are required to add one.
* @return The JSON definitions of field and inputs to add to the block.
* @returns The JSON definitions of field and inputs to add to the block.
*/
private interpolateArguments_(
tokens: Array<string|number>, args: Array<AnyDuringMigration|string>,
@@ -1734,8 +1805,9 @@ export class Block implements IASTNodeLocation, IDeletable {
* Creates a field from the JSON definition of a field. If a field with the
* given type cannot be found, this attempts to create a different field using
* the 'alt' property of the JSON definition (if it exists).
*
* @param element The element to try to turn into a field.
* @return The field defined by the JSON, or null if one couldn't be created.
* @returns The field defined by the JSON, or null if one couldn't be created.
*/
private fieldFromJson_(element: {alt?: string, type?: string, text?: string}):
Field|null {
@@ -1753,10 +1825,11 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Creates an input from the JSON definition of an input. Sets the input's
* check and alignment if they are provided.
*
* @param element The JSON to turn into an input.
* @param warningPrefix The prefix to add to warnings to help the developer
* debug.
* @return The input that has been created, or null if one could not be
* @returns The input that has been created, or null if one could not be
* created for some reason (should never happen).
*/
private inputFromJson_(element: AnyDuringMigration, warningPrefix: string):
@@ -1803,8 +1876,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Returns true if the given string matches one of the input keywords.
*
* @param str The string to check.
* @return True if the given string matches one of the input keywords, false
* @returns True if the given string matches one of the input keywords, false
* otherwise.
*/
private isInputKeyword_(str: string): boolean {
@@ -1815,8 +1889,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Turns a string into the JSON definition of a label field. If the string
* becomes an empty string when trimmed, this returns null.
*
* @param str String to turn into the JSON definition of a label field.
* @return The JSON definition or null.
* @returns The JSON definition or null.
*/
private stringToFieldJson_(str: string): {text: string, type: string}|null {
str = str.trim();
@@ -1831,10 +1906,11 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Add a value input, statement input or local variable to this block.
*
* @param type One of Blockly.inputTypes.
* @param name Language-neutral identifier which may used to find this input
* again. Should be unique to this block.
* @return The input object created.
* @returns The input object created.
*/
protected appendInput_(type: number, name: string): Input {
let connection = null;
@@ -1855,6 +1931,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Move a named input to a different location on this block.
*
* @param name The name of the input to move.
* @param refName Name of input that should be after the moved input, or null
* to be the input at the end.
@@ -1890,6 +1967,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Move a numbered input to a different location on this block.
*
* @param inputIndex Index of the input to move.
* @param refIndex Index of input that should be after the moved input.
*/
@@ -1916,9 +1994,10 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Remove an input from this block.
*
* @param name The name of the input.
* @param opt_quiet True to prevent an error if input is not present.
* @return True if operation succeeds, false if input is not present and
* @returns True if operation succeeds, false if input is not present and
* opt_quiet is true.
* @throws {Error} if the input is not present and opt_quiet is not true.
*/
@@ -1941,8 +2020,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Fetches the named input object.
*
* @param name The name of the input.
* @return The input object, or null if input does not exist.
* @returns The input object, or null if input does not exist.
*/
getInput(name: string): Input|null {
for (let i = 0, input; input = this.inputList[i]; i++) {
@@ -1956,8 +2036,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Fetches the block attached to the named input.
*
* @param name The name of the input.
* @return The attached value block, or null if the input is either
* @returns The attached value block, or null if the input is either
* disconnected or if the input does not exist.
*/
getInputTargetBlock(name: string): Block|null {
@@ -1967,7 +2048,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Returns the comment on this block (or null if there is no comment).
* @return Block's comment.
*
* @returns Block's comment.
*/
getCommentText(): string|null {
return this.commentModel.text;
@@ -1975,6 +2057,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set this block's comment text.
*
* @param text The text, or null to delete.
*/
setCommentText(text: string|null) {
@@ -1991,6 +2074,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set this block's warning text.
*
* @param _text The text, or null to delete.
* @param _opt_id An optional ID for the warning text to be able to maintain
* multiple warnings.
@@ -2000,6 +2084,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Give this block a mutator dialog.
*
* @param _mutator A mutator dialog instance or null to remove.
*/
setMutator(_mutator: Mutator) {}
@@ -2008,7 +2093,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Return the coordinates of the top-left corner of this block relative to the
* drawing surface's origin (0,0), in workspace units.
* @return Object with .x and .y properties.
*
* @returns Object with .x and .y properties.
*/
getRelativeToSurfaceXY(): Coordinate {
return this.xy_;
@@ -2016,6 +2102,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Move a block by a relative offset.
*
* @param dx Horizontal offset, in workspace units.
* @param dy Vertical offset, in workspace units.
*/
@@ -2032,8 +2119,9 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Create a connection of the specified type.
*
* @param type The type of the connection to create.
* @return A new connection of the specified type.
* @returns A new connection of the specified type.
*/
protected makeConnection_(type: number): Connection {
return new Connection(this, type);
@@ -2042,9 +2130,10 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Recursively checks whether all statement and value inputs are filled with
* blocks. Also checks all following statement blocks in this stack.
*
* @param opt_shadowBlocksAreFilled An optional argument controlling whether
* shadow blocks are counted as filled. Defaults to true.
* @return True if all inputs are filled, false otherwise.
* @returns True if all inputs are filled, false otherwise.
*/
allInputsFilled(opt_shadowBlocksAreFilled?: boolean): boolean {
// Account for the shadow block filledness toggle.
@@ -2082,7 +2171,8 @@ export class Block implements IASTNodeLocation, IDeletable {
* Intended to on be used in console logs and errors. If you need a string
* that uses the user's native language (including block text, field values,
* and child blocks), use [toString()]{@link Block#toString}.
* @return The description.
*
* @returns The description.
*/
toDevString(): string {
let msg = this.type ? '"' + this.type + '" block' : 'Block';

12
core/block_animations.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Methods animating a block on connection and disconnection.
*/
/**
* Methods animating a block on connection and disconnection.
*
* @namespace Blockly.blockAnimations
*/
import * as goog from '../closure/goog/goog.js';
@@ -37,6 +34,7 @@ let disconnectGroup: SVGElement|null = null;
/**
* Play some UI effects (sound, animation) when disposing of a block.
*
* @param block The block being disposed of.
* @alias Blockly.blockAnimations.disposeUiEffect
* @internal
@@ -59,6 +57,7 @@ export function disposeUiEffect(block: BlockSvg) {
* Animate a cloned block and eventually dispose of it.
* This is a class method, not an instance method since the original block has
* been destroyed and is no longer accessible.
*
* @param clone SVG element to animate and dispose of.
* @param rect Starting rect of the clone.
* @param rtl True if RTL, false if LTR.
@@ -87,6 +86,7 @@ function disposeUiStep(
/**
* Play some UI effects (sound, ripple) after a connection has been established.
*
* @param block The block being connected.
* @alias Blockly.blockAnimations.connectionUiEffect
* @internal
@@ -124,6 +124,7 @@ export function connectionUiEffect(block: BlockSvg) {
/**
* Expand a ripple around a connection.
*
* @param ripple Element to animate.
* @param start Date of animation's start.
* @param scale Scale of workspace.
@@ -142,6 +143,7 @@ function connectionUiStep(ripple: SVGElement, start: Date, scale: number) {
/**
* Play some UI effects (sound, animation) when disconnecting a block.
*
* @param block The block being disconnected.
* @alias Blockly.blockAnimations.disconnectUiEffect
* @internal
@@ -167,6 +169,7 @@ export function disconnectUiEffect(block: BlockSvg) {
/**
* Animate a brief wiggle of a disconnected block.
*
* @param group SVG element to animate.
* @param magnitude Maximum degrees skew (reversed for RTL).
* @param start Date of animation's start.
@@ -190,6 +193,7 @@ function disconnectUiStep(group: SVGElement, magnitude: number, start: Date) {
/**
* Stop the disconnect UI animation immediately.
*
* @alias Blockly.blockAnimations.disconnectUiStop
* @internal
*/

30
core/block_drag_surface.ts
View File

@@ -4,15 +4,6 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview A class that manages a surface for dragging blocks. When a
* block drag is started, we move the block (and children) to a separate DOM
* element that we move around using translate3d. At the end of the drag, the
* blocks are put back in into the SVG they came from. This helps
* performance by avoiding repainting the entire SVG on every mouse move
* while dragging blocks.
*/
/**
* A class that manages a surface for dragging blocks. When a
* block drag is started, we move the block (and children) to a separate DOM
@@ -20,6 +11,7 @@
* blocks are put back in into the SVG they came from. This helps
* performance by avoiding repainting the entire SVG on every mouse move
* while dragging blocks.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -35,6 +27,7 @@ import * as svgMath from './utils/svg_math.js';
/**
* Class for a drag surface for the currently dragged block. This is a separate
* SVG that contains only the currently moving block, or nothing.
*
* @alias Blockly.BlockDragSurfaceSvg
*/
export class BlockDragSurfaceSvg {
@@ -92,6 +85,7 @@ export class BlockDragSurfaceSvg {
/**
* Set the SVG blocks on the drag surface's group and show the surface.
* Only one block group should be on the drag surface at a time.
*
* @param blocks Block or group of blocks to place on the drag surface.
*/
setBlocksAndShow(blocks: SVGElement) {
@@ -107,6 +101,7 @@ export class BlockDragSurfaceSvg {
/**
* Translate and scale the entire drag surface group to the given position, to
* keep in sync with the workspace.
*
* @param x X translation in pixel coordinates.
* @param y Y translation in pixel coordinates.
* @param scale Scale of the group.
@@ -125,6 +120,7 @@ export class BlockDragSurfaceSvg {
/**
* Translate the drag surface's SVG based on its internal state.
*
* @private
*/
translateSurfaceInternal_() {
@@ -139,6 +135,7 @@ export class BlockDragSurfaceSvg {
/**
* Translates the entire surface by a relative offset.
*
* @param deltaX Horizontal offset in pixel units.
* @param deltaY Vertical offset in pixel units.
*/
@@ -154,6 +151,7 @@ export class BlockDragSurfaceSvg {
* We translate the drag surface instead of the blocks inside the surface
* so that the browser avoids repainting the SVG.
* Because of this, the drag coordinates must be adjusted by scale.
*
* @param x X translation for the entire surface.
* @param y Y translation for the entire surface.
*/
@@ -165,7 +163,8 @@ export class BlockDragSurfaceSvg {
/**
* Reports the surface translation in scaled workspace coordinates.
* Use this when finishing a drag to return blocks to the correct position.
* @return Current translation of the surface.
*
* @returns Current translation of the surface.
*/
getSurfaceTranslation(): Coordinate {
const xy = svgMath.getRelativeXY(this.svg_ as SVGElement);
@@ -175,7 +174,8 @@ export class BlockDragSurfaceSvg {
/**
* Provide a reference to the drag group (primarily for
* BlockSvg.getRelativeToSurfaceXY).
* @return Drag surface group element.
*
* @returns Drag surface group element.
*/
getGroup(): SVGElement|null {
return this.dragGroup_;
@@ -183,6 +183,7 @@ export class BlockDragSurfaceSvg {
/**
* Returns the SVG drag surface.
*
* @returns The SVG drag surface.
*/
getSvgRoot(): SVGElement|null {
@@ -192,7 +193,8 @@ export class BlockDragSurfaceSvg {
/**
* Get the current blocks on the drag surface, if any (primarily
* for BlockSvg.getRelativeToSurfaceXY).
* @return Drag surface block DOM element, or null if no blocks exist.
*
* @returns Drag surface block DOM element, or null if no blocks exist.
*/
getCurrentBlock(): Element|null {
return this.dragGroup_.firstChild as Element;
@@ -202,7 +204,8 @@ export class BlockDragSurfaceSvg {
* Gets the translation of the child block surface
* This surface is in charge of keeping track of how much the workspace has
* moved.
* @return The amount the workspace has been moved.
*
* @returns The amount the workspace has been moved.
*/
getWsTranslation(): Coordinate {
// Returning a copy so the coordinate can not be changed outside this class.
@@ -214,6 +217,7 @@ export class BlockDragSurfaceSvg {
* element.
* If the block is being deleted it doesn't need to go back to the original
* surface, since it would be removed immediately during dispose.
*
* @param opt_newSurface Surface the dragging blocks should be moved to, or
* null if the blocks should be removed from this surface without being
* moved to a different surface.

32
core/block_dragger.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Methods for dragging a block visually.
*/
/**
* Methods for dragging a block visually.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -37,6 +34,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Class for a block dragger. It moves blocks around the workspace when they
* are being dragged by a mouse or touch.
*
* @alias Blockly.BlockDragger
*/
export class BlockDragger implements IBlockDragger {
@@ -84,6 +82,7 @@ export class BlockDragger implements IBlockDragger {
/**
* Sever all links from this object.
*
* @internal
*/
dispose() {
@@ -96,6 +95,7 @@ export class BlockDragger implements IBlockDragger {
/**
* Start dragging a block. This includes moving it to the drag surface.
*
* @param currentDragDeltaXY How far the pointer has moved from the position
* at mouse down, in pixel units.
* @param healStack Whether or not to heal the stack after disconnecting.
@@ -132,8 +132,9 @@ export class BlockDragger implements IBlockDragger {
/**
* Whether or not we should disconnect the block when a drag is started.
*
* @param healStack Whether or not to heal the stack after disconnecting.
* @return True to disconnect the block, false otherwise.
* @returns True to disconnect the block, false otherwise.
*/
protected shouldDisconnect_(healStack: boolean): boolean {
return !!(
@@ -144,6 +145,7 @@ export class BlockDragger implements IBlockDragger {
/**
* Disconnects the block and moves it to a new location.
*
* @param healStack Whether or not to heal the stack after disconnecting.
* @param currentDragDeltaXY How far the pointer has moved from the position
* at mouse down, in pixel units.
@@ -169,6 +171,7 @@ export class BlockDragger implements IBlockDragger {
/**
* Execute a step of block dragging, based on the given event. Update the
* display accordingly.
*
* @param e The most recent move event.
* @param currentDragDeltaXY How far the pointer has moved from the position
* at the start of the drag, in pixel units.
@@ -201,6 +204,7 @@ export class BlockDragger implements IBlockDragger {
/**
* Finish a block drag and put the block back on the workspace.
*
* @param e The mouseup/touchend event.
* @param currentDragDeltaXY How far the pointer has moved from the position
* at the start of the drag, in pixel units.
@@ -254,9 +258,10 @@ export class BlockDragger implements IBlockDragger {
/**
* Calculates the drag delta and new location values after a block is dragged.
*
* @param currentDragDeltaXY How far the pointer has moved from the start of
* the drag, in pixel units.
* @return New location after drag. delta is in workspace units. newLocation
* @returns New location after drag. delta is in workspace units. newLocation
* is the new coordinate where the block should end up.
*/
protected getNewLocationAfterDrag_(currentDragDeltaXY: Coordinate):
@@ -273,7 +278,8 @@ export class BlockDragger implements IBlockDragger {
* May delete the dragging block, if allowed. If `this.wouldDeleteBlock_` is
* not true, the block will not be deleted. This should be called at the end
* of a block drag.
* @return True if the block was deleted.
*
* @returns True if the block was deleted.
*/
protected maybeDeleteBlock_(): boolean {
if (this.wouldDeleteBlock_) {
@@ -288,6 +294,7 @@ export class BlockDragger implements IBlockDragger {
/**
* Updates the necessary information to place a block at a certain location.
*
* @param delta The change in location from where the block started the drag
* to where it ended the drag.
*/
@@ -314,6 +321,7 @@ export class BlockDragger implements IBlockDragger {
* Adds or removes the style of the cursor for the toolbox.
* This is what changes the cursor to display an x when a deletable block is
* held over the toolbox.
*
* @param isEnd True if we are at the end of a drag, false otherwise.
*/
protected updateToolboxStyle_(isEnd: boolean) {
@@ -364,8 +372,9 @@ export class BlockDragger implements IBlockDragger {
* correction for mutator workspaces.
* This function does not consider differing origins. It simply scales the
* input's x and y values.
*
* @param pixelCoord A coordinate with x and y values in CSS pixel units.
* @return The input coordinate divided by the workspace scale.
* @returns The input coordinate divided by the workspace scale.
*/
protected pixelsToWorkspaceUnits_(pixelCoord: Coordinate): Coordinate {
const result = new Coordinate(
@@ -383,6 +392,7 @@ export class BlockDragger implements IBlockDragger {
/**
* Move all of the icons connected to this drag.
*
* @param dxy How far to move the icons from their original positions, in
* workspace units.
*/
@@ -397,7 +407,8 @@ export class BlockDragger implements IBlockDragger {
/**
* Get a list of the insertion markers that currently exist. Drags have 0, 1,
* or 2 insertion markers.
* @return A possibly empty list of insertion marker blocks.
*
* @returns A possibly empty list of insertion marker blocks.
*/
getInsertionMarkers(): BlockSvg[] {
// No insertion markers with the old style of dragged connection managers.
@@ -419,8 +430,9 @@ export interface IconPositionData {
* Make a list of all of the icons (comment, warning, and mutator) that are
* on this block and its descendants. Moving an icon moves the bubble that
* extends from it if that bubble is open.
*
* @param block The root block that is being dragged.
* @return The list of all icons and their locations.
* @returns The list of all icons and their locations.
*/
function initIconData(block: BlockSvg): IconPositionData[] {
// Build a list of icons that need to be moved and where they started.

114
core/block_svg.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Methods for graphically rendering a block as SVG.
*/
/**
* Methods for graphically rendering a block as SVG.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -69,6 +66,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Class for a block's SVG representation.
* Not normally called directly, workspace.newBlock() is preferred.
*
* @alias Blockly.BlockSvg
*/
export class BlockSvg extends Block implements IASTNodeLocationSvg,
@@ -95,6 +93,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* An property used internally to reference the block's rendering debugger.
*
* @internal
*/
renderingDebugger: BlockRenderingDebug|null = null;
@@ -245,7 +244,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Get the secondary colour of a block.
* @return #RRGGBB string.
*
* @returns #RRGGBB string.
*/
getColourSecondary(): string|null {
return this.style.colourSecondary;
@@ -253,7 +253,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Get the tertiary colour of a block.
* @return #RRGGBB string.
*
* @returns #RRGGBB string.
*/
getColourTertiary(): string|null {
return this.style.colourTertiary;
@@ -308,7 +309,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Returns a list of mutator, comment, and warning icons.
* @return List of icons.
*
* @returns List of icons.
*/
getIcons(): Icon[] {
const icons = [];
@@ -326,6 +328,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Sets the parent of this block to be a new block or null.
*
* @param newParent New parent block.
* @internal
*/
@@ -371,7 +374,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* If the block is on the workspace, (0, 0) is the origin of the workspace
* coordinate system.
* This does not change with workspace scale.
* @return Object with .x and .y properties in workspace coordinates.
*
* @returns Object with .x and .y properties in workspace coordinates.
*/
override getRelativeToSurfaceXY(): Coordinate {
let x = 0;
@@ -407,6 +411,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Move a block by a relative offset.
*
* @param dx Horizontal offset in workspace units.
* @param dy Vertical offset in workspace units.
*/
@@ -432,6 +437,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Transforms a block by setting the translation on the transform attribute
* of the block's SVG.
*
* @param x The x coordinate of the translation in workspace units.
* @param y The y coordinate of the translation in workspace units.
*/
@@ -444,6 +450,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* Move this block to its workspace's drag surface, accounting for
* positioning. Generally should be called at the same time as
* setDragging_(true). Does nothing if useDragSurface_ is false.
*
* @internal
*/
moveToDragSurface() {
@@ -466,6 +473,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Move a block to a position.
*
* @param xy The position to move to in workspace units.
*/
moveTo(xy: Coordinate) {
@@ -477,6 +485,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* Move this block back to the workspace block canvas.
* Generally should be called at the same time as setDragging_(false).
* Does nothing if useDragSurface_ is false.
*
* @param newXY The position the block should take on on the workspace canvas,
* in workspace coordinates.
* @internal
@@ -495,6 +504,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* Move this block during a drag, taking into account whether we are using a
* drag surface to translate blocks.
* This block must be a top-level block.
*
* @param newLoc The location to translate to, in workspace coordinates.
* @internal
*/
@@ -556,7 +566,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* Returns the coordinates of a bounding box describing the dimensions of this
* block and any blocks stacked below it.
* Coordinate system: workspace coordinates.
* @return Object with coordinates of the bounding box.
*
* @returns Object with coordinates of the bounding box.
*/
getBoundingRectangle(): Rect {
const blockXY = this.getRelativeToSurfaceXY();
@@ -586,6 +597,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether the block is collapsed or not.
*
* @param collapsed True if collapsed.
*/
override setCollapsed(collapsed: boolean) {
@@ -644,6 +656,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Open the next (or previous) FieldTextInput.
*
* @param start Current field.
* @param forward If true go forward, otherwise backward.
*/
@@ -672,6 +685,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Handle a mouse-down on an SVG block.
*
* @param e Mouse down event or touch start event.
*/
private onMouseDown_(e: Event) {
@@ -683,6 +697,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Load the block's help page in a new window.
*
* @internal
*/
showHelp() {
@@ -695,7 +710,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Generate the context menu for this block.
* @return Context menu options or null if no menu.
*
* @returns Context menu options or null if no menu.
*/
protected generateContextMenu():
Array<ContextMenuOption|LegacyContextMenuOption>|null {
@@ -718,6 +734,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Show the context menu for this block.
*
* @param e Mouse event.
* @internal
*/
@@ -735,6 +752,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Move the connections for this block and all blocks attached under it.
* Also update any attached bubbles.
*
* @param dx Horizontal offset from current location, in workspace units.
* @param dy Vertical offset from current location, in workspace units.
* @internal
@@ -763,6 +781,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Recursively adds or removes the dragging class to this node and its
* children.
*
* @param adding True if adding, false if removing.
* @internal
*/
@@ -785,6 +804,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether this block is movable or not.
*
* @param movable True if movable.
*/
override setMovable(movable: boolean) {
@@ -794,6 +814,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether this block is editable or not.
*
* @param editable True if editable.
*/
override setEditable(editable: boolean) {
@@ -806,6 +827,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Sets whether this block is a shadow block or not.
*
* @param shadow True if a shadow.
* @internal
*/
@@ -817,6 +839,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether this block is an insertion marker block or not.
* Once set this cannot be unset.
*
* @param insertionMarker True if an insertion marker.
* @internal
*/
@@ -834,7 +857,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Return the root node of the SVG or null if none exists.
* @return The root SVG node (probably a group).
*
* @returns The root SVG node (probably a group).
*/
getSvgRoot(): SVGGElement {
return this.svgGroup_;
@@ -842,6 +866,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Dispose of this block.
*
* @param healStack If true, then try to heal any gap by connecting the next
* statement with the previous statement. Otherwise, dispose of all
* children of this block.
@@ -931,7 +956,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Encode a block for copying.
* @return Copy metadata, or null if the block is an insertion marker.
*
* @returns Copy metadata, or null if the block is an insertion marker.
* @internal
*/
toCopyData(): CopyData|null {
@@ -953,6 +979,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Updates the colour of the block to match the block's state.
*
* @internal
*/
applyColour() {
@@ -973,6 +1000,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Updates the color of the block (and children) to match the current disabled
* state.
*
* @internal
*/
updateDisabled() {
@@ -991,7 +1019,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Get the comment icon attached to this block, or null if the block has no
* comment.
* @return The comment icon attached to this block, or null.
*
* @returns The comment icon attached to this block, or null.
*/
getCommentIcon(): Comment|null {
return this.commentIcon_;
@@ -999,6 +1028,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set this block's comment text.
*
* @param text The text, or null to delete.
*/
override setCommentText(text: string|null) {
@@ -1033,6 +1063,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set this block's warning text.
*
* @param text The text, or null to delete.
* @param opt_id An optional ID for the warning text to be able to maintain
* multiple warnings.
@@ -1111,6 +1142,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Give this block a mutator dialog.
*
* @param mutator A mutator dialog instance or null to remove.
*/
override setMutator(mutator: Mutator|null) {
@@ -1131,6 +1163,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether the block is enabled or not.
*
* @param enabled True if enabled.
*/
override setEnabled(enabled: boolean) {
@@ -1145,6 +1178,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether the block is highlighted or not. Block highlighting is
* often used to visually mark blocks currently being executed.
*
* @param highlighted True if highlighted.
*/
setHighlighted(highlighted: boolean) {
@@ -1157,6 +1191,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Adds the visual "select" effect to the block, but does not actually select
* it or fire an event.
*
* @see BlockSvg#select
*/
addSelect() {
@@ -1166,6 +1201,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Removes the visual "select" effect from the block, but does not actually
* unselect it or fire an event.
*
* @see BlockSvg#unselect
*/
removeSelect() {
@@ -1174,6 +1210,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Update the cursor over this block by adding or removing a class.
*
* @param enable True if the delete cursor should be shown, false otherwise.
* @internal
*/
@@ -1187,7 +1224,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Get the colour of a block.
* @return #RRGGBB string.
*
* @returns #RRGGBB string.
*/
override getColour(): string {
return this.style.colourPrimary;
@@ -1195,6 +1233,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Change the colour of a block.
*
* @param colour HSV hue value, or #RRGGBB string.
*/
override setColour(colour: number|string) {
@@ -1212,6 +1251,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set the style and colour values of a block.
*
* @param blockStyleName Name of the block style.
* @throws {Error} if the block style does not exist.
*/
@@ -1239,6 +1279,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* <g> tags do not respect z-index so SVG renders them in the
* order that they are in the DOM. By placing this block first within the
* block group's <g>, it will render on top of any other blocks.
*
* @internal
*/
bringToFront() {
@@ -1260,6 +1301,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether this block can chain onto the bottom of another block.
*
* @param newBoolean True if there can be a previous statement.
* @param opt_check Statement type or list of statement types. Null/undefined
* if any type could be connected.
@@ -1276,6 +1318,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether another block can chain onto the bottom of this block.
*
* @param newBoolean True if there can be a next statement.
* @param opt_check Statement type or list of statement types. Null/undefined
* if any type could be connected.
@@ -1292,6 +1335,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether this block returns a value.
*
* @param newBoolean True if there is an output.
* @param opt_check Returned type or list of returned types. Null or
* undefined if any type could be returned (e.g. variable get).
@@ -1307,6 +1351,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Set whether value inputs are arranged horizontally or vertically.
*
* @param newBoolean True if inputs are horizontal.
*/
override setInputsInline(newBoolean: boolean) {
@@ -1320,9 +1365,10 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Remove an input from this block.
*
* @param name The name of the input.
* @param opt_quiet True to prevent error if input is not present.
* @return True if operation succeeds, false if input is not present and
* @returns True if operation succeeds, false if input is not present and
* opt_quiet is true
* @throws {Error} if the input is not present and opt_quiet is not true.
*/
@@ -1340,6 +1386,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Move a numbered input to a different location on this block.
*
* @param inputIndex Index of the input to move.
* @param refIndex Index of input that should be after the moved input.
*/
@@ -1355,10 +1402,11 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Add a value input, statement input or local variable to this block.
*
* @param type One of Blockly.inputTypes.
* @param name Language-neutral identifier which may used to find this input
* again. Should be unique to this block.
* @return The input object created.
* @returns The input object created.
*/
protected override appendInput_(type: number, name: string): Input {
const input = super.appendInput_(type, name);
@@ -1377,6 +1425,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* Used by the deserializer to be more efficient. Setting a connection's
* tracked_ value to false keeps it from adding itself to the db when it
* gets its first moveTo call, saving expensive ops for later.
*
* @param track If true, start tracking. If false, stop tracking.
* @internal
*/
@@ -1418,10 +1467,11 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Returns connections originating from this block.
*
* @param all If true, return all connections even hidden ones.
* Otherwise, for a non-rendered block return an empty list, and for a
* collapsed block don't return inputs connections.
* @return Array of connections.
* @returns Array of connections.
* @internal
*/
override getConnections_(all: boolean): RenderedConnection[] {
@@ -1450,10 +1500,11 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Walks down a stack of blocks and finds the last next connection on the
* stack.
*
* @param ignoreShadows If true,the last connection on a non-shadow block will
* be returned. If false, this will follow shadows to find the last
* connection.
* @return The last next connection on the stack, or null.
* @returns The last next connection on the stack, or null.
* @internal
*/
override lastConnectionInStack(ignoreShadows: boolean): RenderedConnection
@@ -1465,9 +1516,10 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* Find the connection on this block that corresponds to the given connection
* on the other block.
* Used to match connections between a block and its insertion marker.
*
* @param otherBlock The other block to match against.
* @param conn The other connection to match.
* @return The matching connection on this block, or null.
* @returns The matching connection on this block, or null.
* @internal
*/
override getMatchingConnection(otherBlock: Block, conn: Connection):
@@ -1477,8 +1529,9 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Create a connection of the specified type.
*
* @param type The type of the connection to create.
* @return A new connection of the specified type.
* @returns A new connection of the specified type.
*/
protected override makeConnection_(type: number): RenderedConnection {
return new RenderedConnection(this, type);
@@ -1486,7 +1539,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Return the next statement block directly connected to this block.
* @return The next statement block or null.
*
* @returns The next statement block or null.
*/
override getNextBlock(): BlockSvg|null {
return super.getNextBlock() as BlockSvg;
@@ -1494,7 +1548,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Returns the block connected to the previous connection.
* @return The previous statement block or null.
*
* @returns The previous statement block or null.
*/
override getPreviousBlock(): BlockSvg|null {
return super.getPreviousBlock() as BlockSvg;
@@ -1548,6 +1603,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Schedule snapping to grid and bumping neighbours to occur after a brief
* delay.
*
* @internal
*/
scheduleSnapAndBump() {
@@ -1571,6 +1627,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* Position a block so that it doesn't move the target block when connected.
* The block to position is usually either the first block in a dragged stack
* or an insertion marker.
*
* @param sourceConnection The connection on the moving block's stack.
* @param targetConnection The connection that should stay stationary as this
* block is positioned.
@@ -1591,7 +1648,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
}
/**
* @return The first statement connection or null.
* @returns The first statement connection or null.
* @internal
*/
override getFirstStatementConnection(): RenderedConnection|null {
@@ -1603,8 +1660,9 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* Includes value and statement inputs, as well as any following statement.
* Excludes any connection on an output tab or any preceding statement.
* Blocks are optionally sorted by position; top to bottom.
*
* @param ordered Sort the list if true.
* @return Array of blocks.
* @returns Array of blocks.
*/
override getChildren(ordered: boolean): BlockSvg[] {
return super.getChildren(ordered) as BlockSvg[];
@@ -1612,6 +1670,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Lays out and reflows a block based on its contents and settings.
*
* @param opt_bubble If false, just render this block.
* If true, also render block's parent, grandparent, etc. Defaults to true.
*/
@@ -1694,6 +1753,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Add the cursor SVG to this block's SVG group.
*
* @param cursorSvg The SVG root of the cursor to be added to the block SVG
* group.
* @internal
@@ -1704,6 +1764,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Add the marker SVG to this block's SVG group.
*
* @param markerSvg The SVG root of the marker to be added to the block SVG
* group.
* @internal
@@ -1715,7 +1776,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Returns a bounding box describing the dimensions of this block
* and any blocks stacked below it.
* @return Object with height and width properties in workspace units.
*
* @returns Object with height and width properties in workspace units.
* @internal
*/
getHeightWidth(): {height: number, width: number} {
@@ -1737,6 +1799,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
* Visual effect to show that if the dragging block is dropped, this block
* will be replaced. If a shadow block, it will disappear. Otherwise it will
* bump.
*
* @param add True if highlighting should be added.
* @internal
*/
@@ -1747,6 +1810,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Visual effect to show that if the dragging block is dropped it will connect
* to this input.
*
* @param conn The connection on the input to highlight.
* @param add True if highlighting should be added.
* @internal

39
core/blockly.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The top level namespace used to access the Blockly library.
*/
/**
* The top level namespace used to access the Blockly library.
*
* @namespace Blockly
*/
import * as goog from '../closure/goog/goog.js';
@@ -186,6 +183,7 @@ import {ZoomControls} from './zoom_controls.js';
* buildCompressed gulp task.
* For local builds, you can pass --define='Blockly.VERSION=X.Y.Z' to the
* compiler to override this constant.
*
* @define {string}
* @alias Blockly.VERSION
*/
@@ -290,6 +288,7 @@ export const TOOLBOX_AT_RIGHT = toolbox.Position.RIGHT;
* See workspace.resizeContents to resize the workspace when the contents
* change (e.g. when a block is added or removed).
* Record the height/width of the SVG image.
*
* @param workspace Any workspace in the SVG.
* @see Blockly.common.svgResize
* @alias Blockly.svgResize
@@ -298,6 +297,7 @@ export const svgResize = common.svgResize;
/**
* Close tooltips, context menus, dropdown selections, etc.
*
* @param opt_onlyClosePopups Whether only popups should be closed.
* @see Blockly.WorkspaceSvg.hideChaff
* @alias Blockly.hideChaff
@@ -310,6 +310,7 @@ export function hideChaff(opt_onlyClosePopups?: boolean) {
* Returns the main workspace. Returns the last used main workspace (based on
* focus). Try not to use this function, particularly if there are multiple
* Blockly instances on a page.
*
* @see Blockly.common.getMainWorkspace
* @alias Blockly.getMainWorkspace
*/
@@ -317,6 +318,7 @@ export const getMainWorkspace = common.getMainWorkspace;
/**
* Returns the currently selected copyable object.
*
* @alias Blockly.common.getSelected
*/
export const getSelected = common.getSelected;
@@ -324,6 +326,7 @@ export const getSelected = common.getSelected;
/**
* Define blocks from an array of JSON block definitions, as might be generated
* by the Blockly Developer Tools.
*
* @param jsonArray An array of JSON block definitions.
* @see Blockly.common.defineBlocksWithJsonArray
* @alias Blockly.defineBlocksWithJsonArray
@@ -335,6 +338,7 @@ export const defineBlocksWithJsonArray = common.defineBlocksWithJsonArray;
* dropDownDiv, and Tooltip are rendered into the first time `Blockly.inject`
* is called.
* This method is a NOP if called after the first ``Blockly.inject``.
*
* @param container The container element.
* @see Blockly.common.setParentContainer
* @alias Blockly.setParentContainer
@@ -343,8 +347,9 @@ export const setParentContainer = common.setParentContainer;
/**
* Returns the dimensions of the specified SVG image.
*
* @param svg SVG image.
* @return Contains width and height properties.
* @returns Contains width and height properties.
* @deprecated Use workspace.setCachedParentSvgSize. (2021 March 5)
* @see Blockly.WorkspaceSvg.setCachedParentSvgSize
* @alias Blockly.svgSize
@@ -354,6 +359,7 @@ export const svgSize = svgMath.svgSize;
/**
* Size the workspace when the contents change. This also updates
* scrollbars accordingly.
*
* @param workspace The workspace to resize.
* @deprecated Use workspace.resizeContents. (2021 December)
* @see Blockly.WorkspaceSvg.resizeContents
@@ -369,6 +375,7 @@ export const resizeSvgContents = resizeSvgContentsLocal;
/**
* Copy a block or workspace comment onto the local clipboard.
*
* @param toCopy Block or Workspace Comment to be copied.
* @deprecated Use Blockly.clipboard.copy(). (2021 December)
* @see Blockly.clipboard.copy
@@ -383,7 +390,8 @@ export function copy(toCopy: ICopyable) {
/**
* Paste a block or workspace comment on to the main workspace.
* @return True if the paste was successful, false otherwise.
*
* @returns True if the paste was successful, false otherwise.
* @deprecated Use Blockly.clipboard.paste(). (2021 December)
* @see Blockly.clipboard.paste
* @alias Blockly.paste
@@ -397,6 +405,7 @@ export function paste(): boolean {
/**
* Duplicate this block and its children, or a workspace comment.
*
* @param toDuplicate Block or Workspace Comment to be copied.
* @deprecated Use Blockly.clipboard.duplicate(). (2021 December)
* @see Blockly.clipboard.duplicate
@@ -411,8 +420,9 @@ export function duplicate(toDuplicate: ICopyable) {
/**
* Is the given string a number (includes negative and decimals).
*
* @param str Input string.
* @return True if number, false otherwise.
* @returns True if number, false otherwise.
* @deprecated Use Blockly.utils.string.isNumber(str). (2021 December)
* @see Blockly.utils.string.isNumber
* @alias Blockly.isNumber
@@ -426,8 +436,9 @@ export function isNumber(str: string): boolean {
/**
* Convert a hue (HSV model) into an RGB hex triplet.
*
* @param hue Hue on a colour wheel (0-360).
* @return RGB code, e.g. '#5ba65b'.
* @returns RGB code, e.g. '#5ba65b'.
* @deprecated Use Blockly.utils.colour.hueToHex(). (2021 December)
* @see Blockly.utils.colour.hueToHex
* @alias Blockly.hueToHex
@@ -444,11 +455,12 @@ export function hueToHex(hue: number): string {
* of the active touch stream.
* Use this for events that are not part of a multi-part gesture (e.g.
* mouseover for tooltips).
*
* @param node Node upon which to listen.
* @param name Event name to listen to (e.g. 'mousedown').
* @param thisObject The value of 'this' in the function.
* @param func Function to call when event is triggered.
* @return Opaque data that can be passed to unbindEvent_.
* @returns Opaque data that can be passed to unbindEvent_.
* @deprecated Use Blockly.browserEvents.bind(). (December 2021)
* @see Blockly.browserEvents.bind
* @alias Blockly.bindEvent_
@@ -464,9 +476,10 @@ export function bindEvent_(
/**
* Unbind one or more events event from a function call.
*
* @param bindData Opaque data from bindEvent_.
* This list is emptied during the course of calling this function.
* @return The function call.
* @returns The function call.
* @deprecated Use Blockly.browserEvents.unbind(). (December 2021)
* @see browserEvents.unbind
* @alias Blockly.unbindEvent_
@@ -483,6 +496,7 @@ export function unbindEvent_(bindData: browserEvents.Data): Function {
* touch stream.
* Use this for events that either start or continue a multi-part gesture (e.g.
* mousedown or mousemove, which may be part of a drag or click).
*
* @param node Node upon which to listen.
* @param name Event name to listen to (e.g. 'mousedown').
* @param thisObject The value of 'this' in the function.
@@ -493,7 +507,7 @@ export function unbindEvent_(bindData: browserEvents.Data): Function {
* @param opt_noPreventDefault True if triggering on this event should prevent
* the default handler. False by default. If opt_noPreventDefault is
* provided, opt_noCaptureIdentifier must also be provided.
* @return Opaque data that can be passed to unbindEvent_.
* @returns Opaque data that can be passed to unbindEvent_.
* @deprecated Use Blockly.browserEvents.conditionalBind(). (December 2021)
* @see browserEvents.conditionalBind
* @alias Blockly.bindEventWithChecks_
@@ -523,6 +537,7 @@ export const COLLAPSED_FIELD_NAME = constants.COLLAPSED_FIELD_NAME;
* String for use in the "custom" attribute of a category in toolbox XML.
* This string indicates that the category should be dynamically populated with
* variable blocks.
*
* @alias Blockly.VARIABLE_CATEGORY_NAME
*/
export const VARIABLE_CATEGORY_NAME: string = Variables.CATEGORY_NAME;
@@ -531,6 +546,7 @@ export const VARIABLE_CATEGORY_NAME: string = Variables.CATEGORY_NAME;
* String for use in the "custom" attribute of a category in toolbox XML.
* This string indicates that the category should be dynamically populated with
* variable blocks.
*
* @alias Blockly.VARIABLE_DYNAMIC_CATEGORY_NAME
*/
export const VARIABLE_DYNAMIC_CATEGORY_NAME: string =
@@ -539,6 +555,7 @@ export const VARIABLE_DYNAMIC_CATEGORY_NAME: string =
* String for use in the "custom" attribute of a category in toolbox XML.
* This string indicates that the category should be dynamically populated with
* procedure blocks.
*
* @alias Blockly.PROCEDURE_CATEGORY_NAME
*/
export const PROCEDURE_CATEGORY_NAME: string = Procedures.CATEGORY_NAME;

6
core/blockly_options.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Object that defines user-specified options for the workspace.
*/
/**
* Object that defines user-specified options for the workspace.
*
* @namespace Blockly.BlocklyOptions
*/
import * as goog from '../closure/goog/goog.js';
@@ -22,6 +19,7 @@ import type {ToolboxDefinition} from './utils/toolbox.js';
/**
* Blockly options.
*
* @alias Blockly.BlocklyOptions
*/
export interface BlocklyOptions {

6
core/blocks.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview A mapping of block type names to block prototype objects.
*/
/**
* A mapping of block type names to block prototype objects.
*
* @namespace Blockly.blocks
*/
import * as goog from '../closure/goog/goog.js';
@@ -24,6 +21,7 @@ export type BlockDefinition = AnyDuringMigration;
/**
* A mapping of block type names to block prototype objects.
*
* @alias Blockly.blocks.Blocks
*/
export const Blocks: {[key: string]: BlockDefinition} = Object.create(null);

35
core/browser_events.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Browser event handling.
*/
/**
* Browser event handling.
*
* @namespace Blockly.browserEvents
*/
import * as goog from '../closure/goog/goog.js';
@@ -22,6 +19,7 @@ import * as userAgent from './utils/useragent.js';
/**
* Blockly opaque event data used to unbind events when using
* `bind` and `conditionalBind`.
*
* @alias Blockly.browserEvents.Data
*/
export type Data = [EventTarget, string, (e: Event) => void][];
@@ -45,6 +43,7 @@ const PAGE_MODE_MULTIPLIER = 125;
* touch stream.
* Use this for events that either start or continue a multi-part gesture (e.g.
* mousedown or mousemove, which may be part of a drag or click).
*
* @param node Node upon which to listen.
* @param name Event name to listen to (e.g. 'mousedown').
* @param thisObject The value of 'this' in the function.
@@ -55,13 +54,17 @@ const PAGE_MODE_MULTIPLIER = 125;
* @param opt_noPreventDefault True if triggering on this event should prevent
* the default handler. False by default. If opt_noPreventDefault is
* provided, opt_noCaptureIdentifier must also be provided.
* @return Opaque data that can be passed to unbindEvent_.
* @returns Opaque data that can be passed to unbindEvent_.
* @alias Blockly.browserEvents.conditionalBind
*/
export function conditionalBind(
node: EventTarget, name: string, thisObject: Object|null, func: Function,
opt_noCaptureIdentifier?: boolean, opt_noPreventDefault?: boolean): Data {
let handled = false;
/**
*
* @param e
*/
function wrapFunc(e: Event) {
const captureIdentifier = !opt_noCaptureIdentifier;
// Handle each touch point separately. If the event was a mouse event, this
@@ -119,16 +122,21 @@ export function conditionalBind(
* of the active touch stream.
* Use this for events that are not part of a multi-part gesture (e.g.
* mouseover for tooltips).
*
* @param node Node upon which to listen.
* @param name Event name to listen to (e.g. 'mousedown').
* @param thisObject The value of 'this' in the function.
* @param func Function to call when event is triggered.
* @return Opaque data that can be passed to unbindEvent_.
* @returns Opaque data that can be passed to unbindEvent_.
* @alias Blockly.browserEvents.bind
*/
export function bind(
node: EventTarget, name: string, thisObject: Object|null,
func: Function): Data {
/**
*
* @param e
*/
function wrapFunc(e: Event) {
if (thisObject) {
func.call(thisObject, e);
@@ -179,9 +187,10 @@ export function bind(
/**
* Unbind one or more events event from a function call.
*
* @param bindData Opaque data from bindEvent_.
* This list is emptied during the course of calling this function.
* @return The function call.
* @returns The function call.
* @alias Blockly.browserEvents.unbind
*/
export function unbind(bindData: Data): (e: Event) => void {
@@ -201,8 +210,9 @@ export function unbind(bindData: Data): (e: Event) => void {
/**
* Returns true if this event is targeting a text input widget?
*
* @param e An event.
* @return True if text input.
* @returns True if text input.
* @alias Blockly.browserEvents.isTargetInput
*/
export function isTargetInput(e: Event): boolean {
@@ -230,8 +240,9 @@ export function isTargetInput(e: Event): boolean {
/**
* Returns true this event is a right-click.
*
* @param e Mouse event.
* @return True if right-click.
* @returns True if right-click.
* @alias Blockly.browserEvents.isRightButton
*/
export function isRightButton(e: MouseEvent): boolean {
@@ -246,10 +257,11 @@ export function isRightButton(e: MouseEvent): boolean {
/**
* Returns the converted coordinates of the given mouse event.
* The origin (0,0) is the top-left corner of the Blockly SVG.
*
* @param e Mouse event.
* @param svg SVG element.
* @param matrix Inverted screen CTM to use.
* @return Object with .x and .y properties.
* @returns Object with .x and .y properties.
* @alias Blockly.browserEvents.mouseToSvg
*/
export function mouseToSvg(
@@ -266,8 +278,9 @@ export function mouseToSvg(
/**
* Returns the scroll delta of a mouse event in pixel units.
*
* @param e Mouse event.
* @return Scroll delta object with .x and .y properties.
* @returns Scroll delta object with .x and .y properties.
* @alias Blockly.browserEvents.getScrollDeltaPixels
*/
export function getScrollDeltaPixels(e: WheelEvent): {x: number, y: number} {

58
core/bubble.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Object representing a UI bubble.
*/
/**
* Object representing a UI bubble.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -39,6 +36,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Class for UI bubble.
*
* @alias Blockly.Bubble
*/
export class Bubble implements IBubble {
@@ -129,6 +127,7 @@ export class Bubble implements IBubble {
/**
* Describes whether this bubble has been disposed of (nodes and event
* listeners removed from the page) or not.
*
* @internal
*/
disposed = false;
@@ -141,7 +140,6 @@ export class Bubble implements IBubble {
* @param anchorXY Absolute position of bubble's anchor point.
* @param bubbleWidth Width of bubble, or null if not resizable.
* @param bubbleHeight Height of bubble, or null if not resizable.
* @struct
*/
constructor(
workspace: WorkspaceSvg, content: SVGElement, shape: SVGElement,
@@ -178,9 +176,10 @@ export class Bubble implements IBubble {
/**
* Create the bubble's DOM.
*
* @param content SVG content for the bubble.
* @param hasResize Add diagonal resize gripper if true.
* @return The bubble's SVG group.
* @returns The bubble's SVG group.
*/
private createDom_(content: Element, hasResize: boolean): SVGElement {
/* Create the bubble. Here's the markup that will be generated:
@@ -267,7 +266,8 @@ export class Bubble implements IBubble {
/**
* Return the root node of the bubble's SVG group.
* @return The root SVG node of the bubble's group.
*
* @returns The root SVG node of the bubble's group.
*/
getSvgRoot(): SVGElement {
return this.bubbleGroup_ as SVGElement;
@@ -275,6 +275,7 @@ export class Bubble implements IBubble {
/**
* Expose the block's ID on the bubble's top-level SVG group.
*
* @param id ID of block.
*/
setSvgId(id: string) {
@@ -283,6 +284,7 @@ export class Bubble implements IBubble {
/**
* Handle a mouse-down on bubble's border.
*
* @param e Mouse down event.
*/
private bubbleMouseDown_(e: Event) {
@@ -294,6 +296,7 @@ export class Bubble implements IBubble {
/**
* Show the context menu for this bubble.
*
* @param _e Mouse event.
* @internal
*/
@@ -303,7 +306,8 @@ export class Bubble implements IBubble {
/**
* Get whether this bubble is deletable or not.
* @return True if deletable.
*
* @returns True if deletable.
* @internal
*/
isDeletable(): boolean {
@@ -312,6 +316,7 @@ export class Bubble implements IBubble {
/**
* Update the style of this bubble when it is dragged over a delete area.
*
* @param _enable True if the bubble is about to be deleted, false otherwise.
*/
setDeleteStyle(_enable: boolean) {}
@@ -319,6 +324,7 @@ export class Bubble implements IBubble {
/**
* Handle a mouse-down on bubble's resize corner.
*
* @param e Mouse down event.
*/
private resizeMouseDown_(e: MouseEvent) {
@@ -346,6 +352,7 @@ export class Bubble implements IBubble {
/**
* Resize this bubble to follow the mouse.
*
* @param e Mouse move event.
*/
private resizeMouseMove_(e: MouseEvent) {
@@ -360,6 +367,7 @@ export class Bubble implements IBubble {
/**
* Register a function as a callback event for when the bubble is resized.
*
* @param callback The function to call on resize.
*/
registerResizeEvent(callback: () => void) {
@@ -368,6 +376,7 @@ export class Bubble implements IBubble {
/**
* Register a function as a callback event for when the bubble is moved.
*
* @param callback The function to call on move.
*/
registerMoveEvent(callback: () => void) {
@@ -376,7 +385,8 @@ export class Bubble implements IBubble {
/**
* Move this bubble to the top of the stack.
* @return Whether or not the bubble has been moved.
*
* @returns Whether or not the bubble has been moved.
* @internal
*/
promote(): boolean {
@@ -391,6 +401,7 @@ export class Bubble implements IBubble {
/**
* Notification that the anchor has moved.
* Update the arrow and bubble accordingly.
*
* @param xy Absolute location.
*/
setAnchorLocation(xy: Coordinate) {
@@ -461,11 +472,12 @@ export class Bubble implements IBubble {
/**
* Calculate the what percentage of the bubble overlaps with the visible
* workspace (what percentage of the bubble is visible).
*
* @param relativeMin The position of the top-left corner of the bubble
* relative to the anchor point.
* @param viewMetrics The view metrics of the workspace the bubble will appear
* in.
* @return The percentage of the bubble that is visible.
* @returns The percentage of the bubble that is visible.
*/
private getOverlap_(
relativeMin: {x: number, y: number},
@@ -509,9 +521,10 @@ export class Bubble implements IBubble {
* Calculate what the optimal horizontal position of the top-left corner of
* the bubble is (relative to the anchor point) so that the most area of the
* bubble is shown.
*
* @param viewMetrics The view metrics of the workspace the bubble will appear
* in.
* @return The optimal horizontal position of the top-left corner of the
* @returns The optimal horizontal position of the top-left corner of the
* bubble.
*/
private getOptimalRelativeLeft_(viewMetrics: ContainerRegion): number {
@@ -564,9 +577,11 @@ export class Bubble implements IBubble {
* Calculate what the optimal vertical position of the top-left corner of
* the bubble is (relative to the anchor point) so that the most area of the
* bubble is shown.
*
* @param viewMetrics The view metrics of the workspace the bubble will appear
* in.
* @return The optimal vertical position of the top-left corner of the bubble.
* @returns The optimal vertical position of the top-left corner of the
* bubble.
*/
private getOptimalRelativeTop_(viewMetrics: ContainerRegion): number {
let relativeTop = -this.height_ / 4;
@@ -609,6 +624,7 @@ export class Bubble implements IBubble {
/**
* Move the bubble group to the specified location in workspace coordinates.
*
* @param x The x position to move to.
* @param y The y position to move to.
* @internal
@@ -620,6 +636,7 @@ export class Bubble implements IBubble {
/**
* Triggers a move callback if one exists at the end of a drag.
*
* @param adding True if adding, false if removing.
* @internal
*/
@@ -631,7 +648,8 @@ export class Bubble implements IBubble {
/**
* Get the dimensions of this bubble.
* @return The height and width of the bubble.
*
* @returns The height and width of the bubble.
*/
getBubbleSize(): Size {
return new Size(this.width_, this.height_);
@@ -639,6 +657,7 @@ export class Bubble implements IBubble {
/**
* Size this bubble.
*
* @param width Width of the bubble.
* @param height Height of the bubble.
*/
@@ -750,6 +769,7 @@ export class Bubble implements IBubble {
/**
* Change the colour of a bubble.
*
* @param hexColour Hex code of colour.
*/
setColour(hexColour: string) {
@@ -773,6 +793,7 @@ export class Bubble implements IBubble {
/**
* Move this bubble during a drag, taking into account whether or not there is
* a drag surface.
*
* @param dragSurface The surface that carries rendered items during a drag,
* or null if no drag surface is in use.
* @param newLoc The location to translate to, in workspace coordinates.
@@ -796,7 +817,8 @@ export class Bubble implements IBubble {
/**
* Return the coordinates of the top-left corner of this bubble's body
* relative to the drawing surface's origin (0,0), in workspace units.
* @return Object with .x and .y properties.
*
* @returns Object with .x and .y properties.
*/
getRelativeToSurfaceXY(): Coordinate {
return new Coordinate(
@@ -810,6 +832,7 @@ export class Bubble implements IBubble {
* Set whether auto-layout of this bubble is enabled. The first time a bubble
* is shown it positions itself to not cover any blocks. Once a user has
* dragged it to reposition, it renders where the user put it.
*
* @param enable True if auto-layout should be enabled, false otherwise.
* @internal
*/
@@ -831,6 +854,7 @@ export class Bubble implements IBubble {
/**
* Handle a mouse-up event while dragging a bubble's border or resize handle.
*
* @param _e Mouse up event.
*/
private static bubbleMouseUp_(_e: MouseEvent) {
@@ -840,8 +864,9 @@ export class Bubble implements IBubble {
/**
* Create the text for a non editable bubble.
*
* @param text The text to display.
* @return The top-level node of the text.
* @returns The top-level node of the text.
* @internal
*/
static textToDom(text: string): SVGTextElement {
@@ -861,10 +886,11 @@ export class Bubble implements IBubble {
/**
* Creates a bubble that can not be edited.
*
* @param paragraphElement The text element for the non editable bubble.
* @param block The block that the bubble is attached to.
* @param iconXY The coordinate of the icon.
* @return The non editable bubble.
* @returns The non editable bubble.
* @internal
*/
static createNonEditableBubble(

15
core/bubble_dragger.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Methods for dragging a bubble visually.
*/
/**
* Methods for dragging a bubble visually.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -37,6 +34,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
* Class for a bubble dragger. It moves things on the bubble canvas around the
* workspace when they are being dragged by a mouse or touch. These can be
* block comments, mutators, warnings, or workspace comments.
*
* @alias Blockly.BubbleDragger
*/
export class BubbleDragger {
@@ -71,6 +69,7 @@ export class BubbleDragger {
/**
* Start dragging a bubble. This includes moving it to the drag surface.
*
* @internal
*/
startBubbleDrag() {
@@ -93,6 +92,7 @@ export class BubbleDragger {
/**
* Execute a step of bubble dragging, based on the given event. Update the
* display accordingly.
*
* @param e The most recent move event.
* @param currentDragDeltaXY How far the pointer has moved from the position
* at the start of the drag, in pixel units.
@@ -123,8 +123,9 @@ export class BubbleDragger {
/**
* Whether ending the drag would delete the bubble.
*
* @param dragTarget The drag target that the bubblee is currently over.
* @return Whether dropping the bubble immediately would delete the block.
* @returns Whether dropping the bubble immediately would delete the block.
*/
private shouldDelete_(dragTarget: IDragTarget|null): boolean {
if (dragTarget) {
@@ -148,6 +149,7 @@ export class BubbleDragger {
/**
* Finish a bubble drag and put the bubble back on the workspace.
*
* @param e The mouseup/touchend event.
* @param currentDragDeltaXY How far the pointer has moved from the position
* at the start of the drag, in pixel units.
@@ -210,8 +212,9 @@ export class BubbleDragger {
* correction for mutator workspaces.
* This function does not consider differing origins. It simply scales the
* input's x and y values.
*
* @param pixelCoord A coordinate with x and y values in CSS pixel units.
* @return The input coordinate divided by the workspace scale.
* @returns The input coordinate divided by the workspace scale.
*/
private pixelsToWorkspaceUnits_(pixelCoord: Coordinate): Coordinate {
const result = new Coordinate(

15
core/bump_objects.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Utilities for bumping objects back into worksapce bounds.
*/
/**
* Utilities for bumping objects back into worksapce bounds.
*
* @namespace Blockly.bumpObjects
*/
import * as goog from '../closure/goog/goog.js';
@@ -32,11 +29,12 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Bumps the given object that has passed out of bounds.
*
* @param workspace The workspace containing the object.
* @param scrollMetrics Scroll metrics
* in workspace coordinates.
* @param object The object to bump.
* @return True if block was bumped.
* @returns True if block was bumped.
* @alias Blockly.bumpObjects.bumpIntoBounds
*/
function bumpObjectIntoBounds(
@@ -86,8 +84,9 @@ export const bumpIntoBounds = bumpObjectIntoBounds;
/**
* Creates a handler for bumping objects when they cross fixed bounds.
*
* @param workspace The workspace to handle.
* @return The event handler.
* @returns The event handler.
* @alias Blockly.bumpObjects.bumpIntoBoundsHandler
*/
export function bumpIntoBoundsHandler(workspace: WorkspaceSvg):
@@ -134,10 +133,11 @@ export function bumpIntoBoundsHandler(workspace: WorkspaceSvg):
/**
* Extracts the object from the given event.
*
* @param workspace The workspace the event originated
* from.
* @param e An event containing an object.
* @return The extracted
* @returns The extracted
* object.
*/
function extractObjectFromEvent(
@@ -165,6 +165,7 @@ function extractObjectFromEvent(
/**
* Bumps the top objects in the given workspace into bounds.
*
* @param workspace The workspace.
* @alias Blockly.bumpObjects.bumpTopObjectsIntoBounds
*/

12
core/clipboard.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Blockly's internal clipboard for managing copy-paste.
*/
/**
* Blockly's internal clipboard for managing copy-paste.
*
* @namespace Blockly.clipboard
*/
import * as goog from '../closure/goog/goog.js';
@@ -23,6 +20,7 @@ let copyData: CopyData|null = null;
/**
* Copy a block or workspace comment onto the local clipboard.
*
* @param toCopy Block or Workspace Comment to be copied.
* @alias Blockly.clipboard.copy
* @internal
@@ -40,7 +38,8 @@ function copyInternal(toCopy: ICopyable) {
/**
* Paste a block or workspace comment on to the main workspace.
* @return The pasted thing if the paste was successful, null otherwise.
*
* @returns The pasted thing if the paste was successful, null otherwise.
* @alias Blockly.clipboard.paste
* @internal
*/
@@ -63,8 +62,9 @@ export function paste(): ICopyable|null {
/**
* Duplicate this block and its children, or a workspace comment.
*
* @param toDuplicate Block or Workspace Comment to be duplicated.
* @return The block or workspace comment that was duplicated, or null if the
* @returns The block or workspace comment that was duplicated, or null if the
* duplication failed.
* @alias Blockly.clipboard.duplicate
* @internal

27
core/comment.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Object representing a code comment.
*/
/**
* Object representing a code comment.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -43,6 +40,7 @@ import {Svg} from './utils/svg.js';
/**
* Class for a comment.
*
* @alias Blockly.Comment
*/
export class Comment extends Icon {
@@ -92,6 +90,7 @@ export class Comment extends Icon {
/**
* Draw the comment icon.
*
* @param group The icon group.
*/
protected override drawIcon_(group: Element) {
@@ -123,7 +122,8 @@ export class Comment extends Icon {
/**
* Create the editor for the comment's bubble.
* @return The top-level node of the editor.
*
* @returns The top-level node of the editor.
*/
private createEditor_(): SVGElement {
/* Create the editor. Here's the markup that will be generated in
@@ -169,7 +169,9 @@ export class Comment extends Icon {
});
this.onChangeWrapper_ = browserEvents.conditionalBind(
textarea, 'change', this,
/** @param _e Unused event parameter. */
/**
* @param _e Unused event parameter.
*/
function(this: Comment, _e: Event) {
if (this.cachedText_ !== this.model_.text) {
eventUtils.fire(new (eventUtils.get(eventUtils.BLOCK_CHANGE))!
@@ -179,7 +181,9 @@ export class Comment extends Icon {
});
this.onInputWrapper_ = browserEvents.conditionalBind(
textarea, 'input', this,
/** @param _e Unused event parameter. */
/**
* @param _e Unused event parameter.
*/
function(this: Comment, _e: Event) {
this.model_.text = textarea.value;
});
@@ -226,6 +230,7 @@ export class Comment extends Icon {
/**
* Show or hide the comment bubble.
*
* @param visible True if the bubble should be visible.
*/
override setVisible(visible: boolean) {
@@ -265,6 +270,7 @@ export class Comment extends Icon {
/**
* Show a non-editable bubble.
*
* @suppress {checkTypes} Suppress `this` type mismatch.
*/
private createNonEditableBubble_() {
@@ -277,6 +283,7 @@ export class Comment extends Icon {
/**
* Dispose of the bubble.
*
* @suppress {checkTypes} Suppress `this` type mismatch.
*/
private disposeBubble_() {
@@ -310,6 +317,7 @@ export class Comment extends Icon {
*
* Bring the comment to the top of the stack when clicked on. Also cache the
* current text so it can be used to fire a change event.
*
* @param _e Mouse up event.
*/
private startEdit_(_e: Event) {
@@ -324,7 +332,8 @@ export class Comment extends Icon {
/**
* Get the dimensions of this comment's bubble.
* @return Object with width and height properties.
*
* @returns Object with width and height properties.
*/
getBubbleSize(): Size {
return this.model_.size;
@@ -332,6 +341,7 @@ export class Comment extends Icon {
/**
* Size this comment's bubble.
*
* @param width Width of the bubble.
* @param height Height of the bubble.
*/
@@ -346,6 +356,7 @@ export class Comment extends Icon {
/**
* Update the comment's view to match the model.
*
* @internal
*/
updateText() {

44
core/common.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Common functions used both internally and externally, but which
* must not be at the top level to avoid circular dependencies.
*/
/**
* Common functions used both internally and externally, but which
* must not be at the top level to avoid circular dependencies.
*
* @namespace Blockly.common
*/
import * as goog from '../closure/goog/goog.js';
@@ -32,8 +28,9 @@ const WorkspaceDB_ = Object.create(null);
/**
* Find the workspace with the specified ID.
*
* @param id ID of workspace to find.
* @return The sought after workspace or null if not found.
* @returns The sought after workspace or null if not found.
*/
export function getWorkspaceById(id: string): Workspace|null {
return WorkspaceDB_[id] || null;
@@ -41,7 +38,8 @@ export function getWorkspaceById(id: string): Workspace|null {
/**
* Find all workspaces.
* @return Array of workspaces.
*
* @returns Array of workspaces.
*/
export function getAllWorkspaces(): Workspace[] {
const workspaces = [];
@@ -51,10 +49,20 @@ export function getAllWorkspaces(): Workspace[] {
return workspaces;
}
/**
* Register a workspace in the workspace db.
*
* @param workspace
*/
export function registerWorkspace(workspace: Workspace) {
WorkspaceDB_[workspace.id] = workspace;
}
/**
* Unregister a workspace from the workspace db.
*
* @param workspace
*/
export function unregisterWorkpace(workspace: Workspace) {
delete WorkspaceDB_[workspace.id];
}
@@ -69,7 +77,8 @@ let mainWorkspace: Workspace;
* Returns the last used top level workspace (based on focus). Try not to use
* this function, particularly if there are multiple Blockly instances on a
* page.
* @return The main workspace.
*
* @returns The main workspace.
* @alias Blockly.common.getMainWorkspace
*/
export function getMainWorkspace(): Workspace {
@@ -78,6 +87,7 @@ export function getMainWorkspace(): Workspace {
/**
* Sets last used main workspace.
*
* @param workspace The most recently used top level workspace.
* @alias Blockly.common.setMainWorkspace
*/
@@ -92,6 +102,7 @@ let selected: ICopyable|null = null;
/**
* Returns the currently selected copyable object.
*
* @alias Blockly.common.getSelected
*/
export function getSelected(): ICopyable|null {
@@ -102,6 +113,7 @@ export function getSelected(): ICopyable|null {
* Sets the currently selected block. This function does not visually mark the
* block as selected or fire the required events. If you wish to
* programmatically select a block, use `BlockSvg#select`.
*
* @param newSelection The newly selected block.
* @alias Blockly.common.setSelected
* @internal
@@ -118,7 +130,8 @@ let parentContainer: Element|null;
/**
* Get the container element in which to render the WidgetDiv, DropDownDiv and\
* Tooltip.
* @return The parent container.
*
* @returns The parent container.
* @alias Blockly.common.getParentContainer
*/
export function getParentContainer(): Element|null {
@@ -130,6 +143,7 @@ export function getParentContainer(): Element|null {
* DropDownDiv, and Tooltip are rendered into the first time `Blockly.inject`
* is called.
* This method is a NOP if called after the first ``Blockly.inject``.
*
* @param newParent The container element.
* @alias Blockly.common.setParentContainer
*/
@@ -143,6 +157,7 @@ export function setParentContainer(newParent: Element) {
* See workspace.resizeContents to resize the workspace when the contents
* change (e.g. when a block is added or removed).
* Record the height/width of the SVG image.
*
* @param workspace Any workspace in the SVG.
* @alias Blockly.common.svgResize
*/
@@ -180,11 +195,12 @@ export const draggingConnections: Connection[] = [];
/**
* Get a map of all the block's descendants mapping their type to the number of
* children with that type.
*
* @param block The block to map.
* @param opt_stripFollowing Optionally ignore all following
* statements (blocks that are not inside a value or statement input
* of the block).
* @return Map of types to type counts for descendants of the bock.
* @returns Map of types to type counts for descendants of the bock.
* @alias Blockly.common.getBlockTypeCounts
*/
export function getBlockTypeCounts(
@@ -211,8 +227,9 @@ export function getBlockTypeCounts(
/**
* Helper function for defining a block from JSON. The resulting function has
* the correct value of jsonDef at the point in code where jsonInit is called.
*
* @param jsonDef The JSON definition of a block.
* @return A function that calls jsonInit with the correct value
* @returns A function that calls jsonInit with the correct value
* of jsonDef.
*/
function jsonInitFactory(jsonDef: AnyDuringMigration): () => void {
@@ -224,6 +241,7 @@ function jsonInitFactory(jsonDef: AnyDuringMigration): () => void {
/**
* Define blocks from an array of JSON block definitions, as might be generated
* by the Blockly Developer Tools.
*
* @param jsonArray An array of JSON block definitions.
* @alias Blockly.common.defineBlocksWithJsonArray
*/
@@ -241,8 +259,9 @@ function defineBlocksWithJsonArrayInternal(jsonArray: AnyDuringMigration[]) {
/**
* Define blocks from an array of JSON block definitions, as might be generated
* by the Blockly Developer Tools.
*
* @param jsonArray An array of JSON block definitions.
* @return A map of the block
* @returns A map of the block
* definitions created.
* @alias Blockly.common.defineBlocksWithJsonArray
*/
@@ -270,6 +289,7 @@ export function createBlockDefinitionsFromJsonArray(
/**
* Add the specified block definitions to the block definitions
* dictionary (Blockly.Blocks).
*
* @param blocks A map of block
* type names to block definitions.
* @alias Blockly.common.defineBlocks

22
core/component_manager.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Manager for all items registered with the workspace.
*/
/**
* Manager for all items registered with the workspace.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -36,7 +33,8 @@ class Capability<_T> {
/**
* Returns the name of the capability.
* @return The name.
*
* @returns The name.
*/
toString(): string {
return this.name_;
@@ -45,6 +43,7 @@ class Capability<_T> {
/**
* Manager for all items registered with the workspace.
*
* @alias Blockly.ComponentManager
*/
export class ComponentManager {
@@ -60,6 +59,7 @@ export class ComponentManager {
/**
* Adds a component.
*
* @param componentInfo The data for the component to register.
* @param opt_allowOverrides True to prevent an error when overriding an
* already registered item.
@@ -88,6 +88,7 @@ export class ComponentManager {
/**
* Removes a component.
*
* @param id The ID of the component to remove.
*/
removeComponent(id: string) {
@@ -104,6 +105,7 @@ export class ComponentManager {
/**
* Adds a capability to a existing registered component.
*
* @param id The ID of the component to add the capability to.
* @param capability The capability to add.
*/
@@ -125,6 +127,7 @@ export class ComponentManager {
/**
* Removes a capability from an existing registered component.
*
* @param id The ID of the component to remove the capability from.
* @param capability The capability to remove.
*/
@@ -147,9 +150,10 @@ export class ComponentManager {
/**
* Returns whether the component with this id has the specified capability.
*
* @param id The ID of the component to check.
* @param capability The capability to check for.
* @return Whether the component has the capability.
* @returns Whether the component has the capability.
*/
hasCapability<T>(id: string, capability: string|Capability<T>): boolean {
capability = String(capability).toLowerCase();
@@ -159,8 +163,9 @@ export class ComponentManager {
/**
* Gets the component with the given ID.
*
* @param id The ID of the component to get.
* @return The component with the given name or undefined if not found.
* @returns The component with the given name or undefined if not found.
*/
getComponent(id: string): IComponent|undefined {
return this.componentData.get(id)?.component;
@@ -168,9 +173,10 @@ export class ComponentManager {
/**
* Gets all the components with the specified capability.
*
* @param capability The capability of the component.
* @param sorted Whether to return list ordered by weights.
* @return The components that match the specified capability.
* @returns The components that match the specified capability.
*/
getComponents<T extends IComponent>(
capability: string|Capability<T>, sorted: boolean): T[] {

13
core/config.ts
View File

@@ -4,16 +4,11 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview All the values that we expect developers to be able to change
* before injecting Blockly. Changing these values during run time is not
* generally recommended.
*/
/**
* All the values that we expect developers to be able to change
* before injecting Blockly. Changing these values during run time is not
* generally recommended.
*
* @namespace Blockly.config
*/
import * as goog from '../closure/goog/goog.js';
@@ -43,6 +38,7 @@ const DEFAULT_SNAP_RADIUS = 28;
export const config: Config = {
/**
* Number of pixels the mouse must move before a drag starts.
*
* @alias Blockly.config.dragRadius
*/
dragRadius: 5,
@@ -50,17 +46,20 @@ export const config: Config = {
* Number of pixels the mouse must move before a drag/scroll starts from the
* flyout. Because the drag-intention is determined when this is reached, it
* is larger than dragRadius so that the drag-direction is clearer.
*
* @alias Blockly.config.flyoutDragRadius
*/
flyoutDragRadius: 10,
/**
* Maximum misalignment between connections for them to snap together.
*
* @alias Blockly.config.snapRadius
*/
snapRadius: DEFAULT_SNAP_RADIUS,
/**
* Maximum misalignment between connections for them to snap together.
* This should be the same as the snap radius.
*
* @alias Blockly.config.connectingSnapRadius
*/
connectingSnapRadius: DEFAULT_SNAP_RADIUS,
@@ -69,11 +68,13 @@ export const config: Config = {
* to a new connection. The current previewed connection is considered to be
* this much closer to the matching connection on the block than it actually
* is.
*
* @alias Blockly.config.currentConnectionPreference
*/
currentConnectionPreference: 8,
/**
* Delay in ms between trigger and bumping unconnected block out of alignment.
*
* @alias Blockly.config.bumpDelay
*/
bumpDelay: 250,

75
core/connection.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Components for creating connections between blocks.
*/
/**
* Components for creating connections between blocks.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -31,6 +28,7 @@ import * as Xml from './xml.js';
/**
* Class for a connection between blocks.
*
* @alias Blockly.Connection
*/
export class Connection implements IASTNodeLocationWithBlock {
@@ -52,6 +50,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Has this connection been disposed of?
*
* @internal
*/
disposed = false;
@@ -64,12 +63,14 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Horizontal location of this connection.
*
* @internal
*/
x = 0;
/**
* Vertical location of this connection.
*
* @internal
*/
y = 0;
@@ -87,6 +88,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Connect two connections together. This is the connection on the superior
* block.
*
* @param childConnection Connection on inferior block.
*/
protected connect_(childConnection: Connection) {
@@ -142,6 +144,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Dispose of this connection and deal with connected blocks.
*
* @internal
*/
dispose() {
@@ -162,7 +165,8 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Get the source block for this connection.
* @return The source block.
*
* @returns The source block.
*/
getSourceBlock(): Block {
return this.sourceBlock_;
@@ -171,7 +175,8 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Does the connection belong to a superior block (higher in the source
* stack)?
* @return True if connection faces down or right.
*
* @returns True if connection faces down or right.
*/
isSuperior(): boolean {
return this.type === ConnectionType.INPUT_VALUE ||
@@ -180,7 +185,8 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Is the connection connected?
* @return True if connection is connected to another connection.
*
* @returns True if connection is connected to another connection.
*/
isConnected(): boolean {
return !!this.targetConnection;
@@ -188,7 +194,8 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Get the workspace's connection type checker object.
* @return The connection type checker for the source block's workspace.
*
* @returns The connection type checker for the source block's workspace.
* @internal
*/
getConnectionChecker(): IConnectionChecker {
@@ -198,6 +205,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Called when an attempted connection fails. NOP by default (i.e. for
* headless workspaces).
*
* @param _otherConnection Connection that this connection failed to connect
* to.
* @internal
@@ -207,8 +215,9 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Connect this connection to another connection.
*
* @param otherConnection Connection to connect to.
* @return Whether the the blocks are now connected or not.
* @returns Whether the the blocks are now connected or not.
*/
connect(otherConnection: Connection): boolean {
if (this.targetConnection === otherConnection) {
@@ -279,6 +288,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Disconnect two blocks that are connected by this connection.
*
* @param parentBlock The superior block.
* @param childBlock The inferior block.
*/
@@ -310,7 +320,8 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Returns the block that this connection connects to.
* @return The connected block or null if none is connected.
*
* @returns The connected block or null if none is connected.
*/
targetBlock(): Block|null {
if (this.isConnected()) {
@@ -335,9 +346,10 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Change a connection's compatibility.
*
* @param check Compatible value type or list of value types. Null if all
* types are compatible.
* @return The connection being modified (to allow chaining).
* @returns The connection being modified (to allow chaining).
*/
setCheck(check: string|string[]|null): Connection {
if (check) {
@@ -354,7 +366,8 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Get a connection's compatibility.
* @return List of compatible value types.
*
* @returns List of compatible value types.
* Null if all types are compatible.
*/
getCheck(): string[]|null {
@@ -363,6 +376,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Changes the connection's shadow block.
*
* @param shadowDom DOM representation of a block or null.
*/
setShadowDom(shadowDom: Element|null) {
@@ -371,11 +385,12 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Returns the xml representation of the connection's shadow block.
*
* @param returnCurrent If true, and the shadow block is currently attached to
* this connection, this serializes the state of that block and returns it
* (so that field values are correct). Otherwise the saved shadowDom is
* just returned.
* @return Shadow DOM representation of a block or null.
* @returns Shadow DOM representation of a block or null.
*/
getShadowDom(returnCurrent?: boolean): Element|null {
return returnCurrent && this.targetBlock()!.isShadow() ?
@@ -385,6 +400,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Changes the connection's shadow block.
*
* @param shadowState An state represetation of the block or null.
*/
setShadowState(shadowState: blocks.State|null) {
@@ -394,11 +410,12 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Returns the serialized object representation of the connection's shadow
* block.
*
* @param returnCurrent If true, and the shadow block is currently attached to
* this connection, this serializes the state of that block and returns it
* (so that field values are correct). Otherwise the saved state is just
* returned.
* @return Serialized object representation of the block, or null.
* @returns Serialized object representation of the block, or null.
*/
getShadowState(returnCurrent?: boolean): blocks.State|null {
if (returnCurrent && this.targetBlock() && this.targetBlock()!.isShadow()) {
@@ -415,8 +432,9 @@ export class Connection implements IASTNodeLocationWithBlock {
* and always return an empty list (the default).
* {@link Blockly.RenderedConnection} overrides this behavior with a list
* computed from the rendered positioning.
*
* @param _maxLimit The maximum radius to another connection.
* @return List of connections.
* @returns List of connections.
* @internal
*/
neighbours(_maxLimit: number): Connection[] {
@@ -425,7 +443,8 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Get the parent input of a connection.
* @return The input that the connection belongs to or null if no parent
*
* @returns The input that the connection belongs to or null if no parent
* exists.
* @internal
*/
@@ -444,7 +463,8 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* This method returns a string describing this Connection in developer terms
* (English only). Intended to on be used in console logs and errors.
* @return The description.
*
* @returns The description.
*/
toString(): string {
const block = this.sourceBlock_;
@@ -479,7 +499,8 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Returns the state of the shadowDom_ and shadowState_ properties, then
* temporarily sets those properties to null so no shadow respawns.
* @return The state of both the shadowDom_ and shadowState_ properties.
*
* @returns The state of both the shadowDom_ and shadowState_ properties.
*/
private stashShadowState_():
{shadowDom: Element|null, shadowState: blocks.State|null} {
@@ -493,6 +514,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Reapplies the stashed state of the shadowDom_ and shadowState_ properties.
*
* @param param0 The state to reapply to the shadowDom_ and shadowState_
* properties.
*/
@@ -506,6 +528,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Sets the state of the shadow of this connection.
*
* @param param0 The state to set the shadow of this connection to.
*/
private setShadowStateInternal_({shadowDom = null, shadowState = null}: {
@@ -541,10 +564,11 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Creates a shadow block based on the current shadowState_ or shadowDom_.
* shadowState_ gets priority.
*
* @param attemptToConnect Whether to try to connect the shadow block to this
* connection or not.
* @return The shadow block that was created, or null if both the shadowState_
* and shadowDom_ are null.
* @returns The shadow block that was created, or null if both the
* shadowState_ and shadowDom_ are null.
*/
private createShadowBlock_(attemptToConnect: boolean): Block|null {
const parentBlock = this.getSourceBlock();
@@ -594,6 +618,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Saves the given shadow block to both the shadowDom_ and shadowState_
* properties, in their respective serialized forms.
*
* @param shadow The shadow to serialize, or null.
*/
private serializeShadow_(shadow: Block|null) {
@@ -608,9 +633,10 @@ export class Connection implements IASTNodeLocationWithBlock {
* Returns the connection (starting at the startBlock) which will accept
* the given connection. This includes compatible connection types and
* connection checks.
*
* @param startBlock The block on which to start the search.
* @param orphanConnection The connection that is looking for a home.
* @return The suitable connection point on the chain of blocks, or null.
* @returns The suitable connection point on the chain of blocks, or null.
*/
static getConnectionForOrphanedConnection(
startBlock: Block, orphanConnection: Connection): Connection|null {
@@ -630,6 +656,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Update two connections to target each other.
*
* @param first The first connection to update.
* @param second The second connection to update.
*/
@@ -645,9 +672,10 @@ function connectReciprocally(first: Connection, second: Connection) {
* block, if one can be found. If the block has multiple compatible connections
* (even if they are filled) this returns null. If the block has no compatible
* connections, this returns null.
*
* @param block The superior block.
* @param orphanBlock The inferior block.
* @return The suitable connection point on 'block', or null.
* @returns The suitable connection point on 'block', or null.
*/
function getSingleConnection(block: Block, orphanBlock: Block): Connection|
null {
@@ -673,9 +701,10 @@ function getSingleConnection(block: Block, orphanBlock: Block): Connection|
* are zero or multiple eligible connections, returns null. Otherwise
* returns the only input on the last block in the chain.
* Terminates early for shadow blocks.
*
* @param startBlock The block on which to start the search.
* @param orphanBlock The block that is looking for a home.
* @return The suitable connection point on the chain of blocks, or null.
* @returns The suitable connection point on the chain of blocks, or null.
*/
function getConnectionForOrphanedOutput(
startBlock: Block, orphanBlock: Block): Connection|null {

28
core/connection_checker.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview An object that encapsulates logic for checking whether a
* potential connection is safe and valid.
*/
/**
* An object that encapsulates logic for checking whether a
* potential connection is safe and valid.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -28,18 +24,20 @@ import type {RenderedConnection} from './rendered_connection.js';
/**
* Class for connection type checking logic.
*
* @alias Blockly.ConnectionChecker
*/
export class ConnectionChecker implements IConnectionChecker {
/**
* Check whether the current connection can connect with the target
* connection.
*
* @param a Connection to check compatibility with.
* @param b Connection to check compatibility with.
* @param isDragging True if the connection is being made by dragging a block.
* @param opt_distance The max allowable distance between the connections for
* drag checks.
* @return Whether the connection is legal.
* @returns Whether the connection is legal.
*/
canConnect(
a: Connection|null, b: Connection|null, isDragging: boolean,
@@ -51,12 +49,13 @@ export class ConnectionChecker implements IConnectionChecker {
/**
* Checks whether the current connection can connect with the target
* connection, and return an error code if there are problems.
*
* @param a Connection to check compatibility with.
* @param b Connection to check compatibility with.
* @param isDragging True if the connection is being made by dragging a block.
* @param opt_distance The max allowable distance between the connections for
* drag checks.
* @return Connection.CAN_CONNECT if the connection is legal, an error code
* @returns Connection.CAN_CONNECT if the connection is legal, an error code
* otherwise.
*/
canConnectWithReason(
@@ -86,10 +85,11 @@ export class ConnectionChecker implements IConnectionChecker {
/**
* Helper method that translates a connection error code into a string.
*
* @param errorCode The error code.
* @param a One of the two connections being checked.
* @param b The second of the two connections being checked.
* @return A developer-readable error string.
* @returns A developer-readable error string.
*/
getErrorMessage(errorCode: number, a: Connection|null, b: Connection|null):
string {
@@ -125,9 +125,10 @@ export class ConnectionChecker implements IConnectionChecker {
/**
* Check that connecting the given connections is safe, meaning that it would
* not break any of Blockly's basic assumptions (e.g. no self connections).
*
* @param a The first of the connections to check.
* @param b The second of the connections to check.
* @return An enum with the reason this connection is safe or unsafe.
* @returns An enum with the reason this connection is safe or unsafe.
*/
doSafetyChecks(a: Connection|null, b: Connection|null): number {
if (!a || !b) {
@@ -176,9 +177,10 @@ export class ConnectionChecker implements IConnectionChecker {
* Check whether this connection is compatible with another connection with
* respect to the value type system. E.g. square_root("Hello") is not
* compatible.
*
* @param a Connection to compare.
* @param b Connection to compare against.
* @return True if the connections share a type.
* @returns True if the connections share a type.
*/
doTypeChecks(a: Connection, b: Connection): boolean {
const checkArrayOne = a.getCheck();
@@ -200,10 +202,11 @@ export class ConnectionChecker implements IConnectionChecker {
/**
* Check whether this connection can be made by dragging.
*
* @param a Connection to compare.
* @param b Connection to compare against.
* @param distance The maximum allowable distance between connections.
* @return True if the connection is allowed during a drag.
* @returns True if the connection is allowed during a drag.
*/
doDragChecks(a: RenderedConnection, b: RenderedConnection, distance: number):
boolean {
@@ -264,10 +267,11 @@ export class ConnectionChecker implements IConnectionChecker {
/**
* Helper function for drag checking.
*
* @param a The connection to check, which must be a statement input or next
* connection.
* @param b A nearby connection to check, which must be a previous connection.
* @return True if the connection is allowed, false otherwise.
* @returns True if the connection is allowed, false otherwise.
*/
protected canConnectToPrevious_(a: Connection, b: Connection): boolean {
if (a.targetConnection) {

34
core/connection_db.ts
View File

@@ -4,16 +4,11 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview A database of all the rendered connections that could
* possibly be connected to (i.e. not collapsed, etc).
* Sorted by y coordinate.
*/
/**
* A database of all the rendered connections that could
* possibly be connected to (i.e. not collapsed, etc).
* Sorted by y coordinate.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -32,6 +27,7 @@ import type {Coordinate} from './utils/coordinate.js';
* Database of connections.
* Connections are stored in order of their vertical component. This way
* connections in an area may be looked up quickly using a binary search.
*
* @alias Blockly.ConnectionDB
*/
export class ConnectionDB {
@@ -46,6 +42,7 @@ export class ConnectionDB {
/**
* Add a connection to the database. Should not already exist in the database.
*
* @param connection The connection to be added.
* @param yPos The y position used to decide where to insert the connection.
* @internal
@@ -60,9 +57,11 @@ export class ConnectionDB {
*
* Starts by doing a binary search to find the approximate location, then
* linearly searches nearby for the exact connection.
*
* @param conn The connection to find.
* @param yPos The y position used to find the index of the connection.
* @return The index of the connection, or -1 if the connection was not found.
* @returns The index of the connection, or -1 if the connection was not
* found.
*/
private findIndexOfConnection_(conn: RenderedConnection, yPos: number):
number {
@@ -99,8 +98,9 @@ export class ConnectionDB {
/**
* Finds the correct index for the given y position.
*
* @param yPos The y position used to decide where to insert the connection.
* @return The candidate index.
* @returns The candidate index.
*/
private calculateIndexForYPos_(yPos: number): number {
if (!this.connections_.length) {
@@ -124,6 +124,7 @@ export class ConnectionDB {
/**
* Remove a connection from the database. Must already exist in DB.
*
* @param connection The connection to be removed.
* @param yPos The y position used to find the index of the connection.
* @throws {Error} If the connection cannot be found in the database.
@@ -139,9 +140,10 @@ export class ConnectionDB {
/**
* Find all nearby connections to the given connection.
* Type checking does not apply, since this function is used for bumping.
*
* @param connection The connection whose neighbours should be returned.
* @param maxRadius The maximum radius to another connection.
* @return List of connections.
* @returns List of connections.
*/
getNeighbours(connection: RenderedConnection, maxRadius: number):
RenderedConnection[] {
@@ -167,9 +169,10 @@ export class ConnectionDB {
* Computes if the current connection is within the allowed radius of
* another connection. This function is a closure and has access to outside
* variables.
*
* @param yIndex The other connection's index in the database.
* @return True if the current connection's vertical distance from the other
* connection is less than the allowed radius.
* @returns True if the current connection's vertical distance from the
* other connection is less than the allowed radius.
*/
function checkConnection_(yIndex: number): boolean {
const dx = currentX - db[yIndex].x;
@@ -199,10 +202,11 @@ export class ConnectionDB {
/**
* Is the candidate connection close to the reference connection.
* Extremely fast; only looks at Y distance.
*
* @param index Index in database of candidate connection.
* @param baseY Reference connection's Y value.
* @param maxRadius The maximum radius to another connection.
* @return True if connection is in range.
* @returns True if connection is in range.
*/
private isInYRange_(index: number, baseY: number, maxRadius: number):
boolean {
@@ -211,11 +215,12 @@ export class ConnectionDB {
/**
* Find the closest compatible connection to this connection.
*
* @param conn The connection searching for a compatible mate.
* @param maxRadius The maximum radius to another connection.
* @param dxy Offset between this connection's location in the database and
* the current location (as a result of dragging).
* @return Contains two properties: 'connection' which is either another
* @returns Contains two properties: 'connection' which is either another
* connection or null, and 'radius' which is the distance.
*/
searchForClosest(
@@ -273,9 +278,10 @@ export class ConnectionDB {
/**
* Initialize a set of connection DBs for a workspace.
*
* @param checker The workspace's connection checker, used to decide if
* connections are valid during a drag.
* @return Array of databases.
* @returns Array of databases.
*/
static init(checker: IConnectionChecker): ConnectionDB[] {
// Create four databases, one for each connection type.

6
core/connection_type.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview An enum for the possible types of connections.
*/
/**
* An enum for the possible types of connections.
*
* @namespace Blockly.ConnectionType
*/
import * as goog from '../closure/goog/goog.js';
@@ -18,6 +15,7 @@ goog.declareModuleId('Blockly.ConnectionType');
/**
* Enum for the type of a connection or input.
*
* @alias Blockly.ConnectionType
*/
export enum ConnectionType {

7
core/constants.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Blockly constants.
*/
/**
* Blockly constants.
*
* @namespace Blockly.constants
*/
import * as goog from '../closure/goog/goog.js';
@@ -18,12 +15,14 @@ goog.declareModuleId('Blockly.constants');
/**
* The language-neutral ID given to the collapsed input.
*
* @alias Blockly.constants.COLLAPSED_INPUT_NAME
*/
export const COLLAPSED_INPUT_NAME = '_TEMP_COLLAPSED_INPUT';
/**
* The language-neutral ID given to the collapsed field.
*
* @alias Blockly.constants.COLLAPSED_FIELD_NAME
*/
export const COLLAPSED_FIELD_NAME = '_TEMP_COLLAPSED_FIELD';

36
core/contextmenu.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Functionality for the right-click context menus.
*/
/**
* Functionality for the right-click context menus.
*
* @namespace Blockly.ContextMenu
*/
import * as goog from '../closure/goog/goog.js';
@@ -45,7 +42,8 @@ const dummyOwner = {};
/**
* Gets the block the context menu is currently attached to.
* @return The block the context menu is attached to.
*
* @returns The block the context menu is attached to.
* @alias Blockly.ContextMenu.getCurrentBlock
*/
export function getCurrentBlock(): Block|null {
@@ -54,6 +52,7 @@ export function getCurrentBlock(): Block|null {
/**
* Sets the block the context menu is currently attached to.
*
* @param block The block the context menu is attached to.
* @alias Blockly.ContextMenu.setCurrentBlock
*/
@@ -68,6 +67,7 @@ let menu_: Menu|null = null;
/**
* Construct the menu based on the list of options and show the menu.
*
* @param e Mouse event.
* @param options Array of menu options.
* @param rtl True if RTL, false if LTR.
@@ -95,9 +95,10 @@ export function show(
/**
* Create the context menu object and populate it with the given options.
*
* @param options Array of menu options.
* @param rtl True if RTL, false if LTR.
* @return The menu that will be shown on right click.
* @returns The menu that will be shown on right click.
*/
function populate_(
options: (ContextMenuOption|LegacyContextMenuOption)[],
@@ -133,6 +134,7 @@ function populate_(
/**
* Add the menu to the page and position it correctly.
*
* @param menu The menu to add and position.
* @param e Mouse event for the right click that is making the context
* menu appear.
@@ -169,6 +171,7 @@ function position_(menu: Menu, e: Event, rtl: boolean) {
/**
* Create and render the menu widget inside Blockly's widget div.
*
* @param menu The menu to add to the widget div.
*/
function createWidget_(menu: Menu) {
@@ -187,6 +190,7 @@ function createWidget_(menu: Menu) {
}
/**
* Halts the propagation of the event without doing anything else.
*
* @param e An event.
*/
function haltPropagation(e: Event) {
@@ -197,6 +201,7 @@ function haltPropagation(e: Event) {
/**
* Hide the context menu.
*
* @alias Blockly.ContextMenu.hide
*/
export function hide() {
@@ -206,6 +211,7 @@ export function hide() {
/**
* Dispose of the menu.
*
* @alias Blockly.ContextMenu.dispose
*/
export function dispose() {
@@ -218,9 +224,10 @@ export function dispose() {
/**
* Create a callback function that creates and configures a block,
* then places the new block next to the original.
*
* @param block Original block.
* @param xml XML representation of new block.
* @return Function that creates a block.
* @returns Function that creates a block.
* @alias Blockly.ContextMenu.callbackFactory
*/
export function callbackFactory(block: Block, xml: Element): Function {
@@ -252,9 +259,10 @@ export function callbackFactory(block: Block, xml: Element): Function {
/**
* Make a context menu option for deleting the current workspace comment.
*
* @param comment The workspace comment where the
* right-click originated.
* @return A menu option,
* @returns A menu option,
* containing text, enabled, and a callback.
* @alias Blockly.ContextMenu.commentDeleteOption
* @internal
@@ -275,9 +283,10 @@ export function commentDeleteOption(comment: WorkspaceCommentSvg):
/**
* Make a context menu option for duplicating the current workspace comment.
*
* @param comment The workspace comment where the
* right-click originated.
* @return A menu option,
* @returns A menu option,
* containing text, enabled, and a callback.
* @alias Blockly.ContextMenu.commentDuplicateOption
* @internal
@@ -296,10 +305,11 @@ export function commentDuplicateOption(comment: WorkspaceCommentSvg):
/**
* Make a context menu option for adding a comment on the workspace.
*
* @param ws The workspace where the right-click
* originated.
* @param e The right-click mouse event.
* @return A menu option, containing text, enabled, and a callback.
* @returns A menu option, containing text, enabled, and a callback.
* @suppress {strictModuleDepCheck,checkTypes} Suppress checks while workspace
* comments are not bundled in.
* @alias Blockly.ContextMenu.workspaceCommentOption
@@ -307,8 +317,10 @@ export function commentDuplicateOption(comment: WorkspaceCommentSvg):
*/
export function workspaceCommentOption(
ws: WorkspaceSvg, e: Event): ContextMenuOption {
// Helper function to create and position a comment correctly based on the
// location of the mouse event.
/**
* Helper function to create and position a comment correctly based on the
* location of the mouse event.
*/
function addWsComment() {
const comment = new WorkspaceCommentSvg(
ws, Msg['WORKSPACE_COMMENT_DEFAULT_TEXT'],

25
core/contextmenu_items.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Registers default context menu items.
*/
/**
* Registers default context menu items.
*
* @namespace Blockly.ContextMenuItems
*/
import * as goog from '../closure/goog/goog.js';
@@ -29,6 +26,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Option to undo previous action.
*
* @alias Blockly.ContextMenuItems.registerUndo
*/
export function registerUndo() {
@@ -54,6 +52,7 @@ export function registerUndo() {
/**
* Option to redo previous action.
*
* @alias Blockly.ContextMenuItems.registerRedo
*/
export function registerRedo() {
@@ -79,6 +78,7 @@ export function registerRedo() {
/**
* Option to clean up blocks.
*
* @alias Blockly.ContextMenuItems.registerCleanup
*/
export function registerCleanup() {
@@ -106,6 +106,7 @@ export function registerCleanup() {
}
/**
* Creates a callback to collapse or expand top blocks.
*
* @param shouldCollapse Whether a block should collapse.
* @param topBlocks Top blocks in the workspace.
*/
@@ -134,6 +135,7 @@ function toggleOption_(shouldCollapse: boolean, topBlocks: BlockSvg[]) {
/**
* Option to collapse all blocks.
*
* @alias Blockly.ContextMenuItems.registerCollapse
*/
export function registerCollapse() {
@@ -169,6 +171,7 @@ export function registerCollapse() {
/**
* Option to expand all blocks.
*
* @alias Blockly.ContextMenuItems.registerExpand
*/
export function registerExpand() {
@@ -203,6 +206,7 @@ export function registerExpand() {
}
/**
* Adds a block and its children to a list of deletable blocks.
*
* @param block to delete.
* @param deleteList list of blocks that can be deleted.
* This will be modified in place with the given block and its descendants.
@@ -220,8 +224,9 @@ function addDeletableBlocks_(block: BlockSvg, deleteList: BlockSvg[]) {
/**
* Constructs a list of blocks that can be deleted in the given workspace.
*
* @param workspace to delete all blocks from.
* @return list of blocks to delete.
* @returns list of blocks to delete.
*/
function getDeletableBlocks_(workspace: WorkspaceSvg): BlockSvg[] {
const deleteList: BlockSvg[] = [];
@@ -234,6 +239,7 @@ function getDeletableBlocks_(workspace: WorkspaceSvg): BlockSvg[] {
/**
* Deletes the given blocks. Used to delete all blocks in the workspace.
*
* @param deleteList list of blocks to delete.
* @param eventGroup event group ID with which all delete events should be
* associated.
@@ -255,6 +261,7 @@ function deleteNext_(deleteList: BlockSvg[], eventGroup: string) {
/**
* Option to delete all blocks.
*
* @alias Blockly.ContextMenuItems.registerDeleteAll
*/
export function registerDeleteAll() {
@@ -316,6 +323,7 @@ function registerWorkspaceOptions_() {
/**
* Option to duplicate a block.
*
* @alias Blockly.ContextMenuItems.registerDuplicate
*/
export function registerDuplicate() {
@@ -347,6 +355,7 @@ export function registerDuplicate() {
/**
* Option to add or remove block-level comment.
*
* @alias Blockly.ContextMenuItems.registerComment
*/
export function registerComment() {
@@ -384,6 +393,7 @@ export function registerComment() {
/**
* Option to inline variables.
*
* @alias Blockly.ContextMenuItems.registerInline
*/
export function registerInline() {
@@ -418,6 +428,7 @@ export function registerInline() {
/**
* Option to collapse or expand a block.
*
* @alias Blockly.ContextMenuItems.registerCollapseExpandBlock
*/
export function registerCollapseExpandBlock() {
@@ -446,6 +457,7 @@ export function registerCollapseExpandBlock() {
/**
* Option to disable or enable a block.
*
* @alias Blockly.ContextMenuItems.registerDisable
*/
export function registerDisable() {
@@ -485,6 +497,7 @@ export function registerDisable() {
/**
* Option to delete a block.
*
* @alias Blockly.ContextMenuItems.registerDelete
*/
export function registerDelete() {
@@ -522,6 +535,7 @@ export function registerDelete() {
/**
* Option to open help for a block.
*
* @alias Blockly.ContextMenuItems.registerHelp
*/
export function registerHelp() {
@@ -562,6 +576,7 @@ function registerBlockOptions_() {
/**
* Registers all default context menu items. This should be called once per
* instance of ContextMenuRegistry.
*
* @alias Blockly.ContextMenuItems.registerDefaultOptions
* @internal
*/

13
core/contextmenu_registry.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Registry for context menu option items.
*/
/**
* Registry for context menu option items.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -23,6 +20,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
* Class for the registry of context menu items. This is intended to be a
* singleton. You should not create a new instance, and only access this class
* from ContextMenuRegistry.registry.
*
* @alias Blockly.ContextMenuRegistry
*/
export class ContextMenuRegistry {
@@ -42,6 +40,7 @@ export class ContextMenuRegistry {
/**
* Registers a RegistryItem.
*
* @param item Context menu item to register.
* @throws {Error} if an item with the given ID already exists.
*/
@@ -54,6 +53,7 @@ export class ContextMenuRegistry {
/**
* Unregisters a RegistryItem with the given ID.
*
* @param id The ID of the RegistryItem to remove.
* @throws {Error} if an item with the given ID does not exist.
*/
@@ -66,7 +66,7 @@ export class ContextMenuRegistry {
/**
* @param id The ID of the RegistryItem to get.
* @return RegistryItem or null if not found
* @returns RegistryItem or null if not found
*/
getItem(id: string): RegistryItem|null {
return this.registry_.get(id) ?? null;
@@ -76,11 +76,12 @@ export class ContextMenuRegistry {
* Gets the valid context menu options for the given scope type (e.g. block or
* workspace) and scope. Blocks are only shown if the preconditionFn shows
* they should not be hidden.
*
* @param scopeType Type of scope where menu should be shown (e.g. on a block
* or on a workspace)
* @param scope Current scope of context menu (i.e., the exact workspace or
* block being clicked on)
* @return the list of ContextMenuOptions
* @returns the list of ContextMenuOptions
*/
getContextMenuOptions(scopeType: ScopeType, scope: Scope):
ContextMenuOption[] {

8
core/css.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Inject Blockly's CSS synchronously.
*/
/**
* Inject Blockly's CSS synchronously.
*
* @namespace Blockly.Css
*/
import * as goog from '../closure/goog/goog.js';
@@ -24,6 +21,7 @@ let injected = false;
/**
* Add some CSS to the blob that will be injected later. Allows optional
* components such as fields and the toolbox to store separate CSS.
*
* @param cssContent Multiline CSS string or an array of single lines of CSS.
* @alias Blockly.Css.register
*/
@@ -49,6 +47,7 @@ export function register(cssContent: string|string[]) {
* a) It loads synchronously and doesn't force a redraw later.
* b) It speeds up loading by not blocking on a separate HTTP transfer.
* c) The CSS content may be made dynamic depending on init options.
*
* @param hasCss If false, don't inject CSS (providing CSS becomes the
* document's responsibility).
* @param pathToMedia Path from page to the Blockly media directory.
@@ -79,6 +78,7 @@ export function inject(hasCss: boolean, pathToMedia: string) {
/**
* The CSS content for Blockly.
*
* @alias Blockly.Css.content
*/
let content = `

11
core/delete_area.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The abstract class for a component that can delete a block or
* bubble that is dropped on top of it.
*/
/**
* The abstract class for a component that can delete a block or
* bubble that is dropped on top of it.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -26,6 +22,7 @@ import type {IDraggable} from './interfaces/i_draggable.js';
/**
* Abstract class for a component that can delete a block or bubble that is
* dropped on top of it.
*
* @alias Blockly.DeleteArea
*/
export class DeleteArea extends DragTarget implements IDeleteArea {
@@ -56,9 +53,10 @@ export class DeleteArea extends DragTarget implements IDeleteArea {
* this area.
* This method should check if the element is deletable and is always called
* before onDragEnter/onDragOver/onDragExit.
*
* @param element The block or bubble currently being dragged.
* @param couldConnect Whether the element could could connect to another.
* @return Whether the element provided would be deleted if dropped on this
* @returns Whether the element provided would be deleted if dropped on this
* area.
*/
wouldDelete(element: IDraggable, couldConnect: boolean): boolean {
@@ -74,6 +72,7 @@ export class DeleteArea extends DragTarget implements IDeleteArea {
/**
* Updates the internal wouldDelete_ state.
*
* @param wouldDelete The new value for the wouldDelete state.
*/
protected updateWouldDelete_(wouldDelete: boolean) {

12
core/dialog.ts
View File

@@ -4,13 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Wrapper functions around JS functions for showing
* alert/confirmation dialogs.
*/
/**
* Wrapper functions around JS functions for showing alert/confirmation dialogs.
*
* @namespace Blockly.dialog
*/
import * as goog from '../closure/goog/goog.js';
@@ -39,6 +35,7 @@ let promptImplementation = function(
/**
* Wrapper to window.alert() that app developers may override via setAlert to
* provide alternatives to the modal browser window.
*
* @param message The message to display to the user.
* @param opt_callback The callback when the alert is dismissed.
* @alias Blockly.dialog.alert
@@ -50,6 +47,7 @@ export function alert(
/**
* Sets the function to be run when Blockly.dialog.alert() is called.
*
* @param alertFunction The function to be run.
* @see Blockly.dialog.alert
* @alias Blockly.dialog.setAlert
@@ -63,6 +61,7 @@ export function setAlert(
/**
* Wrapper to window.confirm() that app developers may override via setConfirm
* to provide alternatives to the modal browser window.
*
* @param message The message to display to the user.
* @param callback The callback for handling user response.
* @alias Blockly.dialog.confirm
@@ -83,6 +82,7 @@ function confirmInternal(
/**
* Sets the function to be run when Blockly.dialog.confirm() is called.
*
* @param confirmFunction The function to be run.
* @see Blockly.dialog.confirm
* @alias Blockly.dialog.setConfirm
@@ -98,6 +98,7 @@ export function setConfirm(
* provide alternatives to the modal browser window. Built-in browser prompts
* are often used for better text input experience on mobile device. We strongly
* recommend testing mobile when overriding this.
*
* @param message The message to display to the user.
* @param defaultValue The value to initialize the prompt with.
* @param callback The callback for handling user response.
@@ -111,6 +112,7 @@ export function prompt(
/**
* Sets the function to be run when Blockly.dialog.prompt() is called.
*
* @param promptFunction The function to be run.
* @see Blockly.dialog.prompt
* @alias Blockly.dialog.setPrompt

17
core/drag_target.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The abstract class for a component with custom behaviour when a
* block or bubble is dragged over or dropped on top of it.
*/
/**
* The abstract class for a component with custom behaviour when a
* block or bubble is dragged over or dropped on top of it.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -25,6 +21,7 @@ import type {Rect} from './utils/rect.js';
/**
* Abstract class for a component with custom behaviour when a block or bubble
* is dragged over or dropped on top of it.
*
* @alias Blockly.DragTarget
*/
export class DragTarget implements IDragTarget {
@@ -43,6 +40,7 @@ export class DragTarget implements IDragTarget {
/**
* Handles when a cursor with a block or bubble enters this drag target.
*
* @param _dragElement The block or bubble currently being dragged.
*/
onDragEnter(_dragElement: IDraggable) {}
@@ -51,6 +49,7 @@ export class DragTarget implements IDragTarget {
/**
* Handles when a cursor with a block or bubble is dragged over this drag
* target.
*
* @param _dragElement The block or bubble currently being dragged.
*/
onDragOver(_dragElement: IDraggable) {}
@@ -58,6 +57,7 @@ export class DragTarget implements IDragTarget {
/**
* Handles when a cursor with a block or bubble exits this drag target.
*
* @param _dragElement The block or bubble currently being dragged.
*/
onDragExit(_dragElement: IDraggable) {}
@@ -65,6 +65,7 @@ export class DragTarget implements IDragTarget {
/**
* Handles when a block or bubble is dropped on this component.
* Should not handle delete here.
*
* @param _dragElement The block or bubble currently being dragged.
*/
onDrop(_dragElement: IDraggable) {}
@@ -73,7 +74,8 @@ export class DragTarget implements IDragTarget {
/**
* Returns the bounding rectangle of the drag target area in pixel units
* relative to the Blockly injection div.
* @return The component's bounding box. Null if drag target area should be
*
* @returns The component's bounding box. Null if drag target area should be
* ignored.
*/
getClientRect(): Rect|null {
@@ -84,8 +86,9 @@ export class DragTarget implements IDragTarget {
* Returns whether the provided block or bubble should not be moved after
* being dropped on this component. If true, the element will return to where
* it was when the drag started.
*
* @param _dragElement The block or bubble currently being dragged.
* @return Whether the block or bubble provided should be returned to drag
* @returns Whether the block or bubble provided should be returned to drag
* start.
*/
shouldPreventMove(_dragElement: IDraggable): boolean {

66
core/dropdowndiv.ts
View File

@@ -5,13 +5,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview A div that floats on top of the workspace, for drop-down menus.
* The drop-down can be kept inside the workspace, animate in/out, etc.
*/
/**
* A div that floats on top of the workspace, for drop-down menus.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -115,6 +111,7 @@ export interface PositionMetrics {
/**
* Create and insert the DOM element for this div.
*
* @internal
*/
export function createDom() {
@@ -154,6 +151,7 @@ export function createDom() {
/**
* Set an element to maintain bounds within. Drop-downs will appear
* within the box of this element if possible.
*
* @param boundsElem Element to bind drop-down to.
*/
export function setBoundsElement(boundsElem: Element|null) {
@@ -162,7 +160,8 @@ export function setBoundsElement(boundsElem: Element|null) {
/**
* Provide the div for inserting content into the drop-down.
* @return Div to populate with content.
*
* @returns Div to populate with content.
*/
export function getContentDiv(): Element {
return content;
@@ -176,6 +175,7 @@ export function clearContent() {
/**
* Set the colour for the drop-down.
*
* @param backgroundColour Any CSS colour for the background.
* @param borderColour Any CSS colour for the border.
*/
@@ -189,11 +189,12 @@ export function setColour(backgroundColour: string, borderColour: string) {
* by a particular block. The primary position will be below the block,
* and the secondary position above the block. Drop-down will be
* constrained to the block's workspace.
*
* @param field The field showing the drop-down.
* @param block Block to position the drop-down around.
* @param opt_onHide Optional callback for when the drop-down is hidden.
* @param opt_secondaryYOffset Optional Y offset for above-block positioning.
* @return True if the menu rendered below block; false if above.
* @returns True if the menu rendered below block; false if above.
*/
export function showPositionedByBlock(
field: Field, block: BlockSvg, opt_onHide?: Function,
@@ -207,10 +208,11 @@ export function showPositionedByBlock(
* by a particular field. The primary position will be below the field,
* and the secondary position above the field. Drop-down will be
* constrained to the block's workspace.
*
* @param field The field to position the dropdown against.
* @param opt_onHide Optional callback for when the drop-down is hidden.
* @param opt_secondaryYOffset Optional Y offset for above-block positioning.
* @return True if the menu rendered below block; false if above.
* @returns True if the menu rendered below block; false if above.
*/
export function showPositionedByField(
field: Field, opt_onHide?: Function,
@@ -221,8 +223,9 @@ export function showPositionedByField(
}
/**
* Get the scaled bounding box of a block.
*
* @param block The block.
* @return The scaled bounding box of the block.
* @returns The scaled bounding box of the block.
*/
function getScaledBboxOfBlock(block: BlockSvg): Rect {
const blockSvg = block.getSvgRoot();
@@ -235,8 +238,9 @@ function getScaledBboxOfBlock(block: BlockSvg): Rect {
/**
* Get the scaled bounding box of a field.
*
* @param field The field.
* @return The scaled bounding box of the field.
* @returns The scaled bounding box of the field.
*/
function getScaledBboxOfField(field: Field): Rect {
const bBox = field.getScaledBBox();
@@ -248,11 +252,12 @@ function getScaledBboxOfField(field: Field): Rect {
* by a scaled bounding box. The primary position will be below the rect,
* and the secondary position above the rect. Drop-down will be constrained to
* the block's workspace.
*
* @param bBox The scaled bounding box.
* @param field The field to position the dropdown against.
* @param opt_onHide Optional callback for when the drop-down is hidden.
* @param opt_secondaryYOffset Optional Y offset for above-block positioning.
* @return True if the menu rendered below block; false if above.
* @returns True if the menu rendered below block; false if above.
*/
function showPositionedByRect(
bBox: Rect, field: Field, opt_onHide?: Function,
@@ -286,6 +291,7 @@ function showPositionedByRect(
* will point there, and the container will be positioned below it.
* If we can't maintain the container bounds at the primary point, fall-back to
* the secondary point and position above.
*
* @param newOwner The object showing the drop-down
* @param rtl Right-to-left (true) or left-to-right (false).
* @param primaryX Desired origin point x, in absolute px.
@@ -293,7 +299,7 @@ function showPositionedByRect(
* @param secondaryX Secondary/alternative origin point x, in absolute px.
* @param secondaryY Secondary/alternative origin point y, in absolute px.
* @param opt_onHide Optional callback for when the drop-down is hidden.
* @return True if the menu rendered at the primary origin point.
* @returns True if the menu rendered at the primary origin point.
* @internal
*/
export function show(
@@ -326,7 +332,8 @@ const internal = {};
/**
* Get sizing info about the bounding element.
* @return An object containing size information about the bounding element
*
* @returns An object containing size information about the bounding element
* (bounding box and width/height).
*/
// AnyDuringMigration because: Property 'getBoundsInfo' does not exist on type
@@ -348,12 +355,13 @@ const internal = {};
/**
* Helper to position the drop-down and the arrow, maintaining bounds.
* See explanation of origin points in show.
*
* @param primaryX Desired origin point x, in absolute px.
* @param primaryY Desired origin point y, in absolute px.
* @param secondaryX Secondary/alternative origin point x, in absolute px.
* @param secondaryY Secondary/alternative origin point y, in absolute px.
* @return Various final metrics, including rendered positions for drop-down and
* arrow.
* @returns Various final metrics, including rendered positions for drop-down
* and arrow.
*/
// AnyDuringMigration because: Property 'getPositionMetrics' does not exist on
// type '{}'.
@@ -388,14 +396,15 @@ const internal = {};
/**
* Get the metrics for positioning the div below the source.
*
* @param primaryX Desired origin point x, in absolute px.
* @param primaryY Desired origin point y, in absolute px.
* @param boundsInfo An object containing size information about the bounding
* element (bounding box and width/height).
* @param divSize An object containing information about the size of the
* DropDownDiv (width & height).
* @return Various final metrics, including rendered positions for drop-down and
* arrow.
* @returns Various final metrics, including rendered positions for drop-down
* and arrow.
*/
function getPositionBelowMetrics(
primaryX: number, primaryY: number, boundsInfo: BoundsInfo,
@@ -420,14 +429,15 @@ function getPositionBelowMetrics(
/**
* Get the metrics for positioning the div above the source.
*
* @param secondaryX Secondary/alternative origin point x, in absolute px.
* @param secondaryY Secondary/alternative origin point y, in absolute px.
* @param boundsInfo An object containing size information about the bounding
* element (bounding box and width/height).
* @param divSize An object containing information about the size of the
* DropDownDiv (width & height).
* @return Various final metrics, including rendered positions for drop-down and
* arrow.
* @returns Various final metrics, including rendered positions for drop-down
* and arrow.
*/
function getPositionAboveMetrics(
secondaryX: number, secondaryY: number, boundsInfo: BoundsInfo,
@@ -453,13 +463,14 @@ function getPositionAboveMetrics(
/**
* Get the metrics for positioning the div at the top of the page.
*
* @param sourceX Desired origin point x, in absolute px.
* @param boundsInfo An object containing size information about the bounding
* element (bounding box and width/height).
* @param divSize An object containing information about the size of the
* DropDownDiv (width & height).
* @return Various final metrics, including rendered positions for drop-down and
* arrow.
* @returns Various final metrics, including rendered positions for drop-down
* and arrow.
*/
function getPositionTopOfPageMetrics(
sourceX: number, boundsInfo: BoundsInfo, divSize: Size): PositionMetrics {
@@ -482,11 +493,12 @@ function getPositionTopOfPageMetrics(
/**
* Get the x positions for the left side of the DropDownDiv and the arrow,
* accounting for the bounds of the workspace.
*
* @param sourceX Desired origin point x, in absolute px.
* @param boundsLeft The left edge of the bounding element, in absolute px.
* @param boundsRight The right edge of the bounding element, in absolute px.
* @param divWidth The width of the div in px.
* @return An object containing metrics for the x positions of the left side of
* @returns An object containing metrics for the x positions of the left side of
* the DropDownDiv and the arrow.
* @internal
*/
@@ -514,7 +526,8 @@ export function getPositionX(
/**
* Is the container visible?
* @return True if visible.
*
* @returns True if visible.
*/
export function isVisible(): boolean {
return !!owner;
@@ -522,10 +535,11 @@ export function isVisible(): boolean {
/**
* Hide the menu only if it is owned by the provided object.
*
* @param divOwner Object which must be owning the drop-down to hide.
* @param opt_withoutAnimation True if we should hide the dropdown without
* animating.
* @return True if hidden.
* @returns True if hidden.
*/
export function hideIfOwner(
divOwner: AnyDuringMigration|null,
@@ -600,11 +614,12 @@ export function hideWithoutAnimation() {
/**
* Set the dropdown div's position.
*
* @param primaryX Desired origin point x, in absolute px.
* @param primaryY Desired origin point y, in absolute px.
* @param secondaryX Secondary/alternative origin point x, in absolute px.
* @param secondaryY Secondary/alternative origin point y, in absolute px.
* @return True if the menu rendered at the primary origin point.
* @returns True if the menu rendered at the primary origin point.
*/
function positionInternal(
primaryX: number, primaryY: number, secondaryX: number,
@@ -655,6 +670,7 @@ function positionInternal(
/**
* Repositions the dropdownDiv on window resize. If it doesn't know how to
* calculate the new position, it will just hide it instead.
*
* @internal
*/
export function repositionForWindowResize() {

5
core/events/events.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a result of actions in Blockly's editor.
*/
/**
* Events fired as a result of actions in Blockly's editor.
*
* @namespace Blockly.Events
*/
import * as goog from '../../closure/goog/goog.js';

18
core/events/events_abstract.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Abstract class for events fired as a result of actions in
* Blockly's editor.
*/
/**
* Abstract class for events fired as a result of actions in
* Blockly's editor.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -25,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Abstract class for an event.
*
* @alias Blockly.Events.Abstract
*/
export abstract class Abstract {
@@ -57,7 +54,8 @@ export abstract class Abstract {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
toJson(): AnyDuringMigration {
const json = {'type': this.type};
@@ -69,6 +67,7 @@ export abstract class Abstract {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
fromJson(json: AnyDuringMigration) {
@@ -78,7 +77,8 @@ export abstract class Abstract {
/**
* Does this event record any change of state?
* @return True if null, false if something changed.
*
* @returns True if null, false if something changed.
*/
isNull(): boolean {
return false;
@@ -86,6 +86,7 @@ export abstract class Abstract {
/**
* Run an event.
*
* @param _forward True if run forward, false if run backward (undo).
*/
run(_forward: boolean) {}
@@ -93,7 +94,8 @@ export abstract class Abstract {
/**
* Get workspace the event belongs to.
* @return The workspace the event belongs to.
*
* @returns The workspace the event belongs to.
* @throws {Error} if workspace is null.
* @internal
*/

10
core/events/events_block_base.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Base class for all types of block events.
*/
/**
* Base class for all types of block events.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -22,6 +19,7 @@ import {Abstract as AbstractEvent} from './events_abstract.js';
/**
* Abstract class for a block event.
*
* @alias Blockly.Events.BlockBase
*/
export class BlockBase extends AbstractEvent {
@@ -46,7 +44,8 @@ export class BlockBase extends AbstractEvent {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -56,6 +55,7 @@ export class BlockBase extends AbstractEvent {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

17
core/events/events_block_change.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for a block change event.
*/
/**
* Class for a block change event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -26,6 +23,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a block change event.
*
* @alias Blockly.Events.BlockChange
*/
export class BlockChange extends BlockBase {
@@ -63,7 +61,8 @@ export class BlockChange extends BlockBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -78,6 +77,7 @@ export class BlockChange extends BlockBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -90,7 +90,8 @@ export class BlockChange extends BlockBase {
/**
* Does this event record any change of state?
* @return False if something changed.
*
* @returns False if something changed.
*/
override isNull(): boolean {
return this.oldValue === this.newValue;
@@ -98,6 +99,7 @@ export class BlockChange extends BlockBase {
/**
* Run a change event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {
@@ -157,8 +159,9 @@ export class BlockChange extends BlockBase {
/**
* Returns the extra state of the given block (either as XML or a JSO,
* depending on the block's definition).
*
* @param block The block to get the extra state of.
* @return A stringified version of the extra state of the given block.
* @returns A stringified version of the extra state of the given block.
* @internal
*/
static getExtraBlockState_(block: BlockSvg): string {

11
core/events/events_block_create.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for a block creation event.
*/
/**
* Class for a block creation event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -26,6 +23,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a block creation event.
*
* @alias Blockly.Events.BlockCreate
*/
export class BlockCreate extends BlockBase {
@@ -61,7 +59,8 @@ export class BlockCreate extends BlockBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -76,6 +75,7 @@ export class BlockCreate extends BlockBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -90,6 +90,7 @@ export class BlockCreate extends BlockBase {
/**
* Run a creation event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

11
core/events/events_block_delete.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for a block delete event.
*/
/**
* Class for a block delete event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -26,6 +23,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a block deletion event.
*
* @alias Blockly.Events.BlockDelete
*/
export class BlockDelete extends BlockBase {
@@ -70,7 +68,8 @@ export class BlockDelete extends BlockBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -86,6 +85,7 @@ export class BlockDelete extends BlockBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -102,6 +102,7 @@ export class BlockDelete extends BlockBase {
/**
* Run a deletion event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

10
core/events/events_block_drag.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a block drag.
*/
/**
* Events fired as a block drag.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -24,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a block drag event.
*
* @alias Blockly.Events.BlockDrag
*/
export class BlockDrag extends UiBase {
@@ -57,7 +55,8 @@ export class BlockDrag extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -69,6 +68,7 @@ export class BlockDrag extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

17
core/events/events_block_move.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for a block move event.
*/
/**
* Class for a block move event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -32,6 +29,7 @@ interface BlockLocation {
/**
* Class for a block move event. Created before the move.
*
* @alias Blockly.Events.BlockMove
*/
export class BlockMove extends BlockBase {
@@ -71,7 +69,8 @@ export class BlockMove extends BlockBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -93,6 +92,7 @@ export class BlockMove extends BlockBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -119,7 +119,8 @@ export class BlockMove extends BlockBase {
/**
* Returns the parentId and input if the block is connected,
* or the XY location if disconnected.
* @return Collection of location info.
*
* @returns Collection of location info.
*/
private currentLocation_(): BlockLocation {
const workspace = this.getEventWorkspace_();
@@ -142,7 +143,8 @@ export class BlockMove extends BlockBase {
/**
* Does this event record any change of state?
* @return False if something changed.
*
* @returns False if something changed.
*/
override isNull(): boolean {
return this.oldParentId === this.newParentId &&
@@ -152,6 +154,7 @@ export class BlockMove extends BlockBase {
/**
* Run a move event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

10
core/events/events_bubble_open.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a result of bubble open.
*/
/**
* Events fired as a result of bubble open.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -24,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a bubble open event.
*
* @alias Blockly.Events.BubbleOpen
*/
export class BubbleOpen extends UiBase {
@@ -57,7 +55,8 @@ export class BubbleOpen extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -69,6 +68,7 @@ export class BubbleOpen extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

10
core/events/events_click.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a result of UI click in Blockly's editor.
*/
/**
* Events fired as a result of UI click in Blockly's editor.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -24,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a click event.
*
* @alias Blockly.Events.Click
*/
export class Click extends UiBase {
@@ -59,7 +57,8 @@ export class Click extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -72,6 +71,7 @@ export class Click extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

11
core/events/events_comment_base.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Base class for comment events.
*/
/**
* Base class for comment events.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -27,6 +24,7 @@ import * as eventUtils from './utils.js';
/**
* Abstract class for a comment event.
*
* @alias Blockly.Events.CommentBase
*/
export class CommentBase extends AbstractEvent {
@@ -62,7 +60,8 @@ export class CommentBase extends AbstractEvent {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -74,6 +73,7 @@ export class CommentBase extends AbstractEvent {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -83,6 +83,7 @@ export class CommentBase extends AbstractEvent {
/**
* Helper function for Comment[Create|Delete]
*
* @param event The event to run.
* @param create if True then Create, if False then Delete
*/

14
core/events/events_comment_change.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for comment change event.
*/
/**
* Class for comment change event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -24,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a comment change event.
*
* @alias Blockly.Events.CommentChange
*/
export class CommentChange extends CommentBase {
@@ -60,7 +58,8 @@ export class CommentChange extends CommentBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -71,6 +70,7 @@ export class CommentChange extends CommentBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -81,7 +81,8 @@ export class CommentChange extends CommentBase {
/**
* Does this event record any change of state?
* @return False if something changed.
*
* @returns False if something changed.
*/
override isNull(): boolean {
return this.oldContents_ === this.newContents_;
@@ -89,6 +90,7 @@ export class CommentChange extends CommentBase {
/**
* Run a change event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

11
core/events/events_comment_create.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for comment creation event.
*/
/**
* Class for comment creation event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -25,6 +22,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a comment creation event.
*
* @alias Blockly.Events.CommentCreate
*/
export class CommentCreate extends CommentBase {
@@ -52,7 +50,8 @@ export class CommentCreate extends CommentBase {
// TODO (#1266): "Full" and "minimal" serialization.
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -62,6 +61,7 @@ export class CommentCreate extends CommentBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -71,6 +71,7 @@ export class CommentCreate extends CommentBase {
/**
* Run a creation event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

11
core/events/events_comment_delete.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for comment deletion event.
*/
/**
* Class for comment deletion event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -24,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a comment deletion event.
*
* @alias Blockly.Events.CommentDelete
*/
export class CommentDelete extends CommentBase {
@@ -49,7 +47,8 @@ export class CommentDelete extends CommentBase {
// TODO (#1266): "Full" and "minimal" serialization.
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -58,6 +57,7 @@ export class CommentDelete extends CommentBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -66,6 +66,7 @@ export class CommentDelete extends CommentBase {
/**
* Run a creation event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

15
core/events/events_comment_move.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for comment move event.
*/
/**
* Class for comment move event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -25,6 +22,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a comment move event. Created before the move.
*
* @alias Blockly.Events.CommentMove
*/
export class CommentMove extends CommentBase {
@@ -83,6 +81,7 @@ export class CommentMove extends CommentBase {
/**
* Override the location before the move. Use this if you don't create the
* event until the end of the move, but you know the original location.
*
* @param xy The location before the move, in workspace coordinates.
*/
setOldCoordinate(xy: Coordinate) {
@@ -92,7 +91,8 @@ export class CommentMove extends CommentBase {
// TODO (#1266): "Full" and "minimal" serialization.
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -109,6 +109,7 @@ export class CommentMove extends CommentBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -126,7 +127,8 @@ export class CommentMove extends CommentBase {
/**
* Does this event record any change of state?
* @return False if something changed.
*
* @returns False if something changed.
*/
override isNull(): boolean {
return Coordinate.equals(this.oldCoordinate_, this.newCoordinate_);
@@ -134,6 +136,7 @@ export class CommentMove extends CommentBase {
/**
* Run a move event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

10
core/events/events_marker_move.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a result of a marker move.
*/
/**
* Events fired as a result of a marker move.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -26,6 +23,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a marker move event.
*
* @alias Blockly.Events.MarkerMove
*/
export class MarkerMove extends UiBase {
@@ -72,7 +70,8 @@ export class MarkerMove extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -85,6 +84,7 @@ export class MarkerMove extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

10
core/events/events_selected.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a result of element select action.
*/
/**
* Events fired as a result of element select action.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -23,6 +20,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a selected event.
*
* @alias Blockly.Events.Selected
*/
export class Selected extends UiBase {
@@ -55,7 +53,8 @@ export class Selected extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -66,6 +65,7 @@ export class Selected extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

10
core/events/events_theme_change.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a result of a theme update.
*/
/**
* Events fired as a result of a theme update.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -23,6 +20,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a theme change event.
*
* @alias Blockly.Events.ThemeChange
*/
export class ThemeChange extends UiBase {
@@ -46,7 +44,8 @@ export class ThemeChange extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -56,6 +55,7 @@ export class ThemeChange extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

10
core/events/events_toolbox_item_select.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a result of selecting an item on the toolbox.
*/
/**
* Events fired as a result of selecting an item on the toolbox.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -23,6 +20,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a toolbox item select event.
*
* @alias Blockly.Events.ToolboxItemSelect
*/
export class ToolboxItemSelect extends UiBase {
@@ -55,7 +53,8 @@ export class ToolboxItemSelect extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -66,6 +65,7 @@ export class ToolboxItemSelect extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

10
core/events/events_trashcan_open.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a result of trashcan flyout open and close.
*/
/**
* Events fired as a result of trashcan flyout open and close.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -23,6 +20,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a trashcan open event.
*
* @alias Blockly.Events.TrashcanOpen
*/
export class TrashcanOpen extends UiBase {
@@ -47,7 +45,8 @@ export class TrashcanOpen extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -57,6 +56,7 @@ export class TrashcanOpen extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

11
core/events/events_ui.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview (Deprecated) Events fired as a result of UI actions in
* Blockly's editor.
*/
/**
* (Deprecated) Events fired as a result of UI actions in
* Blockly's editor.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -26,6 +22,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a UI event.
*
* @deprecated December 2020. Instead use a more specific UI event.
* @alias Blockly.Events.Ui
*/
@@ -60,7 +57,8 @@ export class Ui extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -76,6 +74,7 @@ export class Ui extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

7
core/events/events_ui_base.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Base class for events fired as a result of UI actions in
* Blockly's editor.
*/
/**
* Base class for events fired as a result of UI actions in
* Blockly's editor.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -26,6 +22,7 @@ import {Abstract as AbstractEvent} from './events_abstract.js';
* editing to work (e.g. scrolling the workspace, zooming, opening toolbox
* categories).
* UI events do not undo or redo.
*
* @alias Blockly.Events.UiBase
*/
export class UiBase extends AbstractEvent {

10
core/events/events_var_base.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Abstract class for a variable event.
*/
/**
* Abstract class for a variable event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -22,6 +19,7 @@ import {Abstract as AbstractEvent} from './events_abstract.js';
/**
* Abstract class for a variable event.
*
* @alias Blockly.Events.VarBase
*/
export class VarBase extends AbstractEvent {
@@ -46,7 +44,8 @@ export class VarBase extends AbstractEvent {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -56,6 +55,7 @@ export class VarBase extends AbstractEvent {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

11
core/events/events_var_create.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for a variable creation event.
*/
/**
* Class for a variable creation event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -24,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a variable creation event.
*
* @alias Blockly.Events.VarCreate
*/
export class VarCreate extends VarBase {
@@ -52,7 +50,8 @@ export class VarCreate extends VarBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -63,6 +62,7 @@ export class VarCreate extends VarBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -73,6 +73,7 @@ export class VarCreate extends VarBase {
/**
* Run a variable creation event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

11
core/events/events_var_delete.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Classes for all types of variable events.
*/
/**
* Classes for all types of variable events.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -24,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a variable deletion event.
*
* @alias Blockly.Events.VarDelete
*/
export class VarDelete extends VarBase {
@@ -52,7 +50,8 @@ export class VarDelete extends VarBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -63,6 +62,7 @@ export class VarDelete extends VarBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -73,6 +73,7 @@ export class VarDelete extends VarBase {
/**
* Run a variable deletion event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

11
core/events/events_var_rename.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for a variable rename event.
*/
/**
* Class for a variable rename event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -24,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a variable rename event.
*
* @alias Blockly.Events.VarRename
*/
export class VarRename extends VarBase {
@@ -53,7 +51,8 @@ export class VarRename extends VarBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -64,6 +63,7 @@ export class VarRename extends VarBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {
@@ -74,6 +74,7 @@ export class VarRename extends VarBase {
/**
* Run a variable rename event.
*
* @param forward True if run forward, false if run backward (undo).
*/
override run(forward: boolean) {

10
core/events/events_viewport.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Events fired as a result of a viewport change.
*/
/**
* Events fired as a result of a viewport change.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -23,6 +20,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a viewport change event.
*
* @alias Blockly.Events.ViewportChange
*/
export class ViewportChange extends UiBase {
@@ -72,7 +70,8 @@ export class ViewportChange extends UiBase {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = super.toJson();
@@ -85,6 +84,7 @@ export class ViewportChange extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

60
core/events/utils.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Helper methods for events that are fired as a result of
* actions in Blockly's editor.
*/
/**
* Helper methods for events that are fired as a result of
* actions in Blockly's editor.
*
* @namespace Blockly.Events.utils
*/
import * as goog from '../../closure/goog/goog.js';
@@ -41,6 +37,7 @@ let recordUndo = true;
/**
* Sets whether events should be added to the undo stack.
*
* @param newValue True if events should be added to the undo stack.
* @alias Blockly.Events.utils.setRecordUndo
*/
@@ -50,6 +47,7 @@ export function setRecordUndo(newValue: boolean) {
/**
* Returns whether or not events will be added to the undo stack.
*
* @returns True if events will be added to the undo stack.
* @alias Blockly.Events.utils.getRecordUndo
*/
@@ -62,156 +60,182 @@ let disabled = 0;
/**
* Name of event that creates a block. Will be deprecated for BLOCK_CREATE.
*
* @alias Blockly.Events.utils.CREATE
*/
export const CREATE = 'create';
/**
* Name of event that creates a block.
*
* @alias Blockly.Events.utils.BLOCK_CREATE
*/
export const BLOCK_CREATE = CREATE;
/**
* Name of event that deletes a block. Will be deprecated for BLOCK_DELETE.
*
* @alias Blockly.Events.utils.DELETE
*/
export const DELETE = 'delete';
/**
* Name of event that deletes a block.
*
* @alias Blockly.Events.utils.BLOCK_DELETE
*/
export const BLOCK_DELETE = DELETE;
/**
* Name of event that changes a block. Will be deprecated for BLOCK_CHANGE.
*
* @alias Blockly.Events.utils.CHANGE
*/
export const CHANGE = 'change';
/**
* Name of event that changes a block.
*
* @alias Blockly.Events.utils.BLOCK_CHANGE
*/
export const BLOCK_CHANGE = CHANGE;
/**
* Name of event that moves a block. Will be deprecated for BLOCK_MOVE.
*
* @alias Blockly.Events.utils.MOVE
*/
export const MOVE = 'move';
/**
* Name of event that moves a block.
*
* @alias Blockly.Events.utils.BLOCK_MOVE
*/
export const BLOCK_MOVE = MOVE;
/**
* Name of event that creates a variable.
*
* @alias Blockly.Events.utils.VAR_CREATE
*/
export const VAR_CREATE = 'var_create';
/**
* Name of event that deletes a variable.
*
* @alias Blockly.Events.utils.VAR_DELETE
*/
export const VAR_DELETE = 'var_delete';
/**
* Name of event that renames a variable.
*
* @alias Blockly.Events.utils.VAR_RENAME
*/
export const VAR_RENAME = 'var_rename';
/**
* Name of generic event that records a UI change.
*
* @alias Blockly.Events.utils.UI
*/
export const UI = 'ui';
/**
* Name of event that record a block drags a block.
*
* @alias Blockly.Events.utils.BLOCK_DRAG
*/
export const BLOCK_DRAG = 'drag';
/**
* Name of event that records a change in selected element.
*
* @alias Blockly.Events.utils.SELECTED
*/
export const SELECTED = 'selected';
/**
* Name of event that records a click.
*
* @alias Blockly.Events.utils.CLICK
*/
export const CLICK = 'click';
/**
* Name of event that records a marker move.
*
* @alias Blockly.Events.utils.MARKER_MOVE
*/
export const MARKER_MOVE = 'marker_move';
/**
* Name of event that records a bubble open.
*
* @alias Blockly.Events.utils.BUBBLE_OPEN
*/
export const BUBBLE_OPEN = 'bubble_open';
/**
* Name of event that records a trashcan open.
*
* @alias Blockly.Events.utils.TRASHCAN_OPEN
*/
export const TRASHCAN_OPEN = 'trashcan_open';
/**
* Name of event that records a toolbox item select.
*
* @alias Blockly.Events.utils.TOOLBOX_ITEM_SELECT
*/
export const TOOLBOX_ITEM_SELECT = 'toolbox_item_select';
/**
* Name of event that records a theme change.
*
* @alias Blockly.Events.utils.THEME_CHANGE
*/
export const THEME_CHANGE = 'theme_change';
/**
* Name of event that records a viewport change.
*
* @alias Blockly.Events.utils.VIEWPORT_CHANGE
*/
export const VIEWPORT_CHANGE = 'viewport_change';
/**
* Name of event that creates a comment.
*
* @alias Blockly.Events.utils.COMMENT_CREATE
*/
export const COMMENT_CREATE = 'comment_create';
/**
* Name of event that deletes a comment.
*
* @alias Blockly.Events.utils.COMMENT_DELETE
*/
export const COMMENT_DELETE = 'comment_delete';
/**
* Name of event that changes a comment.
*
* @alias Blockly.Events.utils.COMMENT_CHANGE
*/
export const COMMENT_CHANGE = 'comment_change';
/**
* Name of event that moves a comment.
*
* @alias Blockly.Events.utils.COMMENT_MOVE
*/
export const COMMENT_MOVE = 'comment_move';
/**
* Name of event that records a workspace load.
*
* @alias Blockly.Events.utils.FINISHED_LOADING
*/
export const FINISHED_LOADING = 'finished_loading';
@@ -222,6 +246,7 @@ export const FINISHED_LOADING = 'finished_loading';
*
* Not to be confused with bumping so that disconnected connections do not
* appear connected.
*
* @alias Blockly.Events.utils.BumpEvent
*/
export type BumpEvent = BlockCreate|BlockMove|CommentCreate|CommentMove;
@@ -232,6 +257,7 @@ export type BumpEvent = BlockCreate|BlockMove|CommentCreate|CommentMove;
*
* Not to be confused with bumping so that disconnected connections do not
* appear connected.
*
* @alias Blockly.Events.utils.BUMP_EVENTS
*/
export const BUMP_EVENTS: string[] =
@@ -242,6 +268,7 @@ const FIRE_QUEUE: Abstract[] = [];
/**
* Create a custom event and fire it.
*
* @param event Custom data for event.
* @alias Blockly.Events.utils.fire
*/
@@ -281,9 +308,10 @@ function fireNow() {
/**
* Filter the queued events and merge duplicates.
*
* @param queueIn Array of events.
* @param forward True if forward (redo), false if backward (undo).
* @return Array of filtered events.
* @returns Array of filtered events.
* @alias Blockly.Events.utils.filter
*/
export function filter(queueIn: Abstract[], forward: boolean): Abstract[] {
@@ -367,6 +395,7 @@ export function filter(queueIn: Abstract[], forward: boolean): Abstract[] {
/**
* Modify pending undo events so that when they are fired they don't land
* in the undo stack. Called by Workspace.clearUndo.
*
* @alias Blockly.Events.utils.clearPendingUndo
*/
export function clearPendingUndo() {
@@ -377,6 +406,7 @@ export function clearPendingUndo() {
/**
* Stop sending events. Every call to this function MUST also call enable.
*
* @alias Blockly.Events.utils.disable
*/
export function disable() {
@@ -386,6 +416,7 @@ export function disable() {
/**
* Start sending events. Unless events were already disabled when the
* corresponding call to disable was made.
*
* @alias Blockly.Events.utils.enable
*/
export function enable() {
@@ -394,7 +425,8 @@ export function enable() {
/**
* Returns whether events may be fired or not.
* @return True if enabled.
*
* @returns True if enabled.
* @alias Blockly.Events.utils.isEnabled
*/
export function isEnabled(): boolean {
@@ -403,7 +435,8 @@ export function isEnabled(): boolean {
/**
* Current group.
* @return ID string.
*
* @returns ID string.
* @alias Blockly.Events.utils.getGroup
*/
export function getGroup(): string {
@@ -412,6 +445,7 @@ export function getGroup(): string {
/**
* Start or stop a group.
*
* @param state True to start new group, false to end group.
* String to set group explicitly.
* @alias Blockly.Events.utils.setGroup
@@ -433,8 +467,9 @@ function setGroupInternal(state: boolean|string) {
/**
* Compute a list of the IDs of the specified block and all its descendants.
*
* @param block The root block.
* @return List of block IDs.
* @returns List of block IDs.
* @alias Blockly.Events.utils.getDescendantIds
* @internal
*/
@@ -449,9 +484,10 @@ export function getDescendantIds(block: Block): string[] {
/**
* Decode the JSON into an event.
*
* @param json JSON representation.
* @param workspace Target workspace for event.
* @return The event represented by the JSON.
* @returns The event represented by the JSON.
* @throws {Error} if an event type is not found in the registry.
* @alias Blockly.Events.utils.fromJson
*/
@@ -469,8 +505,9 @@ export function fromJson(
/**
* Gets the class for a specific event type from the registry.
*
* @param eventType The type of the event to get.
* @return The event class with the given type or null if none exists.
* @returns The event class with the given type or null if none exists.
* @alias Blockly.Events.utils.get
*/
export function get(eventType: string):
@@ -483,6 +520,7 @@ export function get(eventType: string):
* Use this on applications where all blocks should be connected to a top block.
* Recommend setting the 'disable' option to 'false' in the config so that
* users don't try to re-enable disabled orphan blocks.
*
* @param event Custom data for event.
* @alias Blockly.Events.utils.disableOrphans
*/

10
core/events/workspace_events.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for a finished loading workspace event.
*/
/**
* Class for a finished loading workspace event.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -27,6 +24,7 @@ import * as eventUtils from './utils.js';
* Used to notify the developer when the workspace has finished loading (i.e
* domToWorkspace).
* Finished loading events do not record undo or redo.
*
* @alias Blockly.Events.FinishedLoading
*/
export class FinishedLoading extends AbstractEvent {
@@ -56,7 +54,8 @@ export class FinishedLoading extends AbstractEvent {
/**
* Encode the event as JSON.
* @return JSON representation.
*
* @returns JSON representation.
*/
override toJson(): AnyDuringMigration {
const json = {
@@ -73,6 +72,7 @@ export class FinishedLoading extends AbstractEvent {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

46
core/extensions.ts
View File

@@ -4,18 +4,12 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Extensions are functions that help initialize blocks, usually
* adding dynamic behavior such as onchange handlers and mutators. These
* are applied using Block.applyExtension(), or the JSON "extensions"
* array attribute.
*/
/**
* Extensions are functions that help initialize blocks, usually
* adding dynamic behavior such as onchange handlers and mutators. These
* are applied using Block.applyExtension(), or the JSON "extensions"
* array attribute.
*
* @namespace Blockly.Extensions
*/
import * as goog from '../closure/goog/goog.js';
@@ -40,6 +34,7 @@ export const TEST_ONLY = {allExtensions};
* initialize blocks, usually adding dynamic behavior such as onchange
* handlers and mutators. These are applied using Block.applyExtension(), or
* the JSON "extensions" array attribute.
*
* @param name The name of this extension.
* @param initFn The function to initialize an extended block.
* @throws {Error} if the extension name is empty, the extension is already
@@ -61,6 +56,7 @@ export function register(name: string, initFn: Function) {
/**
* Registers a new extension function that adds all key/value of mixinObj.
*
* @param name The name of this extension.
* @param mixinObj The values to mix in.
* @throws {Error} if the extension name is empty or the extension is already
@@ -81,6 +77,7 @@ export function registerMixin(name: string, mixinObj: AnyDuringMigration) {
* At register time this performs some basic sanity checks on the mutator.
* The wrapper may also add a mutator dialog to the block, if both compose and
* decompose are defined on the mixin.
*
* @param name The name of this mutator extension.
* @param mixinObj The values to mix in.
* @param opt_helperFn An optional function to apply after mixing in the object.
@@ -117,6 +114,7 @@ export function registerMutator(
/**
* Unregisters the extension registered with the given name.
*
* @param name The name of the extension to unregister.
* @alias Blockly.Extensions.unregister
*/
@@ -131,8 +129,9 @@ export function unregister(name: string) {
/**
* Returns whether an extension is registered with the given name.
*
* @param name The name of the extension to check for.
* @return True if the extension is registered. False if it is not registered.
* @returns True if the extension is registered. False if it is not registered.
* @alias Blockly.Extensions.isRegistered
*/
export function isRegistered(name: string): boolean {
@@ -142,6 +141,7 @@ export function isRegistered(name: string): boolean {
/**
* Applies an extension method to a block. This should only be called during
* block construction.
*
* @param name The name of the extension.
* @param block The block to apply the named extension to.
* @param isMutator True if this extension defines a mutator.
@@ -181,6 +181,7 @@ export function apply(name: string, block: Block, isMutator: boolean) {
* Check that the given block does not have any of the four mutator properties
* defined on it. This function should be called before applying a mutator
* extension to a block, to make sure we are not overwriting properties.
*
* @param mutationName The name of the mutation to reference in error messages.
* @param block The block to check.
* @throws {Error} if any of the properties already exist on the block.
@@ -198,9 +199,10 @@ function checkNoMutatorProperties(mutationName: string, block: Block) {
/**
* Checks if the given object has both the 'mutationToDom' and 'domToMutation'
* functions.
*
* @param object The object to check.
* @param errorPrefix The string to prepend to any error message.
* @return True if the object has both functions. False if it has neither
* @returns True if the object has both functions. False if it has neither
* function.
* @throws {Error} if the object has only one of the functions, or either is not
* actually a function.
@@ -214,9 +216,10 @@ function checkXmlHooks(
/**
* Checks if the given object has both the 'saveExtraState' and 'loadExtraState'
* functions.
*
* @param object The object to check.
* @param errorPrefix The string to prepend to any error message.
* @return True if the object has both functions. False if it has neither
* @returns True if the object has both functions. False if it has neither
* function.
* @throws {Error} if the object has only one of the functions, or either is not
* actually a function.
@@ -230,9 +233,10 @@ function checkJsonHooks(
/**
* Checks if the given object has both the 'compose' and 'decompose' functions.
*
* @param object The object to check.
* @param errorPrefix The string to prepend to any error message.
* @return True if the object has both functions. False if it has neither
* @returns True if the object has both functions. False if it has neither
* function.
* @throws {Error} if the object has only one of the functions, or either is not
* actually a function.
@@ -246,10 +250,11 @@ function checkMutatorDialog(
/**
* Checks that both or neither of the given functions exist and that they are
* indeed functions.
*
* @param func1 The first function in the pair.
* @param func2 The second function in the pair.
* @param errorPrefix The string to prepend to any error message.
* @return True if the object has both functions. False if it has neither
* @returns True if the object has both functions. False if it has neither
* function.
* @throws {Error} If the object has only one of the functions, or either is not
* actually a function.
@@ -270,6 +275,7 @@ function checkHasFunctionPair(
/**
* Checks that the given object required mutator properties.
*
* @param errorPrefix The string to prepend to any error message.
* @param object The object to inspect.
*/
@@ -289,9 +295,10 @@ function checkHasMutatorProperties(
/**
* Get a list of values of mutator properties on the given block.
*
* @param block The block to inspect.
* @return A list with all of the defined properties, which should be functions,
* but may be anything other than undefined.
* @returns A list with all of the defined properties, which should be
* functions, but may be anything other than undefined.
*/
function getMutatorProperties(block: Block): AnyDuringMigration[] {
const result = [];
@@ -322,9 +329,10 @@ function getMutatorProperties(block: Block): AnyDuringMigration[] {
* Check that the current mutator properties match a list of old mutator
* properties. This should be called after applying a non-mutator extension,
* to verify that the extension didn't change properties it shouldn't.
*
* @param oldProperties The old values to compare to.
* @param block The block to inspect for new values.
* @return True if the property lists match.
* @returns True if the property lists match.
*/
function mutatorPropertiesMatch(
oldProperties: AnyDuringMigration[], block: Block): boolean {
@@ -342,6 +350,7 @@ function mutatorPropertiesMatch(
/**
* Calls a function after the page has loaded, possibly immediately.
*
* @param fn Function to run.
* @throws Error Will throw if no global document can be found (e.g., Node.js).
* @internal
@@ -376,10 +385,11 @@ export function runAfterPageLoad(fn: () => AnyDuringMigration) {
* loading the first block of any given type, the extension will validate every
* dropdown option has a matching tooltip in the lookupTable. Errors are
* reported as warnings in the console, and are never fatal.
*
* @param dropdownName The name of the field whose value is the key to the
* lookup table.
* @param lookupTable The table of field values to tooltip text.
* @return The extension function.
* @returns The extension function.
* @alias Blockly.Extensions.buildTooltipForDropdown
*/
export function buildTooltipForDropdown(
@@ -432,6 +442,7 @@ export function buildTooltipForDropdown(
/**
* Checks all options keys are present in the provided string lookup table.
* Emits console warnings when they are not.
*
* @param block The block containing the dropdown
* @param dropdownName The name of the dropdown
* @param lookupTable The string lookup table
@@ -457,10 +468,11 @@ function checkDropdownOptionsInTable(
* Builds an extension function that will install a dynamic tooltip. The
* tooltip message should include the string '%1' and that string will be
* replaced with the text of the named field.
*
* @param msgTemplate The template form to of the message text, with %1
* placeholder.
* @param fieldName The field with the replacement text.
* @return The extension function.
* @returns The extension function.
* @alias Blockly.Extensions.buildTooltipWithFieldText
*/
export function buildTooltipWithFieldText(

123
core/field.ts
View File

@@ -4,16 +4,11 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Field. Used for editable titles, variables, etc.
* This is an abstract class that defines the UI on the block. Actual
* instances would be FieldTextInput, FieldDropdown, etc.
*/
/**
* Field. Used for editable titles, variables, etc.
* This is an abstract class that defines the UI on the block. Actual
* instances would be FieldTextInput, FieldDropdown, etc.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -58,6 +53,7 @@ import * as Xml from './xml.js';
/**
* Abstract class for an editable field.
*
* @alias Blockly.Field
*/
export abstract class Field implements IASTNodeLocationSvg,
@@ -140,6 +136,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Has this field been disposed of?
*
* @internal
*/
disposed = false;
@@ -169,12 +166,14 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* The prefix field.
*
* @internal
*/
prefixField: string|null = null;
/**
* The suffix field.
*
* @internal
*/
suffixField: string|null = null;
@@ -233,6 +232,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Process the configuration map passed to the field.
*
* @param config A map of options used to configure the field. See the
* individual field's documentation for a list of properties this
* parameter supports.
@@ -247,6 +247,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Attach this field to a block.
*
* @param block The block containing this field.
*/
setSourceBlock(block: Block) {
@@ -258,7 +259,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Get the renderer constant provider.
* @return The renderer constant provider.
*
* @returns The renderer constant provider.
*/
getConstants(): ConstantProvider|null {
if (!this.constants_ && this.sourceBlock_ && !this.sourceBlock_.disposed &&
@@ -272,7 +274,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Get the block this field is attached to.
* @return The block containing this field.
*
* @returns The block containing this field.
*/
getSourceBlock(): Block {
return this.sourceBlock_;
@@ -281,6 +284,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Initialize everything to render this field. Override
* methods initModel and initView rather than this method.
*
* @final
* @internal
*/
@@ -304,6 +308,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Create the block UI for this field.
*
* @internal
*/
initView() {
@@ -314,6 +319,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Initializes the model of the field after it has been installed on a block.
* No-op by default.
*
* @internal
*/
initModel() {}
@@ -368,6 +374,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Sets the field's value based on the given XML element. Should only be
* called by Blockly.Xml.
*
* @param fieldElement The element containing info about the field's state.
* @internal
*/
@@ -377,9 +384,10 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Serializes this field's value to XML. Should only be called by Blockly.Xml.
*
* @param fieldElement The element to populate with info about the field's
* state.
* @return The element containing info about the field's state.
* @returns The element containing info about the field's state.
* @internal
*/
toXml(fieldElement: Element): Element {
@@ -390,10 +398,11 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Saves this fields value as something which can be serialized to JSON.
* Should only be called by the serialization system.
*
* @param _doFullSerialization If true, this signals to the field that if it
* normally just saves a reference to some state (eg variable fields) it
* should instead serialize the full state of the thing being referenced.
* @return JSON serializable state.
* @returns JSON serializable state.
* @internal
*/
saveState(_doFullSerialization?: boolean): AnyDuringMigration {
@@ -407,6 +416,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Sets the field's state based on the given state value. Should only be
* called by the serialization system.
*
* @param state The state we want to apply to the field.
* @internal
*/
@@ -421,9 +431,10 @@ export abstract class Field implements IASTNodeLocationSvg,
* Returns a stringified version of the XML state, if it should be used.
* Otherwise this returns null, to signal the field should use its own
* serialization.
*
* @param callingClass The class calling this method.
* Used to see if `this` has overridden any relevant hooks.
* @return The stringified version of the XML state, or null.
* @returns The stringified version of the XML state, or null.
*/
protected saveLegacyState(callingClass: AnyDuringMigration): string|null {
if (callingClass.prototype.saveState === this.saveState &&
@@ -442,10 +453,11 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Loads the given state using either the old XML hooks, if they should be
* used. Returns true to indicate loading has been handled, false otherwise.
*
* @param callingClass The class calling this method.
* Used to see if `this` has overridden any relevant hooks.
* @param state The state to apply to the field.
* @return Whether the state was applied or not.
* @returns Whether the state was applied or not.
*/
loadLegacyState(callingClass: AnyDuringMigration, state: AnyDuringMigration):
boolean {
@@ -461,6 +473,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Dispose of all DOM objects and events belonging to this editable field.
*
* @internal
*/
dispose() {
@@ -497,6 +510,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Set whether this field's value can be changed using the editor when the
* source block is editable.
*
* @param enabled True if enabled.
*/
setEnabled(enabled: boolean) {
@@ -507,7 +521,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Check whether this field's value can be changed using the editor when the
* source block is editable.
* @return Whether this field is enabled.
*
* @returns Whether this field is enabled.
*/
isEnabled(): boolean {
return this.enabled_;
@@ -515,7 +530,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Check whether this field defines the showEditor_ function.
* @return Whether this field is clickable.
*
* @returns Whether this field is clickable.
*/
isClickable(): boolean {
return this.enabled_ && !!this.sourceBlock_ &&
@@ -527,7 +543,8 @@ export abstract class Field implements IASTNodeLocationSvg,
* Check whether this field is currently editable. Some fields are never
* EDITABLE (e.g. text labels). Other fields may be EDITABLE but may exist on
* non-editable blocks or be currently disabled.
* @return Whether this field is currently enabled, editable and on an
*
* @returns Whether this field is currently enabled, editable and on an
* editable block.
*/
isCurrentlyEditable(): boolean {
@@ -538,7 +555,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Check whether this field should be serialized by the XML renderer.
* Handles the logic for backwards compatibility and incongruous states.
* @return Whether this field should be serialized or not.
*
* @returns Whether this field should be serialized or not.
*/
isSerializable(): boolean {
let isSerializable = false;
@@ -558,7 +576,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Gets whether this editable field is visible or not.
* @return True if visible.
*
* @returns True if visible.
*/
isVisible(): boolean {
return this.visible_;
@@ -567,6 +586,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Sets whether this editable field is visible or not. Should only be called
* by input.setVisible.
*
* @param visible True if visible.
* @internal
*/
@@ -602,7 +622,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Gets the validation function for editable fields, or null if not set.
* @return Validation function, or null.
*
* @returns Validation function, or null.
*/
getValidator(): Function|null {
return this.validator_;
@@ -611,7 +632,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Gets the group element for this editable field.
* Used for measuring the size and for positioning.
* @return The group element.
*
* @returns The group element.
*/
getSvgRoot(): SVGGElement {
return this.fieldGroup_;
@@ -620,6 +642,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Updates the field to match the colour/style of the block. Should only be
* called by BlockSvg.applyColour().
*
* @internal
*/
applyColour() {}
@@ -641,6 +664,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Calls showEditor_ when the field is clicked if the field is clickable.
* Do not override.
*
* @param opt_e Optional mouse event that triggered the field to open, or
* undefined if triggered programmatically.
* @final
@@ -655,6 +679,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* A developer hook to create an editor for the field. This is no-op by
* default, and must be overriden to create an editor.
*
* @param _e Optional mouse event that triggered the field to open, or
* undefined if triggered programmatically.
*/
@@ -663,6 +688,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Updates the size of the field based on the text.
*
* @param opt_margin margin to use when positioning the text element.
*/
protected updateSize_(opt_margin?: number) {
@@ -694,6 +720,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Position a field's text element after a size change. This handles both LTR
* and RTL positioning.
*
* @param xOffset x offset to use when positioning the text element.
* @param contentWidth The content width.
*/
@@ -749,7 +776,8 @@ export abstract class Field implements IASTNodeLocationSvg,
* Returns the height and width of the field.
*
* This should *in general* be the only place render_ gets called from.
* @return Height and width.
*
* @returns Height and width.
*/
getSize(): Size {
if (!this.isVisible()) {
@@ -773,7 +801,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Returns the bounding box of the rendered field, accounting for workspace
* scaling.
* @return An object with top, bottom, left, and right in pixels relative to
*
* @returns An object with top, bottom, left, and right in pixels relative to
* the top left corner of the page (window coordinates).
* @internal
*/
@@ -810,7 +839,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Get the text from this field to display on the block. May differ from
* ``getText`` due to ellipsis, and other formatting.
* @return Text to display.
*
* @returns Text to display.
*/
protected getDisplayText_(): string {
let text = this.getText();
@@ -835,7 +865,8 @@ export abstract class Field implements IASTNodeLocationSvg,
* Get the text from this field.
* Override getText_ to provide a different behavior than simply casting the
* value to a string.
* @return Current text.
*
* @returns Current text.
* @final
*/
getText(): string {
@@ -853,7 +884,8 @@ export abstract class Field implements IASTNodeLocationSvg,
* Override if the text representation of the value of this field
* is not just a string cast of its value.
* Return null to resort to a string cast.
* @return Current text or null.
*
* @returns Current text or null.
*/
protected getText_(): string|null {
return null;
@@ -864,6 +896,7 @@ export abstract class Field implements IASTNodeLocationSvg,
* rerender this field and adjust for any sizing changes.
* Other fields on the same block will not rerender, because their sizes have
* already been recorded.
*
* @internal
*/
markDirty() {
@@ -878,6 +911,7 @@ export abstract class Field implements IASTNodeLocationSvg,
* rerender this field and adjust for any sizing changes.
* Other fields on the same block will not rerender, because their sizes have
* already been recorded.
*
* @internal
*/
forceRerender() {
@@ -893,6 +927,7 @@ export abstract class Field implements IASTNodeLocationSvg,
* Used to change the value of the field. Handles validation and events.
* Subclasses should override doClassValidation_ and doValueUpdate_ rather
* than this method.
*
* @param newValue New value.
* @final
*/
@@ -948,9 +983,10 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Process the result of validation.
*
* @param newValue New value.
* @param validatedValue Validated value.
* @return New value, or an Error object.
* @returns New value, or an Error object.
*/
private processValidation_(
newValue: AnyDuringMigration,
@@ -970,7 +1006,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Get the current value of the field.
* @return Current value.
*
* @returns Current value.
*/
getValue(): AnyDuringMigration {
return this.value_;
@@ -979,8 +1016,9 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Used to validate a value. Returns input by default. Can be overridden by
* subclasses, see FieldDropdown.
*
* @param opt_newValue The value to be validated.
* @return The validated value, same as input by default.
* @returns The validated value, same as input by default.
*/
protected doClassValidation_(opt_newValue?: AnyDuringMigration):
AnyDuringMigration {
@@ -993,6 +1031,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Used to update the value of a field. Can be overridden by subclasses to do
* custom storage of values/updating of external things.
*
* @param newValue The value to be saved.
*/
protected doValueUpdate_(newValue: AnyDuringMigration) {
@@ -1004,6 +1043,7 @@ export abstract class Field implements IASTNodeLocationSvg,
* Used to notify the field an invalid value was input. Can be overridden by
* subclasses, see FieldTextInput.
* No-op by default.
*
* @param _invalidValue The input value that was determined to be invalid.
*/
protected doValueInvalid_(_invalidValue: AnyDuringMigration) {}
@@ -1011,6 +1051,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Handle a mouse down event on a field.
*
* @param e Mouse down event.
*/
protected onMouseDown_(e: Event) {
@@ -1025,6 +1066,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Sets the tooltip for this field.
*
* @param newTip The text for the tooltip, a function that returns the text
* for the tooltip, a parent object whose tooltip will be used, or null to
* display the tooltip of the parent block. To not display a tooltip pass
@@ -1045,7 +1087,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Returns the tooltip text for this field.
* @return The tooltip text for this field.
*
* @returns The tooltip text for this field.
*/
getTooltip(): string {
const clickTarget = this.getClickTarget_();
@@ -1060,7 +1103,8 @@ export abstract class Field implements IASTNodeLocationSvg,
* The element to bind the click handler to. If not set explicitly, defaults
* to the SVG root of the field. When this element is
* clicked on an editable field, the editor will open.
* @return Element to bind click handler to.
*
* @returns Element to bind click handler to.
*/
protected getClickTarget_(): Element {
return this.clickTarget_ || this.getSvgRoot();
@@ -1069,7 +1113,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Return the absolute coordinates of the top-left corner of this field.
* The origin (0,0) is the top-left corner of the page body.
* @return Object with .x and .y properties.
*
* @returns Object with .x and .y properties.
*/
protected getAbsoluteXY_(): Coordinate {
return style.getPageOffset(this.getClickTarget_() as SVGRectElement);
@@ -1079,7 +1124,8 @@ export abstract class Field implements IASTNodeLocationSvg,
* Whether this field references any Blockly variables. If true it may need
* to be handled differently during serialization and deserialization.
* Subclasses may override this.
* @return True if this field has any variable references.
*
* @returns True if this field has any variable references.
* @internal
*/
referencesVariables(): boolean {
@@ -1089,6 +1135,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Refresh the variable name referenced by this field if this field references
* variables.
*
* @internal
*/
refreshVariableName() {}
@@ -1097,7 +1144,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Search through the list of inputs and their fields in order to find the
* parent input of a field.
* @return The input that the field belongs to.
*
* @returns The input that the field belongs to.
* @internal
*/
getParentInput(): Input {
@@ -1122,7 +1170,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Returns whether or not we should flip the field in RTL.
* @return True if we should flip in RTL.
*
* @returns True if we should flip in RTL.
*/
getFlipRtl(): boolean {
return false;
@@ -1130,7 +1179,8 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Returns whether or not the field is tab navigable.
* @return True if the field is tab navigable.
*
* @returns True if the field is tab navigable.
*/
isTabNavigable(): boolean {
return false;
@@ -1138,8 +1188,9 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Handles the given keyboard shortcut.
*
* @param _shortcut The shortcut to be handled.
* @return True if the shortcut has been handled, false otherwise.
* @returns True if the shortcut has been handled, false otherwise.
*/
onShortcut(_shortcut: KeyboardShortcut): boolean {
return false;
@@ -1147,6 +1198,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Add the cursor SVG to this fields SVG group.
*
* @param cursorSvg The SVG root of the cursor to be added to the field group.
* @internal
*/
@@ -1164,6 +1216,7 @@ export abstract class Field implements IASTNodeLocationSvg,
/**
* Add the marker SVG to this fields SVG group.
*
* @param markerSvg The SVG root of the marker to be added to the field group.
* @internal
*/

25
core/field_angle.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Angle input field.
*/
/**
* Angle input field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -33,6 +30,7 @@ import * as WidgetDiv from './widgetdiv.js';
/**
* Class for an editable angle field.
*
* @alias Blockly.FieldAngle
*/
export class FieldAngle extends FieldTextInput {
@@ -127,24 +125,28 @@ export class FieldAngle extends FieldTextInput {
/**
* Should the angle increase as the angle picker is moved clockwise (true)
* or counterclockwise (false)
*
* @see FieldAngle.CLOCKWISE
*/
this.clockwise_ = FieldAngle.CLOCKWISE;
/**
* The offset of zero degrees (and all other angles).
*
* @see FieldAngle.OFFSET
*/
this.offset_ = FieldAngle.OFFSET;
/**
* The maximum angle to allow before wrapping.
*
* @see FieldAngle.WRAP
*/
this.wrap_ = FieldAngle.WRAP;
/**
* The amount to round angles to when using a mouse or keyboard nav input.
*
* @see FieldAngle.ROUND
*/
this.round_ = FieldAngle.ROUND;
@@ -163,6 +165,7 @@ export class FieldAngle extends FieldTextInput {
/**
* Configure the field based on the given map of options.
*
* @param config A map of options to configure the field based on.
*/
protected override configure_(config: FieldAngleConfig) {
@@ -190,6 +193,7 @@ export class FieldAngle extends FieldTextInput {
/**
* Create the block UI for this field.
*
* @internal
*/
override initView() {
@@ -209,6 +213,7 @@ export class FieldAngle extends FieldTextInput {
/**
* Create and show the angle field's editor.
*
* @param opt_e Optional mouse event that triggered the field to open, or
* undefined if triggered programmatically.
*/
@@ -321,6 +326,7 @@ export class FieldAngle extends FieldTextInput {
/**
* Set the angle to match the mouse's position.
*
* @param e Mouse move event.
*/
protected onMouseMove_(e: Event) {
@@ -359,6 +365,7 @@ export class FieldAngle extends FieldTextInput {
* Handles and displays values that are input via mouse or arrow key input.
* These values need to be rounded and wrapped before being displayed so
* that the text input's value is appropriate.
*
* @param angle New angle.
*/
private displayMouseOrKeyboardValue_(angle: number) {
@@ -414,6 +421,7 @@ export class FieldAngle extends FieldTextInput {
/**
* Handle key down to the editor.
*
* @param e Keyboard event.
*/
protected override onHtmlInputKeyDown_(e: Event) {
@@ -451,8 +459,9 @@ export class FieldAngle extends FieldTextInput {
/**
* Ensure that the input value is a valid angle.
*
* @param opt_newValue The input value.
* @return A valid angle, or null if invalid.
* @returns A valid angle, or null if invalid.
*/
protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
number|null {
@@ -465,8 +474,9 @@ export class FieldAngle extends FieldTextInput {
/**
* Wraps the value so that it is in the range (-360 + wrap, wrap).
*
* @param value The value to wrap.
* @return The wrapped value.
* @returns The wrapped value.
*/
private wrapValue_(value: number): number {
value %= 360;
@@ -481,8 +491,9 @@ export class FieldAngle extends FieldTextInput {
/**
* Construct a FieldAngle from a JSON arg object.
*
* @param options A JSON object with options (angle).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/

31
core/field_checkbox.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Checkbox field. Checked or not checked.
*/
/**
* Checkbox field. Checked or not checked.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -26,6 +23,7 @@ import type {Sentinel} from './utils/sentinel.js';
/**
* Class for a checkbox field.
*
* @alias Blockly.FieldCheckbox
*/
export class FieldCheckbox extends Field {
@@ -84,6 +82,7 @@ export class FieldCheckbox extends Field {
/**
* Configure the field based on the given map of options.
*
* @param config A map of options to configure the field based on.
*/
protected override configure_(config: FieldCheckboxConfig) {
@@ -93,7 +92,8 @@ export class FieldCheckbox extends Field {
/**
* Saves this field's value.
* @return The boolean value held by this field.
*
* @returns The boolean value held by this field.
* @internal
*/
override saveState(): AnyDuringMigration {
@@ -106,6 +106,7 @@ export class FieldCheckbox extends Field {
/**
* Create the block UI for this checkbox.
*
* @internal
*/
override initView() {
@@ -128,6 +129,7 @@ export class FieldCheckbox extends Field {
/**
* Set the character used for the check mark.
*
* @param character The character to use for the check mark, or null to use
* the default.
*/
@@ -143,8 +145,9 @@ export class FieldCheckbox extends Field {
/**
* Ensure that the input value is valid ('TRUE' or 'FALSE').
*
* @param opt_newValue The input value.
* @return A valid value ('TRUE' or 'FALSE), or null if invalid.
* @returns A valid value ('TRUE' or 'FALSE), or null if invalid.
*/
protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
string|null {
@@ -159,6 +162,7 @@ export class FieldCheckbox extends Field {
/**
* Update the value of the field, and update the checkElement.
*
* @param newValue The value to be saved. The default validator guarantees
* that this is a either 'TRUE' or 'FALSE'.
*/
@@ -172,7 +176,8 @@ export class FieldCheckbox extends Field {
/**
* Get the value of this field, either 'TRUE' or 'FALSE'.
* @return The value of this field.
*
* @returns The value of this field.
*/
override getValue(): string {
return this.value_ ? 'TRUE' : 'FALSE';
@@ -180,7 +185,8 @@ export class FieldCheckbox extends Field {
/**
* Get the boolean value of this field.
* @return The boolean value of this field.
*
* @returns The boolean value of this field.
*/
getValueBoolean(): boolean {
return this.value_ as boolean;
@@ -188,7 +194,8 @@ export class FieldCheckbox extends Field {
/**
* Get the text of this field. Used when the block is collapsed.
* @return Text representing the value of this field ('true' or 'false').
*
* @returns Text representing the value of this field ('true' or 'false').
*/
override getText(): string {
return String(this.convertValueToBool_(this.value_));
@@ -199,8 +206,9 @@ export class FieldCheckbox extends Field {
*
* Converts 'TRUE' to true and 'FALSE' to false correctly, everything else
* is cast to a boolean.
*
* @param value The value to convert.
* @return The converted value.
* @returns The converted value.
*/
private convertValueToBool_(value: AnyDuringMigration): boolean {
if (typeof value === 'string') {
@@ -212,8 +220,9 @@ export class FieldCheckbox extends Field {
/**
* Construct a FieldCheckbox from a JSON arg object.
*
* @param options A JSON object with options (checked).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/

32
core/field_colour.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Colour input field.
*/
/**
* Colour input field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -35,6 +32,7 @@ import {Size} from './utils/size.js';
/**
* Class for a colour input field.
*
* @alias Blockly.FieldColour
*/
export class FieldColour extends Field {
@@ -172,6 +170,7 @@ export class FieldColour extends Field {
/**
* Configure the field based on the given map of options.
*
* @param config A map of options to configure the field based on.
*/
protected override configure_(config: FieldColourConfig) {
@@ -183,6 +182,7 @@ export class FieldColour extends Field {
/**
* Create the block UI for this colour field.
*
* @internal
*/
override initView() {
@@ -211,8 +211,9 @@ export class FieldColour extends Field {
/**
* Ensure that the input value is a valid colour.
*
* @param opt_newValue The input value.
* @return A valid colour, or null if invalid.
* @returns A valid colour, or null if invalid.
*/
protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
string|null {
@@ -224,6 +225,7 @@ export class FieldColour extends Field {
/**
* Update the value of this colour field, and update the displayed colour.
*
* @param newValue The value to be saved. The default validator guarantees
* that this is a colour in '#rrggbb' format.
*/
@@ -242,7 +244,8 @@ export class FieldColour extends Field {
/**
* Get the text for this field. Used when the block is collapsed.
* @return Text representing the value of this field.
*
* @returns Text representing the value of this field.
*/
override getText(): string {
let colour = this.value_ as string;
@@ -255,11 +258,12 @@ export class FieldColour extends Field {
/**
* Set a custom colour grid for this field.
*
* @param colours Array of colours for this block, or null to use default
* (FieldColour.COLOURS).
* @param opt_titles Optional array of colour tooltips, or null to use default
* (FieldColour.TITLES).
* @return Returns itself (for method chaining).
* @returns Returns itself (for method chaining).
*/
setColours(colours: string[], opt_titles?: string[]): FieldColour {
this.colours_ = colours;
@@ -271,9 +275,10 @@ export class FieldColour extends Field {
/**
* Set a custom grid size for this field.
*
* @param columns Number of columns for this block, or 0 to use default
* (FieldColour.COLUMNS).
* @return Returns itself (for method chaining).
* @returns Returns itself (for method chaining).
*/
setColumns(columns: number): FieldColour {
this.columns_ = columns;
@@ -297,6 +302,7 @@ export class FieldColour extends Field {
/**
* Handle a click on a colour cell.
*
* @param e Mouse event.
*/
private onClick_(e: MouseEvent) {
@@ -311,6 +317,7 @@ export class FieldColour extends Field {
/**
* Handle a key down event. Navigate around the grid with the
* arrow keys. Enter selects the highlighted colour.
*
* @param e Keyboard event.
*/
private onKeyDown_(e: KeyboardEvent) {
@@ -346,6 +353,7 @@ export class FieldColour extends Field {
/**
* Move the currently highlighted position by dx and dy.
*
* @param dx Change of x
* @param dy Change of y
*/
@@ -403,6 +411,7 @@ export class FieldColour extends Field {
/**
* Handle a mouse move event. Highlight the hovered colour.
*
* @param e Mouse event.
*/
private onMouseMove_(e: MouseEvent) {
@@ -436,7 +445,8 @@ export class FieldColour extends Field {
/**
* Returns the currently highlighted item (if any).
* @return Highlighted item (null if none).
*
* @returns Highlighted item (null if none).
*/
private getHighlighted_(): HTMLElement|null {
if (!this.highlightedIndex_) {
@@ -456,6 +466,7 @@ export class FieldColour extends Field {
/**
* Update the currently highlighted cell.
*
* @param cell the new cell to highlight
* @param index the index of the new cell
*/
@@ -563,8 +574,9 @@ export class FieldColour extends Field {
/**
* Construct a FieldColour from a JSON arg object.
*
* @param options A JSON object with options (colour).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/

43
core/field_dropdown.ts
View File

@@ -4,16 +4,11 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Dropdown input field. Used for editable titles and variables.
* In the interests of a consistent UI, the toolbox shares some functions and
* properties with the context menu.
*/
/**
* Dropdown input field. Used for editable titles and variables.
* In the interests of a consistent UI, the toolbox shares some functions and
* properties with the context menu.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -37,6 +32,7 @@ import * as userAgent from './utils/useragent.js';
/**
* Class for an editable dropdown field.
*
* @alias Blockly.FieldDropdown
*/
export class FieldDropdown extends Field {
@@ -86,12 +82,14 @@ export class FieldDropdown extends Field {
/**
* The prefix field label, of common words set after options are trimmed.
*
* @internal
*/
override prefixField: string|null = null;
/**
* The suffix field label, of common words set after options are trimmed.
*
* @internal
*/
override suffixField: string|null = null;
@@ -156,6 +154,7 @@ export class FieldDropdown extends Field {
/**
* Sets the field's value based on the given XML element. Should only be
* called by Blockly.Xml.
*
* @param fieldElement The element containing info about the field's state.
* @internal
*/
@@ -168,6 +167,7 @@ export class FieldDropdown extends Field {
/**
* Sets the field's value based on the given state.
*
* @param state The state to apply to the dropdown field.
* @internal
*/
@@ -183,6 +183,7 @@ export class FieldDropdown extends Field {
/**
* Create the block UI for this dropdown.
*
* @internal
*/
override initView() {
@@ -208,7 +209,8 @@ export class FieldDropdown extends Field {
/**
* Whether or not the dropdown should add a border rect.
* @return True if the dropdown field should add a border rect.
*
* @returns True if the dropdown field should add a border rect.
*/
protected shouldAddBorderRect_(): boolean {
return !this.getConstants()!.FIELD_DROPDOWN_NO_BORDER_RECT_SHADOW ||
@@ -249,6 +251,7 @@ export class FieldDropdown extends Field {
/**
* Create a dropdown menu under the text.
*
* @param opt_e Optional mouse event that triggered the field to open, or
* undefined if triggered programmatically.
*/
@@ -343,6 +346,7 @@ export class FieldDropdown extends Field {
/**
* Handle an action in the dropdown menu.
*
* @param menuItem The MenuItem selected within menu.
*/
private handleMenuActionEvent_(menuItem: MenuItem) {
@@ -352,6 +356,7 @@ export class FieldDropdown extends Field {
/**
* Handle the selection of an item in the dropdown menu.
*
* @param menu The Menu component clicked.
* @param menuItem The MenuItem selected within menu.
*/
@@ -411,7 +416,7 @@ export class FieldDropdown extends Field {
}
/**
* @return True if the option list is generated by a function.
* @returns True if the option list is generated by a function.
* Otherwise false.
*/
isOptionListDynamic(): boolean {
@@ -420,9 +425,10 @@ export class FieldDropdown extends Field {
/**
* Return a list of the options for this dropdown.
*
* @param opt_useCache For dynamic options, whether or not to use the cached
* options or to re-generate them.
* @return A non-empty array of option tuples:
* @returns A non-empty array of option tuples:
* (human-readable text or image, language-neutral name).
* @throws {TypeError} If generated options are incorrectly structured.
*/
@@ -442,8 +448,9 @@ export class FieldDropdown extends Field {
/**
* Ensure that the input value is a valid language-neutral option.
*
* @param opt_newValue The input value.
* @return A valid language-neutral option, or null if invalid.
* @returns A valid language-neutral option, or null if invalid.
*/
protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
string|null {
@@ -470,6 +477,7 @@ export class FieldDropdown extends Field {
/**
* Update the value of this dropdown field.
*
* @param newValue The value to be saved. The default validator guarantees
* that this is one of the valid dropdown options.
*/
@@ -485,6 +493,7 @@ export class FieldDropdown extends Field {
/**
* Updates the dropdown arrow to match the colour/style of the block.
*
* @internal
*/
override applyColour() {
@@ -526,6 +535,7 @@ export class FieldDropdown extends Field {
/**
* Renders the selected option, which must be an image.
*
* @param imageJson Selected option that must be an image.
*/
private renderSelectedImage_(imageJson: ImageProperties) {
@@ -613,9 +623,10 @@ export class FieldDropdown extends Field {
/**
* Position a drop-down arrow at the appropriate location at render-time.
*
* @param x X position the arrow is being rendered at, in px.
* @param y Y position the arrow is being rendered at, in px.
* @return Amount of space the arrow is taking up, in px.
* @returns Amount of space the arrow is taking up, in px.
*/
private positionSVGArrow_(x: number, y: number): number {
if (!this.svgArrow_) {
@@ -636,7 +647,8 @@ export class FieldDropdown extends Field {
* Use the `getText_` developer hook to override the field's text
* representation. Get the selected option text. If the selected option is an
* image we return the image alt text.
* @return Selected option text.
*
* @returns Selected option text.
*/
protected override getText_(): string|null {
if (!this.selectedOption_) {
@@ -651,8 +663,9 @@ export class FieldDropdown extends Field {
/**
* Construct a FieldDropdown from a JSON arg object.
*
* @param options A JSON object with options (options).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/
@@ -671,11 +684,12 @@ export class FieldDropdown extends Field {
/**
* Use the calculated prefix and suffix lengths to trim all of the options in
* the given array.
*
* @param options Array of option tuples:
* (human-readable text or image, language-neutral name).
* @param prefixLength The length of the common prefix.
* @param suffixLength The length of the common suffix
* @return A new array with all of the option text trimmed.
* @returns A new array with all of the option text trimmed.
*/
static applyTrim_(
options: AnyDuringMigration[][], prefixLength: number,
@@ -730,6 +744,7 @@ FieldDropdown.ARROW_CHAR = userAgent.ANDROID ? '\u25BC' : '\u25BE';
/**
* Validates the data structure to be processed as an options list.
*
* @param options The proposed dropdown options.
* @throws {TypeError} If proposed options are incorrectly structured.
*/

23
core/field_image.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Image field. Used for pictures, icons, etc.
*/
/**
* Image field. Used for pictures, icons, etc.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -26,6 +23,7 @@ import {Svg} from './utils/svg.js';
/**
* Class for an image on a block.
*
* @alias Blockly.FieldImage
*/
export class FieldImage extends Field {
@@ -127,6 +125,7 @@ export class FieldImage extends Field {
/**
* Configure the field based on the given map of options.
*
* @param config A map of options to configure the field based on.
*/
protected override configure_(config: FieldImageConfig) {
@@ -139,6 +138,7 @@ export class FieldImage extends Field {
/**
* Create the block UI for this image.
*
* @internal
*/
override initView() {
@@ -162,8 +162,9 @@ export class FieldImage extends Field {
/**
* Ensure that the input value (the source URL) is a string.
*
* @param opt_newValue The input value.
* @return A string, or null if invalid.
* @returns A string, or null if invalid.
*/
protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
string|null {
@@ -175,6 +176,7 @@ export class FieldImage extends Field {
/**
* Update the value of this image field, and update the displayed image.
*
* @param newValue The value to be saved. The default validator guarantees
* that this is a string.
*/
@@ -188,7 +190,8 @@ export class FieldImage extends Field {
/**
* Get whether to flip this image in RTL
* @return True if we should flip in RTL.
*
* @returns True if we should flip in RTL.
*/
override getFlipRtl(): boolean {
return this.flipRtl_;
@@ -196,6 +199,7 @@ export class FieldImage extends Field {
/**
* Set the alt text of this image.
*
* @param alt New alt text.
*/
setAlt(alt: string|null) {
@@ -220,6 +224,7 @@ export class FieldImage extends Field {
/**
* Set the function that is called when this image is clicked.
*
* @param func The function that is called when the image is clicked, or null
* to remove.
*/
@@ -231,7 +236,8 @@ export class FieldImage extends Field {
* Use the `getText_` developer hook to override the field's text
* representation.
* Return the image alt text instead.
* @return The image alt text.
*
* @returns The image alt text.
*/
protected override getText_(): string|null {
return this.altText_;
@@ -240,9 +246,10 @@ export class FieldImage extends Field {
/**
* Construct a FieldImage from a JSON arg object,
* dereferencing any string table references.
*
* @param options A JSON object with options (src, width, height, alt, and
* flipRtl).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/

15
core/field_label.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Non-editable, non-serializable text field. Used for titles,
* labels, etc.
*/
/**
* Non-editable, non-serializable text field. Used for titles,
* labels, etc.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -26,6 +22,7 @@ import type {Sentinel} from './utils/sentinel.js';
/**
* Class for a non-editable, non-serializable text field.
*
* @alias Blockly.FieldLabel
*/
export class FieldLabel extends Field {
@@ -73,6 +70,7 @@ export class FieldLabel extends Field {
/**
* Create block UI for this label.
*
* @internal
*/
override initView() {
@@ -84,8 +82,9 @@ export class FieldLabel extends Field {
/**
* Ensure that the input value casts to a valid string.
*
* @param opt_newValue The input value.
* @return A valid string, or null if invalid.
* @returns A valid string, or null if invalid.
*/
protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
string|null {
@@ -97,6 +96,7 @@ export class FieldLabel extends Field {
/**
* Set the CSS class applied to the field's textElement_.
*
* @param cssClass The new CSS class name, or null to remove.
*/
setClass(cssClass: string|null) {
@@ -116,8 +116,9 @@ export class FieldLabel extends Field {
/**
* Construct a FieldLabel from a JSON arg object,
* dereferencing any string table references.
*
* @param options A JSON object with options (text, and class).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/

11
core/field_label_serializable.ts
View File

@@ -4,16 +4,11 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Non-editable, serializable text field. Behaves like a
* normal label but is serialized to XML. It may only be
* edited programmatically.
*/
/**
* Non-editable, serializable text field. Behaves like a
* normal label but is serialized to XML. It may only be
* edited programmatically.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -26,6 +21,7 @@ import * as parsing from './utils/parsing.js';
/**
* Class for a non-editable, serializable text field.
*
* @alias Blockly.FieldLabelSerializable
*/
export class FieldLabelSerializable extends FieldLabel {
@@ -59,8 +55,9 @@ export class FieldLabelSerializable extends FieldLabel {
/**
* Construct a FieldLabelSerializable from a JSON arg object,
* dereferencing any string table references.
*
* @param options A JSON object with options (text, and class).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/

31
core/field_multilineinput.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Text Area field.
*/
/**
* Text Area field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -31,6 +28,7 @@ import * as WidgetDiv from './widgetdiv.js';
/**
* Class for an editable text area field.
*
* @alias Blockly.FieldMultilineInput
*/
export class FieldMultilineInput extends FieldTextInput {
@@ -90,9 +88,10 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Serializes this field's value to XML. Should only be called by Blockly.Xml.
*
* @param fieldElement The element to populate with info about the field's
* state.
* @return The element containing info about the field's state.
* @returns The element containing info about the field's state.
* @internal
*/
override toXml(fieldElement: Element): Element {
@@ -108,6 +107,7 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Sets the field's value based on the given XML element. Should only be
* called by Blockly.Xml.
*
* @param fieldElement The element containing info about the field's state.
* @internal
*/
@@ -117,7 +117,8 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Saves this field's value.
* @return The state of this field.
*
* @returns The state of this field.
* @internal
*/
override saveState(): AnyDuringMigration {
@@ -130,6 +131,7 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Sets the field's value based on the given state.
*
* @param state The state of the variable to assign to this variable field.
* @internal
*/
@@ -142,6 +144,7 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Create the block UI for this field.
*
* @internal
*/
override initView() {
@@ -156,7 +159,8 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Get the text from this field as displayed on screen. May differ from
* getText due to ellipsis, and other formatting.
* @return Currently displayed text.
*
* @returns Currently displayed text.
*/
protected override getDisplayText_(): string {
let textLines = this.getText();
@@ -197,6 +201,7 @@ export class FieldMultilineInput extends FieldTextInput {
* field, and updates the text of the field if it is not currently being
* edited (i.e. handled by the htmlInput_). Is being redefined here to update
* overflow state of the field.
*
* @param newValue The value to be saved. The default validator guarantees
* that this is a string.
*/
@@ -327,6 +332,7 @@ export class FieldMultilineInput extends FieldTextInput {
* Show the inline free-text editor on top of the text.
* Overrides the default behaviour to force rerender in order to
* correct block size, based on editor text.
*
* @param _opt_e Optional mouse event that triggered the field to open, or
* undefined if triggered programmatically.
* @param opt_quietInput True if editor should be created without focus.
@@ -339,7 +345,8 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Create the text input editor widget.
* @return The newly created text input editor.
*
* @returns The newly created text input editor.
*/
protected override widgetCreate_(): HTMLTextAreaElement {
const div = WidgetDiv.getDiv();
@@ -384,6 +391,7 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Sets the maxLines config for this field.
*
* @param maxLines Defines the maximum number of lines allowed, before
* scrolling functionality is enabled.
*/
@@ -397,7 +405,8 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Returns the maxLines config of this field.
* @return The maxLines config value.
*
* @returns The maxLines config value.
*/
getMaxLines(): number {
return this.maxLines_;
@@ -406,6 +415,7 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Handle key down to the editor. Override the text input definition of this
* so as to not close the editor when enter is typed in.
*
* @param e Keyboard event.
*/
protected override onHtmlInputKeyDown_(e: Event) {
@@ -419,8 +429,9 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Construct a FieldMultilineInput from a JSON arg object,
* dereferencing any string table references.
*
* @param options A JSON object with options (text, and spellcheck).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/

32
core/field_number.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Number input field
*/
/**
* Number input field
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -24,6 +21,7 @@ import type {Sentinel} from './utils/sentinel.js';
/**
* Class for an editable number field.
*
* @alias Blockly.FieldNumber
*/
export class FieldNumber extends FieldTextInput {
@@ -90,6 +88,7 @@ export class FieldNumber extends FieldTextInput {
/**
* Configure the field based on the given map of options.
*
* @param config A map of options to configure the field based on.
*/
protected override configure_(config: FieldNumberConfig) {
@@ -107,6 +106,7 @@ export class FieldNumber extends FieldTextInput {
* precision. The least significant digit place is inferred from the
* precision. Integers values can be enforces by choosing an integer
* precision.
*
* @param min Minimum value.
* @param max Maximum value.
* @param precision Precision for value.
@@ -123,6 +123,7 @@ export class FieldNumber extends FieldTextInput {
/**
* Sets the minimum value this field can contain. Updates the value to
* reflect.
*
* @param min Minimum value.
*/
setMin(min: number|string|undefined|null) {
@@ -133,6 +134,7 @@ export class FieldNumber extends FieldTextInput {
/**
* Sets the minimum value this field can contain. Called internally to avoid
* value updates.
*
* @param min Minimum value.
*/
private setMinInternal_(min: number|string|undefined|null) {
@@ -149,7 +151,8 @@ export class FieldNumber extends FieldTextInput {
/**
* Returns the current minimum value this field can contain. Default is
* -Infinity.
* @return The current minimum value this field can contain.
*
* @returns The current minimum value this field can contain.
*/
getMin(): number {
return this.min_;
@@ -158,6 +161,7 @@ export class FieldNumber extends FieldTextInput {
/**
* Sets the maximum value this field can contain. Updates the value to
* reflect.
*
* @param max Maximum value.
*/
setMax(max: number|string|undefined|null) {
@@ -168,6 +172,7 @@ export class FieldNumber extends FieldTextInput {
/**
* Sets the maximum value this field can contain. Called internally to avoid
* value updates.
*
* @param max Maximum value.
*/
private setMaxInternal_(max: number|string|undefined|null) {
@@ -184,7 +189,8 @@ export class FieldNumber extends FieldTextInput {
/**
* Returns the current maximum value this field can contain. Default is
* Infinity.
* @return The current maximum value this field can contain.
*
* @returns The current maximum value this field can contain.
*/
getMax(): number {
return this.max_;
@@ -193,6 +199,7 @@ export class FieldNumber extends FieldTextInput {
/**
* Sets the precision of this field's value, i.e. the number to which the
* value is rounded. Updates the field to reflect.
*
* @param precision The number to which the field's value is rounded.
*/
setPrecision(precision: number|string|undefined|null) {
@@ -203,6 +210,7 @@ export class FieldNumber extends FieldTextInput {
/**
* Sets the precision of this field's value. Called internally to avoid
* value updates.
*
* @param precision The number to which the field's value is rounded.
*/
private setPrecisionInternal_(precision: number|string|undefined|null) {
@@ -228,7 +236,8 @@ export class FieldNumber extends FieldTextInput {
* Returns the current precision of this field. The precision being the
* number to which the field's value is rounded. A precision of 0 means that
* the value is not rounded.
* @return The number to which this field's value is rounded.
*
* @returns The number to which this field's value is rounded.
*/
getPrecision(): number {
return this.precision_;
@@ -237,8 +246,9 @@ export class FieldNumber extends FieldTextInput {
/**
* Ensure that the input value is a valid number (must fulfill the
* constraints placed on the field).
*
* @param opt_newValue The input value.
* @return A valid number, or null if invalid.
* @returns A valid number, or null if invalid.
*/
protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
number|null {
@@ -276,7 +286,8 @@ export class FieldNumber extends FieldTextInput {
/**
* Create the number input editor widget.
* @return The newly created number input editor.
*
* @returns The newly created number input editor.
*/
protected override widgetCreate_(): HTMLElement {
const htmlInput = super.widgetCreate_();
@@ -293,8 +304,9 @@ export class FieldNumber extends FieldTextInput {
/**
* Construct a FieldNumber from a JSON arg object.
*
* @param options A JSON object with options (value, min, max, and precision).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/

16
core/field_registry.ts
View File

@@ -4,16 +4,11 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Fields can be created based on a JSON definition. This file
* contains methods for registering those JSON definitions, and building the
* fields based on JSON.
*/
/**
* Fields can be created based on a JSON definition. This file
* contains methods for registering those JSON definitions, and building the
* fields based on JSON.
*
* @namespace Blockly.fieldRegistry
*/
import * as goog from '../closure/goog/goog.js';
@@ -28,6 +23,7 @@ import * as registry from './registry.js';
* Registers a field type.
* fieldRegistry.fromJson uses this registry to
* find the appropriate field type.
*
* @param type The field type name as used in the JSON definition.
* @param fieldClass The field class containing a fromJson function that can
* construct an instance of the field.
@@ -41,6 +37,7 @@ export function register(type: string, fieldClass: IRegistrableField) {
/**
* Unregisters the field registered with the given type.
*
* @param type The field type name as used in the JSON definition.
* @alias Blockly.fieldRegistry.unregister
*/
@@ -52,10 +49,11 @@ export function unregister(type: string) {
* Construct a Field from a JSON arg object.
* Finds the appropriate registered field by the type name as registered using
* fieldRegistry.register.
*
* @param options A JSON object with a type and options specific to the field
* type.
* @return The new field instance or null if a field wasn't found with the given
* type name
* @returns The new field instance or null if a field wasn't found with the
* given type name
* @alias Blockly.fieldRegistry.fromJson
* @internal
*/
@@ -65,6 +63,8 @@ export function fromJson(options: AnyDuringMigration): Field|null {
/**
* Private version of fromJson for stubbing in tests.
*
* @param options
*/
function fromJsonInternal(options: AnyDuringMigration): Field|null {
const fieldObject =

38
core/field_textinput.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Text input field.
*/
/**
* Text input field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -39,6 +36,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Class for an editable text field.
*
* @alias Blockly.FieldTextInput
*/
export class FieldTextInput extends Field {
@@ -161,8 +159,9 @@ export class FieldTextInput extends Field {
/**
* Ensure that the input value casts to a valid string.
*
* @param opt_newValue The input value.
* @return A valid string, or null if invalid.
* @returns A valid string, or null if invalid.
*/
protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
AnyDuringMigration {
@@ -176,6 +175,7 @@ export class FieldTextInput extends Field {
* Called by setValue if the text input is not valid. If the field is
* currently being edited it reverts value of the field to the previous
* value while allowing the display text to be handled by the htmlInput_.
*
* @param _invalidValue The input value that was determined to be invalid.
* This is not used by the text input because its display value is stored
* on the htmlInput_.
@@ -198,6 +198,7 @@ export class FieldTextInput extends Field {
* Called by setValue if the text input is valid. Updates the value of the
* field, and updates the text of the field if it is not currently being
* edited (i.e. handled by the htmlInput_).
*
* @param newValue The value to be saved. The default validator guarantees
* that this is a string.
*/
@@ -212,6 +213,7 @@ export class FieldTextInput extends Field {
/**
* Updates text field to match the colour/style of the block.
*
* @internal
*/
override applyColour() {
@@ -250,6 +252,7 @@ export class FieldTextInput extends Field {
/**
* Set whether this field is spellchecked by the browser.
*
* @param check True if checked.
*/
setSpellcheck(check: boolean) {
@@ -267,6 +270,7 @@ export class FieldTextInput extends Field {
/**
* Show the inline free-text editor on top of the text.
*
* @param _opt_e Optional mouse event that triggered the field to open, or
* undefined if triggered programmatically.
* @param opt_quietInput True if editor should be created without focus.
@@ -299,6 +303,7 @@ export class FieldTextInput extends Field {
/**
* Create and show a text input editor that sits directly over the text input.
*
* @param quietInput True if editor should be created without focus.
*/
private showInlineEditor_(quietInput: boolean) {
@@ -316,7 +321,8 @@ export class FieldTextInput extends Field {
/**
* Create the text input editor widget.
* @return The newly created text input editor.
*
* @returns The newly created text input editor.
*/
protected widgetCreate_(): HTMLElement {
eventUtils.setGroup(true);
@@ -396,6 +402,7 @@ export class FieldTextInput extends Field {
/**
* A callback triggered when the user is done editing the field via the UI.
*
* @param _value The new value of the field.
*/
onFinishEditing_(_value: AnyDuringMigration) {}
@@ -404,6 +411,7 @@ export class FieldTextInput extends Field {
/**
* Bind handlers for user input on the text input field's editor.
*
* @param htmlInput The htmlInput to which event handlers will be bound.
*/
protected bindInputEvents_(htmlInput: HTMLElement) {
@@ -429,6 +437,7 @@ export class FieldTextInput extends Field {
/**
* Handle key down to the editor.
*
* @param e Keyboard event.
*/
protected onHtmlInputKeyDown_(e: Event) {
@@ -460,6 +469,7 @@ export class FieldTextInput extends Field {
/**
* Handle a change to the editor.
*
* @param _e Keyboard event.
*/
private onHtmlInputChange_(_e: Event) {
@@ -478,6 +488,7 @@ export class FieldTextInput extends Field {
* Set the HTML input value and the field's internal value. The difference
* between this and ``setValue`` is that this also updates the HTML input
* value whilst editing.
*
* @param newValue New value.
*/
protected setEditorValue_(newValue: AnyDuringMigration) {
@@ -510,7 +521,8 @@ export class FieldTextInput extends Field {
/**
* Returns whether or not the field is tab navigable.
* @return True if the field is tab navigable.
*
* @returns True if the field is tab navigable.
*/
override isTabNavigable(): boolean {
return true;
@@ -521,7 +533,8 @@ export class FieldTextInput extends Field {
* representation. When we're currently editing, return the current HTML value
* instead. Otherwise, return null which tells the field to use the default
* behaviour (which is a string cast of the field's value).
* @return The HTML value if we're editing, otherwise null.
*
* @returns The HTML value if we're editing, otherwise null.
*/
protected override getText_(): string|null {
if (this.isBeingEdited_ && this.htmlInput_) {
@@ -536,8 +549,9 @@ export class FieldTextInput extends Field {
* Override this method if the field's HTML input representation is different
* than the field's value. This should be coupled with an override of
* `getValueFromEditorText_`.
*
* @param value The value stored in this field.
* @return The text to show on the HTML input.
* @returns The text to show on the HTML input.
*/
protected getEditorText_(value: AnyDuringMigration): string {
return String(value);
@@ -549,8 +563,9 @@ export class FieldTextInput extends Field {
* Override this method if the field's HTML input representation is different
* than the field's value. This should be coupled with an override of
* `getEditorText_`.
*
* @param text Text received from the HTML input.
* @return The value to store.
* @returns The value to store.
*/
protected getValueFromEditorText_(text: string): AnyDuringMigration {
return text;
@@ -559,8 +574,9 @@ export class FieldTextInput extends Field {
/**
* Construct a FieldTextInput from a JSON arg object,
* dereferencing any string table references.
*
* @param options A JSON object with options (text, and spellcheck).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/

53
core/field_variable.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Variable input field.
*/
/**
* Variable input field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -36,6 +33,7 @@ import * as Xml from './xml.js';
/**
* Class for a variable's dropdown field.
*
* @alias Blockly.FieldVariable
*/
export class FieldVariable extends FieldDropdown {
@@ -121,6 +119,7 @@ export class FieldVariable extends FieldDropdown {
/**
* Configure the field based on the given map of options.
*
* @param config A map of options to configure the field based on.
*/
protected override configure_(config: FieldVariableConfig) {
@@ -132,6 +131,7 @@ export class FieldVariable extends FieldDropdown {
* Initialize the model for this field if it has not already been initialized.
* If the value has not been set to a variable by the first render, we make up
* a variable rather than let the value be invalid.
*
* @internal
*/
override initModel() {
@@ -153,6 +153,7 @@ export class FieldVariable extends FieldDropdown {
/**
* Initialize this field based on the given XML.
*
* @param fieldElement The element containing information about the variable
* field's state.
*/
@@ -184,9 +185,10 @@ export class FieldVariable extends FieldDropdown {
/**
* Serialize this field to XML.
*
* @param fieldElement The element to populate with info about the field's
* state.
* @return The element containing info about the field's state.
* @returns The element containing info about the field's state.
*/
override toXml(fieldElement: Element): Element {
// Make sure the variable is initialized.
@@ -202,10 +204,11 @@ export class FieldVariable extends FieldDropdown {
/**
* Saves this field's value.
*
* @param doFullSerialization If true, the variable field will serialize the
* full state of the field being referenced (ie ID, name, and type) rather
* than just a reference to it (ie ID).
* @return The state of the variable field.
* @returns The state of the variable field.
* @internal
*/
override saveState(doFullSerialization?: boolean): AnyDuringMigration {
@@ -225,6 +228,7 @@ export class FieldVariable extends FieldDropdown {
/**
* Sets the field's value based on the given state.
*
* @param state The state of the variable to assign to this variable field.
* @internal
*/
@@ -241,6 +245,7 @@ export class FieldVariable extends FieldDropdown {
/**
* Attach this field to a block.
*
* @param block The block containing this field.
*/
override setSourceBlock(block: Block) {
@@ -252,7 +257,8 @@ export class FieldVariable extends FieldDropdown {
/**
* Get the variable's ID.
* @return Current variable's ID.
*
* @returns Current variable's ID.
*/
override getValue(): string|null {
return this.variable_ ? this.variable_.getId() : null;
@@ -260,8 +266,9 @@ export class FieldVariable extends FieldDropdown {
/**
* Get the text from this field, which is the selected variable's name.
* @return The selected variable's name, or the empty string if no variable is
* selected.
*
* @returns The selected variable's name, or the empty string if no variable
* is selected.
*/
override getText(): string {
return this.variable_ ? this.variable_.name : '';
@@ -271,7 +278,8 @@ export class FieldVariable extends FieldDropdown {
* Get the variable model for the selected variable.
* Not guaranteed to be in the variable map on the workspace (e.g. if accessed
* after the variable has been deleted).
* @return The selected variable, or null if none was selected.
*
* @returns The selected variable, or null if none was selected.
* @internal
*/
getVariable(): VariableModel|null {
@@ -283,7 +291,8 @@ export class FieldVariable extends FieldDropdown {
* Returns null if the variable is not set, because validators should not
* run on the initial setValue call, because the field won't be attached to
* a block and workspace at that point.
* @return Validation function, or null.
*
* @returns Validation function, or null.
*/
override getValidator(): Function|null {
// Validators shouldn't operate on the initial setValue call.
@@ -297,8 +306,9 @@ export class FieldVariable extends FieldDropdown {
/**
* Ensure that the ID belongs to a valid variable of an allowed type.
*
* @param opt_newValue The ID of the new variable to set.
* @return The validated ID, or null if invalid.
* @returns The validated ID, or null if invalid.
*/
protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
string|null {
@@ -328,6 +338,7 @@ export class FieldVariable extends FieldDropdown {
*
* The variable ID should be valid at this point, but if a variable field
* validator returns a bad ID, this could break.
*
* @param newId The value to be saved.
*/
protected override doValueUpdate_(newId: AnyDuringMigration) {
@@ -338,8 +349,9 @@ export class FieldVariable extends FieldDropdown {
/**
* Check whether the given variable type is allowed on this field.
*
* @param type The type to check.
* @return True if the type is in the list of allowed types.
* @returns True if the type is in the list of allowed types.
*/
private typeIsAllowed_(type: string): boolean {
const typeList = this.getVariableTypes_();
@@ -356,7 +368,8 @@ export class FieldVariable extends FieldDropdown {
/**
* Return a list of variable types to include in the dropdown.
* @return Array of variable types.
*
* @returns Array of variable types.
* @throws {Error} if variableTypes is an empty array.
*/
private getVariableTypes_(): string[] {
@@ -381,6 +394,7 @@ export class FieldVariable extends FieldDropdown {
/**
* Parse the optional arguments representing the allowed variable types and
* the default variable type.
*
* @param opt_variableTypes A list of the types of variables to include in the
* dropdown. If null or undefined, variables of all types will be
* displayed in the dropdown.
@@ -424,6 +438,7 @@ export class FieldVariable extends FieldDropdown {
* Refreshes the name of the variable by grabbing the name of the model.
* Used when a variable gets renamed, but the ID stays the same. Should only
* be called by the block.
*
* @internal
*/
override refreshVariableName() {
@@ -434,6 +449,7 @@ export class FieldVariable extends FieldDropdown {
* Handle the selection of an item in the variable dropdown menu.
* Special case the 'Rename variable...' and 'Delete variable...' options.
* In the rename case, prompt the user for a new name.
*
* @param menu The Menu component clicked.
* @param menuItem The MenuItem selected within menu.
*/
@@ -459,7 +475,8 @@ export class FieldVariable extends FieldDropdown {
/**
* Overrides referencesVariables(), indicating this field refers to a
* variable.
* @return True.
*
* @returns True.
* @internal
*/
override referencesVariables(): boolean {
@@ -469,9 +486,10 @@ export class FieldVariable extends FieldDropdown {
/**
* Construct a FieldVariable from a JSON arg object,
* dereferencing any string table references.
*
* @param options A JSON object with options (variable, variableTypes, and
* defaultType).
* @return The new field instance.
* @returns The new field instance.
* @nocollapse
* @internal
*/
@@ -486,7 +504,8 @@ export class FieldVariable extends FieldDropdown {
/**
* Return a sorted list of variable names for variable dropdown menus.
* Include a special option at the end for creating a new variable name.
* @return Array of variable names/id tuples.
*
* @returns Array of variable names/id tuples.
*/
static dropdownCreate(this: FieldVariable): AnyDuringMigration[][] {
if (!this.variable_) {

90
core/flyout_base.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Flyout tray containing blocks which may be created.
*/
/**
* Flyout tray containing blocks which may be created.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -46,6 +43,7 @@ enum FlyoutItemType {
/**
* Class for a flyout.
*
* @alias Blockly.Flyout
*/
export abstract class Flyout extends DeleteArea implements IFlyout {
@@ -58,14 +56,16 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
* Determine if a drag delta is toward the workspace, based on the position
* and orientation of the flyout. This is used in determineDragIntention_ to
* determine if a new block should be created or if the flyout should scroll.
*
* @param currentDragDeltaXY How far the pointer has
* moved from the position at mouse down, in pixel units.
* @return True if the drag is toward the workspace.
* @returns True if the drag is toward the workspace.
*/
abstract isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean;
/**
* Sets the translation of the flyout to match the scrollbars.
*
* @param xyRatio Contains a y property which is a float
* between 0 and 1 specifying the degree of scrolling and a
* similar x property.
@@ -74,6 +74,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Lay out the blocks in the flyout.
*
* @param contents The blocks and buttons to lay
* out.
* @param gaps The visible gaps between blocks.
@@ -82,6 +83,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Scroll the flyout.
*
* @param e Mouse wheel scroll event.
*/
protected abstract wheel_(e: WheelEvent): void;
@@ -94,13 +96,15 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Calculates the x coordinate for the flyout position.
* @return X coordinate.
*
* @returns X coordinate.
*/
abstract getX(): number;
/**
* Calculates the y coordinate for the flyout position.
* @return Y coordinate.
*
* @returns Y coordinate.
*/
abstract getY(): number;
@@ -118,6 +122,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
RTL: boolean;
/**
* Whether the flyout should be laid out horizontally or not.
*
* @internal
*/
horizontalLayout = false;
@@ -163,6 +168,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* The target workspace.
*
* @internal
*/
targetWorkspace!: WorkspaceSvg;
@@ -277,6 +283,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* A map from blocks to the rects which are beneath them to act as input
* targets.
*
* @internal
*/
this.rectMap_ = new WeakMap();
@@ -304,9 +311,10 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
* Creates the flyout's DOM. Only needs to be called once. The flyout can
* either exist as its own SVG element or be a g element nested inside a
* separate SVG element.
*
* @param tagName The type of tag to
* put the flyout in. This should be <svg> or <g>.
* @return The flyout's SVG group.
* @returns The flyout's SVG group.
*/
createDom(tagName: string|Svg<SVGSVGElement>|Svg<SVGGElement>): SVGElement {
/*
@@ -331,6 +339,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Initializes the flyout.
*
* @param targetWorkspace The workspace in which to
* create new blocks.
*/
@@ -382,6 +391,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Dispose of this flyout.
* Unlink from all DOM elements to prevent memory leaks.
*
* @suppress {checkTypes}
*/
dispose() {
@@ -405,7 +415,8 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Get the width of the flyout.
* @return The width of the flyout.
*
* @returns The width of the flyout.
*/
getWidth(): number {
return this.width_;
@@ -413,7 +424,8 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Get the height of the flyout.
* @return The width of the flyout.
*
* @returns The width of the flyout.
*/
getHeight(): number {
return this.height_;
@@ -422,7 +434,8 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Get the scale (zoom level) of the flyout. By default,
* this matches the target workspace scale, but this can be overridden.
* @return Flyout workspace scale.
*
* @returns Flyout workspace scale.
*/
getFlyoutScale(): number {
return this.targetWorkspace.scale;
@@ -430,7 +443,8 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Get the workspace inside the flyout.
* @return The workspace inside the flyout.
*
* @returns The workspace inside the flyout.
* @internal
*/
getWorkspace(): WorkspaceSvg {
@@ -439,7 +453,8 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Is the flyout visible?
* @return True if visible.
*
* @returns True if visible.
*/
isVisible(): boolean {
return this.isVisible_;
@@ -449,6 +464,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
* Set whether the flyout is visible. A value of true does not necessarily
* mean that the flyout is shown. It could be hidden because its container is
* hidden.
*
* @param visible True if visible.
*/
setVisible(visible: boolean) {
@@ -467,6 +483,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Set whether this flyout's container is visible.
*
* @param visible Whether the container is visible.
*/
setContainerVisible(visible: boolean) {
@@ -498,6 +515,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Update the view based on coordinates calculated in position().
*
* @param width The computed width of the flyout's SVG group
* @param height The computed height of the flyout's SVG group.
* @param x The computed x origin of the flyout's SVG group.
@@ -560,6 +578,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Show and populate the flyout.
*
* @param flyoutDef Contents to display
* in the flyout. This is either an array of Nodes, a NodeList, a
* toolbox definition, or a string with the name of the dynamic category.
@@ -615,9 +634,10 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Create the contents array and gaps array necessary to create the layout for
* the flyout.
*
* @param parsedContent The array
* of objects to show in the flyout.
* @return The list of contents and gaps needed to lay out the flyout.
* @returns The list of contents and gaps needed to lay out the flyout.
*/
private createFlyoutInfo_(parsedContent: toolbox.FlyoutItemInfoArray):
{contents: FlyoutItem[], gaps: number[]} {
@@ -673,8 +693,9 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Gets the flyout definition for the dynamic category.
*
* @param categoryName The name of the dynamic category.
* @return The definition of the
* @returns The definition of the
* flyout in one of its many forms.
*/
private getDynamicCategoryContents_(categoryName: string):
@@ -694,9 +715,10 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Creates a flyout button or a flyout label.
*
* @param btnInfo The object holding information about a button or a label.
* @param isLabel True if the button is a label, false otherwise.
* @return The object used to display the button in the
* @returns The object used to display the button in the
* flyout.
*/
private createButton_(btnInfo: toolbox.ButtonOrLabelInfo, isLabel: boolean):
@@ -710,8 +732,9 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Create a block from the xml and permanently disable any blocks that were
* defined as disabled.
*
* @param blockInfo The info of the block.
* @return The block created from the blockInfo.
* @returns The block created from the blockInfo.
*/
private createFlyoutBlock_(blockInfo: toolbox.BlockInfo): BlockSvg {
let block;
@@ -745,8 +768,9 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Returns a block from the array of recycled blocks with the given type, or
* undefined if one cannot be found.
*
* @param blockType The type of the block to try to recycle.
* @return The recycled block, or undefined if
* @returns The recycled block, or undefined if
* one could not be recycled.
*/
private getRecycledBlock_(blockType: string): BlockSvg|undefined {
@@ -762,6 +786,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Adds a gap in the flyout based on block info.
*
* @param blockInfo Information about a block.
* @param gaps The list of gaps between items in the flyout.
* @param defaultGap The default gap between one element and the
@@ -783,6 +808,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Add the necessary gap in the flyout for a separator.
*
* @param sepInfo The object holding
* information about a separator.
* @param gaps The list gaps between items in the flyout.
@@ -848,8 +874,9 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Returns whether the given block can be recycled or not.
*
* @param _block The block to check for recyclability.
* @return True if the block can be recycled. False otherwise.
* @returns True if the block can be recycled. False otherwise.
*/
protected blockIsRecyclable_(_block: BlockSvg): boolean {
// By default, recycling is disabled.
@@ -860,6 +887,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
* Puts a previously created block into the recycle bin and moves it to the
* top of the workspace. Used during large workspace swaps to limit the number
* of new DOM elements we need to create.
*
* @param block The block to recycle.
*/
private recycleBlock_(block: BlockSvg) {
@@ -870,6 +898,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Add listeners to a block that has been added to the flyout.
*
* @param root The root node of the SVG group the block is in.
* @param block The block to add listeners for.
* @param rect The invisible rectangle under the block that acts
@@ -893,8 +922,9 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Handle a mouse-down on an SVG block in a non-closing flyout.
*
* @param block The flyout block to copy.
* @return Function to call when block is clicked.
* @returns Function to call when block is clicked.
*/
private blockMouseDown_(block: BlockSvg): Function {
return (e: MouseEvent) => {
@@ -908,6 +938,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Mouse down on the flyout background. Start a vertical scroll drag.
*
* @param e Mouse down event.
*/
private onMouseDown_(e: MouseEvent) {
@@ -920,8 +951,9 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Does this flyout allow you to create a new instance of the given block?
* Used for deciding if a block can be "dragged out of" the flyout.
*
* @param block The block to copy from the flyout.
* @return True if you can create a new instance of the block, false
* @returns True if you can create a new instance of the block, false
* otherwise.
* @internal
*/
@@ -931,8 +963,9 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Create a copy of this block on the workspace.
*
* @param originalBlock The block to copy from the flyout.
* @return The newly created block.
* @returns The newly created block.
* @throws {Error} if something went wrong with deserialization.
* @internal
*/
@@ -977,6 +1010,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Initialize the given button: move it to the correct location,
* add listeners, etc.
*
* @param button The button to initialize and place.
* @param x The x position of the cursor during this layout pass.
* @param y The y position of the cursor during this layout pass.
@@ -995,14 +1029,17 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Create and place a rectangle corresponding to the given block.
*
* @param block The block to associate the rect to.
* @param x The x position of the cursor during this layout pass.
* @param y The y position of the cursor during this layout pass.
* @param blockHW The height and width of
* the block.
* @param blockHW.height
* @param index The index into the mats list where this rect should
* be placed.
* @return Newly created SVG element for the rectangle behind
* @param blockHW.width
* @returns Newly created SVG element for the rectangle behind
* the block.
*/
protected createRect_(
@@ -1030,6 +1067,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Move a rectangle to sit exactly behind a block, taking into account tabs,
* hats, and any other protrusions we invent.
*
* @param rect The rectangle to move directly behind the block.
* @param block The block the rectangle should be behind.
*/
@@ -1078,7 +1116,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
}
/**
* @return True if this flyout may be scrolled with a scrollbar or
* @returns True if this flyout may be scrolled with a scrollbar or
* by dragging.
* @internal
*/
@@ -1089,8 +1127,9 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Copy a block from the flyout to the workspace and position it correctly.
*
* @param oldBlock The flyout block to copy.
* @return The new block in the main workspace.
* @returns The new block in the main workspace.
*/
private placeNewBlock_(oldBlock: BlockSvg): BlockSvg {
const targetWorkspace = this.targetWorkspace;
@@ -1112,6 +1151,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
/**
* Positions a block on the target workspace.
*
* @param oldBlock The flyout block being copied.
* @param block The block to posiiton.
*/

21
core/flyout_button.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class for a button in the flyout.
*/
/**
* Class for a button in the flyout.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -28,6 +25,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Class for a button or label in the flyout.
*
* @alias Blockly.FlyoutButton
*/
export class FlyoutButton {
@@ -88,7 +86,8 @@ export class FlyoutButton {
/**
* Create the button elements.
* @return The button's SVG group.
*
* @returns The button's SVG group.
*/
createDom(): SVGElement {
let cssClass = this.isLabel_ ? 'blocklyFlyoutLabel' : 'blocklyFlyoutButton';
@@ -190,6 +189,7 @@ export class FlyoutButton {
/**
* Move the button to the given x, y coordinates.
*
* @param x The new x coordinate.
* @param y The new y coordinate.
*/
@@ -199,28 +199,30 @@ export class FlyoutButton {
this.updateTransform_();
}
/** @return Whether or not the button is a label. */
/** @returns Whether or not the button is a label. */
isLabel(): boolean {
return this.isLabel_;
}
/**
* Location of the button.
* @return x, y coordinates.
*
* @returns x, y coordinates.
* @internal
*/
getPosition(): Coordinate {
return this.position_;
}
/** @return Text of the button. */
/** @returns Text of the button. */
getButtonText(): string {
return this.text_;
}
/**
* Get the button's target workspace.
* @return The target workspace of the flyout where this button resides.
*
* @returns The target workspace of the flyout where this button resides.
*/
getTargetWorkspace(): WorkspaceSvg {
return this.targetWorkspace;
@@ -241,6 +243,7 @@ export class FlyoutButton {
/**
* Do something when the button is clicked.
*
* @param e Mouse up event.
*/
private onMouseUp_(e: Event) {

22
core/flyout_horizontal.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Horizontal flyout tray containing blocks which may be created.
*/
/**
* Horizontal flyout tray containing blocks which may be created.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -30,6 +27,7 @@ import * as WidgetDiv from './widgetdiv.js';
/**
* Class for a flyout.
*
* @alias Blockly.HorizontalFlyout
*/
export class HorizontalFlyout extends Flyout {
@@ -47,6 +45,7 @@ export class HorizontalFlyout extends Flyout {
/**
* Sets the translation of the flyout to match the scrollbars.
*
* @param xyRatio Contains a y property which is a float between 0 and 1
* specifying the degree of scrolling and a similar x property.
*/
@@ -73,7 +72,8 @@ export class HorizontalFlyout extends Flyout {
/**
* Calculates the x coordinate for the flyout position.
* @return X coordinate.
*
* @returns X coordinate.
*/
override getX(): number {
// X is always 0 since this is a horizontal flyout.
@@ -82,7 +82,8 @@ export class HorizontalFlyout extends Flyout {
/**
* Calculates the y coordinate for the flyout position.
* @return Y coordinate.
*
* @returns Y coordinate.
*/
override getY(): number {
if (!this.isVisible()) {
@@ -150,6 +151,7 @@ export class HorizontalFlyout extends Flyout {
/**
* Create and set the path for the visible boundaries of the flyout.
*
* @param width The width of the flyout, not including the rounded corners.
* @param height The height of the flyout, not including rounded corners.
*/
@@ -199,6 +201,7 @@ export class HorizontalFlyout extends Flyout {
/**
* Scroll the flyout.
*
* @param e Mouse wheel scroll event.
*/
protected override wheel_(e: WheelEvent) {
@@ -225,6 +228,7 @@ export class HorizontalFlyout extends Flyout {
/**
* Lay out the blocks in the flyout.
*
* @param contents The blocks and buttons to lay out.
* @param gaps The visible gaps between blocks.
*/
@@ -281,9 +285,10 @@ export class HorizontalFlyout extends Flyout {
* Determine if a drag delta is toward the workspace, based on the position
* and orientation of the flyout. This is used in determineDragIntention_ to
* determine if a new block should be created or if the flyout should scroll.
*
* @param currentDragDeltaXY How far the pointer has moved from the position
* at mouse down, in pixel units.
* @return True if the drag is toward the workspace.
* @returns True if the drag is toward the workspace.
* @internal
*/
override isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean {
@@ -304,7 +309,8 @@ export class HorizontalFlyout extends Flyout {
/**
* Returns the bounding rectangle of the drag target area in pixel units
* relative to viewport.
* @return The component's bounding box. Null if drag target area should be
*
* @returns The component's bounding box. Null if drag target area should be
* ignored.
*/
override getClientRect(): Rect|null {

9
core/flyout_metrics_manager.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Calculates and reports flyout workspace metrics.
*/
/**
* Calculates and reports flyout workspace metrics.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -23,6 +20,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Calculates metrics for a flyout's workspace.
* The metrics are mainly used to size scrollbars for the flyout.
*
* @alias Blockly.FlyoutMetricsManager
*/
export class FlyoutMetricsManager extends MetricsManager {
@@ -41,7 +39,8 @@ export class FlyoutMetricsManager extends MetricsManager {
/**
* Gets the bounding box of the blocks on the flyout's workspace.
* This is in workspace coordinates.
* @return The bounding box of the blocks on the workspace.
*
* @returns The bounding box of the blocks on the workspace.
*/
private getBoundingBox_(): SVGRect|
{height: number, y: number, width: number, x: number} {

24
core/flyout_vertical.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Layout code for a vertical variant of the flyout.
*/
/**
* Layout code for a vertical variant of the flyout.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -35,6 +32,7 @@ import * as WidgetDiv from './widgetdiv.js';
/**
* Class for a flyout.
*
* @alias Blockly.VerticalFlyout
*/
export class VerticalFlyout extends Flyout {
@@ -54,8 +52,11 @@ export class VerticalFlyout extends Flyout {
/**
* Sets the translation of the flyout to match the scrollbars.
*
* @param xyRatio Contains a y property which is a float between 0 and 1
* specifying the degree of scrolling and a similar x property.
* @param xyRatio.x
* @param xyRatio.y
*/
protected override setMetrics_(xyRatio: {x: number, y: number}) {
if (!this.isVisible()) {
@@ -78,7 +79,8 @@ export class VerticalFlyout extends Flyout {
/**
* Calculates the x coordinate for the flyout position.
* @return X coordinate.
*
* @returns X coordinate.
*/
override getX(): number {
if (!this.isVisible()) {
@@ -126,7 +128,8 @@ export class VerticalFlyout extends Flyout {
/**
* Calculates the y coordinate for the flyout position.
* @return Y coordinate.
*
* @returns Y coordinate.
*/
override getY(): number {
// Y is always 0 since this is a vertical flyout.
@@ -155,6 +158,7 @@ export class VerticalFlyout extends Flyout {
/**
* Create and set the path for the visible boundaries of the flyout.
*
* @param width The width of the flyout, not including the rounded corners.
* @param height The height of the flyout, not including rounded corners.
*/
@@ -190,6 +194,7 @@ export class VerticalFlyout extends Flyout {
/**
* Scroll the flyout.
*
* @param e Mouse wheel scroll event.
*/
protected override wheel_(e: WheelEvent) {
@@ -215,6 +220,7 @@ export class VerticalFlyout extends Flyout {
/**
* Lay out the blocks in the flyout.
*
* @param contents The blocks and buttons to lay out.
* @param gaps The visible gaps between blocks.
*/
@@ -264,9 +270,10 @@ export class VerticalFlyout extends Flyout {
* Determine if a drag delta is toward the workspace, based on the position
* and orientation of the flyout. This is used in determineDragIntention_ to
* determine if a new block should be created or if the flyout should scroll.
*
* @param currentDragDeltaXY How far the pointer has moved from the position
* at mouse down, in pixel units.
* @return True if the drag is toward the workspace.
* @returns True if the drag is toward the workspace.
* @internal
*/
override isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean {
@@ -287,7 +294,8 @@ export class VerticalFlyout extends Flyout {
/**
* Returns the bounding rectangle of the drag target area in pixel units
* relative to viewport.
* @return The component's bounding box. Null if drag target area should be
*
* @returns The component's bounding box. Null if drag target area should be
* ignored.
*/
override getClientRect(): Rect|null {

47
core/generator.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Utility functions for generating executable code from
* Blockly code.
*/
/**
* Utility functions for generating executable code from
* Blockly code.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -26,6 +22,7 @@ import type {Workspace} from './workspace.js';
/**
* Class for a code generator that translates the blocks into a language.
*
* @unrestricted
* @alias Blockly.Generator
*/
@@ -110,8 +107,9 @@ export class Generator {
/**
* Generate code for all blocks in the workspace to the specified language.
*
* @param workspace Workspace to generate code from.
* @return Generated code.
* @returns Generated code.
*/
workspaceToCode(workspace?: Workspace): string {
if (!workspace) {
@@ -171,9 +169,10 @@ export class Generator {
/**
* Prepend a common prefix onto each line of code.
* Intended for indenting code or adding comment markers.
*
* @param text The lines of code.
* @param prefix The common prefix.
* @return The prefixed lines of code.
* @returns The prefixed lines of code.
*/
prefixLines(text: string, prefix: string): string {
return prefix + text.replace(/(?!\n$)\n/g, '\n' + prefix);
@@ -181,8 +180,9 @@ export class Generator {
/**
* Recursively spider a tree of blocks, returning all their comments.
*
* @param block The block from which to start spidering.
* @return Concatenated list of comments.
* @returns Concatenated list of comments.
*/
allNestedComments(block: Block): string {
const comments = [];
@@ -203,9 +203,10 @@ export class Generator {
/**
* Generate code for the specified block (and attached blocks).
* The generator must be initialized before calling this function.
*
* @param block The block to generate code for.
* @param opt_thisOnly True to generate code for only this statement.
* @return For statement blocks, the generated code.
* @returns For statement blocks, the generated code.
* For value blocks, an array containing the generated code and an
* operator order value. Returns '' if block is null.
*/
@@ -262,11 +263,12 @@ export class Generator {
/**
* Generate code representing the specified value input.
*
* @param block The block containing the input.
* @param name The name of the input.
* @param outerOrder The maximum binding strength (minimum order value) of any
* operators adjacent to "block".
* @return Generated code or '' if no blocks are connected or the specified
* @returns Generated code or '' if no blocks are connected or the specified
* input does not exist.
*/
valueToCode(block: Block, name: string, outerOrder: number): string {
@@ -336,9 +338,10 @@ export class Generator {
* statement input. Indent the code.
* This is mainly used in generators. When trying to generate code to evaluate
* look at using workspaceToCode or blockToCode.
*
* @param block The block containing the input.
* @param name The name of the input.
* @return Generated code or '' if no blocks are connected.
* @returns Generated code or '' if no blocks are connected.
*/
statementToCode(block: Block, name: string): string {
const targetBlock = block.getInputTargetBlock(name);
@@ -361,9 +364,10 @@ export class Generator {
* Add statement suffix at the start of the loop block (right after the loop
* statement executes), and a statement prefix to the end of the loop block
* (right before the loop statement executes).
*
* @param branch Code for loop contents.
* @param block Enclosing block.
* @return Loop contents, with infinite loop trap added.
* @returns Loop contents, with infinite loop trap added.
*/
addLoopTrap(branch: string, block: Block): string {
if (this.INFINITE_LOOP_TRAP) {
@@ -387,9 +391,10 @@ export class Generator {
/**
* Inject a block ID into a message to replace '%1'.
* Used for STATEMENT_PREFIX, STATEMENT_SUFFIX, and INFINITE_LOOP_TRAP.
*
* @param msg Code snippet with '%1'.
* @param block Block which has an ID.
* @return Code snippet with ID.
* @returns Code snippet with ID.
*/
injectId(msg: string, block: Block): string {
const id = block.id.replace(/\$/g, '$$$$'); // Issue 251.
@@ -398,6 +403,7 @@ export class Generator {
/**
* Add one or more words to the list of reserved words for this language.
*
* @param words Comma-separated list of words to add to the list.
* No spaces. Duplicates are ok.
*/
@@ -422,7 +428,7 @@ export class Generator {
* @param desiredName The desired name of the function (e.g. mathIsPrime).
* @param code A list of statements or one multi-line code string. Use ' '
* for indents (they will be replaced).
* @return The actual name of the new function. This may differ from
* @returns The actual name of the new function. This may differ from
* desiredName if the former has already been taken by the user.
*/
protected provideFunction_(desiredName: string, code: string[]|string):
@@ -455,6 +461,7 @@ export class Generator {
* Hook for code to run before code generation starts.
* Subclasses may override this, e.g. to initialise the database of variable
* names.
*
* @param _workspace Workspace to generate code from.
*/
init(_workspace: Workspace) {
@@ -473,10 +480,11 @@ export class Generator {
* Subclasses may override this, e.g. to generate code for statements
* following the block, or to handle comments for the specified block and any
* connected value blocks.
*
* @param _block The current block.
* @param code The code created for this block.
* @param _opt_thisOnly True to generate code for only this statement.
* @return Code with comments and subsequent blocks added.
* @returns Code with comments and subsequent blocks added.
*/
protected scrub_(_block: Block, code: string, _opt_thisOnly?: boolean):
string {
@@ -488,8 +496,9 @@ export class Generator {
* Hook for code to run at end of code generation.
* Subclasses may override this, e.g. to prepend the generated code with
* import statements or variable definitions.
*
* @param code Generated code.
* @return Completed code.
* @returns Completed code.
*/
finish(code: string): string {
// Optionally override
@@ -504,8 +513,9 @@ export class Generator {
* anything.
* Subclasses may override this, e.g. if their language does not allow
* naked values.
*
* @param line Line of generated code.
* @return Legal line of code.
* @returns Legal line of code.
*/
scrubNakedValue(line: string): string {
// Optionally override
@@ -516,6 +526,7 @@ export class Generator {
Object.defineProperties(Generator.prototype, {
/**
* A database of variable names.
*
* @name Blockly.Generator.prototype.variableDB_
* @deprecated 'variableDB_' was renamed to 'nameDB_' (May 2021).
* @suppress {checkTypes}
@@ -523,7 +534,7 @@ Object.defineProperties(Generator.prototype, {
// AnyDuringMigration because: Type 'Names | undefined' is not assignable to
// type 'PropertyDescriptor'.
variableDB_: ({
/** @return Name database. */
/** @returns Name database. */
get(this: Generator): Names |
undefined {
deprecation.warn(

66
core/gesture.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The class representing an in-progress gesture, usually a drag
* or a tap.
*/
/**
* The class representing an in-progress gesture, usually a drag
* or a tap.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -50,6 +46,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
// TODO: Consider touchcancel/pointercancel.
/**
* Class for one gesture.
*
* @alias Blockly.Gesture
*/
export class Gesture {
@@ -190,6 +187,7 @@ export class Gesture {
/**
* Sever all links from this object.
*
* @internal
*/
dispose() {
@@ -215,6 +213,7 @@ export class Gesture {
/**
* Update internal state based on an event.
*
* @param e The most recent mouse or touch event.
*/
private updateFromEvent_(e: Event) {
@@ -234,9 +233,10 @@ export class Gesture {
/**
* DO MATH to set currentDragDeltaXY_ based on the most recent mouse position.
*
* @param currentXY The most recent mouse/pointer position, in pixel units,
* with (0, 0) at the window's top left corner.
* @return True if the drag just exceeded the drag radius for the first time.
* @returns True if the drag just exceeded the drag radius for the first time.
*/
private updateDragDelta_(currentXY: Coordinate): boolean {
this.currentDragDeltaXY_ =
@@ -263,7 +263,8 @@ export class Gesture {
* gesture. If a block should be dragged from the flyout this function creates
* the new block on the main workspace and updates targetBlock_ and
* startWorkspace_.
* @return True if a block is being dragged from the flyout.
*
* @returns True if a block is being dragged from the flyout.
*/
private updateIsDraggingFromFlyout_(): boolean {
if (!this.targetBlock_) {
@@ -300,7 +301,8 @@ export class Gesture {
* the drag radius is exceeded. It should be called no more than once per
* gesture. If a bubble should be dragged this function creates the necessary
* BubbleDragger and starts the drag.
* @return True if a bubble is being dragged.
*
* @returns True if a bubble is being dragged.
*/
private updateIsDraggingBubble_(): boolean {
if (!this.startBubble_) {
@@ -319,7 +321,8 @@ export class Gesture {
* gesture. If a block should be dragged, either from the flyout or in the
* workspace, this function creates the necessary BlockDragger and starts the
* drag.
* @return True if a block is being dragged.
*
* @returns True if a block is being dragged.
*/
private updateIsDraggingBlock_(): boolean {
if (!this.targetBlock_) {
@@ -411,6 +414,7 @@ export class Gesture {
/**
* Start a gesture: update the workspace to indicate that a gesture is in
* progress and bind mousemove and mouseup handlers.
*
* @param e A mouse down or touch start event.
* @internal
*/
@@ -471,6 +475,7 @@ export class Gesture {
/**
* Bind gesture events.
*
* @param e A mouse down or touch start event.
* @internal
*/
@@ -486,6 +491,7 @@ export class Gesture {
/**
* Handle a mouse move or touch move event.
*
* @param e A mouse move or touch move event.
* @internal
*/
@@ -505,6 +511,7 @@ export class Gesture {
/**
* Handle a mouse up or touch end event.
*
* @param e A mouse up or touch end event.
* @internal
*/
@@ -548,6 +555,7 @@ export class Gesture {
/**
* Cancel an in-progress gesture. If a workspace or block drag is in
* progress, end the drag at the most recent location.
*
* @internal
*/
cancel() {
@@ -572,6 +580,7 @@ export class Gesture {
/**
* Handle a real or faked right-click event by showing a context menu.
*
* @param e A mouse move or touch move event.
* @internal
*/
@@ -596,6 +605,7 @@ export class Gesture {
/**
* Handle a mousedown/touchstart event on a workspace.
*
* @param e A mouse down or touch start event.
* @param ws The workspace the event hit.
* @internal
@@ -613,6 +623,7 @@ export class Gesture {
/**
* Fires a workspace click event.
*
* @param ws The workspace that a user clicks on.
*/
private fireWorkspaceClick_(ws: WorkspaceSvg) {
@@ -622,6 +633,7 @@ export class Gesture {
/**
* Handle a mousedown/touchstart event on a flyout.
*
* @param e A mouse down or touch start event.
* @param flyout The flyout the event hit.
* @internal
@@ -638,6 +650,7 @@ export class Gesture {
/**
* Handle a mousedown/touchstart event on a block.
*
* @param e A mouse down or touch start event.
* @param block The block the event hit.
* @internal
@@ -654,6 +667,7 @@ export class Gesture {
/**
* Handle a mousedown/touchstart event on a bubble.
*
* @param e A mouse down or touch start event.
* @param bubble The bubble the event hit.
* @internal
@@ -711,6 +725,7 @@ export class Gesture {
/**
* Execute a workspace click. When in accessibility mode shift clicking will
* move the cursor.
*
* @param _e A mouse up or touch end event.
*/
private doWorkspaceClick_(_e: Event) {
@@ -741,6 +756,7 @@ export class Gesture {
/**
* Record the field that a gesture started on.
*
* @param field The field the gesture started on.
* @internal
*/
@@ -757,6 +773,7 @@ export class Gesture {
/**
* Record the bubble that a gesture started on
*
* @param bubble The bubble the gesture started on.
* @internal
*/
@@ -769,6 +786,7 @@ export class Gesture {
/**
* Record the block that a gesture started on, and set the target block
* appropriately.
*
* @param block The block the gesture started on.
* @internal
*/
@@ -788,6 +806,7 @@ export class Gesture {
* Record the block that a gesture targets, meaning the block that will be
* dragged if this turns into a drag. If this block is a shadow, that will be
* its first non-shadow parent.
*
* @param block The block the gesture targets.
*/
private setTargetBlock_(block: BlockSvg) {
@@ -802,6 +821,7 @@ export class Gesture {
/**
* Record the workspace that a gesture started on.
*
* @param ws The workspace the gesture started on.
*/
private setStartWorkspace_(ws: WorkspaceSvg) {
@@ -812,6 +832,7 @@ export class Gesture {
/**
* Record the flyout that a gesture started on.
*
* @param flyout The flyout the gesture started on.
*/
private setStartFlyout_(flyout: IFlyout) {
@@ -828,7 +849,8 @@ export class Gesture {
/**
* Whether this gesture is a click on a bubble. This should only be called
* when ending a gesture (mouse up, touch end).
* @return Whether this gesture was a click on a bubble.
*
* @returns Whether this gesture was a click on a bubble.
*/
private isBubbleClick_(): boolean {
// A bubble click starts on a bubble and never escapes the drag radius.
@@ -839,7 +861,8 @@ export class Gesture {
/**
* Whether this gesture is a click on a block. This should only be called
* when ending a gesture (mouse up, touch end).
* @return Whether this gesture was a click on a block.
*
* @returns Whether this gesture was a click on a block.
*/
private isBlockClick_(): boolean {
// A block click starts on a block, never escapes the drag radius, and is
@@ -852,7 +875,8 @@ export class Gesture {
/**
* Whether this gesture is a click on a field. This should only be called
* when ending a gesture (mouse up, touch end).
* @return Whether this gesture was a click on a field.
*
* @returns Whether this gesture was a click on a field.
*/
private isFieldClick_(): boolean {
const fieldClickable =
@@ -864,7 +888,8 @@ export class Gesture {
/**
* Whether this gesture is a click on a workspace. This should only be called
* when ending a gesture (mouse up, touch end).
* @return Whether this gesture was a click on a workspace.
*
* @returns Whether this gesture was a click on a workspace.
*/
private isWorkspaceClick_(): boolean {
const onlyTouchedWorkspace =
@@ -878,7 +903,8 @@ export class Gesture {
* Whether this gesture is a drag of either a workspace or block.
* This function is called externally to block actions that cannot be taken
* mid-drag (e.g. using the keyboard to delete the selected blocks).
* @return True if this gesture is a drag of a workspace or block.
*
* @returns True if this gesture is a drag of a workspace or block.
* @internal
*/
isDragging(): boolean {
@@ -890,7 +916,8 @@ export class Gesture {
* Whether this gesture has already been started. In theory every mouse down
* has a corresponding mouse up, but in reality it is possible to lose a
* mouse up, leaving an in-process gesture hanging.
* @return Whether this gesture was a click on a workspace.
*
* @returns Whether this gesture was a click on a workspace.
* @internal
*/
hasStarted(): boolean {
@@ -900,7 +927,8 @@ export class Gesture {
/**
* Get a list of the insertion markers that currently exist. Block drags have
* 0, 1, or 2 insertion markers.
* @return A possibly empty list of insertion marker blocks.
*
* @returns A possibly empty list of insertion marker blocks.
* @internal
*/
getInsertionMarkers(): BlockSvg[] {
@@ -913,7 +941,8 @@ export class Gesture {
/**
* Gets the current dragger if an item is being dragged. Null if nothing is
* being dragged.
* @return The dragger that is currently in use or null if no drag is in
*
* @returns The dragger that is currently in use or null if no drag is in
* progress.
*/
getCurrentDragger(): WorkspaceDragger|BubbleDragger|IBlockDragger|null {
@@ -929,7 +958,8 @@ export class Gesture {
/**
* Is a drag or other gesture currently in progress on any workspace?
* @return True if gesture is occurring.
*
* @returns True if gesture is occurring.
*/
static inProgress(): boolean {
const workspaces = common.getAllWorkspaces();

22
core/grid.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Object for configuring and updating a workspace grid in
* Blockly.
*/
/**
* Object for configuring and updating a workspace grid in
* Blockly.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -24,6 +20,7 @@ import {GridOptions} from './blockly_options.js';
/**
* Class for a workspace's grid.
*
* @alias Blockly.Grid
*/
export class Grid {
@@ -63,7 +60,8 @@ export class Grid {
/**
* Whether blocks should snap to the grid, based on the initial configuration.
* @return True if blocks should snap, false otherwise.
*
* @returns True if blocks should snap, false otherwise.
* @internal
*/
shouldSnap(): boolean {
@@ -72,7 +70,8 @@ export class Grid {
/**
* Get the spacing of the grid points (in px).
* @return The spacing of the grid points.
*
* @returns The spacing of the grid points.
* @internal
*/
getSpacing(): number {
@@ -82,7 +81,8 @@ export class Grid {
/**
* Get the ID of the pattern element, which should be randomized to avoid
* conflicts with other Blockly instances on the page.
* @return The pattern ID.
*
* @returns The pattern ID.
* @internal
*/
getPatternId(): string {
@@ -91,6 +91,7 @@ export class Grid {
/**
* Update the grid with a new scale.
*
* @param scale The new workspace scale.
* @internal
*/
@@ -117,6 +118,7 @@ export class Grid {
/**
* Set the attributes on one of the lines in the grid. Use this to update the
* length and stroke width of the grid lines.
*
* @param line Which line to update.
* @param width The new stroke size (in px).
* @param x1 The new x start position of the line (in px).
@@ -139,6 +141,7 @@ export class Grid {
/**
* Move the grid to a new x and y position, and make sure that change is
* visible.
*
* @param x The new x position of the grid (in px).
* @param y The new y position of the grid (in px).
* @internal
@@ -150,10 +153,11 @@ export class Grid {
/**
* Create the DOM for the grid described by options.
*
* @param rnd A random ID to append to the pattern's ID.
* @param gridOptions The object containing grid configuration.
* @param defs The root SVG element for this workspace's defs.
* @return The SVG element for the grid pattern.
* @returns The SVG element for the grid pattern.
* @internal
*/
static createDom(rnd: string, gridOptions: GridOptions, defs: SVGElement):

19
core/icon.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Object representing an icon on a block.
*/
/**
* Object representing an icon on a block.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -27,6 +24,7 @@ import * as svgMath from './utils/svg_math.js';
/**
* Class for an icon.
*
* @alias Blockly.Icon
*/
export abstract class Icon {
@@ -88,7 +86,8 @@ export abstract class Icon {
/**
* Is the associated bubble visible?
* @return True if the bubble is visible.
*
* @returns True if the bubble is visible.
*/
isVisible(): boolean {
return !!this.bubble_;
@@ -96,6 +95,7 @@ export abstract class Icon {
/**
* Clicking on the icon toggles if the bubble is visible.
*
* @param e Mouse click event.
*/
protected iconClick_(e: MouseEvent) {
@@ -117,6 +117,7 @@ export abstract class Icon {
/**
* Notification that the icon has moved. Update the arrow accordingly.
*
* @param xy Absolute location in workspace coordinates.
*/
setIconLocation(xy: Coordinate) {
@@ -144,7 +145,8 @@ export abstract class Icon {
/**
* Returns the center of the block's icon relative to the surface.
* @return Object with x and y properties in workspace coordinates.
*
* @returns Object with x and y properties in workspace coordinates.
*/
getIconLocation(): Coordinate|null {
return this.iconXY_;
@@ -154,7 +156,8 @@ export abstract class Icon {
* Get the size of the icon as used for rendering.
* This differs from the actual size of the icon, because it bulges slightly
* out of its row rather than increasing the height of its row.
* @return Height and width.
*
* @returns Height and width.
*/
getCorrectedSize(): Size {
// TODO (#2562): Remove getCorrectedSize.
@@ -163,6 +166,7 @@ export abstract class Icon {
/**
* Draw the icon.
*
* @param _group The icon group.
*/
protected drawIcon_(_group: Element) {}
@@ -170,6 +174,7 @@ export abstract class Icon {
/**
* Show or hide the icon.
*
* @param _visible True if the icon should be visible.
*/
setVisible(_visible: boolean) {}

20
core/inject.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Functions for injecting Blockly into a web page.
*/
/**
* Functions for injecting Blockly into a web page.
*
* @namespace Blockly.inject
*/
import * as goog from '../closure/goog/goog.js';
@@ -40,9 +37,10 @@ import {WorkspaceSvg} from './workspace_svg.js';
/**
* Inject a Blockly editor into the specified container element (usually a div).
*
* @param container Containing element, or its ID, or a CSS selector.
* @param opt_options Optional dictionary of options.
* @return Newly created main workspace.
* @returns Newly created main workspace.
* @alias Blockly.inject
*/
export function inject(
@@ -101,9 +99,10 @@ export function inject(
/**
* Create the SVG image.
*
* @param container Containing element.
* @param options Dictionary of options.
* @return Newly created SVG image.
* @returns Newly created SVG image.
*/
function createDom(container: Element, options: Options): Element {
// Sadly browsers (Chrome vs Firefox) are currently inconsistent in laying
@@ -152,11 +151,12 @@ function createDom(container: Element, options: Options): Element {
/**
* Create a main workspace and add it to the SVG.
*
* @param svg SVG element with pattern defined.
* @param options Dictionary of options.
* @param blockDragSurface Drag surface SVG for the blocks.
* @param workspaceDragSurface Drag surface SVG for the workspace.
* @return Newly created main workspace.
* @returns Newly created main workspace.
*/
function createMainWorkspace(
svg: Element, options: Options, blockDragSurface: BlockDragSurfaceSvg,
@@ -206,6 +206,7 @@ function createMainWorkspace(
/**
* Initialize Blockly with various handlers.
*
* @param mainWorkspace Newly created main workspace.
*/
function init(mainWorkspace: WorkspaceSvg) {
@@ -275,6 +276,7 @@ function init(mainWorkspace: WorkspaceSvg) {
/**
* Handle a key-down on SVG drawing surface. Does nothing if the main workspace
* is not visible.
*
* @param e Key down event.
*/
// TODO (https://github.com/google/blockly/issues/1998) handle cases where there
@@ -340,6 +342,7 @@ function bindDocumentEvents() {
/**
* Load sounds for the given workspace.
*
* @param pathToMedia The path to the media directory.
* @param workspace The workspace to load sounds for.
*/
@@ -369,6 +372,9 @@ function loadSounds(pathToMedia: string, workspace: WorkspaceSvg) {
// Bind temporary hooks that preload the sounds.
const soundBinds: AnyDuringMigration[] = [];
/**
*
*/
function unbindSounds() {
while (soundBinds.length) {
browserEvents.unbind(soundBinds.pop());

39
core/input.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Object representing an input (value, statement, or dummy).
*/
/**
* Object representing an input (value, statement, or dummy).
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -29,6 +26,7 @@ import type {RenderedConnection} from './rendered_connection.js';
/**
* Class for an input with an optional field.
*
* @alias Blockly.Input
*/
export class Input {
@@ -61,7 +59,8 @@ export class Input {
/**
* Get the source block for this input.
* @return The source block, or null if there is none.
*
* @returns The source block, or null if there is none.
*/
getSourceBlock(): Block {
return this.sourceBlock_;
@@ -70,10 +69,11 @@ export class Input {
/**
* Add a field (or label from string), and all prefix and suffix fields, to
* the end of the input's field row.
*
* @param field Something to add as a field.
* @param opt_name Language-neutral identifier which may used to find this
* field again. Should be unique to the host block.
* @return The input being append to (to allow chaining).
* @returns The input being append to (to allow chaining).
*/
appendField(field: string|Field, opt_name?: string): Input {
this.insertFieldAt(this.fieldRow.length, field, opt_name);
@@ -83,11 +83,12 @@ export class Input {
/**
* Inserts a field (or label from string), and all prefix and suffix fields,
* at the location of the input's field row.
*
* @param index The index at which to insert field.
* @param field Something to add as a field.
* @param opt_name Language-neutral identifier which may used to find this
* field again. Should be unique to the host block.
* @return The index following the last inserted field.
* @returns The index following the last inserted field.
*/
insertFieldAt(index: number, field: string|Field, opt_name?: string): number {
if (index < 0 || index > this.fieldRow.length) {
@@ -137,9 +138,10 @@ export class Input {
/**
* Remove a field from this input.
*
* @param name The name of the field.
* @param opt_quiet True to prevent an error if field is not present.
* @return True if operation succeeds, false if field is not present and
* @returns True if operation succeeds, false if field is not present and
* opt_quiet is true.
* @throws {Error} if the field is not present and opt_quiet is false.
*/
@@ -164,7 +166,8 @@ export class Input {
/**
* Gets whether this input is visible or not.
* @return True if visible.
*
* @returns True if visible.
*/
isVisible(): boolean {
return this.visible_;
@@ -173,8 +176,9 @@ export class Input {
/**
* Sets whether this input is visible or not.
* Should only be used to collapse/uncollapse a block.
*
* @param visible True if visible.
* @return List of blocks to render.
* @returns List of blocks to render.
* @internal
*/
setVisible(visible: boolean): BlockSvg[] {
@@ -208,6 +212,7 @@ export class Input {
/**
* Mark all fields on this input as dirty.
*
* @internal
*/
markDirty() {
@@ -218,9 +223,10 @@ export class Input {
/**
* Change a connection's compatibility.
*
* @param check Compatible value type or list of value types. Null if all
* types are compatible.
* @return The input being modified (to allow chaining).
* @returns The input being modified (to allow chaining).
*/
setCheck(check: string|string[]|null): Input {
if (!this.connection) {
@@ -232,9 +238,10 @@ export class Input {
/**
* Change the alignment of the connection's field(s).
*
* @param align One of the values of Align. In RTL mode directions
* are reversed, and Align.RIGHT aligns to the left.
* @return The input being modified (to allow chaining).
* @returns The input being modified (to allow chaining).
*/
setAlign(align: Align): Input {
this.align = align;
@@ -247,8 +254,9 @@ export class Input {
/**
* Changes the connection's shadow block.
*
* @param shadow DOM representation of a block or null.
* @return The input being modified (to allow chaining).
* @returns The input being modified (to allow chaining).
*/
setShadowDom(shadow: Element|null): Input {
if (!this.connection) {
@@ -260,7 +268,8 @@ export class Input {
/**
* Returns the XML representation of the connection's shadow block.
* @return Shadow DOM representation of a block or null.
*
* @returns Shadow DOM representation of a block or null.
*/
getShadowDom(): Element|null {
if (!this.connection) {
@@ -281,6 +290,7 @@ export class Input {
/**
* Sever all links to this input.
*
* @suppress {checkTypes}
*/
dispose() {
@@ -296,6 +306,7 @@ export class Input {
export namespace Input {
/**
* Enum for alignment of inputs.
*
* @alias Blockly.Input.Align
*/
export enum Align {

6
core/input_types.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview An enum for the possible types of inputs.
*/
/**
* An enum for the possible types of inputs.
*
* @namespace Blockly.inputTypes
*/
import * as goog from '../closure/goog/goog.js';
@@ -20,6 +17,7 @@ import {ConnectionType} from './connection_type.js';
/**
* Enum for the type of a connection or input.
*
* @alias Blockly.inputTypes
*/
export enum inputTypes {

40
core/insertion_marker_manager.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Class that controls updates to connections during drags.
*/
/**
* Class that controls updates to connections during drags.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -50,6 +47,7 @@ const DUPLICATE_BLOCK_ERROR = 'The insertion marker ' +
* Class that controls updates to connections during drags. It is primarily
* responsible for finding the closest eligible connection and highlighting or
* unhighlighting it as needed during a drag.
*
* @alias Blockly.InsertionMarkerManager
*/
export class InsertionMarkerManager {
@@ -152,6 +150,7 @@ export class InsertionMarkerManager {
/**
* Sever all links from this object.
*
* @internal
*/
dispose() {
@@ -173,6 +172,7 @@ export class InsertionMarkerManager {
/**
* Update the available connections for the top block. These connections can
* change if a block is unplugged and the stack is healed.
*
* @internal
*/
updateAvailableConnections() {
@@ -182,7 +182,8 @@ export class InsertionMarkerManager {
/**
* Return whether the block would be deleted if dropped immediately, based on
* information from the most recent move event.
* @return True if the block would be deleted if dropped immediately.
*
* @returns True if the block would be deleted if dropped immediately.
* @internal
*/
wouldDeleteBlock(): boolean {
@@ -192,7 +193,8 @@ export class InsertionMarkerManager {
/**
* Return whether the block would be connected if dropped immediately, based
* on information from the most recent move event.
* @return True if the block would be connected if dropped immediately.
*
* @returns True if the block would be connected if dropped immediately.
* @internal
*/
wouldConnectBlock(): boolean {
@@ -202,6 +204,7 @@ export class InsertionMarkerManager {
/**
* Connect to the closest connection and render the results.
* This should be called at the end of a drag.
*
* @internal
*/
applyConnections() {
@@ -231,6 +234,7 @@ export class InsertionMarkerManager {
/**
* Update connections based on the most recent move location.
*
* @param dxy Position relative to drag start, in workspace units.
* @param dragTarget The drag target that the block is currently over.
* @internal
@@ -254,8 +258,9 @@ export class InsertionMarkerManager {
/**
* Create an insertion marker that represents the given block.
*
* @param sourceBlock The block that the insertion marker will represent.
* @return The insertion marker that represents the given block.
* @returns The insertion marker that represents the given block.
*/
private createMarkerBlock_(sourceBlock: BlockSvg): BlockSvg {
const imType = sourceBlock.type;
@@ -315,7 +320,8 @@ export class InsertionMarkerManager {
* should only be called once, at the beginning of a drag. If the stack has
* more than one block, this function will populate lastOnStack_ and create
* the corresponding insertion marker.
* @return A list of available connections.
*
* @returns A list of available connections.
*/
private initAvailableConnections_(): RenderedConnection[] {
const available = this.topBlock_.getConnections_(false);
@@ -340,10 +346,11 @@ export class InsertionMarkerManager {
/**
* Whether the previews (insertion marker and replacement marker) should be
* updated based on the closest candidate and the current drag distance.
*
* @param candidate An object containing a local connection, a closest
* connection, and a radius. Returned by getCandidate_.
* @param dxy Position relative to drag start, in workspace units.
* @return Whether the preview should be updated.
* @returns Whether the preview should be updated.
*/
private shouldUpdatePreviews_(
candidate: CandidateConnection, dxy: Coordinate): boolean {
@@ -390,8 +397,9 @@ export class InsertionMarkerManager {
/**
* Find the nearest valid connection, which may be the same as the current
* closest connection.
*
* @param dxy Position relative to drag start, in workspace units.
* @return An object containing a local connection, a closest connection, and
* @returns An object containing a local connection, a closest connection, and
* a radius.
*/
private getCandidate_(dxy: Coordinate): CandidateConnection {
@@ -424,7 +432,9 @@ export class InsertionMarkerManager {
/**
* Decide the radius at which to start searching for the closest connection.
* @return The radius at which to start the search for the closest connection.
*
* @returns The radius at which to start the search for the closest
* connection.
*/
private getStartRadius_(): number {
// If there is already a connection highlighted,
@@ -441,10 +451,11 @@ export class InsertionMarkerManager {
/**
* Whether ending the drag would delete the block.
*
* @param candidate An object containing a local connection, a closest
* connection, and a radius.
* @param dragTarget The drag target that the block is currently over.
* @return Whether dropping the block immediately would delete the block.
* @returns Whether dropping the block immediately would delete the block.
*/
private shouldDelete_(
candidate: CandidateConnection, dragTarget: IDragTarget|null): boolean {
@@ -465,6 +476,7 @@ export class InsertionMarkerManager {
* needed.
* At the beginning of this function, this.localConnection_ and
* this.closestConnection_ should both be null.
*
* @param candidate An object containing a local connection, a closest
* connection, and a radius.
*/
@@ -533,6 +545,7 @@ export class InsertionMarkerManager {
* needed.
* At the end of this function, this.localConnection_ and
* this.closestConnection_ should both be null.
*
* @param candidate An object containing a local connection, a closest
* connection, and a radius.
*/
@@ -757,7 +770,8 @@ export class InsertionMarkerManager {
/**
* Get a list of the insertion markers that currently exist. Drags have 0, 1,
* or 2 insertion markers.
* @return A possibly empty list of insertion marker blocks.
*
* @returns A possibly empty list of insertion marker blocks.
* @internal
*/
getInsertionMarkers(): BlockSvg[] {

6
core/interfaces/i_ast_node_location.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for an AST node location.
*/
/**
* The interface for an AST node location.
*
* @namespace Blockly.IASTNodeLocation
*/
import * as goog from '../../closure/goog/goog.js';
@@ -18,6 +15,7 @@ goog.declareModuleId('Blockly.IASTNodeLocation');
/**
* An AST node location interface.
*
* @alias Blockly.IASTNodeLocation
*/
export interface IASTNodeLocation {}

8
core/interfaces/i_ast_node_location_svg.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for an AST node location SVG.
*/
/**
* The interface for an AST node location SVG.
*
* @namespace Blockly.IASTNodeLocationSvg
*/
import * as goog from '../../closure/goog/goog.js';
@@ -20,17 +17,20 @@ import type {IASTNodeLocation} from './i_ast_node_location.js';
/**
* An AST node location SVG interface.
*
* @alias Blockly.IASTNodeLocationSvg
*/
export interface IASTNodeLocationSvg extends IASTNodeLocation {
/**
* Add the marker SVG to this node's SVG group.
*
* @param markerSvg The SVG root of the marker to be added to the SVG group.
*/
setMarkerSvg(markerSvg: SVGElement|null): void;
/**
* Add the cursor SVG to this node's SVG group.
*
* @param cursorSvg The SVG root of the cursor to be added to the SVG group.
*/
setCursorSvg(cursorSvg: SVGElement|null): void;

10
core/interfaces/i_ast_node_location_with_block.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for an AST node location that has an associated
* block.
*/
/**
* The interface for an AST node location that has an associated
* block.
*
* @namespace Blockly.IASTNodeLocationWithBlock
*/
import * as goog from '../../closure/goog/goog.js';
@@ -27,12 +23,14 @@ import type {Block} from '../block.js';
/**
* An AST node location that has an associated block.
*
* @alias Blockly.IASTNodeLocationWithBlock
*/
export interface IASTNodeLocationWithBlock extends IASTNodeLocation {
/**
* Get the source block associated with this node.
* @return The source block.
*
* @returns The source block.
*/
getSourceBlock(): Block;
}

8
core/interfaces/i_autohideable.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for a component that is automatically hidden
* when WorkspaceSvg.hideChaff is called.
*/
/**
* The interface for a component that is automatically hidden
* when WorkspaceSvg.hideChaff is called.
*
* @namespace Blockly.IAutoHideable
*/
import * as goog from '../../closure/goog/goog.js';
@@ -22,11 +18,13 @@ import type {IComponent} from './i_component.js';
/**
* Interface for a component that can be automatically hidden.
*
* @alias Blockly.IAutoHideable
*/
export interface IAutoHideable extends IComponent {
/**
* Hides the component. Called in WorkspaceSvg.hideChaff.
*
* @param onlyClosePopups Whether only popups should be closed.
* Flyouts should not be closed if this is true.
*/

12
core/interfaces/i_block_dragger.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for a block dragger.
*/
/**
* The interface for a block dragger.
*
* @namespace Blockly.IBlockDragger
*/
import * as goog from '../../closure/goog/goog.js';
@@ -27,11 +24,13 @@ goog.declareModuleId('Blockly.IBlockDragger');
/**
* A block dragger interface.
*
* @alias Blockly.IBlockDragger
*/
export interface IBlockDragger {
/**
* Start dragging a block. This includes moving it to the drag surface.
*
* @param currentDragDeltaXY How far the pointer has moved from the position
* at mouse down, in pixel units.
* @param healStack Whether or not to heal the stack after disconnecting.
@@ -41,6 +40,7 @@ export interface IBlockDragger {
/**
* Execute a step of block dragging, based on the given event. Update the
* display accordingly.
*
* @param e The most recent move event.
* @param currentDragDeltaXY How far the pointer has moved from the position
* at the start of the drag, in pixel units.
@@ -49,6 +49,7 @@ export interface IBlockDragger {
/**
* Finish a block drag and put the block back on the workspace.
*
* @param e The mouseup/touchend event.
* @param currentDragDeltaXY How far the pointer has moved from the position
* at the start of the drag, in pixel units.
@@ -58,7 +59,8 @@ export interface IBlockDragger {
/**
* Get a list of the insertion markers that currently exist. Drags have 0, 1,
* or 2 insertion markers.
* @return A possibly empty list of insertion marker blocks.
*
* @returns A possibly empty list of insertion marker blocks.
*/
getInsertionMarkers(): BlockSvg[];

10
core/interfaces/i_bounded_element.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for a bounded element.
*/
/**
* The interface for a bounded element.
*
* @namespace Blockly.IBoundedElement
*/
import * as goog from '../../closure/goog/goog.js';
@@ -23,18 +20,21 @@ goog.declareModuleId('Blockly.IBoundedElement');
/**
* A bounded element interface.
*
* @alias Blockly.IBoundedElement
*/
export interface IBoundedElement {
/**
* Returns the coordinates of a bounded element describing the dimensions of
* the element. Coordinate system: workspace coordinates.
* @return Object with coordinates of the bounded element.
*
* @returns Object with coordinates of the bounded element.
*/
getBoundingRectangle(): Rect;
/**
* Move the element by a relative offset.
*
* @param dx Horizontal offset in workspace units.
* @param dy Vertical offset in workspace units.
*/

17
core/interfaces/i_bubble.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for a bubble.
*/
/**
* The interface for a bubble.
*
* @namespace Blockly.IBubble
*/
import * as goog from '../../closure/goog/goog.js';
@@ -30,19 +27,22 @@ import type {IDraggable} from './i_draggable.js';
/**
* A bubble interface.
*
* @alias Blockly.IBubble
*/
export interface IBubble extends IDraggable, IContextMenu {
/**
* Return the coordinates of the top-left corner of this bubble's body
* relative to the drawing surface's origin (0,0), in workspace units.
* @return Object with .x and .y properties.
*
* @returns Object with .x and .y properties.
*/
getRelativeToSurfaceXY(): Coordinate;
/**
* Return the root node of the bubble's SVG group.
* @return The root SVG node of the bubble's group.
*
* @returns The root SVG node of the bubble's group.
*/
getSvgRoot(): SVGElement;
@@ -50,12 +50,14 @@ export interface IBubble extends IDraggable, IContextMenu {
* Set whether auto-layout of this bubble is enabled. The first time a bubble
* is shown it positions itself to not cover any blocks. Once a user has
* dragged it to reposition, it renders where the user put it.
*
* @param enable True if auto-layout should be enabled, false otherwise.
*/
setAutoLayout(enable: boolean): void;
/**
* Sets whether or not this bubble is being dragged.
*
* @param adding True if dragging, false otherwise.
*/
setDragging(dragging: boolean): void;
@@ -63,6 +65,7 @@ export interface IBubble extends IDraggable, IContextMenu {
/**
* Move this bubble during a drag, taking into account whether or not there is
* a drag surface.
*
* @param dragSurface The surface that carries rendered items during a drag,
* or null if no drag surface is in use.
* @param newLoc The location to translate to, in workspace coordinates.
@@ -72,6 +75,7 @@ export interface IBubble extends IDraggable, IContextMenu {
/**
* Move the bubble to the specified location in workspace coordinates.
*
* @param x The x position to move to.
* @param y The y position to move to.
*/
@@ -79,6 +83,7 @@ export interface IBubble extends IDraggable, IContextMenu {
/**
* Update the style of this bubble when it is dragged over a delete area.
*
* @param enable True if the bubble is about to be deleted, false otherwise.
*/
setDeleteStyle(enable: boolean): void;

12
core/interfaces/i_collapsible_toolbox_item.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for a collapsible toolbox item.
*/
/**
* The interface for a collapsible toolbox item.
*
* @namespace Blockly.ICollapsibleToolboxItem
*/
import * as goog from '../../closure/goog/goog.js';
@@ -26,18 +23,21 @@ import type {IToolboxItem} from './i_toolbox_item.js';
/**
* Interface for an item in the toolbox that can be collapsed.
*
* @alias Blockly.ICollapsibleToolboxItem
*/
export interface ICollapsibleToolboxItem extends ISelectableToolboxItem {
/**
* Gets any children toolbox items. (ex. Gets the subcategories)
* @return The child toolbox items.
*
* @returns The child toolbox items.
*/
getChildToolboxItems(): IToolboxItem[];
/**
* Whether the toolbox item is expanded to show its child subcategories.
* @return True if the toolbox item shows its children, false if it is
*
* @returns True if the toolbox item shows its children, false if it is
* collapsed.
*/
isExpanded(): boolean;

7
core/interfaces/i_component.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Interface for a workspace component that can be registered with
* the ComponentManager.
*/
/**
* Interface for a workspace component that can be registered with
* the ComponentManager.
*
* @namespace Blockly.IComponent
*/
import * as goog from '../../closure/goog/goog.js';
@@ -21,6 +17,7 @@ goog.declareModuleId('Blockly.IComponent');
/**
* The interface for a workspace component that can be registered with the
* ComponentManager.
*
* @alias Blockly.IComponent
*/
export interface IComponent {

25
core/interfaces/i_connection_checker.ts
View File

@@ -4,14 +4,10 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for an object that encapsulates logic for
* checking whether a potential connection is safe and valid.
*/
/**
* The interface for an object that encapsulates logic for
* checking whether a potential connection is safe and valid.
*
* @namespace Blockly.IConnectionChecker
*/
import * as goog from '../../closure/goog/goog.js';
@@ -29,18 +25,20 @@ goog.declareModuleId('Blockly.IConnectionChecker');
/**
* Class for connection type checking logic.
*
* @alias Blockly.IConnectionChecker
*/
export interface IConnectionChecker {
/**
* Check whether the current connection can connect with the target
* connection.
*
* @param a Connection to check compatibility with.
* @param b Connection to check compatibility with.
* @param isDragging True if the connection is being made by dragging a block.
* @param opt_distance The max allowable distance between the connections for
* drag checks.
* @return Whether the connection is legal.
* @returns Whether the connection is legal.
*/
canConnect(
a: Connection|null, b: Connection|null, isDragging: boolean,
@@ -49,12 +47,13 @@ export interface IConnectionChecker {
/**
* Checks whether the current connection can connect with the target
* connection, and return an error code if there are problems.
*
* @param a Connection to check compatibility with.
* @param b Connection to check compatibility with.
* @param isDragging True if the connection is being made by dragging a block.
* @param opt_distance The max allowable distance between the connections for
* drag checks.
* @return Connection.CAN_CONNECT if the connection is legal, an error code
* @returns Connection.CAN_CONNECT if the connection is legal, an error code
* otherwise.
*/
canConnectWithReason(
@@ -63,10 +62,11 @@ export interface IConnectionChecker {
/**
* Helper method that translates a connection error code into a string.
*
* @param errorCode The error code.
* @param a One of the two connections being checked.
* @param b The second of the two connections being checked.
* @return A developer-readable error string.
* @returns A developer-readable error string.
*/
getErrorMessage(errorCode: number, a: Connection|null, b: Connection|null):
string;
@@ -74,9 +74,10 @@ export interface IConnectionChecker {
/**
* Check that connecting the given connections is safe, meaning that it would
* not break any of Blockly's basic assumptions (e.g. no self connections).
*
* @param a The first of the connections to check.
* @param b The second of the connections to check.
* @return An enum with the reason this connection is safe or unsafe.
* @returns An enum with the reason this connection is safe or unsafe.
*/
doSafetyChecks(a: Connection|null, b: Connection|null): number;
@@ -84,18 +85,20 @@ export interface IConnectionChecker {
* Check whether this connection is compatible with another connection with
* respect to the value type system. E.g. square_root("Hello") is not
* compatible.
*
* @param a Connection to compare.
* @param b Connection to compare against.
* @return True if the connections share a type.
* @returns True if the connections share a type.
*/
doTypeChecks(a: Connection, b: Connection): boolean;
/**
* Check whether this connection can be made by dragging.
*
* @param a Connection to compare.
* @param b Connection to compare against.
* @param distance The maximum allowable distance between connections.
* @return True if the connection is allowed during a drag.
* @returns True if the connection is allowed during a drag.
*/
doDragChecks(a: RenderedConnection, b: RenderedConnection, distance: number):
boolean;

6
core/interfaces/i_contextmenu.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for an object that supports a right-click.
*/
/**
* The interface for an object that supports a right-click.
*
* @namespace Blockly.IContextMenu
*/
import * as goog from '../../closure/goog/goog.js';
@@ -20,6 +17,7 @@ goog.declareModuleId('Blockly.IContextMenu');
export interface IContextMenu {
/**
* Show the context menu for this object.
*
* @param e Mouse event.
*/
showContextMenu(e: Event): void;

8
core/interfaces/i_copyable.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for an object that is copyable.
*/
/**
* The interface for an object that is copyable.
*
* @namespace Blockly.ICopyable
*/
import * as goog from '../../closure/goog/goog.js';
@@ -23,7 +20,8 @@ import type {ISelectable} from './i_selectable.js';
export interface ICopyable extends ISelectable {
/**
* Encode for copying.
* @return Copy metadata.
*
* @returns Copy metadata.
* @internal
*/
toCopyData(): CopyData|null;

9
core/interfaces/i_deletable.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview The interface for an object that is deletable.
*/
/**
* The interface for an object that is deletable.
*
* @namespace Blockly.IDeletable
*/
import * as goog from '../../closure/goog/goog.js';
@@ -18,12 +15,14 @@ goog.declareModuleId('Blockly.IDeletable');
/**
* The interface for an object that can be deleted.
*
* @alias Blockly.IDeletable
*/
export interface IDeletable {
/**
* Get whether this object is deletable or not.
* @return True if deletable.
*
* @returns True if deletable.
*/
isDeletable(): boolean;
}

Some files were not shown because too many files have changed in this diff Show More