CodingPirates/blockly
1
0
Fork 0
mirror of https://github.com/google/blockly.git synced 2026-03-02 11:20:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore: change return to returns and add some newlines

Browse Source
This commit is contained in:
Maribeth Bottorff
2022-08-16 16:13:39 -07:00
parent 169959bc08
commit d6d8656a45
172 changed files with 2752 additions and 772 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
core/block.ts
View File

@@ -6,6 +6,7 @@
/**
* The class representing one block.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -49,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
*/
@@ -74,6 +76,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Has this block been disposed of?
*
* @internal
*/
disposed = false;
@@ -180,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;
@@ -210,6 +214,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* A count of statement inputs on the block.
*
* @internal
*/
statementInputCount = 0;
@@ -305,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.
@@ -376,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.
*/
@@ -391,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.
*/
@@ -434,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;
@@ -455,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.
*/
@@ -482,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[] {
@@ -508,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 {
@@ -538,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_;
@@ -546,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++) {
@@ -563,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 {
let block = this;
@@ -584,7 +598,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();
@@ -592,7 +607,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();
@@ -601,7 +617,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 {
@@ -617,7 +634,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;
@@ -633,7 +651,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 {
@@ -653,8 +672,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) {
@@ -678,6 +698,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
*/
@@ -730,8 +751,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];
@@ -746,7 +768,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 &&
@@ -755,6 +778,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block is deletable or not.
*
* @param deletable True if deletable.
*/
setDeletable(deletable: boolean) {
@@ -763,7 +787,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 &&
@@ -772,6 +797,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block is movable or not.
*
* @param movable True if movable.
*/
setMovable(movable: boolean) {
@@ -783,7 +809,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()) {
@@ -795,7 +822,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_;
@@ -803,6 +831,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block is a shadow block or not.
*
* @param shadow True if a shadow.
* @internal
*/
@@ -812,7 +841,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_;
@@ -821,6 +851,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
*/
@@ -830,7 +861,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;
@@ -838,6 +870,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether this block is editable or not.
*
* @param editable True if editable.
*/
setEditable(editable: boolean) {
@@ -851,7 +884,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;
@@ -861,9 +895,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 {
@@ -882,6 +917,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.
*/
@@ -891,6 +927,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.
@@ -901,7 +938,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);
@@ -909,7 +947,8 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Get the colour of a block.
* @return #RRGGBB string.
*
* @returns #RRGGBB string.
*/
getColour(): string {
return this.colour_;
@@ -917,7 +956,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_;
@@ -925,7 +965,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_;
@@ -933,6 +974,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.
*/
@@ -944,6 +986,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) {
@@ -955,6 +998,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.
*/
@@ -972,8 +1016,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') {
@@ -995,7 +1040,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 = [];
@@ -1011,7 +1057,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[] {
@@ -1035,6 +1082,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
*/
@@ -1052,6 +1100,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.
@@ -1068,8 +1117,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);
@@ -1081,6 +1131,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.
*/
@@ -1094,6 +1145,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.
@@ -1125,6 +1177,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.
@@ -1156,6 +1209,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).
@@ -1186,6 +1240,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) {
@@ -1198,7 +1253,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) {
@@ -1225,6 +1281,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set the block's output shape.
*
* @param outputShape Value representing an output shape.
*/
setOutputShape(outputShape: number|null) {
@@ -1233,7 +1290,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_;
@@ -1241,7 +1299,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;
@@ -1249,6 +1308,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether the block is enabled or not.
*
* @param enabled True if enabled.
*/
setEnabled(enabled: boolean) {
@@ -1263,7 +1323,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();
@@ -1279,7 +1340,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_;
@@ -1287,6 +1349,7 @@ export class Block implements IASTNodeLocation, IDeletable {
/**
* Set whether the block is collapsed or not.
*
* @param collapsed True if collapsed.
*/
setCollapsed(collapsed: boolean) {
@@ -1299,10 +1362,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 = [];
@@ -1317,8 +1381,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();
@@ -1417,9 +1482,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);
@@ -1427,9 +1493,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);
@@ -1437,9 +1504,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 || '');
@@ -1448,6 +1516,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) {
@@ -1542,6 +1611,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.
*/
@@ -1562,6 +1632,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.
*/
@@ -1580,6 +1651,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.
*/
@@ -1606,6 +1678,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.
@@ -1647,6 +1720,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.
*/
@@ -1682,11 +1756,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>,
@@ -1727,8 +1802,12 @@ 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.
* @param element.alt
* @param element.type
* @param element.text
* @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 {
@@ -1746,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):
@@ -1796,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 {
@@ -1808,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();
@@ -1824,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;
@@ -1848,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.
@@ -1883,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.
*/
@@ -1909,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.
*/
@@ -1934,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++) {
@@ -1949,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 {
@@ -1960,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;
@@ -1968,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) {
@@ -1984,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.
@@ -1993,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) {}
@@ -2001,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_;
@@ -2009,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.
*/
@@ -2025,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);
@@ -2035,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.
@@ -2075,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';

21
core/block_drag_surface.ts
View File

@@ -11,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';
@@ -26,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 {
@@ -83,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) {
@@ -98,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.
@@ -116,6 +120,7 @@ export class BlockDragSurfaceSvg {
/**
* Translate the drag surface's SVG based on its internal state.
*
* @private
*/
translateSurfaceInternal_() {
@@ -130,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.
*/
@@ -145,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.
*/
@@ -156,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);
@@ -166,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_;
@@ -174,6 +183,7 @@ export class BlockDragSurfaceSvg {
/**
* Returns the SVG drag surface.
*
* @returns The SVG drag surface.
*/
getSvgRoot(): SVGElement|null {
@@ -183,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;
@@ -193,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.
@@ -205,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.

28
core/block_dragger.ts
View File

@@ -6,6 +6,7 @@
/**
* Methods for dragging a block visually.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -33,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 {
@@ -80,6 +82,7 @@ export class BlockDragger implements IBlockDragger {
/**
* Sever all links from this object.
*
* @internal
*/
dispose() {
@@ -92,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.
@@ -128,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 !!(
@@ -140,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.
@@ -165,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.
@@ -197,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.
@@ -250,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):
@@ -269,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_) {
@@ -284,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.
*/
@@ -310,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) {
@@ -360,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(
@@ -379,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.
*/
@@ -393,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.
@@ -415,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.

110
core/block_svg.ts
View File

@@ -6,6 +6,7 @@
/**
* Methods for graphically rendering a block as SVG.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -65,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,
@@ -91,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;
@@ -241,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;
@@ -249,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;
@@ -304,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 = [];
@@ -322,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
*/
@@ -367,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;
@@ -403,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.
*/
@@ -428,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.
*/
@@ -440,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() {
@@ -462,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) {
@@ -473,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
@@ -491,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
*/
@@ -552,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();
@@ -582,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) {
@@ -640,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.
*/
@@ -668,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) {
@@ -679,6 +697,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Load the block's help page in a new window.
*
* @internal
*/
showHelp() {
@@ -691,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 {
@@ -714,6 +734,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Show the context menu for this block.
*
* @param e Mouse event.
* @internal
*/
@@ -731,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
@@ -759,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
*/
@@ -781,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) {
@@ -790,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) {
@@ -802,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
*/
@@ -813,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
*/
@@ -830,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_;
@@ -838,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.
@@ -927,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 {
@@ -949,6 +979,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Updates the colour of the block to match the block's state.
*
* @internal
*/
applyColour() {
@@ -969,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() {
@@ -987,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_;
@@ -995,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) {
@@ -1029,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.
@@ -1107,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) {
@@ -1127,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) {
@@ -1141,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) {
@@ -1153,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() {
@@ -1162,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() {
@@ -1170,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
*/
@@ -1183,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;
@@ -1191,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) {
@@ -1208,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.
*/
@@ -1235,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() {
@@ -1255,6 +1300,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.
@@ -1271,6 +1317,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.
@@ -1287,6 +1334,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).
@@ -1302,6 +1350,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) {
@@ -1315,9 +1364,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.
*/
@@ -1335,6 +1385,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.
*/
@@ -1350,10 +1401,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);
@@ -1372,6 +1424,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
*/
@@ -1413,10 +1466,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[] {
@@ -1445,10 +1499,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
@@ -1460,9 +1515,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):
@@ -1472,8 +1528,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);
@@ -1481,7 +1538,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;
@@ -1489,7 +1547,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;
@@ -1543,6 +1602,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg,
/**
* Schedule snapping to grid and bumping neighbours to occur after a brief
* delay.
*
* @internal
*/
scheduleSnapAndBump() {
@@ -1567,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.
@@ -1587,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 {
@@ -1599,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[];
@@ -1608,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.
*/
@@ -1690,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
@@ -1700,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
@@ -1711,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} {
@@ -1733,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
*/
@@ -1743,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

2
core/blockly_options.ts
View File

@@ -6,6 +6,7 @@
/**
* Object that defines user-specified options for the workspace.
*
* @namespace Blockly.BlocklyOptions
*/
import * as goog from '../closure/goog/goog.js';
@@ -18,6 +19,7 @@ import type {ToolboxDefinition} from './utils/toolbox.js';
/**
* Blockly options.
*
* @alias Blockly.BlocklyOptions
*/
export interface BlocklyOptions {

2
core/blocks.ts
View File

@@ -6,6 +6,7 @@
/**
* A mapping of block type names to block prototype objects.
*
* @namespace Blockly.blocks
*/
import * as goog from '../closure/goog/goog.js';
@@ -20,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);

54
core/bubble.ts
View File

@@ -6,6 +6,7 @@
/**
* Object representing a UI bubble.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -35,6 +36,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Class for UI bubble.
*
* @alias Blockly.Bubble
*/
export class Bubble implements IBubble {
@@ -125,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;
@@ -174,9 +177,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:
@@ -263,7 +267,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;
@@ -271,6 +276,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) {
@@ -279,6 +285,7 @@ export class Bubble implements IBubble {
/**
* Handle a mouse-down on bubble's border.
*
* @param e Mouse down event.
*/
private bubbleMouseDown_(e: Event) {
@@ -290,6 +297,7 @@ export class Bubble implements IBubble {
/**
* Show the context menu for this bubble.
*
* @param _e Mouse event.
* @internal
*/
@@ -299,7 +307,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 {
@@ -308,6 +317,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) {}
@@ -315,6 +325,7 @@ export class Bubble implements IBubble {
/**
* Handle a mouse-down on bubble's resize corner.
*
* @param e Mouse down event.
*/
private resizeMouseDown_(e: MouseEvent) {
@@ -342,6 +353,7 @@ export class Bubble implements IBubble {
/**
* Resize this bubble to follow the mouse.
*
* @param e Mouse move event.
*/
private resizeMouseMove_(e: MouseEvent) {
@@ -356,6 +368,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) {
@@ -364,6 +377,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) {
@@ -372,7 +386,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 {
@@ -387,6 +402,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) {
@@ -457,11 +473,14 @@ 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 relativeMin.x
* @param viewMetrics The view metrics of the workspace the bubble will appear
* in.
* @return The percentage of the bubble that is visible.
* @param relativeMin.y
* @returns The percentage of the bubble that is visible.
*/
private getOverlap_(
relativeMin: {x: number, y: number},
@@ -505,9 +524,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 {
@@ -560,9 +580,10 @@ 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;
@@ -605,6 +626,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
@@ -616,6 +638,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
*/
@@ -627,7 +650,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_);
@@ -635,6 +659,7 @@ export class Bubble implements IBubble {
/**
* Size this bubble.
*
* @param width Width of the bubble.
* @param height Height of the bubble.
*/
@@ -746,6 +771,7 @@ export class Bubble implements IBubble {
/**
* Change the colour of a bubble.
*
* @param hexColour Hex code of colour.
*/
setColour(hexColour: string) {
@@ -769,6 +795,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.
@@ -792,7 +819,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(
@@ -806,6 +834,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
*/
@@ -827,6 +856,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) {
@@ -836,8 +866,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 {
@@ -857,10 +888,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(

12
core/clipboard.ts
View File

@@ -6,6 +6,7 @@
/**
* Blockly's internal clipboard for managing copy-paste.
*
* @namespace Blockly.clipboard
*/
import * as goog from '../closure/goog/goog.js';
@@ -19,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
@@ -29,6 +31,8 @@ export function copy(toCopy: ICopyable) {
/**
* Private version of copy for stubbing in tests.
*
* @param toCopy
*/
function copyInternal(toCopy: ICopyable) {
copyData = toCopy.toCopyData();
@@ -36,7 +40,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
*/
@@ -59,8 +64,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
@@ -71,6 +77,8 @@ export function duplicate(toDuplicate: ICopyable): ICopyable|null {
/**
* Private version of duplicate for stubbing in tests.
*
* @param toDuplicate
*/
function duplicateInternal(toDuplicate: ICopyable): ICopyable|null {
const oldCopyData = copyData;

39
core/common.ts
View File

@@ -7,6 +7,7 @@
/**
* 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';
@@ -27,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;
@@ -36,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 = [];
@@ -46,10 +49,18 @@ export function getAllWorkspaces(): Workspace[] {
return workspaces;
}
/**
*
* @param workspace
*/
export function registerWorkspace(workspace: Workspace) {
WorkspaceDB_[workspace.id] = workspace;
}
/**
*
* @param workspace
*/
export function unregisterWorkpace(workspace: Workspace) {
delete WorkspaceDB_[workspace.id];
}
@@ -64,7 +75,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 {
@@ -73,6 +85,7 @@ export function getMainWorkspace(): Workspace {
/**
* Sets last used main workspace.
*
* @param workspace The most recently used top level workspace.
* @alias Blockly.common.setMainWorkspace
*/
@@ -87,6 +100,7 @@ let selected: ICopyable|null = null;
/**
* Returns the currently selected copyable object.
*
* @alias Blockly.common.getSelected
*/
export function getSelected(): ICopyable|null {
@@ -97,6 +111,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
@@ -113,7 +128,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 {
@@ -125,6 +141,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
*/
@@ -138,6 +155,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
*/
@@ -175,11 +193,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(
@@ -206,8 +225,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 {
@@ -219,6 +239,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
*/
@@ -228,6 +249,8 @@ export function defineBlocksWithJsonArray(jsonArray: AnyDuringMigration[]) {
/**
* Private version of defineBlocksWithJsonArray for stubbing in tests.
*
* @param jsonArray
*/
function defineBlocksWithJsonArrayInternal(jsonArray: AnyDuringMigration[]) {
defineBlocks(createBlockDefinitionsFromJsonArray(jsonArray));
@@ -236,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
*/
@@ -265,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

18
core/component_manager.ts
View File

@@ -6,6 +6,7 @@
/**
* Manager for all items registered with the workspace.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -32,7 +33,8 @@ class Capability<_T> {
/**
* Returns the name of the capability.
* @return The name.
*
* @returns The name.
*/
toString(): string {
return this.name_;
@@ -41,6 +43,7 @@ class Capability<_T> {
/**
* Manager for all items registered with the workspace.
*
* @alias Blockly.ComponentManager
*/
export class ComponentManager {
@@ -56,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.
@@ -84,6 +88,7 @@ export class ComponentManager {
/**
* Removes a component.
*
* @param id The ID of the component to remove.
*/
removeComponent(id: string) {
@@ -100,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.
*/
@@ -121,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.
*/
@@ -143,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();
@@ -155,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;
@@ -164,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>(capability: string|Capability<T>, sorted: boolean): T[] {
capability = String(capability).toLowerCase();

73
core/connection.ts
View File

@@ -6,6 +6,7 @@
/**
* Components for creating connections between blocks.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -27,6 +28,7 @@ import * as Xml from './xml.js';
/**
* Class for a connection between blocks.
*
* @alias Blockly.Connection
*/
export class Connection implements IASTNodeLocationWithBlock {
@@ -48,6 +50,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Has this connection been disposed of?
*
* @internal
*/
disposed = false;
@@ -60,12 +63,14 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Horizontal location of this connection.
*
* @internal
*/
x = 0;
/**
* Vertical location of this connection.
*
* @internal
*/
y = 0;
@@ -83,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) {
@@ -140,6 +146,7 @@ export class Connection implements IASTNodeLocationWithBlock {
/**
* Dispose of this connection and deal with connected blocks.
*
* @internal
*/
dispose() {
@@ -160,7 +167,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_;
@@ -169,7 +177,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 ||
@@ -178,7 +187,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;
@@ -186,7 +196,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 {
@@ -196,6 +207,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
@@ -205,8 +217,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) {
@@ -276,6 +289,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.
*/
@@ -307,7 +321,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()) {
@@ -332,9 +347,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) {
@@ -351,7 +367,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 {
@@ -360,6 +377,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) {
@@ -368,11 +386,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() ?
@@ -382,6 +401,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) {
@@ -391,11 +411,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()) {
@@ -412,8 +433,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[] {
@@ -422,7 +444,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
*/
@@ -441,7 +464,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_;
@@ -476,7 +500,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} {
@@ -490,8 +515,11 @@ 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.
* @param param0.shadowDom
* @param param0.shadowState
*/
private applyShadowState_({shadowDom, shadowState}: {
shadowDom: Element|null,
@@ -503,7 +531,10 @@ 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.
* @param param0.shadowDom
* @param param0.shadowState
*/
private setShadowStateInternal_({shadowDom = null, shadowState = null}: {
shadowDom?: Element|null,
@@ -538,9 +569,10 @@ 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_
* @returns The shadow block that was created, or null if both the shadowState_
* and shadowDom_ are null.
*/
private createShadowBlock_(attemptToConnect: boolean): Block|null {
@@ -591,6 +623,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) {
@@ -605,9 +638,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 {
@@ -627,6 +661,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.
*/
@@ -642,9 +677,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 {
@@ -670,9 +706,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 {

23
core/connection_checker.ts
View File

@@ -7,6 +7,7 @@
/**
* An object that encapsulates logic for checking whether a
* potential connection is safe and valid.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -23,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,
@@ -46,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(
@@ -81,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 {
@@ -120,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) {
@@ -171,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();
@@ -195,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 {
@@ -259,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) {

2
core/connection_type.ts
View File

@@ -6,6 +6,7 @@
/**
* An enum for the possible types of connections.
*
* @namespace Blockly.ConnectionType
*/
import * as goog from '../closure/goog/goog.js';
@@ -14,6 +15,7 @@ goog.declareModuleId('Blockly.ConnectionType');
/**
* Enum for the type of a connection or input.
*
* @alias Blockly.ConnectionType
*/
export enum ConnectionType {

3
core/constants.ts
View File

@@ -6,6 +6,7 @@
/**
* Blockly constants.
*
* @namespace Blockly.constants
*/
import * as goog from '../closure/goog/goog.js';
@@ -14,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';

25
core/contextmenu_items.ts
View File

@@ -6,6 +6,7 @@
/**
* Registers default context menu items.
*
* @namespace Blockly.ContextMenuItems
*/
import * as goog from '../closure/goog/goog.js';
@@ -26,6 +27,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Option to undo previous action.
*
* @alias Blockly.ContextMenuItems.registerUndo
*/
export function registerUndo() {
@@ -51,6 +53,7 @@ export function registerUndo() {
/**
* Option to redo previous action.
*
* @alias Blockly.ContextMenuItems.registerRedo
*/
export function registerRedo() {
@@ -76,6 +79,7 @@ export function registerRedo() {
/**
* Option to clean up blocks.
*
* @alias Blockly.ContextMenuItems.registerCleanup
*/
export function registerCleanup() {
@@ -103,6 +107,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.
*/
@@ -110,6 +115,10 @@ function toggleOption_(shouldCollapse: boolean, topBlocks: BlockSvg[]) {
const DELAY = 10;
let ms = 0;
let timeoutCounter = 0;
/**
*
* @param block
*/
function timeoutFn(block: BlockSvg) {
timeoutCounter--;
block.setCollapsed(shouldCollapse);
@@ -131,6 +140,7 @@ function toggleOption_(shouldCollapse: boolean, topBlocks: BlockSvg[]) {
/**
* Option to collapse all blocks.
*
* @alias Blockly.ContextMenuItems.registerCollapse
*/
export function registerCollapse() {
@@ -166,6 +176,7 @@ export function registerCollapse() {
/**
* Option to expand all blocks.
*
* @alias Blockly.ContextMenuItems.registerExpand
*/
export function registerExpand() {
@@ -200,6 +211,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.
@@ -217,8 +229,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[] = [];
@@ -231,6 +244,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.
@@ -252,6 +266,7 @@ function deleteNext_(deleteList: BlockSvg[], eventGroup: string) {
/**
* Option to delete all blocks.
*
* @alias Blockly.ContextMenuItems.registerDeleteAll
*/
export function registerDeleteAll() {
@@ -313,6 +328,7 @@ function registerWorkspaceOptions_() {
/**
* Option to duplicate a block.
*
* @alias Blockly.ContextMenuItems.registerDuplicate
*/
export function registerDuplicate() {
@@ -344,6 +360,7 @@ export function registerDuplicate() {
/**
* Option to add or remove block-level comment.
*
* @alias Blockly.ContextMenuItems.registerComment
*/
export function registerComment() {
@@ -383,6 +400,7 @@ export function registerComment() {
/**
* Option to inline variables.
*
* @alias Blockly.ContextMenuItems.registerInline
*/
export function registerInline() {
@@ -417,6 +435,7 @@ export function registerInline() {
/**
* Option to collapse or expand a block.
*
* @alias Blockly.ContextMenuItems.registerCollapseExpandBlock
*/
export function registerCollapseExpandBlock() {
@@ -445,6 +464,7 @@ export function registerCollapseExpandBlock() {
/**
* Option to disable or enable a block.
*
* @alias Blockly.ContextMenuItems.registerDisable
*/
export function registerDisable() {
@@ -484,6 +504,7 @@ export function registerDisable() {
/**
* Option to delete a block.
*
* @alias Blockly.ContextMenuItems.registerDelete
*/
export function registerDelete() {
@@ -521,6 +542,7 @@ export function registerDelete() {
/**
* Option to open help for a block.
*
* @alias Blockly.ContextMenuItems.registerHelp
*/
export function registerHelp() {
@@ -561,6 +583,7 @@ function registerBlockOptions_() {
/**
* Registers all default context menu items. This should be called once per
* instance of ContextMenuRegistry.
*
* @alias Blockly.ContextMenuItems.registerDefaultOptions
* @internal
*/

9
core/contextmenu_registry.ts
View File

@@ -6,6 +6,7 @@
/**
* Registry for context menu option items.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -19,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 {
@@ -38,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.
*/
@@ -50,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.
*/
@@ -62,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;
@@ -72,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[] {

6
core/delete_area.ts
View File

@@ -7,6 +7,7 @@
/**
* 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';
@@ -21,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 {
@@ -51,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 {
@@ -69,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) {

10
core/dialog.ts
View File

@@ -6,6 +6,7 @@
/**
* Wrapper functions around JS functions for showing alert/confirmation dialogs.
*
* @namespace Blockly.dialog
*/
import * as goog from '../closure/goog/goog.js';
@@ -34,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
@@ -45,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
@@ -58,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
@@ -69,6 +73,9 @@ export function confirm(
/**
* Private version of confirm for stubbing in tests.
*
* @param message
* @param callback
*/
function confirmInternal(
message: string, callback: (p1: boolean) => AnyDuringMigration) {
@@ -78,6 +85,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
@@ -93,6 +101,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.
@@ -106,6 +115,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

12
core/drag_target.ts
View File

@@ -7,6 +7,7 @@
/**
* 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';
@@ -20,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 {
@@ -38,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) {}
@@ -46,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) {}
@@ -53,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) {}
@@ -60,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) {}
@@ -68,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 {
@@ -79,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 {

53
core/dropdowndiv.ts
View File

@@ -7,6 +7,7 @@
/**
* A div that floats on top of the workspace, for drop-down menus.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -110,6 +111,7 @@ export interface PositionMetrics {
/**
* Create and insert the DOM element for this div.
*
* @internal
*/
export function createDom() {
@@ -149,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) {
@@ -157,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;
@@ -171,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.
*/
@@ -184,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,
@@ -202,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,
@@ -216,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();
@@ -230,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();
@@ -243,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,
@@ -281,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.
@@ -288,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(
@@ -321,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
@@ -343,11 +355,12 @@ 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
* @returns Various final metrics, including rendered positions for drop-down and
* arrow.
*/
// AnyDuringMigration because: Property 'getPositionMetrics' does not exist on
@@ -383,13 +396,14 @@ 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
* @returns Various final metrics, including rendered positions for drop-down and
* arrow.
*/
function getPositionBelowMetrics(
@@ -415,13 +429,14 @@ 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
* @returns Various final metrics, including rendered positions for drop-down and
* arrow.
*/
function getPositionAboveMetrics(
@@ -448,12 +463,13 @@ 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
* @returns Various final metrics, including rendered positions for drop-down and
* arrow.
*/
function getPositionTopOfPageMetrics(
@@ -477,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
*/
@@ -509,7 +526,8 @@ export function getPositionX(
/**
* Is the container visible?
* @return True if visible.
*
* @returns True if visible.
*/
export function isVisible(): boolean {
return !!owner;
@@ -517,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,
@@ -595,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,
@@ -650,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() {

6
core/events/events_block_drag.ts
View File

@@ -6,6 +6,7 @@
/**
* Events fired as a block drag.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -20,6 +21,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a block drag event.
*
* @alias Blockly.Events.BlockDrag
*/
export class BlockDrag extends UiBase {
@@ -53,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();
@@ -65,6 +68,7 @@ export class BlockDrag extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

6
core/events/events_theme_change.ts
View File

@@ -6,6 +6,7 @@
/**
* Events fired as a result of a theme update.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -19,6 +20,7 @@ import * as eventUtils from './utils.js';
/**
* Class for a theme change event.
*
* @alias Blockly.Events.ThemeChange
*/
export class ThemeChange extends UiBase {
@@ -42,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();
@@ -52,6 +55,7 @@ export class ThemeChange extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

6
core/events/events_toolbox_item_select.ts
View File

@@ -6,6 +6,7 @@
/**
* Events fired as a result of selecting an item on the toolbox.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -19,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 {
@@ -51,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();
@@ -62,6 +65,7 @@ export class ToolboxItemSelect extends UiBase {
/**
* Decode the JSON event.
*
* @param json JSON representation.
*/
override fromJson(json: AnyDuringMigration) {

59
core/events/utils.ts
View File

@@ -7,6 +7,7 @@
/**
* 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';
@@ -36,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
*/
@@ -45,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
*/
@@ -57,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';
@@ -217,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;
@@ -227,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[] =
@@ -237,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
*/
@@ -246,6 +278,8 @@ export function fire(event: Abstract) {
/**
* Private version of fireInternal for stubbing in tests.
*
* @param event
*/
function fireInternal(event: Abstract) {
if (!isEnabled()) {
@@ -276,9 +310,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[] {
@@ -362,6 +397,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() {
@@ -372,6 +408,7 @@ export function clearPendingUndo() {
/**
* Stop sending events. Every call to this function MUST also call enable.
*
* @alias Blockly.Events.utils.disable
*/
export function disable() {
@@ -381,6 +418,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() {
@@ -389,7 +427,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 {
@@ -398,7 +437,8 @@ export function isEnabled(): boolean {
/**
* Current group.
* @return ID string.
*
* @returns ID string.
* @alias Blockly.Events.utils.getGroup
*/
export function getGroup(): string {
@@ -407,6 +447,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
@@ -417,6 +458,8 @@ export function setGroup(state: boolean|string) {
/**
* Private version of setGroup for stubbing in tests.
*
* @param state
*/
function setGroupInternal(state: boolean|string) {
if (typeof state === 'boolean') {
@@ -428,8 +471,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
*/
@@ -444,9 +488,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
*/
@@ -464,8 +509,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):
@@ -478,6 +524,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
*/

51
core/extensions.ts
View File

@@ -9,6 +9,7 @@
* 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';
@@ -33,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
@@ -54,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
@@ -74,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.
@@ -110,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
*/
@@ -124,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 {
@@ -135,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.
@@ -174,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.
@@ -191,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.
@@ -207,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.
@@ -223,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.
@@ -239,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.
@@ -263,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.
*/
@@ -282,8 +295,9 @@ 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,
* @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[] {
@@ -315,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 {
@@ -335,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
@@ -369,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(
@@ -393,7 +410,11 @@ export function buildTooltipForDropdown(
});
}
/** The actual extension. */
/**
* The actual extension.
*
* @param this
*/
function extensionFn(this: Block) {
if (this.type && blockTypesChecked.indexOf(this.type) === -1) {
checkDropdownOptionsInTable(this, dropdownName, lookupTable);
@@ -425,6 +446,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
@@ -450,10 +472,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(
@@ -469,7 +492,11 @@ export function buildTooltipWithFieldText(
});
}
/** The actual extension. */
/**
* The actual extension.
*
* @param this
*/
function extensionFn(this: Block) {
this.setTooltip(function(this: Block) {
const field = this.getField(fieldName);
@@ -485,6 +512,8 @@ export function buildTooltipWithFieldText(
* uses the tooltip text at the time this extension is initialized. This takes
* advantage of the fact that all other values from JSON are initialized before
* extensions.
*
* @param this
*/
function extensionParentTooltip(this: Block) {
const tooltipWhenNotConnected = this.tooltip;

21
core/field_angle.ts
View File

@@ -6,6 +6,7 @@
/**
* Angle input field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -29,6 +30,7 @@ import * as WidgetDiv from './widgetdiv.js';
/**
* Class for an editable angle field.
*
* @alias Blockly.FieldAngle
*/
export class FieldAngle extends FieldTextInput {
@@ -123,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;
@@ -159,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) {
@@ -186,6 +193,7 @@ export class FieldAngle extends FieldTextInput {
/**
* Create the block UI for this field.
*
* @internal
*/
override initView() {
@@ -205,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.
*/
@@ -317,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) {
@@ -355,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) {
@@ -410,6 +421,7 @@ export class FieldAngle extends FieldTextInput {
/**
* Handle key down to the editor.
*
* @param e Keyboard event.
*/
protected override onHtmlInputKeyDown_(e: Event) {
@@ -447,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 {
@@ -461,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;
@@ -477,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
*/

28
core/field_colour.ts
View File

@@ -6,6 +6,7 @@
/**
* Colour input field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -31,6 +32,7 @@ import {Size} from './utils/size.js';
/**
* Class for a colour input field.
*
* @alias Blockly.FieldColour
*/
export class FieldColour extends Field {
@@ -168,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) {
@@ -179,6 +182,7 @@ export class FieldColour extends Field {
/**
* Create the block UI for this colour field.
*
* @internal
*/
override initView() {
@@ -207,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 {
@@ -220,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.
*/
@@ -238,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;
@@ -251,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;
@@ -267,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;
@@ -293,6 +302,7 @@ export class FieldColour extends Field {
/**
* Handle a click on a colour cell.
*
* @param e Mouse event.
*/
private onClick_(e: MouseEvent) {
@@ -307,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) {
@@ -342,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
*/
@@ -399,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) {
@@ -432,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_) {
@@ -452,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
*/
@@ -559,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
*/

19
core/field_image.ts
View File

@@ -6,6 +6,7 @@
/**
* Image field. Used for pictures, icons, etc.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -22,6 +23,7 @@ import {Svg} from './utils/svg.js';
/**
* Class for an image on a block.
*
* @alias Blockly.FieldImage
*/
export class FieldImage extends Field {
@@ -123,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) {
@@ -135,6 +138,7 @@ export class FieldImage extends Field {
/**
* Create the block UI for this image.
*
* @internal
*/
override initView() {
@@ -158,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 {
@@ -171,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.
*/
@@ -184,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_;
@@ -192,6 +199,7 @@ export class FieldImage extends Field {
/**
* Set the alt text of this image.
*
* @param alt New alt text.
*/
setAlt(alt: string|null) {
@@ -216,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.
*/
@@ -227,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_;
@@ -236,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
*/

10
core/field_label.ts
View File

@@ -7,6 +7,7 @@
/**
* Non-editable, non-serializable text field. Used for titles,
* labels, etc.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -21,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 {
@@ -68,6 +70,7 @@ export class FieldLabel extends Field {
/**
* Create block UI for this label.
*
* @internal
*/
override initView() {
@@ -79,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 {
@@ -92,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) {
@@ -111,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
*/

27
core/field_multilineinput.ts
View File

@@ -6,6 +6,7 @@
/**
* Text Area field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -27,6 +28,7 @@ import * as WidgetDiv from './widgetdiv.js';
/**
* Class for an editable text area field.
*
* @alias Blockly.FieldMultilineInput
*/
export class FieldMultilineInput extends FieldTextInput {
@@ -86,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 {
@@ -104,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
*/
@@ -113,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 {
@@ -126,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
*/
@@ -138,6 +144,7 @@ export class FieldMultilineInput extends FieldTextInput {
/**
* Create the block UI for this field.
*
* @internal
*/
override initView() {
@@ -152,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();
@@ -193,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.
*/
@@ -323,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.
@@ -335,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();
@@ -380,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.
*/
@@ -393,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_;
@@ -402,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) {
@@ -415,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
*/

28
core/field_number.ts
View File

@@ -6,6 +6,7 @@
/**
* Number input field
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -20,6 +21,7 @@ import type {Sentinel} from './utils/sentinel.js';
/**
* Class for an editable number field.
*
* @alias Blockly.FieldNumber
*/
export class FieldNumber extends FieldTextInput {
@@ -86,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) {
@@ -103,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.
@@ -119,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) {
@@ -129,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) {
@@ -145,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_;
@@ -154,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) {
@@ -164,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) {
@@ -180,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_;
@@ -189,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) {
@@ -199,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) {
@@ -224,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_;
@@ -233,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 {
@@ -272,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_();
@@ -289,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
*/

34
core/field_textinput.ts
View File

@@ -6,6 +6,7 @@
/**
* Text input field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -35,6 +36,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Class for an editable text field.
*
* @alias Blockly.FieldTextInput
*/
export class FieldTextInput extends Field {
@@ -157,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 {
@@ -172,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_.
@@ -194,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.
*/
@@ -208,6 +213,7 @@ export class FieldTextInput extends Field {
/**
* Updates text field to match the colour/style of the block.
*
* @internal
*/
override applyColour() {
@@ -246,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) {
@@ -263,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.
@@ -295,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) {
@@ -312,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);
@@ -392,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) {}
@@ -400,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) {
@@ -425,6 +437,7 @@ export class FieldTextInput extends Field {
/**
* Handle key down to the editor.
*
* @param e Keyboard event.
*/
protected onHtmlInputKeyDown_(e: Event) {
@@ -456,6 +469,7 @@ export class FieldTextInput extends Field {
/**
* Handle a change to the editor.
*
* @param _e Keyboard event.
*/
private onHtmlInputChange_(_e: Event) {
@@ -474,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) {
@@ -506,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;
@@ -517,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_) {
@@ -532,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);
@@ -545,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;
@@ -555,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
*/

48
core/field_variable.ts
View File

@@ -6,6 +6,7 @@
/**
* Variable input field.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -32,6 +33,7 @@ import * as Xml from './xml.js';
/**
* Class for a variable's dropdown field.
*
* @alias Blockly.FieldVariable
*/
export class FieldVariable extends FieldDropdown {
@@ -117,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) {
@@ -128,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() {
@@ -149,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.
*/
@@ -180,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.
@@ -198,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 {
@@ -221,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
*/
@@ -237,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) {
@@ -248,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;
@@ -256,7 +266,8 @@ 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
*
* @returns The selected variable's name, or the empty string if no variable is
* selected.
*/
override getText(): string {
@@ -267,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 {
@@ -279,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.
@@ -293,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 {
@@ -324,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) {
@@ -334,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_();
@@ -352,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[] {
@@ -377,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.
@@ -420,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() {
@@ -430,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.
*/
@@ -455,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 {
@@ -465,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
*/
@@ -482,7 +504,9 @@ 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.
*
* @param this
* @returns Array of variable names/id tuples.
*/
static dropdownCreate(this: FieldVariable): AnyDuringMigration[][] {
if (!this.variable_) {

17
core/flyout_button.ts
View File

@@ -6,6 +6,7 @@
/**
* Class for a button in the flyout.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -24,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 {
@@ -84,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';
@@ -186,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.
*/
@@ -195,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;
@@ -237,6 +243,7 @@ export class FlyoutButton {
/**
* Do something when the button is clicked.
*
* @param e Mouse up event.
*/
private onMouseUp_(e: Event) {

20
core/flyout_horizontal.ts
View File

@@ -6,6 +6,7 @@
/**
* Horizontal flyout tray containing blocks which may be created.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -26,6 +27,7 @@ import * as WidgetDiv from './widgetdiv.js';
/**
* Class for a flyout.
*
* @alias Blockly.HorizontalFlyout
*/
export class HorizontalFlyout extends Flyout {
@@ -43,8 +45,11 @@ 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.
* @param xyRatio.x
* @param xyRatio.y
*/
protected override setMetrics_(xyRatio: {x: number, y: number}) {
if (!this.isVisible()) {
@@ -69,7 +74,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.
@@ -78,7 +84,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()) {
@@ -146,6 +153,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.
*/
@@ -195,6 +203,7 @@ export class HorizontalFlyout extends Flyout {
/**
* Scroll the flyout.
*
* @param e Mouse wheel scroll event.
*/
protected override wheel_(e: WheelEvent) {
@@ -221,6 +230,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.
*/
@@ -277,9 +287,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 {
@@ -300,7 +311,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 {

5
core/flyout_metrics_manager.ts
View File

@@ -6,6 +6,7 @@
/**
* Calculates and reports flyout workspace metrics.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -19,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 {
@@ -37,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} {

50
core/generator.ts
View File

@@ -7,6 +7,7 @@
/**
* Utility functions for generating executable code from
* Blockly code.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -21,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
*/
@@ -105,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) {
@@ -166,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);
@@ -176,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 = [];
@@ -198,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.
*/
@@ -257,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 {
@@ -331,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);
@@ -356,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) {
@@ -382,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.
@@ -393,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.
*/
@@ -417,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):
@@ -450,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) {
@@ -468,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 {
@@ -483,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
@@ -499,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
@@ -511,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}
@@ -518,14 +534,20 @@ Object.defineProperties(Generator.prototype, {
// AnyDuringMigration because: Type 'Names | undefined' is not assignable to
// type 'PropertyDescriptor'.
variableDB_: ({
/** @return Name database. */
/**
* @param this
* @returns Name database.
*/
get(this: Generator): Names |
undefined {
deprecation.warn(
'variableDB_', 'May 2021', 'September 2022', 'nameDB_');
return this.nameDB_;
},
/** @param nameDb New name database. */
/**
* @param this
* @param nameDb New name database.
*/
set(this: Generator, nameDb: Names|undefined) {
deprecation.warn('variableDB_', 'May 2021', 'September2022', 'nameDB_');
this.nameDB_ = nameDb;

35
core/input.ts
View File

@@ -6,6 +6,7 @@
/**
* Object representing an input (value, statement, or dummy).
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -25,6 +26,7 @@ import type {RenderedConnection} from './rendered_connection.js';
/**
* Class for an input with an optional field.
*
* @alias Blockly.Input
*/
export class Input {
@@ -57,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_;
@@ -66,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);
@@ -79,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) {
@@ -133,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.
*/
@@ -160,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_;
@@ -169,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[] {
@@ -204,6 +212,7 @@ export class Input {
/**
* Mark all fields on this input as dirty.
*
* @internal
*/
markDirty() {
@@ -214,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) {
@@ -228,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;
@@ -243,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) {
@@ -256,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) {
@@ -277,6 +290,7 @@ export class Input {
/**
* Sever all links to this input.
*
* @suppress {checkTypes}
*/
dispose() {
@@ -292,6 +306,7 @@ export class Input {
export namespace Input {
/**
* Enum for alignment of inputs.
*
* @alias Blockly.Input.Align
*/
export enum Align {

2
core/input_types.ts
View File

@@ -6,6 +6,7 @@
/**
* An enum for the possible types of inputs.
*
* @namespace Blockly.inputTypes
*/
import * as goog from '../closure/goog/goog.js';
@@ -16,6 +17,7 @@ import {ConnectionType} from './connection_type.js';
/**
* Enum for the type of a connection or input.
*
* @alias Blockly.inputTypes
*/
export enum inputTypes {

35
core/insertion_marker_manager.ts
View File

@@ -6,6 +6,7 @@
/**
* Class that controls updates to connections during drags.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -46,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 {
@@ -148,6 +150,7 @@ export class InsertionMarkerManager {
/**
* Sever all links from this object.
*
* @internal
*/
dispose() {
@@ -169,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() {
@@ -178,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 {
@@ -188,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 {
@@ -198,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() {
@@ -227,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
@@ -250,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;
@@ -311,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);
@@ -336,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 {
@@ -386,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 {
@@ -420,7 +432,8 @@ 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,
@@ -437,10 +450,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 {
@@ -461,6 +475,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.
*/
@@ -529,6 +544,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.
*/
@@ -753,7 +769,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[] {

81
core/keyboard_nav/ast_node.ts
View File

@@ -7,6 +7,7 @@
/**
* The class representing an AST node.
* Used to traverse the Blockly AST.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -27,6 +28,7 @@ import type {Workspace} from '../workspace.js';
* Class for an AST node.
* It is recommended that you use one of the createNode methods instead of
* creating a node directly.
*
* @alias Blockly.ASTNode
*/
export class ASTNode {
@@ -78,6 +80,7 @@ export class ASTNode {
/**
* Parse the optional parameters.
*
* @param params The user specified parameters.
*/
private processParams_(params: Params|null) {
@@ -93,7 +96,8 @@ export class ASTNode {
* Gets the value pointed to by this node.
* It is the callers responsibility to check the node type to figure out what
* type of object they get back from this.
* @return The current field, connection, workspace, or block the cursor is
*
* @returns The current field, connection, workspace, or block the cursor is
* on.
*/
getLocation(): IASTNodeLocation {
@@ -103,7 +107,8 @@ export class ASTNode {
/**
* The type of the current location.
* One of ASTNode.types
* @return The type of the location.
*
* @returns The type of the location.
*/
getType(): string {
return this.type_;
@@ -111,7 +116,8 @@ export class ASTNode {
/**
* The coordinate on the workspace.
* @return The workspace coordinate or null if the location is not a
*
* @returns The workspace coordinate or null if the location is not a
* workspace.
*/
getWsCoordinate(): Coordinate {
@@ -120,7 +126,8 @@ export class ASTNode {
/**
* Whether the node points to a connection.
* @return [description]
*
* @returns [description]
* @internal
*/
isConnection(): boolean {
@@ -131,7 +138,8 @@ export class ASTNode {
* Given an input find the next editable field or an input with a non null
* connection in the same block. The current location must be an input
* connection.
* @return The AST node holding the next field or connection or null if there
*
* @returns The AST node holding the next field or connection or null if there
* is no editable field or input connection after the given input.
*/
private findNextForInput_(): ASTNode|null {
@@ -160,7 +168,8 @@ export class ASTNode {
/**
* Given a field find the next editable field or an input with a non null
* connection in the same block. The current location must be a field.
* @return The AST node pointing to the next field or connection or null if
*
* @returns The AST node pointing to the next field or connection or null if
* there is no editable field or input connection after the given input.
*/
private findNextForField_(): ASTNode|null {
@@ -190,7 +199,8 @@ export class ASTNode {
* Given an input find the previous editable field or an input with a non null
* connection in the same block. The current location must be an input
* connection.
* @return The AST node holding the previous field or connection.
*
* @returns The AST node holding the previous field or connection.
*/
private findPrevForInput_(): ASTNode|null {
const location = this.location_ as Connection;
@@ -218,7 +228,8 @@ export class ASTNode {
/**
* Given a field find the previous editable field or an input with a non null
* connection in the same block. The current location must be a field.
* @return The AST node holding the previous input or field.
*
* @returns The AST node holding the previous input or field.
*/
private findPrevForField_(): ASTNode|null {
const location = this.location_ as Field;
@@ -249,8 +260,9 @@ export class ASTNode {
/**
* Navigate between stacks of blocks on the workspace.
*
* @param forward True to go forward. False to go backwards.
* @return The first block of the next stack or null if there are no blocks on
* @returns The first block of the next stack or null if there are no blocks on
* the workspace.
*/
private navigateBetweenStacks_(forward: boolean): ASTNode|null {
@@ -287,8 +299,9 @@ export class ASTNode {
* Finds the top most AST node for a given block.
* This is either the previous connection, output connection or block
* depending on what kind of connections the block has.
*
* @param block The block that we want to find the top connection on.
* @return The AST node containing the top connection.
* @returns The AST node containing the top connection.
*/
private findTopASTNodeForBlock_(block: Block): ASTNode|null {
const topConnection = getParentConnection(block);
@@ -302,8 +315,9 @@ export class ASTNode {
/**
* Get the AST node pointing to the input that the block is nested under or if
* the block is not nested then get the stack AST node.
*
* @param block The source block of the current location.
* @return The AST node pointing to the input connection or the top block of
* @returns The AST node pointing to the input connection or the top block of
* the stack this block is in.
*/
private getOutAstNodeForBlock_(block: Block): ASTNode|null {
@@ -331,8 +345,9 @@ export class ASTNode {
/**
* Find the first editable field or input with a connection on a given block.
*
* @param block The source block of the current location.
* @return An AST node pointing to the first field or input.
* @returns An AST node pointing to the first field or input.
* Null if there are no editable fields or inputs with connections on the
* block.
*/
@@ -356,7 +371,8 @@ export class ASTNode {
/**
* Finds the source block of the location of this node.
* @return The source block of the location, or null if the node is of type
*
* @returns The source block of the location, or null if the node is of type
* workspace.
*/
getSourceBlock(): Block|null {
@@ -373,7 +389,8 @@ export class ASTNode {
/**
* Find the element to the right of the current element in the AST.
* @return An AST node that wraps the next field, connection, block, or
*
* @returns An AST node that wraps the next field, connection, block, or
* workspace. Or null if there is no node to the right.
*/
next(): ASTNode|null {
@@ -413,7 +430,8 @@ export class ASTNode {
/**
* Find the element one level below and all the way to the left of the current
* location.
* @return An AST node that wraps the next field, connection, workspace, or
*
* @returns An AST node that wraps the next field, connection, workspace, or
* block. Or null if there is nothing below this node.
*/
in(): ASTNode|null {
@@ -446,7 +464,8 @@ export class ASTNode {
/**
* Find the element to the left of the current element in the AST.
* @return An AST node that wraps the previous field, connection, workspace or
*
* @returns An AST node that wraps the previous field, connection, workspace or
* block. Or null if no node exists to the left.
* null.
*/
@@ -489,7 +508,8 @@ export class ASTNode {
/**
* Find the next element that is one position above and all the way to the
* left of the current location.
* @return An AST node that wraps the next field, connection, workspace or
*
* @returns An AST node that wraps the next field, connection, workspace or
* block. Or null if we are at the workspace level.
*/
out(): ASTNode|null {
@@ -537,8 +557,9 @@ export class ASTNode {
/**
* Whether an AST node of the given type points to a connection.
*
* @param type The type to check. One of ASTNode.types.
* @return True if a node of the given type points to a connection.
* @returns True if a node of the given type points to a connection.
*/
private static isConnectionType_(type: string): boolean {
switch (type) {
@@ -553,8 +574,9 @@ export class ASTNode {
/**
* Create an AST node pointing to a field.
*
* @param field The location of the AST node.
* @return An AST node pointing to a field.
* @returns An AST node pointing to a field.
*/
static createFieldNode(field: Field): ASTNode|null {
if (!field) {
@@ -567,8 +589,9 @@ export class ASTNode {
* Creates an AST node pointing to a connection. If the connection has a
* parent input then create an AST node of type input that will hold the
* connection.
*
* @param connection This is the connection the node will point to.
* @return An AST node pointing to a connection.
* @returns An AST node pointing to a connection.
*/
static createConnectionNode(connection: Connection): ASTNode|null {
if (!connection) {
@@ -599,8 +622,9 @@ export class ASTNode {
/**
* Creates an AST node pointing to an input. Stores the input connection as
* the location.
*
* @param input The input used to create an AST node.
* @return An AST node pointing to a input.
* @returns An AST node pointing to a input.
*/
static createInputNode(input: Input): ASTNode|null {
if (!input || !input.connection) {
@@ -611,8 +635,9 @@ export class ASTNode {
/**
* Creates an AST node pointing to a block.
*
* @param block The block used to create an AST node.
* @return An AST node pointing to a block.
* @returns An AST node pointing to a block.
*/
static createBlockNode(block: Block): ASTNode|null {
if (!block) {
@@ -625,9 +650,10 @@ export class ASTNode {
* Create an AST node of type stack. A stack, represented by its top block, is
* the set of all blocks connected to a top block, including the top
* block.
*
* @param topBlock A top block has no parent and can be found in the list
* returned by workspace.getTopBlocks().
* @return An AST node of type stack that points to the top block on the
* @returns An AST node of type stack that points to the top block on the
* stack.
*/
static createStackNode(topBlock: Block): ASTNode|null {
@@ -639,9 +665,10 @@ export class ASTNode {
/**
* Creates an AST node pointing to a workspace.
*
* @param workspace The workspace that we are on.
* @param wsCoordinate The position on the workspace for this node.
* @return An AST node pointing to a workspace and a position on the
* @returns An AST node pointing to a workspace and a position on the
* workspace.
*/
static createWorkspaceNode(
@@ -656,8 +683,9 @@ export class ASTNode {
/**
* Creates an AST node for the top position on a block.
* This is either an output connection, previous connection, or block.
*
* @param block The block to find the top most AST node on.
* @return The AST node holding the top most position on the block.
* @returns The AST node holding the top most position on the block.
*/
static createTopNode(block: Block): ASTNode|null {
let astNode;
@@ -699,8 +727,9 @@ export type Params = ASTNode.Params;
* This is either an output connection, previous connection or undefined.
* If both connections exist return the one that is actually connected
* to another block.
*
* @param block The block to find the parent connection on.
* @return The connection connecting to the parent of the block.
* @returns The connection connecting to the parent of the block.
*/
function getParentConnection(block: Block): Connection {
let topConnection = block.outputConnection;

29
core/keyboard_nav/basic_cursor.ts
View File

@@ -7,6 +7,7 @@
/**
* The class representing a basic cursor.
* Used to demo switching between different cursors.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -22,6 +23,7 @@ import {Cursor} from './cursor.js';
* Class for a basic cursor.
* This will allow the user to get to all nodes in the AST by hitting next or
* previous.
*
* @alias Blockly.BasicCursor
*/
export class BasicCursor extends Cursor {
@@ -35,7 +37,8 @@ export class BasicCursor extends Cursor {
/**
* Find the next node in the pre order traversal.
* @return The next node, or null if the current node is not set or there is
*
* @returns The next node, or null if the current node is not set or there is
* no next value.
*/
override next(): ASTNode|null {
@@ -55,7 +58,8 @@ export class BasicCursor extends Cursor {
* For a basic cursor we only have the ability to go next and previous, so
* in will also allow the user to get to the next node in the pre order
* traversal.
* @return The next node, or null if the current node is not set or there is
*
* @returns The next node, or null if the current node is not set or there is
* no next value.
*/
override in(): ASTNode|null {
@@ -64,7 +68,8 @@ export class BasicCursor extends Cursor {
/**
* Find the previous node in the pre order traversal.
* @return The previous node, or null if the current node is not set or there
*
* @returns The previous node, or null if the current node is not set or there
* is no previous value.
*/
override prev(): ASTNode|null {
@@ -84,7 +89,8 @@ export class BasicCursor extends Cursor {
* For a basic cursor we only have the ability to go next and previous, so
* out will allow the user to get to the previous node in the pre order
* traversal.
* @return The previous node, or null if the current node is not set or there
*
* @returns The previous node, or null if the current node is not set or there
* is no previous value.
*/
override out(): ASTNode|null {
@@ -95,10 +101,11 @@ export class BasicCursor extends Cursor {
* Uses pre order traversal to navigate the Blockly AST. This will allow
* a user to easily navigate the entire Blockly AST without having to go in
* and out levels on the tree.
*
* @param node The current position in the AST.
* @param isValid A function true/false depending on whether the given node
* should be traversed.
* @return The next node in the traversal.
* @returns The next node in the traversal.
*/
protected getNextNode_(
node: ASTNode|null, isValid: (p1: ASTNode|null) => boolean): ASTNode
@@ -127,10 +134,11 @@ export class BasicCursor extends Cursor {
* Reverses the pre order traversal in order to find the previous node. This
* will allow a user to easily navigate the entire Blockly AST without having
* to go in and out levels on the tree.
*
* @param node The current position in the AST.
* @param isValid A function true/false depending on whether the given node
* should be traversed.
* @return The previous node in the traversal or null if no previous node
* @returns The previous node in the traversal or null if no previous node
* exists.
*/
protected getPreviousNode_(
@@ -157,8 +165,9 @@ export class BasicCursor extends Cursor {
/**
* Decides what nodes to traverse and which ones to skip. Currently, it
* skips output, stack and workspace nodes.
*
* @param node The AST node to check whether it is valid.
* @return True if the node should be visited, false otherwise.
* @returns True if the node should be visited, false otherwise.
*/
protected validNode_(node: ASTNode|null): boolean {
let isValid = false;
@@ -173,8 +182,9 @@ export class BasicCursor extends Cursor {
/**
* From the given node find either the next valid sibling or parent.
*
* @param node The current position in the AST.
* @return The parent AST node or null if there are no valid parents.
* @returns The parent AST node or null if there are no valid parents.
*/
private findSiblingOrParent_(node: ASTNode|null): ASTNode|null {
if (!node) {
@@ -189,8 +199,9 @@ export class BasicCursor extends Cursor {
/**
* Get the right most child of a node.
*
* @param node The node to find the right most child of.
* @return The right most child of the given node, or the node if no child
* @returns The right most child of the given node, or the node if no child
* exists.
*/
private getRightMostChild_(node: ASTNode|null): ASTNode|null {

14
core/keyboard_nav/cursor.ts
View File

@@ -7,6 +7,7 @@
/**
* The class representing a cursor.
* Used primarily for keyboard navigation.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -21,6 +22,7 @@ import {Marker} from './marker.js';
/**
* Class for a cursor.
* A cursor controls how a user navigates the Blockly AST.
*
* @alias Blockly.Cursor
*/
export class Cursor extends Marker {
@@ -33,7 +35,8 @@ export class Cursor extends Marker {
/**
* Find the next connection, field, or block.
* @return The next element, or null if the current node is not set or there
*
* @returns The next element, or null if the current node is not set or there
* is no next value.
*/
next(): ASTNode|null {
@@ -57,7 +60,8 @@ export class Cursor extends Marker {
/**
* Find the in connection or field.
* @return The in element, or null if the current node is not set or there is
*
* @returns The in element, or null if the current node is not set or there is
* no in value.
*/
in(): ASTNode|null {
@@ -81,7 +85,8 @@ export class Cursor extends Marker {
/**
* Find the previous connection, field, or block.
* @return The previous element, or null if the current node is not set or
*
* @returns The previous element, or null if the current node is not set or
* there is no previous value.
*/
prev(): ASTNode|null {
@@ -105,7 +110,8 @@ export class Cursor extends Marker {
/**
* Find the out connection, field, or block.
* @return The out element, or null if the current node is not set or there is
*
* @returns The out element, or null if the current node is not set or there is
* no out value.
*/
out(): ASTNode|null {

11
core/keyboard_nav/marker.ts
View File

@@ -7,6 +7,7 @@
/**
* The class representing a marker.
* Used primarily for keyboard navigation to show a marked location.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -21,6 +22,7 @@ import type {ASTNode} from './ast_node.js';
/**
* Class for a marker.
* This is used in keyboard navigation to save a location in the Blockly AST.
*
* @alias Blockly.Marker
*/
export class Marker {
@@ -48,6 +50,7 @@ export class Marker {
/**
* Sets the object in charge of drawing the marker.
*
* @param drawer The object in charge of drawing the marker.
*/
setDrawer(drawer: MarkerSvg) {
@@ -56,7 +59,8 @@ export class Marker {
/**
* Get the current drawer for the marker.
* @return The object in charge of drawing the marker.
*
* @returns The object in charge of drawing the marker.
*/
getDrawer(): MarkerSvg {
return this.drawer_;
@@ -64,7 +68,8 @@ export class Marker {
/**
* Gets the current location of the marker.
* @return The current field, connection, or block the marker is on.
*
* @returns The current field, connection, or block the marker is on.
*/
getCurNode(): ASTNode {
return this.curNode_;
@@ -74,6 +79,7 @@ export class Marker {
* Set the location of the marker and call the update method.
* Setting isStack to true will only work if the newLocation is the top most
* output or previous connection on a stack.
*
* @param newNode The new location of the marker.
*/
setCurNode(newNode: ASTNode) {
@@ -86,6 +92,7 @@ export class Marker {
/**
* Redraw the current marker.
*
* @internal
*/
draw() {

5
core/keyboard_nav/tab_navigate_cursor.ts
View File

@@ -7,6 +7,7 @@
/**
* The class representing a cursor that is used to navigate
* between tab navigable fields.
*
* @class
*/
import * as goog from '../../closure/goog/goog.js';
@@ -20,13 +21,15 @@ import {BasicCursor} from './basic_cursor.js';
/**
* A cursor for navigating between tab navigable fields.
*
* @alias Blockly.TabNavigateCursor
*/
export class TabNavigateCursor extends BasicCursor {
/**
* Skip all nodes except for tab navigable fields.
*
* @param node The AST node to check whether it is valid.
* @return True if the node should be visited, false otherwise.
* @returns True if the node should be visited, false otherwise.
*/
override validNode_(node: ASTNode|null): boolean {
let isValid = false;

15
core/marker_manager.ts
View File

@@ -6,6 +6,7 @@
/**
* Object in charge of managing markers and the cursor.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -18,6 +19,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Class to manage the multiple markers and the cursor on a workspace.
*
* @alias Blockly.MarkerManager
*/
export class MarkerManager {
@@ -44,6 +46,7 @@ export class MarkerManager {
/**
* Register the marker by adding it to the map of markers.
*
* @param id A unique identifier for the marker.
* @param marker The marker to register.
*/
@@ -59,6 +62,7 @@ export class MarkerManager {
/**
* Unregister the marker by removing it from the map of markers.
*
* @param id The ID of the marker to unregister.
*/
unregisterMarker(id: string) {
@@ -75,7 +79,8 @@ export class MarkerManager {
/**
* Get the cursor for the workspace.
* @return The cursor for this workspace.
*
* @returns The cursor for this workspace.
*/
getCursor(): Cursor|null {
return this.cursor_;
@@ -83,8 +88,9 @@ export class MarkerManager {
/**
* Get a single marker that corresponds to the given ID.
*
* @param id A unique identifier for the marker.
* @return The marker that corresponds to the given ID, or null if none
* @returns The marker that corresponds to the given ID, or null if none
* exists.
*/
getMarker(id: string): Marker|null {
@@ -94,6 +100,7 @@ export class MarkerManager {
/**
* Sets the cursor and initializes the drawer for use with keyboard
* navigation.
*
* @param cursor The cursor used to move around this workspace.
*/
setCursor(cursor: Cursor) {
@@ -111,6 +118,7 @@ export class MarkerManager {
/**
* Add the cursor SVG to this workspace SVG group.
*
* @param cursorSvg The SVG root of the cursor to be added to the workspace
* SVG group.
* @internal
@@ -127,6 +135,7 @@ export class MarkerManager {
/**
* Add the marker SVG to this workspaces SVG group.
*
* @param markerSvg The SVG root of the marker to be added to the workspace
* SVG group.
* @internal
@@ -149,6 +158,7 @@ export class MarkerManager {
/**
* Redraw the attached cursor SVG if needed.
*
* @internal
*/
updateMarkers() {
@@ -160,6 +170,7 @@ export class MarkerManager {
/**
* Dispose of the marker manager.
* Go through and delete all markers associated with this marker manager.
*
* @suppress {checkTypes}
* @internal
*/

24
core/menu.ts
View File

@@ -6,6 +6,7 @@
/**
* Blockly menu similar to Closure's goog.ui.Menu
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -23,6 +24,7 @@ import * as style from './utils/style.js';
/**
* A basic menu class.
*
* @alias Blockly.Menu
*/
export class Menu {
@@ -72,6 +74,7 @@ export class Menu {
/**
* Add a new menu item to the bottom of this menu.
*
* @param menuItem Menu item to append.
* @internal
*/
@@ -81,6 +84,7 @@ export class Menu {
/**
* Creates the menu DOM.
*
* @param container Element upon which to append this menu.
*/
render(container: Element) {
@@ -115,7 +119,8 @@ export class Menu {
/**
* Gets the menu's element.
* @return The DOM element.
*
* @returns The DOM element.
* @internal
*/
getElement(): Element|null {
@@ -124,6 +129,7 @@ export class Menu {
/**
* Focus the menu element.
*
* @internal
*/
focus() {
@@ -149,6 +155,7 @@ export class Menu {
/**
* Set the menu accessibility role.
*
* @param roleName role name.
* @internal
*/
@@ -192,8 +199,9 @@ export class Menu {
/**
* Returns the child menu item that owns the given DOM element,
* or null if no such menu item is found.
*
* @param elem DOM element whose owner is to be returned.
* @return Menu item for which the DOM element belongs to.
* @returns Menu item for which the DOM element belongs to.
*/
private getMenuItem_(elem: Element): MenuItem|null {
const menuElem = this.getElement();
@@ -221,6 +229,7 @@ export class Menu {
/**
* Highlights the given menu item, or clears highlighting if null.
*
* @param item Item to highlight, or null.
* @internal
*/
@@ -245,6 +254,7 @@ export class Menu {
/**
* Highlights the next highlightable item (or the first if nothing is
* currently highlighted).
*
* @internal
*/
highlightNext() {
@@ -258,6 +268,7 @@ export class Menu {
/**
* Highlights the previous highlightable item (or the last if nothing is
* currently highlighted).
*
* @internal
*/
highlightPrevious() {
@@ -281,6 +292,7 @@ export class Menu {
/**
* Helper function that manages the details of moving the highlight among
* child menuitems in response to keyboard events.
*
* @param startIndex Start index.
* @param delta Step direction: 1 to go down, -1 to go up.
*/
@@ -300,6 +312,7 @@ export class Menu {
/**
* Handles mouseover events. Highlight menuitems as the user hovers over them.
*
* @param e Mouse event to handle.
*/
private handleMouseOver_(e: Event) {
@@ -318,6 +331,7 @@ export class Menu {
/**
* Handles click events. Pass the event onto the child menuitem to handle.
*
* @param e Click event to handle.
*/
private handleClick_(e: Event) {
@@ -350,6 +364,7 @@ export class Menu {
/**
* Handles mouse enter events. Focus the element.
*
* @param _e Mouse event to handle.
*/
private handleMouseEnter_(_e: Event) {
@@ -358,6 +373,7 @@ export class Menu {
/**
* Handles mouse leave events. Blur and clear highlight.
*
* @param _e Mouse event to handle.
*/
private handleMouseLeave_(_e: Event) {
@@ -373,6 +389,7 @@ export class Menu {
* Attempts to handle a keyboard event, if the menu item is enabled, by
* calling
* {@link handleKeyEventInternal_}.
*
* @param e Key event to handle.
*/
private handleKeyEvent_(e: Event) {
@@ -432,7 +449,8 @@ export class Menu {
/**
* Get the size of a rendered menu.
* @return Object with width and height properties.
*
* @returns Object with width and height properties.
* @internal
*/
getSize(): Size {

25
core/menuitem.ts
View File

@@ -6,6 +6,7 @@
/**
* Blockly menu item similar to Closure's goog.ui.MenuItem
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -18,6 +19,7 @@ import * as idGenerator from './utils/idgenerator.js';
/**
* Class representing an item in a menu.
*
* @alias Blockly.MenuItem
*/
export class MenuItem {
@@ -56,7 +58,8 @@ export class MenuItem {
/**
* Creates the menuitem's DOM.
* @return Completed DOM.
*
* @returns Completed DOM.
*/
createDom(): Element {
const element = (document.createElement('div'));
@@ -108,7 +111,8 @@ export class MenuItem {
/**
* Gets the menu item's element.
* @return The DOM element.
*
* @returns The DOM element.
* @internal
*/
getElement(): Element|null {
@@ -117,7 +121,8 @@ export class MenuItem {
/**
* Gets the unique ID for this menu item.
* @return Unique component ID.
*
* @returns Unique component ID.
* @internal
*/
getId(): string {
@@ -126,7 +131,8 @@ export class MenuItem {
/**
* Gets the value associated with the menu item.
* @return value Value associated with the menu item.
*
* @returns value Value associated with the menu item.
* @internal
*/
getValue(): AnyDuringMigration {
@@ -135,6 +141,7 @@ export class MenuItem {
/**
* Set menu item's rendering direction.
*
* @param rtl True if RTL, false if LTR.
* @internal
*/
@@ -144,6 +151,7 @@ export class MenuItem {
/**
* Set the menu item's accessibility role.
*
* @param roleName Role name.
* @internal
*/
@@ -154,6 +162,7 @@ export class MenuItem {
/**
* Sets the menu item to be checkable or not. Set to true for menu items
* that represent checkable options.
*
* @param checkable Whether the menu item is checkable.
* @internal
*/
@@ -163,6 +172,7 @@ export class MenuItem {
/**
* Checks or unchecks the component.
*
* @param checked Whether to check or uncheck the component.
* @internal
*/
@@ -172,6 +182,7 @@ export class MenuItem {
/**
* Highlights or unhighlights the component.
*
* @param highlight Whether to highlight or unhighlight the component.
* @internal
*/
@@ -196,7 +207,8 @@ export class MenuItem {
/**
* Returns true if the menu item is enabled, false otherwise.
* @return Whether the menu item is enabled.
*
* @returns Whether the menu item is enabled.
* @internal
*/
isEnabled(): boolean {
@@ -205,6 +217,7 @@ export class MenuItem {
/**
* Enables or disables the menu item.
*
* @param enabled Whether to enable or disable the menu item.
* @internal
*/
@@ -215,6 +228,7 @@ export class MenuItem {
/**
* Performs the appropriate action when the menu item is activated
* by the user.
*
* @internal
*/
performAction() {
@@ -226,6 +240,7 @@ export class MenuItem {
/**
* Set the handler that's called when the menu item is activated by the user.
* `obj` will be used as the 'this' object in the function when called.
*
* @param fn The handler.
* @param obj Used as the 'this' object in fn when called.
* @internal

28
core/mutator.ts
View File

@@ -7,6 +7,7 @@
/**
* Object representing a mutator dialog. A mutator allows the
* user to change the shape of a block using a nested blocks editor.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -36,6 +37,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Class for a mutator dialog.
*
* @alias Blockly.Mutator
*/
export class Mutator extends Icon {
@@ -74,7 +76,10 @@ export class Mutator extends Icon {
*/
private updateWorkspacePid_: AnyDuringMigration = 0;
/** @param quarkNames List of names of sub-blocks for flyout. */
/**
* @param block
* @param quarkNames List of names of sub-blocks for flyout.
*/
constructor(block: BlockSvg, quarkNames: string[]) {
super(block);
this.quarkNames_ = quarkNames;
@@ -82,6 +87,7 @@ export class Mutator extends Icon {
/**
* Set the block this mutator is associated with.
*
* @param block The block associated with this mutator.
* @internal
*/
@@ -91,7 +97,8 @@ export class Mutator extends Icon {
/**
* Returns the workspace inside this mutator icon's bubble.
* @return The workspace inside this mutator icon's bubble or null if the
*
* @returns The workspace inside this mutator icon's bubble or null if the
* mutator isn't open.
* @internal
*/
@@ -101,6 +108,7 @@ export class Mutator extends Icon {
/**
* Draw the mutator icon.
*
* @param group The icon group.
*/
protected override drawIcon_(group: Element) {
@@ -136,6 +144,7 @@ export class Mutator extends Icon {
/**
* Clicking on the icon toggles if the mutator bubble is visible.
* Disable if block is uneditable.
*
* @param e Mouse click event.
*/
protected override iconClick_(e: MouseEvent) {
@@ -146,7 +155,8 @@ export class Mutator extends Icon {
/**
* Create the editor for the mutator'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:
@@ -210,6 +220,7 @@ export class Mutator extends Icon {
}
/**
* @param options
* @internal
*/
// eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -294,6 +305,7 @@ export class Mutator extends Icon {
/**
* Show or hide the mutator bubble.
*
* @param visible True if the bubble should be visible.
*/
override setVisible(visible: boolean) {
@@ -376,6 +388,7 @@ export class Mutator extends Icon {
/**
* Fired whenever a change is made to the mutator's workspace.
*
* @param e Custom data for event.
*/
private workspaceChanged_(e: Abstract) {
@@ -390,8 +403,9 @@ export class Mutator extends Icon {
/**
* Returns whether the given event in the mutator workspace should be ignored
* when deciding whether to update the workspace and compose the block or not.
*
* @param e The event.
* @return Whether to ignore the event or not.
* @returns Whether to ignore the event or not.
*/
shouldIgnoreMutatorEvent_(e: Abstract) {
return e.isUiEvent || e.type === eventUtils.CREATE ||
@@ -507,10 +521,11 @@ export class Mutator extends Icon {
/**
* Reconnect an block to a mutated input.
*
* @param connectionChild Connection on child block.
* @param block Parent block.
* @param inputName Name of input on parent block.
* @return True iff a reconnection was made, false otherwise.
* @returns True iff a reconnection was made, false otherwise.
*/
static reconnect(
connectionChild: Connection, block: Block, inputName: string): boolean {
@@ -534,8 +549,9 @@ export class Mutator extends Icon {
/**
* Get the parent workspace of a workspace that is inside a mutator, taking
* into account whether it is a flyout.
*
* @param workspace The workspace that is inside a mutator.
* @return The mutator's parent workspace or null.
* @returns The mutator's parent workspace or null.
*/
static findParentWs(workspace: WorkspaceSvg): WorkspaceSvg|null {
let outerWs = null;

24
core/names.ts
View File

@@ -6,6 +6,7 @@
/**
* Utility functions for handling variable and procedure names.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -23,6 +24,7 @@ import type {Workspace} from './workspace.js';
/**
* Class for a database of entity names (variables, procedures, etc).
*
* @alias Blockly.Names
*/
export class Names {
@@ -71,6 +73,7 @@ export class Names {
/**
* Set the variable map that maps from variable name to variable object.
*
* @param map The map to track.
*/
setVariableMap(map: VariableMap) {
@@ -80,8 +83,9 @@ export class Names {
/**
* Get the name for a user-defined variable, based on its ID.
* This should only be used for variables of NameType VARIABLE.
*
* @param id The ID to look up in the variable map.
* @return The name of the referenced variable, or null if there was no
* @returns The name of the referenced variable, or null if there was no
* variable map or the variable was not found in the map.
*/
private getNameForUserVariable_(id: string): string|null {
@@ -103,6 +107,7 @@ export class Names {
/**
* Generate names for user variables, but only ones that are being used.
*
* @param workspace Workspace to generate variables from.
*/
populateVariables(workspace: Workspace) {
@@ -114,6 +119,7 @@ export class Names {
/**
* Generate names for procedures.
*
* @param workspace Workspace to generate procedures from.
*/
// eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -125,10 +131,11 @@ export class Names {
/**
* Convert a Blockly entity name to a legal exportable entity name.
*
* @param nameOrId The Blockly entity name (no constraints) or variable ID.
* @param type The type of the name in Blockly ('VARIABLE', 'PROCEDURE',
* 'DEVELOPER_VARIABLE', etc...).
* @return An entity name that is legal in the exported language.
* @returns An entity name that is legal in the exported language.
*/
getName(nameOrId: string, type: NameType|string): string {
let name = nameOrId;
@@ -159,9 +166,10 @@ export class Names {
/**
* Return a list of all known user-created names of a specified name type.
*
* @param type The type of entity in Blockly ('VARIABLE', 'PROCEDURE',
* 'DEVELOPER_VARIABLE', etc...).
* @return A list of Blockly entity names (no constraints).
* @returns A list of Blockly entity names (no constraints).
*/
getUserNames(type: NameType|string): string[] {
const userNames = this.db.get(type)?.keys();
@@ -173,10 +181,11 @@ export class Names {
* Ensure that this is a new name not overlapping any previously defined name.
* Also check against list of reserved words for the current language and
* ensure name doesn't collide.
*
* @param name The Blockly entity name (no constraints).
* @param type The type of entity in Blockly ('VARIABLE', 'PROCEDURE',
* 'DEVELOPER_VARIABLE', etc...).
* @return An entity name that is legal in the exported language.
* @returns An entity name that is legal in the exported language.
*/
getDistinctName(name: string, type: NameType|string): string {
let safeName = this.safeName_(name);
@@ -200,8 +209,9 @@ export class Names {
* Given a proposed entity name, generate a name that conforms to the
* [_A-Za-z][_A-Za-z0-9]* format that most languages consider legal for
* variable and function names.
*
* @param name Potentially illegal entity name.
* @return Safe entity name.
* @returns Safe entity name.
*/
private safeName_(name: string): string {
if (!name) {
@@ -222,9 +232,10 @@ export class Names {
/**
* Do the given two entity names refer to the same entity?
* Blockly names are case-insensitive.
*
* @param name1 First name.
* @param name2 Second name.
* @return True if names are the same.
* @returns True if names are the same.
*/
static equals(name1: string, name2: string): boolean {
// name1.localeCompare(name2) is slower.
@@ -242,6 +253,7 @@ export namespace Names {
* Therefore, Blockly keeps a separate name type to disambiguate.
* getName('foo', 'VARIABLE') -> 'foo'
* getName('foo', 'PROCEDURE') -> 'foo2'
*
* @alias Blockly.Names.NameType
*/
export enum NameType {

14
core/positionable_helpers.ts
View File

@@ -6,6 +6,7 @@
/**
* Utility functions for positioning UI elements.
*
* @namespace Blockly.uiPosition
*/
import * as goog from '../closure/goog/goog.js';
@@ -25,6 +26,7 @@ import type {WorkspaceSvg} from './workspace_svg.js';
/**
* Enum for vertical positioning.
*
* @alias Blockly.uiPosition.verticalPosition
* @internal
*/
@@ -35,6 +37,7 @@ export enum verticalPosition {
/**
* Enum for horizontal positioning.
*
* @alias Blockly.uiPosition.horizontalPosition
* @internal
*/
@@ -45,6 +48,7 @@ export enum horizontalPosition {
/**
* An object defining a horizontal and vertical positioning.
*
* @alias Blockly.uiPosition.Position
* @internal
*/
@@ -55,6 +59,7 @@ export interface Position {
/**
* Enum for bump rules to use for dealing with collisions.
*
* @alias Blockly.uiPosition.bumpDirection
* @internal
*/
@@ -68,13 +73,14 @@ export enum bumpDirection {
* element of the specified size given the restraints and locations of the
* scrollbars. This method does not take into account any already placed UI
* elements.
*
* @param position The starting horizontal and vertical position.
* @param size the size of the UI element to get a start position for.
* @param horizontalPadding The horizontal padding to use.
* @param verticalPadding The vertical padding to use.
* @param metrics The workspace UI metrics.
* @param workspace The workspace.
* @return The suggested start position.
* @returns The suggested start position.
* @alias Blockly.uiPosition.getStartPositionRect
* @internal
*/
@@ -118,9 +124,10 @@ export function getStartPositionRect(
* the toolbox.
* If in horizontal orientation, defaults to the bottom corner. If in vertical
* orientation, defaults to the right corner.
*
* @param workspace The workspace.
* @param metrics The workspace metrics.
* @return The suggested corner position.
* @returns The suggested corner position.
* @alias Blockly.uiPosition.getCornerOppositeToolbox
* @internal
*/
@@ -140,13 +147,14 @@ export function getCornerOppositeToolbox(
* Returns a position Rect based on a starting position that is bumped
* so that it doesn't intersect with any of the provided savedPositions. This
* method does not check that the bumped position is still within bounds.
*
* @param startRect The starting position to use.
* @param margin The margin to use between elements when bumping.
* @param bumpDir The direction to bump if there is a collision with an existing
* UI element.
* @param savedPositions List of rectangles that represent the positions of UI
* elements already placed.
* @return The suggested position rectangle.
* @returns The suggested position rectangle.
* @alias Blockly.uiPosition.bumpPositionRect
* @internal
*/

37
core/procedures.ts
View File

@@ -6,6 +6,7 @@
/**
* Utility functions for handling procedures.
*
* @namespace Blockly.Procedures
*/
import * as goog from '../closure/goog/goog.js';
@@ -37,18 +38,21 @@ import * as Xml from './xml.js';
* procedure blocks.
* See also Blockly.Variables.CATEGORY_NAME and
* Blockly.VariablesDynamic.CATEGORY_NAME.
*
* @alias Blockly.Procedures.CATEGORY_NAME
*/
export const CATEGORY_NAME = 'PROCEDURE';
/**
* The default argument for a procedures_mutatorarg block.
*
* @alias Blockly.Procedures.DEFAULT_ARG
*/
export const DEFAULT_ARG = 'x';
/**
* Procedure block type.
*
* @alias Blockly.Procedures.ProcedureBlock
*/
export interface ProcedureBlock {
@@ -59,8 +63,9 @@ export interface ProcedureBlock {
/**
* Find all user-created procedure definitions in a workspace.
*
* @param root Root workspace.
* @return Pair of arrays, the first contains procedures without return
* @returns Pair of arrays, the first contains procedures without return
* variables, the second with. Each procedure is defined by a three-element
* list of name, parameter list, and return value boolean.
* @alias Blockly.Procedures.allProcedures
@@ -83,9 +88,10 @@ export function allProcedures(root: Workspace): AnyDuringMigration[][][] {
/**
* Comparison function for case-insensitive sorting of the first element of
* a tuple.
*
* @param ta First tuple.
* @param tb Second tuple.
* @return -1, 0, or 1 to signify greater than, equality, or less than.
* @returns -1, 0, or 1 to signify greater than, equality, or less than.
*/
function procTupleComparator(
ta: AnyDuringMigration[], tb: AnyDuringMigration[]): number {
@@ -96,9 +102,10 @@ function procTupleComparator(
* Ensure two identically-named procedures don't exist.
* Take the proposed procedure name, and return a legal name i.e. one that
* is not empty and doesn't collide with other procedures.
*
* @param name Proposed procedure name.
* @param block Block to disambiguate.
* @return Non-colliding name.
* @returns Non-colliding name.
* @alias Blockly.Procedures.findLegalName
*/
export function findLegalName(name: string, block: Block): string {
@@ -121,11 +128,12 @@ export function findLegalName(name: string, block: Block): string {
/**
* Does this procedure have a legal name? Illegal names include names of
* procedures already defined.
*
* @param name The questionable name.
* @param workspace The workspace to scan for collisions.
* @param opt_exclude Optional block to exclude from comparisons (one doesn't
* want to collide with oneself).
* @return True if the name is legal.
* @returns True if the name is legal.
*/
function isLegalName(
name: string, workspace: Workspace, opt_exclude?: Block): boolean {
@@ -134,11 +142,12 @@ function isLegalName(
/**
* Return if the given name is already a procedure name.
*
* @param name The questionable name.
* @param workspace The workspace to scan for collisions.
* @param opt_exclude Optional block to exclude from comparisons (one doesn't
* want to collide with oneself).
* @return True if the name is used, otherwise return false.
* @returns True if the name is used, otherwise return false.
* @alias Blockly.Procedures.isNameUsed
*/
export function isNameUsed(
@@ -163,8 +172,10 @@ export function isNameUsed(
/**
* Rename a procedure. Called by the editable field.
*
* @param this
* @param name The proposed new name.
* @return The accepted name.
* @returns The accepted name.
* @alias Blockly.Procedures.rename
*/
export function rename(this: Field, name: string): string {
@@ -189,8 +200,9 @@ export function rename(this: Field, name: string): string {
/**
* Construct the blocks required by the flyout for the procedure category.
*
* @param workspace The workspace containing procedures.
* @return Array of XML block elements.
* @returns Array of XML block elements.
* @alias Blockly.Procedures.flyoutCategory
*/
export function flyoutCategory(workspace: WorkspaceSvg): Element[] {
@@ -245,6 +257,7 @@ export function flyoutCategory(workspace: WorkspaceSvg): Element[] {
/**
* Add items to xmlList for each listed procedure.
*
* @param procedureList A list of procedures, each of which is defined by a
* three-element list of name, parameter list, and return value boolean.
* @param templateName The type of the block to generate.
@@ -287,6 +300,7 @@ export function flyoutCategory(workspace: WorkspaceSvg): Element[] {
/**
* Updates the procedure mutator's flyout so that the arg block is not a
* duplicate of another arg.
*
* @param workspace The procedure mutator's workspace. This workspace's flyout
* is what is being updated.
*/
@@ -316,6 +330,7 @@ function updateMutatorFlyout(workspace: WorkspaceSvg) {
/**
* Listens for when a procedure mutator is opened. Then it triggers a flyout
* update and adds a mutator change listener to the mutator workspace.
*
* @param e The event that triggered this listener.
* @alias Blockly.Procedures.mutatorOpenListener
* @internal
@@ -343,6 +358,7 @@ export function mutatorOpenListener(e: Abstract) {
/**
* Listens for changes in a procedure mutator and triggers flyout updates when
* necessary.
*
* @param e The event that triggered this listener.
*/
function mutatorChangeListener(e: Abstract) {
@@ -358,9 +374,10 @@ function mutatorChangeListener(e: Abstract) {
/**
* Find all the callers of a named procedure.
*
* @param name Name of procedure.
* @param workspace The workspace to find callers in.
* @return Array of caller blocks.
* @returns Array of caller blocks.
* @alias Blockly.Procedures.getCallers
*/
export function getCallers(name: string, workspace: Workspace): Block[] {
@@ -384,6 +401,7 @@ export function getCallers(name: string, workspace: Workspace): Block[] {
/**
* When a procedure definition changes its parameters, find and edit all its
* callers.
*
* @param defBlock Procedure definition block.
* @alias Blockly.Procedures.mutateCallers
*/
@@ -415,9 +433,10 @@ export function mutateCallers(defBlock: Block) {
/**
* Find the definition block for the named procedure.
*
* @param name Name of procedure.
* @param workspace The workspace to search.
* @return The procedure definition block, or null not found.
* @returns The procedure definition block, or null not found.
* @alias Blockly.Procedures.getDefinition
*/
export function getDefinition(name: string, workspace: Workspace): Block|null {

27
core/registry.ts
View File

@@ -7,6 +7,7 @@
/**
* This file is a universal registry that provides generic methods
* for registering and unregistering different types of classes.
*
* @namespace Blockly.registry
*/
import * as goog from '../closure/goog/goog.js';
@@ -47,12 +48,14 @@ const nameMap: {[key: string]: {[key: string]: string}} = Object.create(null);
/**
* The string used to register the default class for a type of plugin.
*
* @alias Blockly.registry.DEFAULT
*/
export const DEFAULT = 'default';
/**
* A name with the type of the element stored in the generic.
*
* @alias Blockly.registry.Type
*/
export class Type<_T> {
@@ -61,7 +64,8 @@ export class Type<_T> {
/**
* Returns the name of the type.
* @return The name.
*
* @returns The name.
*/
toString(): string {
return this.name;
@@ -98,6 +102,7 @@ export class Type<_T> {
/**
* Registers a class based on a type and name.
*
* @param type The type of the plugin.
* (e.g. Field, Renderer)
* @param name The plugin's name. (Ex. field_angle, geras)
@@ -155,6 +160,7 @@ export function register<T>(
/**
* Checks the given registry item for properties that are required based on the
* type.
*
* @param type The type of the plugin. (e.g. Field, Renderer)
* @param registryItem A class or object that we are checking for the required
* properties.
@@ -171,6 +177,7 @@ function validate(type: string, registryItem: Function|AnyDuringMigration) {
/**
* Unregisters the registry item with the given type and name.
*
* @param type The type of the plugin.
* (e.g. Field, Renderer)
* @param name The plugin's name. (Ex. field_angle, geras)
@@ -193,12 +200,13 @@ export function unregister<T>(type: string|Type<T>, name: string) {
/**
* Gets the registry item for the given name and type. This can be either a
* class or an object.
*
* @param type The type of the plugin.
* (e.g. Field, Renderer)
* @param name The plugin's name. (Ex. field_angle, geras)
* @param opt_throwIfMissing Whether or not to throw an error if we are unable
* to find the plugin.
* @return The class or object with the given name and type or null if none
* @returns The class or object with the given name and type or null if none
* exists.
*/
function getItem<T>(
@@ -223,10 +231,11 @@ function getItem<T>(
/**
* Returns whether or not the registry contains an item with the given type and
* name.
*
* @param type The type of the plugin.
* (e.g. Field, Renderer)
* @param name The plugin's name. (Ex. field_angle, geras)
* @return True if the registry has an item with the given type and name, false
* @returns True if the registry has an item with the given type and name, false
* otherwise.
* @alias Blockly.registry.hasItem
*/
@@ -242,12 +251,13 @@ export function hasItem<T>(type: string|Type<T>, name: string): boolean {
/**
* Gets the class for the given name and type.
*
* @param type The type of the plugin.
* (e.g. Field, Renderer)
* @param name The plugin's name. (Ex. field_angle, geras)
* @param opt_throwIfMissing Whether or not to throw an error if we are unable
* to find the plugin.
* @return The class with the given name and type or null if none exists.
* @returns The class with the given name and type or null if none exists.
* @alias Blockly.registry.getClass
*/
export function getClass<T>(
@@ -260,12 +270,13 @@ export function getClass<T>(
/**
* Gets the object for the given name and type.
*
* @param type The type of the plugin.
* (e.g. Category)
* @param name The plugin's name. (Ex. logic_category)
* @param opt_throwIfMissing Whether or not to throw an error if we are unable
* to find the object.
* @return The object with the given name and type or null if none exists.
* @returns The object with the given name and type or null if none exists.
* @alias Blockly.registry.getObject
*/
export function getObject<T>(
@@ -275,12 +286,13 @@ export function getObject<T>(
/**
* Returns a map of items registered with the given type.
*
* @param type The type of the plugin. (e.g. Category)
* @param opt_cased Whether or not to return a map with cased keys (rather than
* caseless keys). False by default.
* @param opt_throwIfMissing Whether or not to throw an error if we are unable
* to find the object. False by default.
* @return A map of objects with the given type, or null if none exists.
* @returns A map of objects with the given type, or null if none exists.
* @alias Blockly.registry.getAllItems
*/
export function getAllItems<T>(
@@ -313,11 +325,12 @@ export function getAllItems<T>(
/**
* Gets the class from Blockly options for the given type.
* This is used for plugins that override a built in feature. (e.g. Toolbox)
*
* @param type The type of the plugin.
* @param options The option object to check for the given plugin.
* @param opt_throwIfMissing Whether or not to throw an error if we are unable
* to find the plugin.
* @return The class for the plugin.
* @returns The class for the plugin.
* @alias Blockly.registry.getClassFromOptions
*/
export function getClassFromOptions<T>(

35
core/rendered_connection.ts
View File

@@ -6,6 +6,7 @@
/**
* Components for creating connections between blocks.
*
* @class
*/
import * as goog from '../closure/goog/goog.js';
@@ -42,6 +43,7 @@ const BUMP_RANDOMNESS = 10;
/**
* Class for a connection between blocks that may be rendered on screen.
*
* @alias Blockly.RenderedConnection
*/
export class RenderedConnection extends Connection {
@@ -86,6 +88,7 @@ export class RenderedConnection extends Connection {
/**
* Dispose of this connection. Remove it from the database (if it is
* tracked) and call the super-function to deal with connected blocks.
*
* @internal
*/
override dispose() {
@@ -97,7 +100,8 @@ export class RenderedConnection extends Connection {
/**
* Get the source block for this connection.
* @return The source block.
*
* @returns The source block.
*/
override getSourceBlock(): BlockSvg {
return super.getSourceBlock() as BlockSvg;
@@ -105,7 +109,8 @@ export class RenderedConnection extends Connection {
/**
* 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.
*/
override targetBlock(): BlockSvg|null {
return super.targetBlock() as BlockSvg;
@@ -114,8 +119,9 @@ export class RenderedConnection extends Connection {
/**
* Returns the distance between this connection and another connection in
* workspace units.
*
* @param otherConnection The other connection to measure the distance to.
* @return The distance between connections, in workspace units.
* @returns The distance between connections, in workspace units.
*/
distanceFrom(otherConnection: Connection): number {
const xDiff = this.x - otherConnection.x;
@@ -126,6 +132,7 @@ export class RenderedConnection extends Connection {
/**
* Move the block(s) belonging to the connection to a point where they don't
* visually interfere with the specified connection.
*
* @param staticConnection The connection to move away from.
* @internal
*/
@@ -173,6 +180,7 @@ export class RenderedConnection extends Connection {
/**
* Change the connection's coordinates.
*
* @param x New absolute x coordinate, in workspace coordinates.
* @param y New absolute y coordinate, in workspace coordinates.
*/
@@ -190,6 +198,7 @@ export class RenderedConnection extends Connection {
/**
* Change the connection's coordinates.
*
* @param dx Change to x coordinate, in workspace units.
* @param dy Change to y coordinate, in workspace units.
*/
@@ -200,6 +209,7 @@ export class RenderedConnection extends Connection {
/**
* Move this connection to the location given by its offset within the block
* and the location of the block's top left corner.
*
* @param blockTL The location of the top left corner of the block, in
* workspace coordinates.
*/
@@ -210,6 +220,7 @@ export class RenderedConnection extends Connection {
/**
* Set the offset of this connection relative to the top left of its block.
*
* @param x The new relative x, in workspace units.
* @param y The new relative y, in workspace units.
*/
@@ -220,7 +231,8 @@ export class RenderedConnection extends Connection {
/**
* Get the offset of this connection relative to the top left of its block.
* @return The offset of the connection.
*
* @returns The offset of the connection.
* @internal
*/
getOffsetInBlock(): Coordinate {
@@ -229,6 +241,7 @@ export class RenderedConnection extends Connection {
/**
* Move the blocks on either side of this connection right next to each other.
*
* @internal
*/
tighten() {
@@ -251,10 +264,11 @@ export class RenderedConnection extends Connection {
/**
* Find the closest compatible connection to this connection.
* All parameters are in workspace units.
*
* @param maxLimit 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.
*/
closest(maxLimit: number, dxy: Coordinate):
@@ -311,6 +325,7 @@ export class RenderedConnection extends Connection {
/**
* Set whether this connections is tracked in the database or not.
*
* @param doTracking If true, start tracking. If false, stop tracking.
* @internal
*/
@@ -342,6 +357,7 @@ export class RenderedConnection extends Connection {
* collapsed.
*
* Also closes down-stream icons/bubbles.
*
* @internal
*/
stopTrackingAll() {
@@ -368,7 +384,8 @@ export class RenderedConnection extends Connection {
* Start tracking this connection, as well as all down-stream connections on
* any block attached to this connection. This happens when a block is
* expanded.
* @return List of blocks to render.
*
* @returns List of blocks to render.
*/
startTrackingAll(): Block[] {
this.setTracking(true);
@@ -410,6 +427,7 @@ export class RenderedConnection extends Connection {
* Behavior after a connection attempt fails.
* Bumps this connection away from the other connection. Called when an
* attempted connection fails.
*
* @param otherConnection Connection that this connection failed to connect
* to.
* @internal
@@ -430,6 +448,7 @@ export class RenderedConnection extends Connection {
/**
* Disconnect two blocks that are connected by this connection.
*
* @param parentBlock The superior block.
* @param childBlock The inferior block.
*/
@@ -472,9 +491,10 @@ export class RenderedConnection extends Connection {
/**
* Find all nearby compatible connections to this connection.
* Type checking does not apply, since this function is used for bumping.
*
* @param maxLimit The maximum radius to another connection, in workspace
* units.
* @return List of connections.
* @returns List of connections.
* @internal
*/
override neighbours(maxLimit: number): Connection[] {
@@ -484,6 +504,7 @@ export class RenderedConnection extends Connection {
/**
* Connect two connections together. This is the connection on the superior
* block. Rerender blocks as needed.
*
* @param childConnection Connection on inferior block.
*/
protected override connect_(childConnection: Connection) {

11
core/renderers/common/block_rendering.ts
View File

@@ -6,6 +6,7 @@
/**
* Namespace for block rendering functionality.
*
* @namespace Blockly.blockRendering
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -50,7 +51,8 @@ import {Renderer} from './renderer.js';
/**
* Returns whether the debugger is turned on.
* @return Whether the debugger is turned on.
*
* @returns Whether the debugger is turned on.
* @alias Blockly.blockRendering.isDebuggerEnabled
* @deprecated
* @internal
@@ -65,6 +67,7 @@ export function isDebuggerEnabled(): boolean {
/**
* Registers a new renderer.
*
* @param name The name of the renderer.
* @param rendererClass The new renderer class to register.
* @throws {Error} if a renderer with the same name has already been registered.
@@ -75,6 +78,7 @@ export function register(name: string, rendererClass: Function) {
/**
* Unregisters the renderer registered with the given name.
*
* @param name The name of the renderer.
* @alias Blockly.blockRendering.unregister
*/
@@ -84,6 +88,7 @@ export function unregister(name: string) {
/**
* Turn on the blocks debugger.
*
* @alias Blockly.blockRendering.startDebugger
* @deprecated
* @internal
@@ -98,6 +103,7 @@ export function startDebugger() {
/**
* Turn off the blocks debugger.
*
* @alias Blockly.blockRendering.stopDebugger
* @deprecated
* @internal
@@ -112,10 +118,11 @@ export function stopDebugger() {
/**
* Initialize anything needed for rendering (constants, etc).
*
* @param name Name of the renderer to initialize.
* @param theme The workspace theme object.
* @param opt_rendererOverrides Rendering constant overrides.
* @return The new instance of a renderer.
* @returns The new instance of a renderer.
* Already initialized.
* @alias Blockly.blockRendering.init
* @internal

70
core/renderers/common/constants.ts
View File

@@ -6,6 +6,7 @@
/**
* An object that provides constants for rendering blocks.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -108,6 +109,7 @@ export type Shape = BaseShape|DynamicShape;
/**
* An object that provides constants for rendering blocks.
*
* @alias Blockly.blockRendering.ConstantProvider
*/
export class ConstantProvider {
@@ -241,6 +243,7 @@ export class ConstantProvider {
/**
* The backing colour of a field's border rect.
*
* @internal
*/
FIELD_BORDER_RECT_COLOUR = '#fff';
@@ -294,6 +297,7 @@ export class ConstantProvider {
/**
* The ID of the emboss filter, or the empty string if no filter is set.
*
* @internal
*/
embossFilterId = '';
@@ -305,6 +309,7 @@ export class ConstantProvider {
/**
* The ID of the disabled pattern, or the empty string if no pattern is set.
*
* @internal
*/
disabledPatternId = '';
@@ -335,48 +340,56 @@ export class ConstantProvider {
/**
* Cursor colour.
*
* @internal
*/
CURSOR_COLOUR = '#cc0a0a';
/**
* Immovable marker colour.
*
* @internal
*/
MARKER_COLOUR = '#4286f4';
/**
* Width of the horizontal cursor.
*
* @internal
*/
CURSOR_WS_WIDTH = 100;
/**
* Height of the horizontal cursor.
*
* @internal
*/
WS_CURSOR_HEIGHT = 5;
/**
* Padding around a stack.
*
* @internal
*/
CURSOR_STACK_PADDING = 10;
/**
* Padding around a block.
*
* @internal
*/
CURSOR_BLOCK_PADDING = 2;
/**
* Stroke of the cursor.
*
* @internal
*/
CURSOR_STROKE_WIDTH = 4;
/**
* Whether text input and colour fields fill up the entire source block.
*
* @internal
*/
FULL_BLOCK_FIELDS = false;
@@ -384,12 +397,14 @@ export class ConstantProvider {
/**
* The main colour of insertion markers, in hex. The block is rendered a
* transparent grey by changing the fill opacity in CSS.
*
* @internal
*/
INSERTION_MARKER_COLOUR = '#000000';
/**
* The insertion marker opacity.
*
* @internal
*/
INSERTION_MARKER_OPACITY = 0.2;
@@ -489,6 +504,7 @@ export class ConstantProvider {
/**
* A random identifier used to ensure a unique ID is used for each
* filter/pattern for the case of multiple Blockly instances on a page.
*
* @internal
*/
this.randomIdentifier = String(Math.random()).substring(2);
@@ -496,6 +512,7 @@ export class ConstantProvider {
/**
* Initialize shape objects based on the constants set in the constructor.
*
* @internal
*/
init() {
@@ -529,6 +546,7 @@ export class ConstantProvider {
/**
* Refresh constants properties that depend on the theme.
*
* @param theme The current workspace theme.
* @internal
*/
@@ -546,6 +564,7 @@ export class ConstantProvider {
/**
* Sets dynamic properties that depend on other values or theme properties.
*
* @param theme The current workspace theme.
*/
protected setDynamicProperties_(theme: Theme) {
@@ -558,6 +577,7 @@ export class ConstantProvider {
/**
* Set constants related to fonts.
*
* @param theme The current workspace theme.
*/
protected setFontConstants_(theme: Theme) {
@@ -583,6 +603,7 @@ export class ConstantProvider {
/**
* Set constants from a theme's component styles.
*
* @param theme The current workspace theme.
*/
protected setComponentConstants_(theme: Theme) {
@@ -601,8 +622,9 @@ export class ConstantProvider {
/**
* Get or create a block style based on a single colour value. Generate a
* name for the style based on the colour.
*
* @param colour #RRGGBB colour string.
* @return An object containing the style and an autogenerated name for that
* @returns An object containing the style and an autogenerated name for that
* style.
* @internal
*/
@@ -616,8 +638,9 @@ export class ConstantProvider {
/**
* Gets the BlockStyle for the given block style name.
*
* @param blockStyleName The name of the block style.
* @return The named block style, or a default style if no style with the
* @returns The named block style, or a default style if no style with the
* given name was found.
*/
getBlockStyle(blockStyleName: string|null): BlockStyle {
@@ -629,8 +652,9 @@ export class ConstantProvider {
/**
* Create a block style object based on the given colour.
*
* @param colour #RRGGBB colour string.
* @return A populated block style based on the given colour.
* @returns A populated block style based on the given colour.
*/
protected createBlockStyle_(colour: string): BlockStyle {
return this.validatedBlockStyle_({'colourPrimary': colour});
@@ -639,8 +663,13 @@ export class ConstantProvider {
/**
* Get a full block style object based on the input style object. Populate
* any missing values.
*
* @param blockStyle A full or partial block style object.
* @return A full block style object, with all required properties populated.
* @param blockStyle.colourPrimary
* @param blockStyle.colourSecondary
* @param blockStyle.colourTertiary
* @param blockStyle.hat
* @returns A full block style object, with all required properties populated.
*/
protected validatedBlockStyle_(blockStyle: {
colourPrimary: string,
@@ -670,8 +699,9 @@ export class ConstantProvider {
/**
* Generate a secondary colour from the passed in primary colour.
*
* @param inputColour Primary colour.
* @return The generated secondary colour.
* @returns The generated secondary colour.
*/
protected generateSecondaryColour_(inputColour: string): string {
return colour.blend('#fff', inputColour, 0.6) || inputColour;
@@ -679,8 +709,9 @@ export class ConstantProvider {
/**
* Generate a tertiary colour from the passed in primary colour.
*
* @param inputColour Primary colour.
* @return The generated tertiary colour.
* @returns The generated tertiary colour.
*/
protected generateTertiaryColour_(inputColour: string): string {
return colour.blend('#fff', inputColour, 0.3) || inputColour;
@@ -689,6 +720,7 @@ export class ConstantProvider {
/**
* Dispose of this constants provider.
* Delete all DOM elements that this provider created.
*
* @internal
*/
dispose() {
@@ -707,7 +739,7 @@ export class ConstantProvider {
}
/**
* @return An object containing sizing and path information about collapsed
* @returns An object containing sizing and path information about collapsed
* block indicators.
* @internal
*/
@@ -724,7 +756,7 @@ export class ConstantProvider {
}
/**
* @return An object containing sizing and path information about start hats.
* @returns An object containing sizing and path information about start hats.
* @internal
*/
makeStartHat(): StartHat {
@@ -740,7 +772,7 @@ export class ConstantProvider {
}
/**
* @return An object containing sizing and path information about puzzle tabs.
* @returns An object containing sizing and path information about puzzle tabs.
* @internal
*/
makePuzzleTab(): PuzzleTab {
@@ -753,9 +785,10 @@ export class ConstantProvider {
* versions of the paths are the same, but the Y sign flips. Forward and
* back are the signs to use to move the cursor in the direction that the
* path is being drawn.
*
* @param up True if the path should be drawn from bottom to top, false
* otherwise.
* @return A path fragment describing a puzzle tab.
* @returns A path fragment describing a puzzle tab.
*/
function makeMainPath(up: boolean): string {
const forward = up ? -1 : 1;
@@ -796,7 +829,7 @@ export class ConstantProvider {
}
/**
* @return An object containing sizing and path information about notches.
* @returns An object containing sizing and path information about notches.
* @internal
*/
makeNotch(): Notch {
@@ -807,9 +840,10 @@ export class ConstantProvider {
/**
* Make the main path for the notch.
*
* @param dir Direction multiplier to apply to horizontal offsets along the
* path. Either 1 or -1.
* @return A path fragment describing a notch.
* @returns A path fragment describing a notch.
*/
function makeMainPath(dir: number): string {
return svgPaths.line([
@@ -831,7 +865,7 @@ export class ConstantProvider {
}
/**
* @return An object containing sizing and path information about inside
* @returns An object containing sizing and path information about inside
* corners.
* @internal
*/
@@ -853,7 +887,7 @@ export class ConstantProvider {
}
/**
* @return An object containing sizing and path information about outside
* @returns An object containing sizing and path information about outside
* corners.
* @internal
*/
@@ -887,8 +921,9 @@ export class ConstantProvider {
/**
* Get an object with connection shape and sizing information based on the
* type of the connection.
*
* @param connection The connection to find a shape object for
* @return The shape object for the connection.
* @returns The shape object for the connection.
* @internal
*/
shapeFor(connection: RenderedConnection): Shape {
@@ -906,6 +941,7 @@ export class ConstantProvider {
/**
* Create any DOM elements that this renderer needs (filters, patterns, etc).
*
* @param svg The root of the workspace's SVG.
* @param tagName The name to use for the CSS style tag.
* @param selector The CSS selector to use.
@@ -1056,6 +1092,7 @@ export class ConstantProvider {
/**
* Inject renderer specific CSS into the page.
*
* @param tagName The name of the style tag to use.
* @param selector The CSS selector to use.
*/
@@ -1080,8 +1117,9 @@ export class ConstantProvider {
/**
* Get any renderer specific CSS to inject when the renderer is initialized.
*
* @param selector CSS selector to use.
* @return Array of CSS strings.
* @returns Array of CSS strings.
*/
protected getCSS_(selector: string): string[] {
return [

6
core/renderers/common/debug.ts
View File

@@ -6,6 +6,7 @@
/**
* Block rendering debugging functionality.
*
* @namespace Blockly.blockRendering.debug
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -18,7 +19,8 @@ import * as deprecation from '../../utils/deprecation.js';
let useDebugger = false;
/**
* Returns whether the debugger is turned on.
* @return Whether the debugger is turned on.
*
* @returns Whether the debugger is turned on.
* @alias Blockly.blockRendering.debug.isDebuggerEnabled
* @internal
*/
@@ -28,6 +30,7 @@ export function isDebuggerEnabled(): boolean {
/**
* Turn on the blocks debugger.
*
* @alias Blockly.blockRendering.debug.startDebugger
* @deprecated March 2022. Use the rendering debugger in @blockly/dev-tools.
* See https://www.npmjs.com/package/@blockly/dev-tools for more information.
@@ -43,6 +46,7 @@ export function startDebugger() {
/**
* Turn off the blocks debugger.
*
* @alias Blockly.blockRendering.debug.stopDebugger
* @deprecated March 2022. Use the rendering debugger in @blockly/dev-tools.
* See https://www.npmjs.com/package/@blockly/dev-tools for more information.

13
core/renderers/common/debugger.ts
View File

@@ -6,6 +6,7 @@
/**
* Methods for rendering debug graphics.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -31,12 +32,14 @@ import type {RenderInfo} from './info.js';
/**
* An object that renders rectangles and dots for debugging rendering code.
*
* @alias Blockly.blockRendering.Debug
*/
export class Debug {
/**
* Configuration object containing booleans to enable and disable debug
* rendering of specific rendering components.
*
* @struct
*/
static config = {
@@ -71,6 +74,7 @@ export class Debug {
/**
* Remove all elements the this object created on the last pass.
*
* @internal
*/
clearElems() {
@@ -84,6 +88,7 @@ export class Debug {
/**
* Draw a debug rectangle for a spacer (empty) row.
*
* @param row The row to render.
* @param cursorY The y position of the top of the row.
* @param isRtl Whether the block is rendered RTL.
@@ -117,6 +122,7 @@ export class Debug {
/**
* Draw a debug rectangle for a horizontal spacer.
*
* @param elem The spacer to render.
* @param rowHeight The height of the container row.
* @param isRtl Whether the block is rendered RTL.
@@ -151,6 +157,7 @@ export class Debug {
/**
* Draw a debug rectangle for an in-row element.
*
* @param elem The element to render.
* @param isRtl Whether the block is rendered RTL.
* @internal
@@ -203,6 +210,7 @@ export class Debug {
* Draw a circle at the location of the given connection. Inputs and outputs
* share the same colours, as do previous and next. When positioned correctly
* a connected pair will look like a bullseye.
*
* @param conn The connection to circle.
* @suppress {visibility} Suppress visibility of conn.offsetInBlock_ since
* this is a debug module.
@@ -251,6 +259,7 @@ export class Debug {
/**
* Draw a debug rectangle for a non-empty row.
*
* @param row The non-empty row to render.
* @param cursorY The y position of the top of the row.
* @param isRtl Whether the block is rendered RTL.
@@ -298,6 +307,7 @@ export class Debug {
/**
* Draw debug rectangles for a non-empty row and all of its subcomponents.
*
* @param row The non-empty row to render.
* @param cursorY The y position of the top of the row.
* @param isRtl Whether the block is rendered RTL.
@@ -321,6 +331,7 @@ export class Debug {
/**
* Draw a debug rectangle around the entire block.
*
* @param info Rendering information about the block to debug.
* @internal
*/
@@ -366,6 +377,7 @@ export class Debug {
/**
* Do all of the work to draw debug information for the whole block.
*
* @param block The block to draw debug information for.
* @param info Rendering information about the block to debug.
* @internal
@@ -413,6 +425,7 @@ export class Debug {
/**
* Show a debug filter to highlight that a block has been rendered.
*
* @param svgPath The block's SVG path.
* @internal
*/

12
core/renderers/common/drawer.ts
View File

@@ -6,6 +6,7 @@
/**
* Methods for graphically rendering a block as SVG.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -29,6 +30,7 @@ import type {RenderInfo} from './info.js';
/**
* An object that draws a block based on the given rendering information.
*
* @alias Blockly.blockRendering.Drawer
*/
export class Drawer {
@@ -62,6 +64,7 @@ export class Drawer {
* joined with spaces and set directly on the block. This guarantees that
* the steps are separated by spaces for improved readability, but isn't
* required.
*
* @internal
*/
draw() {
@@ -151,6 +154,7 @@ export class Drawer {
/**
* Add steps for the jagged edge of a row on a collapsed block.
*
* @param row The row to draw the side of.
*/
protected drawJaggedEdge_(row: Row) {
@@ -162,6 +166,7 @@ export class Drawer {
/**
* Add steps for an external value input, rendered as a notch in the side
* of the block.
*
* @param row The row that this input belongs to.
*/
protected drawValueInput_(row: Row) {
@@ -185,6 +190,7 @@ export class Drawer {
/**
* Add steps for a statement input.
*
* @param row The row that this input belongs to.
*/
protected drawStatementInput_(row: Row) {
@@ -210,6 +216,7 @@ export class Drawer {
/**
* Add steps for the right side of a row that does not have value or
* statement input connections.
*
* @param row The row to draw the side of.
*/
protected drawRightSideRow_(row: Row) {
@@ -289,6 +296,7 @@ export class Drawer {
/**
* Push a field or icon's new position to its SVG root.
*
* @param fieldInfo The rendering information for the field or icon.
*/
protected layoutField_(fieldInfo: Icon|Field) {
@@ -336,6 +344,7 @@ export class Drawer {
/**
* Add steps for an inline input.
*
* @param input The information about the input to render.
*/
protected drawInlineInput_(input: InlineInput) {
@@ -361,6 +370,7 @@ export class Drawer {
* Position the connection on an inline value input, taking into account
* RTL and the small gap between the parent block and child block which lets
* the parent block's dark path show through.
*
* @param input The information about the input that the connection is on.
*/
protected positionInlineInputConnection_(input: InlineInput) {
@@ -381,6 +391,7 @@ export class Drawer {
* Position the connection on a statement input, taking into account
* RTL and the small gap between the parent block and child block which lets
* the parent block's dark path show through.
*
* @param row The row that the connection is on.
*/
protected positionStatementInputConnection_(row: Row) {
@@ -398,6 +409,7 @@ export class Drawer {
* Position the connection on an external value input, taking into account
* RTL and the small gap between the parent block and child block which lets
* the parent block's dark path show through.
*
* @param row The row that the connection is on.
*/
protected positionExternalValueConnection_(row: Row) {

15
core/renderers/common/i_path_object.ts
View File

@@ -7,6 +7,7 @@
/**
* The interface for an object that owns a block's rendering SVG
* elements.
*
* @namespace Blockly.blockRendering.IPathObject
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -29,6 +30,7 @@ import type {ConstantProvider} from './constants.js';
/**
* An interface for a block's path object.
*
* @param _root The root SVG element.
* @param _constants The renderer's constants.
* @alias Blockly.blockRendering.IPathObject
@@ -57,6 +59,7 @@ export interface IPathObject {
/**
* Set the path generated by the renderer onto the respective SVG element.
*
* @param pathString The path.
* @internal
*/
@@ -65,6 +68,7 @@ export interface IPathObject {
/**
* Apply the stored colours to the block's path, taking into account whether
* the paths belong to a shadow block.
*
* @param block The source block.
* @internal
*/
@@ -72,6 +76,7 @@ export interface IPathObject {
/**
* Update the style.
*
* @param blockStyle The block style to use.
* @internal
*/
@@ -79,12 +84,14 @@ export interface IPathObject {
/**
* Flip the SVG paths in RTL.
*
* @internal
*/
flipRTL: () => void;
/**
* 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
@@ -93,6 +100,7 @@ export interface IPathObject {
/**
* 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
@@ -102,6 +110,7 @@ export interface IPathObject {
/**
* Set whether the block shows a highlight or not. Block highlighting is
* often used to visually mark blocks currently being executed.
*
* @param highlighted True if highlighted.
* @internal
*/
@@ -109,6 +118,7 @@ export interface IPathObject {
/**
* Add or remove styling showing that a block is selected.
*
* @param enable True if selection is enabled, false otherwise.
* @internal
*/
@@ -116,6 +126,7 @@ export interface IPathObject {
/**
* Add or remove styling showing that a block is dragged over a delete area.
*
* @param enable True if the block is being dragged over a delete area, false
* otherwise.
* @internal
@@ -124,6 +135,7 @@ export interface IPathObject {
/**
* Add or remove styling showing that a block is an insertion marker.
*
* @param enable True if the block is an insertion marker, false otherwise.
* @internal
*/
@@ -131,6 +143,7 @@ export interface IPathObject {
/**
* Add or remove styling showing that a block is movable.
*
* @param enable True if the block is movable, false otherwise.
* @internal
*/
@@ -140,6 +153,7 @@ export interface IPathObject {
* Add or remove styling that shows that if the dragging block is dropped,
* this block will be replaced. If a shadow block, it will disappear.
* Otherwise it will bump.
*
* @param enable True if styling should be added.
* @internal
*/
@@ -148,6 +162,7 @@ export interface IPathObject {
/**
* Add or remove styling that shows that if the dragging block is dropped,
* this block will be connected to the input.
*
* @param conn The connection on the input to highlight.
* @param enable True if styling should be added.
* @internal

33
core/renderers/common/info.ts
View File

@@ -6,6 +6,7 @@
/**
* Methods for graphically rendering a block as SVG.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -46,6 +47,7 @@ import type {Renderer} from './renderer.js';
* This measure pass does not propagate changes to the block (although fields
* may choose to rerender when getSize() is called). However, calling it
* repeatedly may be expensive.
*
* @alias Blockly.blockRendering.RenderInfo
*/
export class RenderInfo {
@@ -145,7 +147,8 @@ export class RenderInfo {
/**
* Get the block renderer in use.
* @return The block renderer in use.
*
* @returns The block renderer in use.
* @internal
*/
getRenderer(): Renderer {
@@ -159,6 +162,7 @@ export class RenderInfo {
* This measure pass does not propagate changes to the block (although fields
* may choose to rerender when getSize() is called). However, calling it
* repeatedly may be expensive.
*
* @internal
*/
measure() {
@@ -227,6 +231,7 @@ export class RenderInfo {
/**
* Create all non-spacer elements that belong on the top row.
*
* @internal
*/
populateTopRow_() {
@@ -271,6 +276,7 @@ export class RenderInfo {
/**
* Create all non-spacer elements that belong on the bottom row.
*
* @internal
*/
populateBottomRow_() {
@@ -315,6 +321,7 @@ export class RenderInfo {
/**
* Add an input element to the active row, if needed, and record the type of
* the input on the row.
*
* @param input The input to record information about.
* @param activeRow The row that is currently being populated.
*/
@@ -346,9 +353,10 @@ export class RenderInfo {
/**
* Decide whether to start a new row between the two Blockly.Inputs.
*
* @param input The first input to consider
* @param lastInput The input that follows.
* @return True if the next input should be rendered on a new row.
* @returns True if the next input should be rendered on a new row.
*/
protected shouldStartNewRow_(input: Input, lastInput: Input): boolean {
// If this is the first input, just add to the existing row.
@@ -401,9 +409,10 @@ export class RenderInfo {
* Calculate the width of a spacer element in a row based on the previous and
* next elements in that row. For instance, extra padding is added between
* two editable fields.
*
* @param prev The element before the spacer.
* @param next The element after the spacer.
* @return The size of the spacing between the two elements.
* @returns The size of the spacing between the two elements.
*/
protected getInRowSpacing_(prev: Measurable|null, next: Measurable|null):
number {
@@ -509,8 +518,9 @@ export class RenderInfo {
/**
* Calculate the desired width of an input row.
*
* @param _row The input row.
* @return The desired width of the input row.
* @returns The desired width of the input row.
*/
protected getDesiredRowWidth_(_row: Row): number {
return this.width - this.startX;
@@ -520,6 +530,7 @@ export class RenderInfo {
* Modify the given row to add the given amount of padding around its fields.
* The exact location of the padding is based on the alignment property of the
* last input in the field.
*
* @param row The row to add padding to.
* @param missingSpace How much padding to add.
*/
@@ -551,6 +562,7 @@ export class RenderInfo {
/**
* Align the elements of a statement row based on computed bounds.
* Unlike other types of rows, statement rows add space in multiple places.
*
* @param row The statement row to resize.
*/
protected alignStatementRow_(row: InputRow) {
@@ -588,9 +600,10 @@ export class RenderInfo {
/**
* Create a spacer row to go between prev and next, and set its size.
*
* @param prev The previous row.
* @param next The next row.
* @return The newly created spacer row.
* @returns The newly created spacer row.
*/
protected makeSpacerRow_(prev: Row, next: Row): SpacerRow {
const height = this.getSpacerRowHeight_(prev, next);
@@ -607,9 +620,10 @@ export class RenderInfo {
/**
* Calculate the width of a spacer row.
*
* @param _prev The row before the spacer.
* @param _next The row after the spacer.
* @return The desired width of the spacer row between these two rows.
* @returns The desired width of the spacer row between these two rows.
*/
protected getSpacerRowWidth_(_prev: Row, _next: Row): number {
return this.width - this.startX;
@@ -617,9 +631,10 @@ export class RenderInfo {
/**
* Calculate the height of a spacer row.
*
* @param _prev The row before the spacer.
* @param _next The row after the spacer.
* @return The desired height of the spacer row between these two rows.
* @returns The desired height of the spacer row between these two rows.
*/
protected getSpacerRowHeight_(_prev: Row, _next: Row): number {
return this.constants_.MEDIUM_PADDING;
@@ -630,9 +645,10 @@ export class RenderInfo {
* This base implementation puts the centerline at the middle of the row
* vertically, with no special cases. You will likely need extra logic to
* handle (at minimum) top and bottom rows.
*
* @param row The row containing the element.
* @param elem The element to place.
* @return The desired centerline of the given element, as an offset from the
* @returns The desired centerline of the given element, as an offset from the
* top left of the block.
*/
protected getElemCenterline_(row: Row, elem: Measurable): number {
@@ -663,6 +679,7 @@ export class RenderInfo {
/**
* Record final position information on elements on the given row, for use in
* drawing. At minimum this records xPos and centerline on each element.
*
* @param row The row containing the elements.
*/
protected recordElemPositions_(row: Row) {

41
core/renderers/common/marker_svg.ts
View File

@@ -6,6 +6,7 @@
/**
* Methods for graphically rendering a marker as SVG.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -45,6 +46,7 @@ const HEIGHT_MULTIPLIER = 3 / 4;
/**
* Class for a marker.
*
* @alias Blockly.blockRendering.MarkerSvg
*/
export class MarkerSvg {
@@ -91,7 +93,8 @@ export class MarkerSvg {
/**
* Return the root node of the SVG or null if none exists.
* @return The root SVG node.
*
* @returns The root SVG node.
*/
getSvgRoot(): SVGElement {
// AnyDuringMigration because: Type 'SVGGElement | null' is not assignable
@@ -101,7 +104,8 @@ export class MarkerSvg {
/**
* Get the marker.
* @return The marker to draw for.
*
* @returns The marker to draw for.
*/
getMarker(): Marker {
return this.marker;
@@ -110,7 +114,8 @@ export class MarkerSvg {
/**
* True if the marker should be drawn as a cursor, false otherwise.
* A cursor is drawn as a flashing line. A marker is drawn as a solid line.
* @return True if the marker is a cursor, false otherwise.
*
* @returns True if the marker is a cursor, false otherwise.
*/
isCursor(): boolean {
return this.marker.type === 'cursor';
@@ -118,7 +123,8 @@ export class MarkerSvg {
/**
* Create the DOM element for the marker.
* @return The marker controls SVG group.
*
* @returns The marker controls SVG group.
* @internal
*/
createDom(): SVGElement {
@@ -132,6 +138,7 @@ export class MarkerSvg {
/**
* Attaches the SVG root of the marker to the SVG group of the parent.
*
* @param newParent The workspace, field, or block that the marker SVG element
* should be attached to.
*/
@@ -152,6 +159,7 @@ export class MarkerSvg {
/**
* Update the marker.
*
* @param oldNode The previous node the marker was on or null.
* @param curNode The node that we want to draw the marker for.
*/
@@ -181,6 +189,7 @@ export class MarkerSvg {
/**
* Update the marker's visible state based on the type of curNode..
*
* @param curNode The node that we want to draw the marker for.
*/
protected showAtLocation_(curNode: ASTNode) {
@@ -212,6 +221,7 @@ export class MarkerSvg {
/**
* Show the marker as a combination of the previous connection and block,
* the output connection and block, or just the block.
*
* @param curNode The node to draw the marker for.
*/
private showWithBlockPrevOutput_(curNode: ASTNode) {
@@ -240,6 +250,7 @@ export class MarkerSvg {
/**
* Position and display the marker for a block.
*
* @param curNode The node to draw the marker for.
*/
protected showWithBlock_(curNode: ASTNode) {
@@ -248,6 +259,7 @@ export class MarkerSvg {
/**
* Position and display the marker for a previous connection.
*
* @param curNode The node to draw the marker for.
*/
protected showWithPrevious_(curNode: ASTNode) {
@@ -256,6 +268,7 @@ export class MarkerSvg {
/**
* Position and display the marker for an output connection.
*
* @param curNode The node to draw the marker for.
*/
protected showWithOutput_(curNode: ASTNode) {
@@ -265,6 +278,7 @@ export class MarkerSvg {
/**
* Position and display the marker for a workspace coordinate.
* This is a horizontal line.
*
* @param curNode The node to draw the marker for.
*/
protected showWithCoordinates_(curNode: ASTNode) {
@@ -284,6 +298,7 @@ export class MarkerSvg {
/**
* Position and display the marker for a field.
* This is a box around the field.
*
* @param curNode The node to draw the marker for.
*/
protected showWithField_(curNode: ASTNode) {
@@ -299,6 +314,7 @@ export class MarkerSvg {
/**
* Position and display the marker for an input.
* This is a puzzle piece.
*
* @param curNode The node to draw the marker for.
*/
protected showWithInput_(curNode: ASTNode) {
@@ -313,6 +329,7 @@ export class MarkerSvg {
/**
* Position and display the marker for a next connection.
* This is a horizontal line.
*
* @param curNode The node to draw the marker for.
*/
protected showWithNext_(curNode: ASTNode) {
@@ -332,6 +349,7 @@ export class MarkerSvg {
/**
* Position and display the marker for a stack.
* This is a box with extra padding around the entire stack of blocks.
*
* @param curNode The node to draw the marker for.
*/
protected showWithStack_(curNode: ASTNode) {
@@ -376,6 +394,7 @@ export class MarkerSvg {
/**
* Position the marker for a block.
* Displays an outline of the top half of a rectangle around a block.
*
* @param width The width of the block.
* @param markerOffset The extra padding for around the block.
* @param markerHeight The height of the marker.
@@ -398,6 +417,7 @@ export class MarkerSvg {
/**
* Position the marker for an input connection.
* Displays a filled in puzzle piece.
*
* @param connection The connection to position marker around.
*/
protected positionInput_(connection: RenderedConnection) {
@@ -418,6 +438,7 @@ export class MarkerSvg {
/**
* Move and show the marker at the specified coordinate in workspace units.
* Displays a horizontal line.
*
* @param x The new x, in workspace units.
* @param y The new y, in workspace units.
* @param width The new width, in workspace units.
@@ -438,6 +459,7 @@ export class MarkerSvg {
/**
* Position the marker for an output connection.
* Displays a puzzle outline and the top and bottom path.
*
* @param width The width of the block.
* @param height The height of the block.
* @param connectionShape The shape object for the connection.
@@ -464,6 +486,7 @@ export class MarkerSvg {
* Position the marker for a previous connection.
* Displays a half rectangle with a notch in the top to represent the previous
* connection.
*
* @param width The width of the block.
* @param markerOffset The offset of the marker from around the block.
* @param markerHeight The height of the marker.
@@ -492,6 +515,7 @@ export class MarkerSvg {
/**
* Move and show the marker at the specified coordinate in workspace units.
* Displays a filled in rectangle.
*
* @param x The new x, in workspace units.
* @param y The new y, in workspace units.
* @param width The new width, in workspace units.
@@ -515,6 +539,7 @@ export class MarkerSvg {
/**
* Flip the SVG paths in RTL.
*
* @param markerSvg The marker that we want to flip.
*/
private flipRtl_(markerSvg: SVGElement) {
@@ -531,6 +556,7 @@ export class MarkerSvg {
/**
* Fire event for the marker or marker.
*
* @param oldNode The old node the marker used to be on.
* @param curNode The new node the marker is currently on.
*/
@@ -543,7 +569,8 @@ export class MarkerSvg {
/**
* Get the properties to make a marker blink.
* @return The object holding attributes to make the marker blink.
*
* @returns The object holding attributes to make the marker blink.
*/
protected getBlinkProperties_(): AnyDuringMigration {
return {
@@ -557,7 +584,8 @@ export class MarkerSvg {
/**
* Create the marker SVG.
* @return The SVG node created.
*
* @returns The SVG node created.
*/
protected createDomInternal_(): Element {
/* This markup will be generated and added to the .svgGroup_:
@@ -651,6 +679,7 @@ export class MarkerSvg {
/**
* Apply the marker's colour.
*
* @param _curNode The node that we want to draw the marker for.
*/
protected applyColour_(_curNode: ASTNode) {

20
core/renderers/common/path_object.ts
View File

@@ -6,6 +6,7 @@
/**
* An object that owns a block's rendering SVG elements.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -28,6 +29,7 @@ import type {IPathObject} from './i_path_object.js';
/**
* An object that handles creating and setting each of the SVG elements
* used by the renderer.
*
* @alias Blockly.blockRendering.PathObject
*/
export class PathObject implements IPathObject {
@@ -38,6 +40,7 @@ export class PathObject implements IPathObject {
/**
* Holds the cursors svg element when the cursor is attached to the block.
* This is null if there is no cursor on the block.
*
* @internal
*/
// AnyDuringMigration because: Type 'null' is not assignable to type
@@ -47,6 +50,7 @@ export class PathObject implements IPathObject {
/**
* Holds the markers svg element when the marker is attached to the block.
* This is null if there is no marker on the block.
*
* @internal
*/
// AnyDuringMigration because: Type 'null' is not assignable to type
@@ -77,6 +81,7 @@ export class PathObject implements IPathObject {
/**
* Set the path generated by the renderer onto the respective SVG element.
*
* @param pathString The path.
* @internal
*/
@@ -86,6 +91,7 @@ export class PathObject implements IPathObject {
/**
* Flip the SVG paths in RTL.
*
* @internal
*/
flipRTL() {
@@ -95,6 +101,7 @@ export class PathObject implements IPathObject {
/**
* 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
@@ -113,6 +120,7 @@ export class PathObject implements IPathObject {
/**
* 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
@@ -136,6 +144,7 @@ export class PathObject implements IPathObject {
/**
* Apply the stored colours to the block's path, taking into account whether
* the paths belong to a shadow block.
*
* @param block The source block.
* @internal
*/
@@ -149,6 +158,7 @@ export class PathObject implements IPathObject {
/**
* Set the style.
*
* @param blockStyle The block style to use.
* @internal
*/
@@ -158,6 +168,7 @@ export class PathObject implements IPathObject {
/**
* Add or remove the given CSS class on the path object's root SVG element.
*
* @param className The name of the class to add or remove
* @param add True if the class should be added. False if it should be
* removed.
@@ -173,6 +184,7 @@ export class PathObject implements IPathObject {
/**
* Set whether the block shows a highlight or not. Block highlighting is
* often used to visually mark blocks currently being executed.
*
* @param enable True if highlighted.
* @internal
*/
@@ -187,6 +199,7 @@ export class PathObject implements IPathObject {
/**
* Updates the look of the block to reflect a shadow state.
*
* @param shadow True if the block is a shadow block.
*/
protected updateShadow_(shadow: boolean) {
@@ -198,6 +211,7 @@ export class PathObject implements IPathObject {
/**
* Updates the look of the block to reflect a disabled state.
*
* @param disabled True if disabled.
*/
protected updateDisabled_(disabled: boolean) {
@@ -210,6 +224,7 @@ export class PathObject implements IPathObject {
/**
* Add or remove styling showing that a block is selected.
*
* @param enable True if selection is enabled, false otherwise.
* @internal
*/
@@ -219,6 +234,7 @@ export class PathObject implements IPathObject {
/**
* Add or remove styling showing that a block is dragged over a delete area.
*
* @param enable True if the block is being dragged over a delete area, false
* otherwise.
* @internal
@@ -229,6 +245,7 @@ export class PathObject implements IPathObject {
/**
* Add or remove styling showing that a block is an insertion marker.
*
* @param enable True if the block is an insertion marker, false otherwise.
* @internal
*/
@@ -238,6 +255,7 @@ export class PathObject implements IPathObject {
/**
* Add or remove styling showing that a block is movable.
*
* @param enable True if the block is movable, false otherwise.
* @internal
*/
@@ -249,6 +267,7 @@ export class PathObject implements IPathObject {
* Add or remove styling that shows that if the dragging block is dropped,
* this block will be replaced. If a shadow block, it will disappear.
* Otherwise it will bump.
*
* @param enable True if styling should be added.
* @internal
*/
@@ -259,6 +278,7 @@ export class PathObject implements IPathObject {
/**
* Add or remove styling that shows that if the dragging block is dropped,
* this block will be connected to the input.
*
* @param _conn The connection on the input to highlight.
* @param _enable True if styling should be added.
* @internal

41
core/renderers/common/renderer.ts
View File

@@ -6,6 +6,7 @@
/**
* Base renderer.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -34,6 +35,7 @@ import {PathObject} from './path_object.js';
/**
* The base class for a block renderer.
*
* @alias Blockly.blockRendering.Renderer
*/
export class Renderer implements IRegistrable {
@@ -45,6 +47,7 @@ export class Renderer implements IRegistrable {
/**
* Rendering constant overrides, passed in through options.
*
* @internal
*/
overrides: object|null = null;
@@ -59,7 +62,8 @@ export class Renderer implements IRegistrable {
/**
* Gets the class name that identifies this renderer.
* @return The CSS class name.
*
* @returns The CSS class name.
* @internal
*/
getClassName(): string {
@@ -68,6 +72,7 @@ export class Renderer implements IRegistrable {
/**
* Initialize the renderer.
*
* @param theme The workspace theme object.
* @param opt_rendererOverrides Rendering constant overrides.
* @internal
@@ -84,6 +89,7 @@ export class Renderer implements IRegistrable {
/**
* Create any DOM elements that this renderer needs.
*
* @param svg The root of the workspace's SVG.
* @param theme The workspace theme object.
* @internal
@@ -96,6 +102,7 @@ export class Renderer implements IRegistrable {
/**
* Refresh the renderer after a theme change.
*
* @param svg The root of the workspace's SVG.
* @param theme The workspace theme object.
* @internal
@@ -117,6 +124,7 @@ export class Renderer implements IRegistrable {
/**
* Dispose of this renderer.
* Delete all DOM elements that this renderer and its constants created.
*
* @internal
*/
dispose() {
@@ -127,7 +135,8 @@ export class Renderer implements IRegistrable {
/**
* Create a new instance of the renderer's constant provider.
* @return The constant provider.
*
* @returns The constant provider.
*/
protected makeConstants_(): ConstantProvider {
return new ConstantProvider();
@@ -135,8 +144,9 @@ export class Renderer implements IRegistrable {
/**
* Create a new instance of the renderer's render info object.
*
* @param block The block to measure.
* @return The render info object.
* @returns The render info object.
*/
protected makeRenderInfo_(block: BlockSvg): RenderInfo {
return new RenderInfo(this, block);
@@ -144,10 +154,11 @@ export class Renderer implements IRegistrable {
/**
* Create a new instance of the renderer's drawer.
*
* @param block The block to render.
* @param info An object containing all information needed to render this
* block.
* @return The drawer.
* @returns The drawer.
*/
protected makeDrawer_(block: BlockSvg, info: RenderInfo): Drawer {
return new Drawer(block, info);
@@ -155,7 +166,8 @@ export class Renderer implements IRegistrable {
/**
* Create a new instance of the renderer's debugger.
* @return The renderer debugger.
*
* @returns The renderer debugger.
* @suppress {strictModuleDepCheck} Debug renderer only included in
* playground.
*/
@@ -165,9 +177,10 @@ export class Renderer implements IRegistrable {
/**
* Create a new instance of the renderer's marker drawer.
*
* @param workspace The workspace the marker belongs to.
* @param marker The marker.
* @return The object in charge of drawing the marker.
* @returns The object in charge of drawing the marker.
* @internal
*/
makeMarkerDrawer(workspace: WorkspaceSvg, marker: Marker): MarkerSvg {
@@ -176,9 +189,10 @@ export class Renderer implements IRegistrable {
/**
* Create a new instance of a renderer path object.
*
* @param root The root SVG element.
* @param style The style object to use for colouring.
* @return The renderer path object.
* @returns The renderer path object.
* @internal
*/
makePathObject(root: SVGElement, style: BlockStyle): IPathObject {
@@ -188,7 +202,8 @@ export class Renderer implements IRegistrable {
/**
* Get the current renderer's constant provider. We assume that when this is
* called, the renderer has already been initialized.
* @return The constant provider.
*
* @returns The constant provider.
* @internal
*/
getConstants(): ConstantProvider {
@@ -197,8 +212,9 @@ export class Renderer implements IRegistrable {
/**
* Determine whether or not to highlight a connection.
*
* @param _conn The connection to determine whether or not to highlight.
* @return True if we should highlight the connection.
* @returns True if we should highlight the connection.
* @internal
*/
shouldHighlightConnection(_conn: Connection): boolean {
@@ -210,11 +226,12 @@ export class Renderer implements IRegistrable {
* block-clump. If the clump is a row the end is the last input. If the clump
* is a stack, the end is the last next connection. If the clump is neither,
* then this returns false.
*
* @param topBlock The top block of the block clump we want to try and connect
* to.
* @param orphanBlock The orphan block that wants to find a home.
* @param localType The type of the connection being dragged.
* @return Whether there is a home for the orphan or not.
* @returns Whether there is a home for the orphan or not.
* @internal
*/
orphanCanConnectAtEnd(
@@ -229,10 +246,11 @@ export class Renderer implements IRegistrable {
/**
* Chooses a connection preview method based on the available connection, the
* current dragged connection, and the block being dragged.
*
* @param closest The available connection.
* @param local The connection currently being dragged.
* @param topBlock The block currently being dragged.
* @return The preview type to display.
* @returns The preview type to display.
* @internal
*/
getConnectionPreviewMethod(
@@ -253,6 +271,7 @@ export class Renderer implements IRegistrable {
/**
* Render the block.
*
* @param block The block to render.
* @internal
*/

2
core/renderers/geras/constants.ts
View File

@@ -7,6 +7,7 @@
/**
* An object that provides constants for rendering blocks in Geras
* mode.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -17,6 +18,7 @@ import {ConstantProvider as BaseConstantProvider} from '../common/constants.js';
/**
* An object that provides constants for rendering blocks in Geras mode.
*
* @alias Blockly.geras.ConstantProvider
*/
export class ConstantProvider extends BaseConstantProvider {

2
core/renderers/geras/drawer.ts
View File

@@ -6,6 +6,7 @@
/**
* Renderer that preserves the look and feel of Blockly pre-2019.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -26,6 +27,7 @@ import type {PathObject} from './path_object.js';
/**
* An object that draws a block based on the given rendering information.
*
* @alias Blockly.geras.Drawer
*/
export class Drawer extends BaseDrawer {

3
core/renderers/geras/geras.ts
View File

@@ -1,4 +1,4 @@
/** @fileoverview Re-exports of Blockly.geras.* modules. */
/** @file Re-exports of Blockly.geras.* modules. */
/**
* @license
@@ -8,6 +8,7 @@
/**
* Re-exports of Blockly.geras.* modules.
*
* @namespace Blockly.geras
*/
import * as goog from '../../../closure/goog/goog.js';

16
core/renderers/geras/highlight_constants.ts
View File

@@ -6,6 +6,7 @@
/**
* Objects for rendering highlights on blocks.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -63,6 +64,7 @@ export interface JaggedTeeth {
* Some highlights are simple offsets of the parent paths and can be generated
* programmatically. Others, especially on curves, are just made out of piles
* of constants and are hard to tweak.
*
* @alias Blockly.geras.HighlightConstantProvider
*/
export class HighlightConstantProvider {
@@ -94,6 +96,7 @@ export class HighlightConstantProvider {
/**
* The start point, which is offset in both X and Y, as an SVG path chunk.
*
* @internal
*/
this.START_POINT = svgPaths.moveBy(this.OFFSET, this.OFFSET);
@@ -101,6 +104,7 @@ export class HighlightConstantProvider {
/**
* Initialize shape objects based on the constants set in the constructor.
*
* @internal
*/
init() {
@@ -141,7 +145,7 @@ export class HighlightConstantProvider {
}
/**
* @return An object containing sizing and path information about inside
* @returns An object containing sizing and path information about inside
* corner highlights.
* @internal
*/
@@ -185,7 +189,7 @@ export class HighlightConstantProvider {
}
/**
* @return An object containing sizing and path information about outside
* @returns An object containing sizing and path information about outside
* corner highlights.
* @internal
*/
@@ -234,7 +238,7 @@ export class HighlightConstantProvider {
}
/**
* @return An object containing sizing and path information about puzzle tab
* @returns An object containing sizing and path information about puzzle tab
* highlights.
* @internal
*/
@@ -284,7 +288,7 @@ export class HighlightConstantProvider {
}
/**
* @return An object containing sizing and path information about notch
* @returns An object containing sizing and path information about notch
* highlights.
* @internal
*/
@@ -296,7 +300,7 @@ export class HighlightConstantProvider {
}
/**
* @return An object containing sizing and path information about collapsed
* @returns An object containing sizing and path information about collapsed
* block edge highlights.
* @internal
*/
@@ -307,7 +311,7 @@ export class HighlightConstantProvider {
}
/**
* @return An object containing sizing and path information about start
* @returns An object containing sizing and path information about start
* highlights.
* @internal
*/

13
core/renderers/geras/highlighter.ts
View File

@@ -7,6 +7,7 @@
/**
* Methods for adding highlights on block, for rendering in
* compatibility mode.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -39,6 +40,7 @@ import type {InlineInput} from './measurables/inline_input.js';
* position of each part of the block. The resulting paths are not continuous
* or closed paths. The highlights for tabs and notches are loosely based on
* tab and notch shapes, but are not exactly the same.
*
* @alias Blockly.geras.Highlighter
*/
export class Highlighter {
@@ -85,7 +87,8 @@ export class Highlighter {
/**
* Get the steps for the highlight path.
* @return The steps for the highlight path.
*
* @returns The steps for the highlight path.
* @internal
*/
getPath(): string {
@@ -94,6 +97,7 @@ export class Highlighter {
/**
* Add a highlight to the top corner of a block.
*
* @param row The top row of the block.
* @internal
*/
@@ -124,6 +128,7 @@ export class Highlighter {
/**
* Add a highlight on a jagged edge for a collapsed block.
*
* @param row The row to highlight.
* @internal
*/
@@ -138,6 +143,7 @@ export class Highlighter {
/**
* Add a highlight on a value input.
*
* @param row The row the input belongs to.
* @internal
*/
@@ -159,6 +165,7 @@ export class Highlighter {
/**
* Add a highlight on a statement input.
*
* @param row The row to highlight.
* @internal
*/
@@ -182,6 +189,7 @@ export class Highlighter {
/**
* Add a highlight on the right side of a row.
*
* @param row The row to highlight.
* @internal
*/
@@ -201,6 +209,7 @@ export class Highlighter {
/**
* Add a highlight to the bottom row.
*
* @param row The row to highlight.
* @internal
*/
@@ -225,6 +234,7 @@ export class Highlighter {
/**
* Draw the highlight on the left side of the block.
*
* @internal
*/
drawLeft() {
@@ -258,6 +268,7 @@ export class Highlighter {
/**
* Add a highlight to an inline input.
*
* @param input The input to highlight.
* @internal
*/

5
core/renderers/geras/info.ts
View File

@@ -7,6 +7,7 @@
/**
* Old (compatibility) renderer.
* Geras: spirit of old age.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -38,6 +39,7 @@ import type {Renderer} from './renderer.js';
* This measure pass does not propagate changes to the block (although fields
* may choose to rerender when getSize() is called). However, calling it
* repeatedly may be expensive.
*
* @alias Blockly.geras.RenderInfo
*/
export class RenderInfo extends BaseRenderInfo {
@@ -58,7 +60,8 @@ export class RenderInfo extends BaseRenderInfo {
/**
* Get the block renderer in use.
* @return The block renderer in use.
*
* @returns The block renderer in use.
* @internal
*/
override getRenderer(): Renderer {

2
core/renderers/geras/measurables/inline_input.ts
View File

@@ -7,6 +7,7 @@
/**
* Objects representing inline inputs with connections on a
* rendered block.
*
* @class
*/
import * as goog from '../../../../closure/goog/goog.js';
@@ -22,6 +23,7 @@ import type {ConstantProvider as GerasConstantProvider} from '../constants.js';
/**
* An object containing information about the space an inline input takes up
* during rendering.
*
* @alias Blockly.geras.InlineInput
*/
export class InlineInput extends BaseInlineInput {

2
core/renderers/geras/measurables/statement_input.ts
View File

@@ -7,6 +7,7 @@
/**
* Objects representing statement inputs with connections on a
* rendered block.
*
* @class
*/
import * as goog from '../../../../closure/goog/goog.js';
@@ -22,6 +23,7 @@ import type {ConstantProvider as GerasConstantProvider} from '../constants.js';
/**
* An object containing information about the space a statement input takes up
* during rendering.
*
* @alias Blockly.geras.StatementInput
*/
export class StatementInput extends BaseStatementInput {

4
core/renderers/geras/path_object.ts
View File

@@ -6,6 +6,7 @@
/**
* An object that owns a block's rendering SVG elements.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -28,6 +29,7 @@ import type {ConstantProvider} from './constants.js';
/**
* An object that handles creating and setting each of the SVG elements
* used by the renderer.
*
* @alias Blockly.geras.PathObject
*/
export class PathObject extends BasePathObject {
@@ -38,6 +40,7 @@ export class PathObject extends BasePathObject {
/**
* The colour of the dark path on the block in '#RRGGBB' format.
*
* @internal
*/
colourDark = '#000000';
@@ -74,6 +77,7 @@ export class PathObject extends BasePathObject {
/**
* Set the highlight path generated by the renderer onto the SVG element.
*
* @param highlightPath The highlight path.
* @internal
*/

20
core/renderers/geras/renderer.ts
View File

@@ -6,6 +6,7 @@
/**
* Geras renderer.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -30,6 +31,7 @@ import {PathObject} from './path_object.js';
/**
* The geras renderer.
*
* @alias Blockly.geras.Renderer
*/
export class Renderer extends BaseRenderer {
@@ -50,6 +52,9 @@ export class Renderer extends BaseRenderer {
/**
* Initialize the renderer. Geras has a highlight provider in addition to
* the normal constant provider.
*
* @param theme
* @param opt_rendererOverrides
* @internal
*/
override init(theme: Theme, opt_rendererOverrides: AnyDuringMigration) {
@@ -69,8 +74,9 @@ export class Renderer extends BaseRenderer {
/**
* Create a new instance of the renderer's render info object.
*
* @param block The block to measure.
* @return The render info object.
* @returns The render info object.
*/
protected override makeRenderInfo_(block: BlockSvg): RenderInfo {
return new RenderInfo(this, block);
@@ -78,10 +84,11 @@ export class Renderer extends BaseRenderer {
/**
* Create a new instance of the renderer's drawer.
*
* @param block The block to render.
* @param info An object containing all information needed to render this
* block.
* @return The drawer.
* @returns The drawer.
*/
protected override makeDrawer_(block: BlockSvg, info: BaseRenderInfo):
Drawer {
@@ -90,9 +97,10 @@ export class Renderer extends BaseRenderer {
/**
* Create a new instance of a renderer path object.
*
* @param root The root SVG element.
* @param style The style object to use for colouring.
* @return The renderer path object.
* @returns The renderer path object.
* @internal
*/
override makePathObject(root: SVGElement, style: BlockStyle): PathObject {
@@ -102,7 +110,8 @@ export class Renderer extends BaseRenderer {
/**
* Create a new instance of the renderer's highlight constant provider.
* @return The highlight constant provider.
*
* @returns The highlight constant provider.
*/
protected makeHighlightConstants_(): HighlightConstantProvider {
return new HighlightConstantProvider((this.getConstants()));
@@ -111,7 +120,8 @@ export class Renderer extends BaseRenderer {
/**
* Get the renderer's highlight constant provider. We assume that when this
* is called, the renderer has already been initialized.
* @return The highlight constant provider.
*
* @returns The highlight constant provider.
* @internal
*/
getHighlightConstants(): HighlightConstantProvider {

2
core/renderers/measurables/base.ts
View File

@@ -6,6 +6,7 @@
/**
* Methods for graphically rendering a block as SVG.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -20,6 +21,7 @@ import {Types} from './types.js';
* The base class to represent a part of a block that takes up space during
* rendering. The constructor for each non-spacer Measurable records the size
* of the block element (e.g. field, statement input).
*
* @alias Blockly.blockRendering.Measurable
*/
export class Measurable {

11
core/renderers/measurables/bottom_row.ts
View File

@@ -7,6 +7,7 @@
/**
* Object representing a bottom row on a rendered block.
* of its subcomponents.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -25,18 +26,21 @@ import {Types} from './types.js';
* a block as well as spacing information for the bottom row.
* Elements in a bottom row can consist of corners, spacers and next
* connections.
*
* @struct
* @alias Blockly.blockRendering.BottomRow
*/
export class BottomRow extends Row {
/**
* Whether this row has a next connection.
*
* @internal
*/
hasNextConnection = false;
/**
* The next connection on the row, if any.
*
* @internal
*/
connection: NextConnection|null = null;
@@ -45,6 +49,7 @@ export class BottomRow extends Row {
* The amount that the bottom of the block extends below the horizontal
* edge, e.g. because of a next connection. Must be non-negative (see
* #2820).
*
* @internal
*/
descenderHeight = 0;
@@ -66,8 +71,9 @@ export class BottomRow extends Row {
/**
* Returns whether or not the bottom row has a left square corner.
*
* @param block The block whose bottom row this represents.
* @return Whether or not the bottom row has a left square corner.
* @returns Whether or not the bottom row has a left square corner.
*/
hasLeftSquareCorner(block: BlockSvg): boolean {
return !!block.outputConnection || !!block.getNextBlock();
@@ -75,8 +81,9 @@ export class BottomRow extends Row {
/**
* Returns whether or not the bottom row has a right square corner.
*
* @param _block The block whose bottom row this represents.
* @return Whether or not the bottom row has a right square corner.
* @returns Whether or not the bottom row has a right square corner.
*/
hasRightSquareCorner(_block: BlockSvg): boolean {
return true;

2
core/renderers/measurables/connection.ts
View File

@@ -7,6 +7,7 @@
/**
* Base class representing the space a connection takes up during
* rendering.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -23,6 +24,7 @@ import {Types} from './types.js';
/**
* The base class to represent a connection and the space that it takes up on
* the block.
*
* @alias Blockly.blockRendering.Connection
*/
export class Connection extends Measurable {

2
core/renderers/measurables/external_value_input.ts
View File

@@ -7,6 +7,7 @@
/**
* Class representing external value inputs with connections on a
* rendered block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -23,6 +24,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space an external value input
* takes up during rendering
*
* @struct
* @alias Blockly.blockRendering.ExternalValueInput
*/

2
core/renderers/measurables/field.ts
View File

@@ -7,6 +7,7 @@
/**
* Objects representing a field in a row of a rendered
* block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -24,6 +25,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space a field takes up during
* rendering
*
* @struct
* @alias Blockly.blockRendering.Field
*/

2
core/renderers/measurables/hat.ts
View File

@@ -7,6 +7,7 @@
/**
* Objects representing a hat in a row of a rendered
* block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -21,6 +22,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space a hat takes up during
* rendering.
*
* @struct
* @alias Blockly.blockRendering.Hat
*/

3
core/renderers/measurables/icon.ts
View File

@@ -7,6 +7,7 @@
/**
* Objects representing an icon in a row of a rendered
* block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -23,6 +24,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space an icon takes up during
* rendering
*
* @struct
* @alias Blockly.blockRendering.Icon
*/
@@ -32,6 +34,7 @@ export class Icon extends Measurable {
/**
* An object containing information about the space an icon takes up during
* rendering
*
* @param constants The rendering constants provider.
* @param icon The icon to measure and store information for.
* @internal

2
core/renderers/measurables/in_row_spacer.ts
View File

@@ -7,6 +7,7 @@
/**
* Objects representing a spacer in a row of a rendered
* block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -21,6 +22,7 @@ import {Types} from './types.js';
/**
* An object containing information about a spacer between two elements on a
* row.
*
* @struct
* @alias Blockly.blockRendering.InRowSpacer
*/

2
core/renderers/measurables/inline_input.ts
View File

@@ -7,6 +7,7 @@
/**
* Class representing inline inputs with connections on a rendered
* block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -23,6 +24,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space an inline input takes up
* during rendering
*
* @struct
* @alias Blockly.blockRendering.InlineInput
*/

2
core/renderers/measurables/input_connection.ts
View File

@@ -6,6 +6,7 @@
/**
* Class representing inputs with connections on a rendered block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -23,6 +24,7 @@ import {Types} from './types.js';
/**
* The base class to represent an input that takes up space on a block
* during rendering
*
* @alias Blockly.blockRendering.InputConnection
*/
export class InputConnection extends Connection {

4
core/renderers/measurables/input_row.ts
View File

@@ -7,6 +7,7 @@
/**
* Object representing a row that holds one or more inputs on a
* rendered block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -23,12 +24,14 @@ import {Types} from './types.js';
/**
* An object containing information about a row that holds one or more inputs.
*
* @struct
* @alias Blockly.blockRendering.InputRow
*/
export class InputRow extends Row {
/**
* The total width of all blocks connected to this row.
*
* @internal
*/
connectedBlockWidths = 0;
@@ -44,6 +47,7 @@ export class InputRow extends Row {
/**
* Inspect all subcomponents and populate all size properties on the row.
*
* @internal
*/
override measure() {

2
core/renderers/measurables/jagged_edge.ts
View File

@@ -7,6 +7,7 @@
/**
* Objects representing a jagged edge in a row of a rendered
* block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -21,6 +22,7 @@ import {Types} from './types.js';
/**
* An object containing information about the jagged edge of a collapsed block
* takes up during rendering
*
* @struct
* @alias Blockly.blockRendering.JaggedEdge
*/

2
core/renderers/measurables/next_connection.ts
View File

@@ -7,6 +7,7 @@
/**
* Class representing the space a next connection takes up during
* rendering.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -22,6 +23,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space a next connection takes
* up during rendering.
*
* @struct
* @alias Blockly.blockRendering.NextConnection
*/

2
core/renderers/measurables/output_connection.ts
View File

@@ -7,6 +7,7 @@
/**
* Class representing the space a output connection takes up
* during rendering.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -22,6 +23,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space an output connection takes
* up during rendering.
*
* @struct
* @alias Blockly.blockRendering.OutputConnection
*/

2
core/renderers/measurables/previous_connection.ts
View File

@@ -7,6 +7,7 @@
/**
* Class representing the space a previous connection takes up
* during rendering.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -22,6 +23,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space a previous connection takes
* up during rendering.
*
* @struct
* @alias Blockly.blockRendering.PreviousConnection
*/

2
core/renderers/measurables/round_corner.ts
View File

@@ -7,6 +7,7 @@
/**
* Objects representing a round corner in a row of a rendered
* block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -21,6 +22,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space a rounded corner takes up
* during rendering.
*
* @struct
* @alias Blockly.blockRendering.RoundCorner
*/

32
core/renderers/measurables/row.ts
View File

@@ -6,6 +6,7 @@
/**
* Object representing a single row on a rendered block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -22,6 +23,7 @@ import {Types} from './types.js';
/**
* An object representing a single row on a rendered block and all of its
* subcomponents.
*
* @alias Blockly.blockRendering.Row
*/
export class Row {
@@ -30,12 +32,14 @@ export class Row {
/**
* An array of elements contained in this row.
*
* @internal
*/
elements: Measurable[] = [];
/**
* The height of the row.
*
* @internal
*/
height = 0;
@@ -43,12 +47,14 @@ export class Row {
/**
* The width of the row, from the left edge of the block to the right.
* Does not include child blocks unless they are inline.
*
* @internal
*/
width = 0;
/**
* The minimum height of the row.
*
* @internal
*/
minHeight = 0;
@@ -56,6 +62,7 @@ export class Row {
/**
* The minimum width of the row, from the left edge of the block to the
* right. Does not include child blocks unless they are inline.
*
* @internal
*/
minWidth = 0;
@@ -63,6 +70,7 @@ export class Row {
/**
* The width of the row, from the left edge of the block to the edge of the
* block or any connected child blocks.
*
* @internal
*/
widthWithConnectedBlocks = 0;
@@ -70,6 +78,7 @@ export class Row {
/**
* The Y position of the row relative to the origin of the block's svg
* group.
*
* @internal
*/
yPos = 0;
@@ -77,18 +86,21 @@ export class Row {
/**
* The X position of the row relative to the origin of the block's svg
* group.
*
* @internal
*/
xPos = 0;
/**
* Whether the row has any external inputs.
*
* @internal
*/
hasExternalInput = false;
/**
* Whether the row has any statement inputs.
*
* @internal
*/
hasStatement = false;
@@ -102,18 +114,21 @@ export class Row {
/**
* Whether the row has any inline inputs.
*
* @internal
*/
hasInlineInput = false;
/**
* Whether the row has any dummy inputs.
*
* @internal
*/
hasDummyInput = false;
/**
* Whether the row has a jagged edge.
*
* @internal
*/
hasJaggedEdge = false;
@@ -121,6 +136,7 @@ export class Row {
/**
* Alignment of the row.
*
* @internal
*/
align: number|null = null;
@@ -143,7 +159,8 @@ export class Row {
/**
* Get the last input on this row, if it has one.
* @return The last input on the row, or null.
*
* @returns The last input on the row, or null.
* @internal
*/
getLastInput(): InputConnection {
@@ -161,6 +178,7 @@ export class Row {
/**
* Inspect all subcomponents and populate all size properties on the row.
*
* @internal
*/
measure() {
@@ -169,7 +187,8 @@ export class Row {
/**
* Determines whether this row should start with an element spacer.
* @return Whether the row should start with a spacer.
*
* @returns Whether the row should start with a spacer.
* @internal
*/
startsWithElemSpacer(): boolean {
@@ -178,7 +197,8 @@ export class Row {
/**
* Determines whether this row should end with an element spacer.
* @return Whether the row should end with a spacer.
*
* @returns Whether the row should end with a spacer.
* @internal
*/
endsWithElemSpacer(): boolean {
@@ -187,7 +207,8 @@ export class Row {
/**
* Convenience method to get the first spacer element on this row.
* @return The first spacer element on this row.
*
* @returns The first spacer element on this row.
* @internal
*/
getFirstSpacer(): InRowSpacer {
@@ -204,7 +225,8 @@ export class Row {
/**
* Convenience method to get the last spacer element on this row.
* @return The last spacer element on this row.
*
* @returns The last spacer element on this row.
* @internal
*/
getLastSpacer(): InRowSpacer {

2
core/renderers/measurables/spacer_row.ts
View File

@@ -6,6 +6,7 @@
/**
* Object representing a spacer between two rows.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -20,6 +21,7 @@ import {Types} from './types.js';
/**
* An object containing information about a spacer between two rows.
*
* @struct
* @alias Blockly.blockRendering.SpacerRow
*/

2
core/renderers/measurables/square_corner.ts
View File

@@ -7,6 +7,7 @@
/**
* Objects representing a square corner in a row of a rendered
* block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -21,6 +22,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space a square corner takes up
* during rendering.
*
* @struct
* @alias Blockly.blockRendering.SquareCorner
*/

2
core/renderers/measurables/statement_input.ts
View File

@@ -7,6 +7,7 @@
/**
* Class representing statement inputs with connections on a
* rendered block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -23,6 +24,7 @@ import {Types} from './types.js';
/**
* An object containing information about the space a statement input takes up
* during rendering
*
* @struct
* @alias Blockly.blockRendering.StatementInput
*/

9
core/renderers/measurables/top_row.ts
View File

@@ -6,6 +6,7 @@
/**
* Object representing a top row on a rendered block.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -27,6 +28,7 @@ import {Types} from './types.js';
* connections.
* After this constructor is called, the row will contain all non-spacer
* elements it needs.
*
* @struct
* @alias Blockly.blockRendering.TopRow
*/
@@ -35,6 +37,7 @@ export class TopRow extends Row {
* The starting point for drawing the row, in the y direction.
* This allows us to draw hats and similar shapes that don't start at the
* origin. Must be non-negative (see #2820).
*
* @internal
*/
capline = 0;
@@ -61,8 +64,9 @@ export class TopRow extends Row {
/**
* Returns whether or not the top row has a left square corner.
*
* @param block The block whose top row this represents.
* @return Whether or not the top row has a left square corner.
* @returns Whether or not the top row has a left square corner.
* @internal
*/
hasLeftSquareCorner(block: BlockSvg): boolean {
@@ -77,8 +81,9 @@ export class TopRow extends Row {
/**
* Returns whether or not the top row has a right square corner.
*
* @param _block The block whose top row this represents.
* @return Whether or not the top row has a right square corner.
* @returns Whether or not the top row has a right square corner.
*/
hasRightSquareCorner(_block: BlockSvg): boolean {
return true;

79
core/renderers/measurables/types.ts
View File

@@ -6,6 +6,7 @@
/**
* Measurable types.
*
* @namespace Blockly.blockRendering.Types
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -17,6 +18,7 @@ import type {Row} from './row.js';
/**
* Types of rendering elements.
*
* @alias Blockly.blockRendering.Types
*/
class TypesContainer {
@@ -50,12 +52,14 @@ class TypesContainer {
/**
* A Left Corner Union Type.
*
* @internal
*/
LEFT_CORNER = this.LEFT_SQUARE_CORNER | this.LEFT_ROUND_CORNER;
/**
* A Right Corner Union Type.
*
* @internal
*/
RIGHT_CORNER = this.RIGHT_SQUARE_CORNER | this.RIGHT_ROUND_CORNER;
@@ -70,8 +74,9 @@ class TypesContainer {
/**
* Get the enum flag value of an existing type or register a new type.
*
* @param type The name of the type.
* @return The enum flag value associated with that type.
* @returns The enum flag value associated with that type.
* @internal
*/
getType(type: string): number {
@@ -84,8 +89,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a field.
*
* @param elem The element to check.
* @return 1 if the object stores information about a field.
* @returns 1 if the object stores information about a field.
* @internal
*/
isField(elem: Measurable): number {
@@ -94,8 +100,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a hat.
*
* @param elem The element to check.
* @return 1 if the object stores information about a hat.
* @returns 1 if the object stores information about a hat.
* @internal
*/
isHat(elem: Measurable): number {
@@ -104,8 +111,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about an icon.
*
* @param elem The element to check.
* @return 1 if the object stores information about an icon.
* @returns 1 if the object stores information about an icon.
* @internal
*/
isIcon(elem: Measurable): number {
@@ -114,8 +122,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a spacer.
*
* @param elem The element to check.
* @return 1 if the object stores information about a spacer.
* @returns 1 if the object stores information about a spacer.
* @internal
*/
isSpacer(elem: Measurable|Row): number {
@@ -124,8 +133,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about an in-row spacer.
*
* @param elem The element to check.
* @return 1 if the object stores information about an in-row spacer.
* @returns 1 if the object stores information about an in-row spacer.
* @internal
*/
isInRowSpacer(elem: Measurable): number {
@@ -134,8 +144,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about an input.
*
* @param elem The element to check.
* @return 1 if the object stores information about an input.
* @returns 1 if the object stores information about an input.
* @internal
*/
isInput(elem: Measurable): number {
@@ -144,8 +155,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about an external input.
*
* @param elem The element to check.
* @return 1 if the object stores information about an external input.
* @returns 1 if the object stores information about an external input.
* @internal
*/
isExternalInput(elem: Measurable): number {
@@ -154,8 +166,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about an inline input.
*
* @param elem The element to check.
* @return 1 if the object stores information about an inline input.
* @returns 1 if the object stores information about an inline input.
* @internal
*/
isInlineInput(elem: Measurable): number {
@@ -164,8 +177,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a statement input.
*
* @param elem The element to check.
* @return 1 if the object stores information about a statement input.
* @returns 1 if the object stores information about a statement input.
* @internal
*/
isStatementInput(elem: Measurable): number {
@@ -174,8 +188,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a previous connection.
*
* @param elem The element to check.
* @return 1 if the object stores information about a previous connection.
* @returns 1 if the object stores information about a previous connection.
* @internal
*/
isPreviousConnection(elem: Measurable): number {
@@ -184,8 +199,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a next connection.
*
* @param elem The element to check.
* @return 1 if the object stores information about a next connection.
* @returns 1 if the object stores information about a next connection.
* @internal
*/
isNextConnection(elem: Measurable): number {
@@ -195,8 +211,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a previous or next
* connection.
*
* @param elem The element to check.
* @return 1 if the object stores information about a previous or next
* @returns 1 if the object stores information about a previous or next
* connection.
* @internal
*/
@@ -206,8 +223,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a left round corner.
*
* @param elem The element to check.
* @return 1 if the object stores information about a left round corner.
* @returns 1 if the object stores information about a left round corner.
* @internal
*/
isLeftRoundedCorner(elem: Measurable): number {
@@ -216,8 +234,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a right round corner.
*
* @param elem The element to check.
* @return 1 if the object stores information about a right round corner.
* @returns 1 if the object stores information about a right round corner.
* @internal
*/
isRightRoundedCorner(elem: Measurable): number {
@@ -226,8 +245,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a left square corner.
*
* @param elem The element to check.
* @return 1 if the object stores information about a left square corner.
* @returns 1 if the object stores information about a left square corner.
* @internal
*/
isLeftSquareCorner(elem: Measurable): number {
@@ -236,8 +256,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a right square corner.
*
* @param elem The element to check.
* @return 1 if the object stores information about a right square corner.
* @returns 1 if the object stores information about a right square corner.
* @internal
*/
isRightSquareCorner(elem: Measurable): number {
@@ -246,8 +267,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a corner.
*
* @param elem The element to check.
* @return 1 if the object stores information about a corner.
* @returns 1 if the object stores information about a corner.
* @internal
*/
isCorner(elem: Measurable): number {
@@ -256,8 +278,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a jagged edge.
*
* @param elem The element to check.
* @return 1 if the object stores information about a jagged edge.
* @returns 1 if the object stores information about a jagged edge.
* @internal
*/
isJaggedEdge(elem: Measurable): number {
@@ -266,8 +289,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a row.
*
* @param row The row to check.
* @return 1 if the object stores information about a row.
* @returns 1 if the object stores information about a row.
* @internal
*/
isRow(row: Row): number {
@@ -276,8 +300,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a between-row spacer.
*
* @param row The row to check.
* @return 1 if the object stores information about a between-row spacer.
* @returns 1 if the object stores information about a between-row spacer.
* @internal
*/
isBetweenRowSpacer(row: Row): number {
@@ -286,8 +311,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a top row.
*
* @param row The row to check.
* @return 1 if the object stores information about a top row.
* @returns 1 if the object stores information about a top row.
* @internal
*/
isTopRow(row: Row): number {
@@ -296,8 +322,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a bottom row.
*
* @param row The row to check.
* @return 1 if the object stores information about a bottom row.
* @returns 1 if the object stores information about a bottom row.
* @internal
*/
isBottomRow(row: Row): number {
@@ -306,8 +333,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about a top or bottom row.
*
* @param row The row to check.
* @return 1 if the object stores information about a top or bottom row.
* @returns 1 if the object stores information about a top or bottom row.
* @internal
*/
isTopOrBottomRow(row: Row): number {
@@ -316,8 +344,9 @@ class TypesContainer {
/**
* Whether a measurable stores information about an input row.
*
* @param row The row to check.
* @return 1 if the object stores information about an input row.
* @returns 1 if the object stores information about an input row.
* @internal
*/
isInputRow(row: Row): number {

2
core/renderers/minimalist/constants.ts
View File

@@ -7,6 +7,7 @@
/**
* An object that provides constants for rendering blocks in the
* minimalist renderer.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -17,6 +18,7 @@ import {ConstantProvider as BaseConstantProvider} from '../common/constants.js';
/**
* An object that provides constants for rendering blocks in the sample.
*
* @alias Blockly.minimalist.ConstantProvider
*/
export class ConstantProvider extends BaseConstantProvider {

2
core/renderers/minimalist/drawer.ts
View File

@@ -6,6 +6,7 @@
/**
* Minimalist rendering drawer.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -19,6 +20,7 @@ import type {RenderInfo} from './info.js';
/**
* An object that draws a block based on the given rendering information.
*
* @alias Blockly.minimalist.Drawer
*/
export class Drawer extends BaseDrawer {

5
core/renderers/minimalist/info.ts
View File

@@ -6,6 +6,7 @@
/**
* Minimalist render info object.
*
* @class
*/
import * as goog from '../../../closure/goog/goog.js';
@@ -23,6 +24,7 @@ import type {Renderer} from './renderer.js';
* This measure pass does not propagate changes to the block (although fields
* may choose to rerender when getSize() is called). However, calling it
* repeatedly may be expensive.
*
* @alias Blockly.minimalist.RenderInfo
*/
export class RenderInfo extends BaseRenderInfo {
@@ -37,7 +39,8 @@ export class RenderInfo extends BaseRenderInfo {
/**
* Get the block renderer in use.
* @return The block renderer in use.
*
* @returns The block renderer in use.
* @internal
*/
override getRenderer(): Renderer {

3
core/renderers/minimalist/minimalist.ts
View File

@@ -1,4 +1,4 @@
/** @fileoverview Re-exports of Blockly.minimalist.* modules. */
/** @file Re-exports of Blockly.minimalist.* modules. */
/**
* @license
@@ -8,6 +8,7 @@
/**
* Re-exports of Blockly.minimalist.* modules.
*
* @namespace Blockly.minimalist
*/
import * as goog from '../../../closure/goog/goog.js';

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