diff --git a/core/events/events_abstract.ts b/core/events/events_abstract.ts index 39d01c040..f22c9c3b8 100644 --- a/core/events/events_abstract.ts +++ b/core/events/events_abstract.ts @@ -34,7 +34,16 @@ export abstract class Abstract { /** The workspace identifier for this event. */ workspaceId?: string = undefined; + + /** + * An ID for the group of events this block is associated with. + * + * Groups define events that should be treated as an single action from the + * user's perspective, and should be undone together. + */ group: string; + + /** Whether this event is undoable or not. */ recordUndo: boolean; /** Whether or not the event is a UI event. */ @@ -45,14 +54,7 @@ export abstract class Abstract { /** @alias Blockly.Events.Abstract */ constructor() { - /** - * The event group ID for the group this event belongs to. Groups define - * events that should be treated as an single action from the user's - * perspective, and should be undone together. - */ this.group = eventUtils.getGroup(); - - /** Sets whether the event should be added to the undo stack. */ this.recordUndo = eventUtils.getRecordUndo(); } diff --git a/core/events/events_block_base.ts b/core/events/events_block_base.ts index cd134c516..8d2c79665 100644 --- a/core/events/events_block_base.ts +++ b/core/events/events_block_base.ts @@ -20,12 +20,14 @@ import {Abstract as AbstractEvent, AbstractEventJson} from './events_abstract.js /** - * Abstract class for a block event. + * Abstract class for any event related to blocks. * * @alias Blockly.Events.BlockBase */ export class BlockBase extends AbstractEvent { override isBlank = true; + + /** The ID of the block associated with this event. */ blockId?: string; /** @@ -38,10 +40,7 @@ export class BlockBase extends AbstractEvent { if (!opt_block) return; - /** The block ID for the block this event pertains to */ this.blockId = opt_block.id; - - /** The workspace identifier for this event. */ this.workspaceId = opt_block.workspace.id; } diff --git a/core/events/events_block_change.ts b/core/events/events_block_change.ts index e9c34013c..288fe0e46 100644 --- a/core/events/events_block_change.ts +++ b/core/events/events_block_change.ts @@ -24,15 +24,26 @@ import * as eventUtils from './utils.js'; /** - * Class for a block change event. + * Notifies listeners when some element of a block has changed (e.g. + * field values, comments, etc). * * @alias Blockly.Events.BlockChange */ export class BlockChange extends BlockBase { override type = eventUtils.BLOCK_CHANGE; + /** + * The element that changed; one of 'field', 'comment', 'collapsed', + * 'disabled', 'inline', or 'mutation' + */ element?: string; + + /** The name of the field that changed, if this is a change to a field. */ name?: string; + + /** The original value of the element. */ oldValue: unknown; + + /** The new value of the element. */ newValue: unknown; /** diff --git a/core/events/events_block_create.ts b/core/events/events_block_create.ts index 4a6ad8232..d88f84388 100644 --- a/core/events/events_block_create.ts +++ b/core/events/events_block_create.ts @@ -24,16 +24,23 @@ import {Workspace} from '../workspace.js'; /** - * Class for a block creation event. + * Notifies listeners when a block (or connected stack of blocks) is + * created. * * @alias Blockly.Events.BlockCreate */ export class BlockCreate extends BlockBase { override type = eventUtils.BLOCK_CREATE; + + /** The XML representation of the created block(s). */ xml?: Element|DocumentFragment; - ids?: string[]; + + /** The JSON respresentation of the created block(s). */ json?: blocks.State; + /** All of the IDs of created blocks. */ + ids?: string[]; + /** @param opt_block The created block. Undefined for a blank event. */ constructor(opt_block?: Block) { super(opt_block); @@ -50,7 +57,6 @@ export class BlockCreate extends BlockBase { this.xml = Xml.blockToDomWithXY(opt_block); this.ids = eventUtils.getDescendantIds(opt_block); - /** JSON representation of the block that was just created. */ this.json = blocks.save(opt_block, {addCoordinates: true}) as blocks.State; } diff --git a/core/events/events_block_delete.ts b/core/events/events_block_delete.ts index 0f5cf56e8..77071b95d 100644 --- a/core/events/events_block_delete.ts +++ b/core/events/events_block_delete.ts @@ -24,15 +24,24 @@ import {Workspace} from '../workspace.js'; /** - * Class for a block deletion event. + * Notifies listeners when a block (or connected stack of blocks) is + * deleted. * * @alias Blockly.Events.BlockDelete */ export class BlockDelete extends BlockBase { + /** The XML representation of the deleted block(s). */ oldXml?: Element|DocumentFragment; - ids?: string[]; - wasShadow?: boolean; + + /** The JSON respresentation of the deleted block(s). */ oldJson?: blocks.State; + + /** All of the IDs of deleted blocks. */ + ids?: string[]; + + /** True if the deleted block was a shadow block, false otherwise. */ + wasShadow?: boolean; + override type = eventUtils.BLOCK_DELETE; /** @param opt_block The deleted block. Undefined for a blank event. */ @@ -53,11 +62,7 @@ export class BlockDelete extends BlockBase { this.oldXml = Xml.blockToDomWithXY(opt_block); this.ids = eventUtils.getDescendantIds(opt_block); - - /** Was the block that was just deleted a shadow? */ this.wasShadow = opt_block.isShadow(); - - /** JSON representation of the block that was just deleted. */ this.oldJson = blocks.save(opt_block, {addCoordinates: true}) as blocks.State; } diff --git a/core/events/events_block_drag.ts b/core/events/events_block_drag.ts index 822e5dfce..bf928d713 100644 --- a/core/events/events_block_drag.ts +++ b/core/events/events_block_drag.ts @@ -22,14 +22,23 @@ import {Workspace} from '../workspace.js'; /** - * Class for a block drag event. + * Notifies listeners when a block is being manually dragged/dropped. * * @alias Blockly.Events.BlockDrag */ export class BlockDrag extends UiBase { + /** The ID of the top-level block being dragged. */ blockId?: string; + + /** True if this is the start of a drag, false if this is the end of one. */ isStart?: boolean; + + /** + * A list of all of the blocks (i.e. all descendants of the block associated + * with the block ID) being dragged. + */ blocks?: Block[]; + override type = eventUtils.BLOCK_DRAG; /** @@ -46,11 +55,7 @@ export class BlockDrag extends UiBase { if (!opt_block) return; this.blockId = opt_block.id; - - /** Whether this is the start of a block drag. */ this.isStart = opt_isStart; - - /** The blocks affected by this drag event. */ this.blocks = opt_blocks; } diff --git a/core/events/events_block_move.ts b/core/events/events_block_move.ts index 2aaffa524..a0bb9bbd5 100644 --- a/core/events/events_block_move.ts +++ b/core/events/events_block_move.ts @@ -30,18 +30,42 @@ interface BlockLocation { } /** - * Class for a block move event. Created before the move. + * Notifies listeners when a block is moved. This could be from one + * connection to another, or from one location on the workspace to another. * * @alias Blockly.Events.BlockMove */ export class BlockMove extends BlockBase { override type = eventUtils.BLOCK_MOVE; + + /** The ID of the old parent block. Undefined if it was a top-level block. */ oldParentId?: string; + + /** + * The name of the old input. Undefined if it was a top-level block or the + * parent's next block. + */ oldInputName?: string; + + /** + * The old X and Y workspace coordinates of the block if it was a top level + * block. Undefined if it was not a top level block. + */ oldCoordinate?: Coordinate; + /** The ID of the new parent block. Undefined if it is a top-level block. */ newParentId?: string; + + /** + * The name of the new input. Undefined if it is a top-level block or the + * parent's next block. + */ newInputName?: string; + + /** + * The new X and Y workspace coordinates of the block if it is a top level + * block. Undefined if it is not a top level block. + */ newCoordinate?: Coordinate; /** @param opt_block The moved block. Undefined for a blank event. */ diff --git a/core/events/events_bubble_open.ts b/core/events/events_bubble_open.ts index 6e6c26934..8ea2f967e 100644 --- a/core/events/events_bubble_open.ts +++ b/core/events/events_bubble_open.ts @@ -27,9 +27,15 @@ import type {Workspace} from '../workspace.js'; * @alias Blockly.Events.BubbleOpen */ export class BubbleOpen extends UiBase { + /** The ID of the block the bubble is attached to. */ blockId?: string; + + /** True if the bubble is opening, false if closing. */ isOpen?: boolean; + + /** The type of bubble; one of 'mutator', 'comment', or 'warning'. */ bubbleType?: BubbleType; + override type = eventUtils.BUBBLE_OPEN; /** @@ -46,11 +52,7 @@ export class BubbleOpen extends UiBase { if (!opt_block) return; this.blockId = opt_block.id; - - /** Whether the bubble is opening (false if closing). */ this.isOpen = opt_isOpen; - - /** The type of bubble. One of 'mutator', 'comment', or 'warning'. */ this.bubbleType = opt_bubbleType; } diff --git a/core/events/events_click.ts b/core/events/events_click.ts index a5cafd718..f9ac79817 100644 --- a/core/events/events_click.ts +++ b/core/events/events_click.ts @@ -23,12 +23,18 @@ import {Workspace} from '../workspace.js'; /** - * Class for a click event. + * Notifies listeners that ome blockly element was clicked. * * @alias Blockly.Events.Click */ export class Click extends UiBase { + /** The ID of the block that was clicked, if a block was clicked. */ blockId?: string; + + /** + * The type of element that was clicked; one of 'block', 'workspace', + * or 'zoom_controls'. + */ targetType?: ClickTarget; override type = eventUtils.CLICK; @@ -51,8 +57,6 @@ export class Click extends UiBase { super(workspaceId); this.blockId = opt_block ? opt_block.id : undefined; - - /** The type of element targeted by this click event. */ this.targetType = opt_targetType; } diff --git a/core/events/events_comment_base.ts b/core/events/events_comment_base.ts index dd681a79d..cfbb333c0 100644 --- a/core/events/events_comment_base.ts +++ b/core/events/events_comment_base.ts @@ -31,6 +31,8 @@ import type {Workspace} from '../workspace.js'; */ export class CommentBase extends AbstractEvent { override isBlank = true; + + /** The ID of the comment that this event references. */ commentId?: string; /** @@ -44,20 +46,9 @@ export class CommentBase extends AbstractEvent { if (!opt_comment) return; - /** The ID of the comment this event pertains to. */ this.commentId = opt_comment.id; - - /** The workspace identifier for this event. */ this.workspaceId = opt_comment.workspace.id; - - /** - * The event group ID for the group this event belongs to. Groups define - * events that should be treated as an single action from the user's - * perspective, and should be undone together. - */ this.group = eventUtils.getGroup(); - - /** Sets whether the event should be added to the undo stack. */ this.recordUndo = eventUtils.getRecordUndo(); } diff --git a/core/events/events_comment_change.ts b/core/events/events_comment_change.ts index f1007ed6c..afecc21ca 100644 --- a/core/events/events_comment_change.ts +++ b/core/events/events_comment_change.ts @@ -22,13 +22,18 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a comment change event. + * Notifies listeners that the contents of a workspace comment has changed. * * @alias Blockly.Events.CommentChange */ export class CommentChange extends CommentBase { override type = eventUtils.COMMENT_CHANGE; + + // TODO(#6774): We should remove underscores. + /** The previous contents of the comment. */ oldContents_?: string; + + /** The new contents of the comment. */ newContents_?: string; /** diff --git a/core/events/events_comment_create.ts b/core/events/events_comment_create.ts index fa54b0e96..712c7248c 100644 --- a/core/events/events_comment_create.ts +++ b/core/events/events_comment_create.ts @@ -23,13 +23,14 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a comment creation event. + * Notifies listeners that a workspace comment was created. * * @alias Blockly.Events.CommentCreate */ export class CommentCreate extends CommentBase { override type = eventUtils.COMMENT_CREATE; + /** The XML representation of the created workspace comment. */ xml?: Element|DocumentFragment; /** diff --git a/core/events/events_comment_delete.ts b/core/events/events_comment_delete.ts index 8ec7b5913..fdc513b23 100644 --- a/core/events/events_comment_delete.ts +++ b/core/events/events_comment_delete.ts @@ -22,12 +22,14 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a comment deletion event. + * Notifies listeners that a workspace comment has been deleted. * * @alias Blockly.Events.CommentDelete */ export class CommentDelete extends CommentBase { override type = eventUtils.COMMENT_DELETE; + + /** The XML representation of the deleted workspace comment. */ xml?: Element; /** diff --git a/core/events/events_comment_move.ts b/core/events/events_comment_move.ts index e40c48569..fa05de2a8 100644 --- a/core/events/events_comment_move.ts +++ b/core/events/events_comment_move.ts @@ -23,15 +23,21 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a comment move event. Created before the move. + * Notifies listeners that a workspace comment has moved. * * @alias Blockly.Events.CommentMove */ export class CommentMove extends CommentBase { override type = eventUtils.COMMENT_MOVE; + + /** The comment that is being moved. */ comment_?: WorkspaceComment; + + // TODO(#6774): We should remove underscores. + /** The location of the comment before the move, in workspace coordinates. */ oldCoordinate_?: Coordinate; - /** The location after the move, in workspace coordinates. */ + + /** The location of the comment after the move, in workspace coordinates. */ newCoordinate_?: Coordinate; /** @@ -45,12 +51,7 @@ export class CommentMove extends CommentBase { return; // Blank event to be populated by fromJson. } - /** - * The comment that is being moved. - */ this.comment_ = opt_comment; - - /** The location before the move, in workspace coordinates. */ this.oldCoordinate_ = opt_comment.getXY(); } diff --git a/core/events/events_marker_move.ts b/core/events/events_marker_move.ts index 3639c738b..9ba2fdc8b 100644 --- a/core/events/events_marker_move.ts +++ b/core/events/events_marker_move.ts @@ -24,15 +24,28 @@ import * as eventUtils from './utils.js'; /** - * Class for a marker move event. + * Notifies listeners that a marker (used for keyboard navigation) has + * moved. * * @alias Blockly.Events.MarkerMove */ export class MarkerMove extends UiBase { + /** The ID of the block the marker is now on, if any. */ blockId?: string; + + /** The old node the marker used to be on, if any. */ oldNode?: ASTNode; + + /** The new node the marker is now on. */ newNode?: ASTNode; + + /** + * True if this is a cursor event, false otherwise. + * For information about cursors vs markers see {@link + * https://blocklycodelabs.dev/codelabs/keyboard-navigation/index.html?index=..%2F..index#1}. + */ isCursor?: boolean; + override type = eventUtils.MARKER_MOVE; /** @@ -54,16 +67,9 @@ export class MarkerMove extends UiBase { } super(workspaceId); - /** The block identifier for this event. */ this.blockId = opt_block?.id; - - /** The old node the marker used to be on. */ this.oldNode = opt_oldNode || undefined; - - /** The new node the marker is now on. */ this.newNode = opt_newNode; - - /** Whether this is a cursor event. */ this.isCursor = isCursor; } diff --git a/core/events/events_procedure_base.ts b/core/events/events_procedure_base.ts index 1c17db24a..f775a30a2 100644 --- a/core/events/events_procedure_base.ts +++ b/core/events/events_procedure_base.ts @@ -15,6 +15,10 @@ import type {Workspace} from '../workspace.js'; export abstract class ProcedureBase extends AbstractEvent { isBlank = false; + /** + * @param workspace The workspace the procedure model exists in. + * @param model The procedure model associated with this event. + */ constructor(workspace: Workspace, public readonly model: IProcedureModel) { super(); this.workspaceId = workspace.id; diff --git a/core/events/events_procedure_change_return.ts b/core/events/events_procedure_change_return.ts index a6e3c6be7..974049cb9 100644 --- a/core/events/events_procedure_change_return.ts +++ b/core/events/events_procedure_change_return.ts @@ -14,7 +14,7 @@ import * as eventUtils from './utils.js'; /** - * Represents a procedure's return type/status changing. + * Notifies listeners that a procedure's return type/status has changed. */ export class ProcedureChangeReturn extends ProcedureBase { /** A string used to check the type of the event. */ diff --git a/core/events/events_procedure_create.ts b/core/events/events_procedure_create.ts index ddccfb983..d294dc6c1 100644 --- a/core/events/events_procedure_create.ts +++ b/core/events/events_procedure_create.ts @@ -15,7 +15,7 @@ import * as eventUtils from './utils.js'; /** - * Represents a procedure data model being created. + * Notifies listeners that a procedure data model has been created. */ export class ProcedureCreate extends ProcedureBase { /** A string used to check the type of the event. */ diff --git a/core/events/events_procedure_delete.ts b/core/events/events_procedure_delete.ts index e7555aeba..3a841c2e8 100644 --- a/core/events/events_procedure_delete.ts +++ b/core/events/events_procedure_delete.ts @@ -15,7 +15,7 @@ import * as eventUtils from './utils.js'; /** - * Represents a procedure data model being deleted. + * Notifies listeners that a procedure data model has been deleted. */ export class ProcedureDelete extends ProcedureBase { /** A string used to check the type of the event. */ diff --git a/core/events/events_procedure_enable.ts b/core/events/events_procedure_enable.ts index 3ae52e93f..8ec32f3d6 100644 --- a/core/events/events_procedure_enable.ts +++ b/core/events/events_procedure_enable.ts @@ -13,7 +13,8 @@ import {ProcedureBase, ProcedureBaseJson} from './events_procedure_base.js'; import * as eventUtils from './utils.js'; /** - * Represents a procedure data model being enabled or disabled. + * Notifies listeners that the procedure data model has been enabled or + * disabled. */ export class ProcedureEnable extends ProcedureBase { /** A string used to check the type of the event. */ diff --git a/core/events/events_procedure_parameter_base.ts b/core/events/events_procedure_parameter_base.ts index 1bbfb2429..f03094d25 100644 --- a/core/events/events_procedure_parameter_base.ts +++ b/core/events/events_procedure_parameter_base.ts @@ -16,6 +16,11 @@ import type {Workspace} from '../workspace.js'; * The base event for an event associated with a procedure parameter. */ export abstract class ProcedureParameterBase extends ProcedureBase { + /** + * @param workspace The workspace the parameter model exists in. + * @param model The procedure model the parameter model belongs to. + * @param parameter The parameter model associated with this event. + */ constructor( workspace: Workspace, model: IProcedureModel, public readonly parameter: IParameterModel) { diff --git a/core/events/events_procedure_parameter_create.ts b/core/events/events_procedure_parameter_create.ts index 1271effc3..8fae7b9ae 100644 --- a/core/events/events_procedure_parameter_create.ts +++ b/core/events/events_procedure_parameter_create.ts @@ -16,7 +16,7 @@ import * as eventUtils from './utils.js'; /** - * Represents a parameter being added to a procedure. + * Notifies listeners that a parameter has been added to a procedure model. */ export class ProcedureParameterCreate extends ProcedureParameterBase { /** A string used to check the type of the event. */ diff --git a/core/events/events_procedure_parameter_delete.ts b/core/events/events_procedure_parameter_delete.ts index 4ee43bb0b..aa479a37d 100644 --- a/core/events/events_procedure_parameter_delete.ts +++ b/core/events/events_procedure_parameter_delete.ts @@ -14,7 +14,7 @@ import {ProcedureParameterBase, ProcedureParameterBaseJson} from './events_proce import * as eventUtils from './utils.js'; /** - * Represents a parameter being removed from a procedure. + * Notifies listeners that a parameter has been removed from a procedure. */ export class ProcedureParameterDelete extends ProcedureParameterBase { /** A string used to check the type of the event. */ diff --git a/core/events/events_procedure_parameter_rename.ts b/core/events/events_procedure_parameter_rename.ts index 9baafc11b..3b0aa71f6 100644 --- a/core/events/events_procedure_parameter_rename.ts +++ b/core/events/events_procedure_parameter_rename.ts @@ -13,13 +13,16 @@ import {ProcedureParameterBase, ProcedureParameterBaseJson} from './events_proce import * as eventUtils from './utils.js'; /** - * Represents a parameter of a procedure being renamed. + * Notifies listeners that a procedure parameter was renamed. */ export class ProcedureParameterRename extends ProcedureParameterBase { /** A string used to check the type of the event. */ type = eventUtils.PROCEDURE_PARAMETER_RENAME; + + /** The new name of the procedure parameter. */ private readonly newName: string; + /** @param oldName The old name of the procedure parameter. */ constructor( workspace: Workspace, procedure: IProcedureModel, parameter: IParameterModel, public readonly oldName: string) { diff --git a/core/events/events_procedure_rename.ts b/core/events/events_procedure_rename.ts index 0b849d771..80217d10b 100644 --- a/core/events/events_procedure_rename.ts +++ b/core/events/events_procedure_rename.ts @@ -11,14 +11,14 @@ import type {Workspace} from '../workspace.js'; import {ProcedureBase, ProcedureBaseJson} from './events_procedure_base.js'; import * as eventUtils from './utils.js'; -/** - * Represents a procedure being renamed. - */ +/** Notifies listeners that a procedure model has been renamed. */ export class ProcedureRename extends ProcedureBase { /** A string used to check the type of the event. */ type = eventUtils.PROCEDURE_RENAME; + private newName: string; + /** @param oldName The old name of the procedure model. */ constructor( workspace: Workspace, model: IProcedureModel, public readonly oldName: string) { diff --git a/core/events/events_selected.ts b/core/events/events_selected.ts index 347bdb22a..03fcfd9d9 100644 --- a/core/events/events_selected.ts +++ b/core/events/events_selected.ts @@ -23,12 +23,20 @@ import type {Workspace} from '../workspace.js'; /** * Class for a selected event. + * Notifies listeners that a new element has been selected. * * @alias Blockly.Events.Selected */ export class Selected extends UiBase { + /** The id of the last selected selectable element. */ oldElementId?: string; + + /** + * The id of the newly selected selectable element, + * or undefined if unselected. + */ newElementId?: string; + override type = eventUtils.SELECTED; /** @@ -44,10 +52,7 @@ export class Selected extends UiBase { opt_workspaceId?: string) { super(opt_workspaceId); - /** The id of the last selected element. */ this.oldElementId = opt_oldElementId ?? undefined; - - /** The id of the selected element. */ this.newElementId = opt_newElementId ?? undefined; } diff --git a/core/events/events_theme_change.ts b/core/events/events_theme_change.ts index 75c5641e2..9f5a58464 100644 --- a/core/events/events_theme_change.ts +++ b/core/events/events_theme_change.ts @@ -21,12 +21,14 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a theme change event. + * Notifies listeners that the workspace theme has changed. * * @alias Blockly.Events.ThemeChange */ export class ThemeChange extends UiBase { + /** The name of the new theme that has been set. */ themeName?: string; + override type = eventUtils.THEME_CHANGE; /** @@ -36,8 +38,6 @@ export class ThemeChange extends UiBase { */ constructor(opt_themeName?: string, opt_workspaceId?: string) { super(opt_workspaceId); - - /** The theme name. */ this.themeName = opt_themeName; } diff --git a/core/events/events_toolbox_item_select.ts b/core/events/events_toolbox_item_select.ts index 81e8a7eda..2f47eb9d8 100644 --- a/core/events/events_toolbox_item_select.ts +++ b/core/events/events_toolbox_item_select.ts @@ -21,13 +21,17 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a toolbox item select event. + * Notifies listeners that a toolbox item has been selected. * * @alias Blockly.Events.ToolboxItemSelect */ export class ToolboxItemSelect extends UiBase { + /** The previously selected toolbox item. */ oldItem?: string; + + /** The newly selected toolbox item. */ newItem?: string; + override type = eventUtils.TOOLBOX_ITEM_SELECT; /** @@ -42,11 +46,7 @@ export class ToolboxItemSelect extends UiBase { opt_oldItem?: string|null, opt_newItem?: string|null, opt_workspaceId?: string) { super(opt_workspaceId); - - /** The previously selected toolbox item. */ this.oldItem = opt_oldItem ?? undefined; - - /** The newly selected toolbox item. */ this.newItem = opt_newItem ?? undefined; } diff --git a/core/events/events_trashcan_open.ts b/core/events/events_trashcan_open.ts index fd6001dfd..95876dfd8 100644 --- a/core/events/events_trashcan_open.ts +++ b/core/events/events_trashcan_open.ts @@ -22,11 +22,15 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a trashcan open event. + * Notifies listeners when the trashcan is opening or closing. * * @alias Blockly.Events.TrashcanOpen */ export class TrashcanOpen extends UiBase { + /** + * True if the trashcan is currently opening (previously closed). + * False if it is currently closing (previously open). + */ isOpen?: boolean; override type = eventUtils.TRASHCAN_OPEN; @@ -38,8 +42,6 @@ export class TrashcanOpen extends UiBase { */ constructor(opt_isOpen?: boolean, opt_workspaceId?: string) { super(opt_workspaceId); - - /** Whether the trashcan flyout is opening (false if closing). */ this.isOpen = opt_isOpen; } diff --git a/core/events/events_var_base.ts b/core/events/events_var_base.ts index 41370702d..0bbd48fcf 100644 --- a/core/events/events_var_base.ts +++ b/core/events/events_var_base.ts @@ -26,6 +26,7 @@ import type {Workspace} from '../workspace.js'; */ export class VarBase extends AbstractEvent { override isBlank = true; + /** The ID of the variable this event references. */ varId?: string; /** @@ -37,10 +38,7 @@ export class VarBase extends AbstractEvent { this.isBlank = typeof opt_variable === 'undefined'; if (!opt_variable) return; - /** The variable id for the variable this event pertains to. */ this.varId = opt_variable.getId(); - - /** The workspace identifier for this event. */ this.workspaceId = opt_variable.workspace.id; } diff --git a/core/events/events_var_create.ts b/core/events/events_var_create.ts index 925071c59..c30fb8463 100644 --- a/core/events/events_var_create.ts +++ b/core/events/events_var_create.ts @@ -22,13 +22,17 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a variable creation event. + * Notifies listeners that a variable model has been created. * * @alias Blockly.Events.VarCreate */ export class VarCreate extends VarBase { override type = eventUtils.VAR_CREATE; + + /** The type of the variable that was created. */ varType?: string; + + /** The name of the variable that was created. */ varName?: string; /** diff --git a/core/events/events_var_delete.ts b/core/events/events_var_delete.ts index ca9e2de97..d3f6c6f4f 100644 --- a/core/events/events_var_delete.ts +++ b/core/events/events_var_delete.ts @@ -4,11 +4,6 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * Classes for all types of variable events. - * - * @class - */ import * as goog from '../../closure/goog/goog.js'; goog.declareModuleId('Blockly.Events.VarDelete'); @@ -22,13 +17,15 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a variable deletion event. + * Notifies listeners that a variable model has been deleted. * - * @alias Blockly.Events.VarDelete + * @class */ export class VarDelete extends VarBase { override type = eventUtils.VAR_DELETE; + /** The type of the variable that was deleted. */ varType?: string; + /** The name of the variable that was deleted. */ varName?: string; /** diff --git a/core/events/events_var_rename.ts b/core/events/events_var_rename.ts index 278a1510d..bed95cf62 100644 --- a/core/events/events_var_rename.ts +++ b/core/events/events_var_rename.ts @@ -4,11 +4,6 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * Class for a variable rename event. - * - * @class - */ import * as goog from '../../closure/goog/goog.js'; goog.declareModuleId('Blockly.Events.VarRename'); @@ -22,13 +17,17 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a variable rename event. + * Notifies listeners that a variable model was renamed. * - * @alias Blockly.Events.VarRename + * @class */ export class VarRename extends VarBase { override type = eventUtils.VAR_RENAME; + + /** The previous name of the variable. */ oldName?: string; + + /** The new name of the variable. */ newName?: string; /** diff --git a/core/events/events_viewport.ts b/core/events/events_viewport.ts index 3367e35f8..7f853fae2 100644 --- a/core/events/events_viewport.ts +++ b/core/events/events_viewport.ts @@ -21,15 +21,32 @@ import type {Workspace} from '../workspace.js'; /** - * Class for a viewport change event. + * Notifies listeners that the workspace surface's position or scale has + * changed. + * + * Does not notify when the workspace itself resizes. * * @alias Blockly.Events.ViewportChange */ export class ViewportChange extends UiBase { + /** + * Top edge of the visible portion of the workspace, relative to the + * workspace origin. + */ viewTop?: number; + + /** + * The left edge of the visible portion of the workspace, relative to + * the workspace origin. + */ viewLeft?: number; + + /** The scale of the workpace. */ scale?: number; + + /** The previous scale of the workspace. */ oldScale?: number; + override type = eventUtils.VIEWPORT_CHANGE; /** @@ -48,22 +65,9 @@ export class ViewportChange extends UiBase { opt_workspaceId?: string, opt_oldScale?: number) { super(opt_workspaceId); - /** - * Top-edge of the visible portion of the workspace, relative to the - * workspace origin. - */ this.viewTop = opt_top; - - /** - * Left-edge of the visible portion of the workspace, relative to the - * workspace origin. - */ this.viewLeft = opt_left; - - /** The scale of the workspace. */ this.scale = opt_scale; - - /** The old scale of the workspace. */ this.oldScale = opt_oldScale; } diff --git a/core/events/workspace_events.ts b/core/events/workspace_events.ts index 95b533d54..6f6fc7e8e 100644 --- a/core/events/workspace_events.ts +++ b/core/events/workspace_events.ts @@ -19,10 +19,8 @@ import * as eventUtils from './utils.js'; /** - * Class for a finished loading event. - * Used to notify the developer when the workspace has finished loading (i.e - * domToWorkspace). - * Finished loading events do not record undo or redo. + * Notifies listeners when the workspace has finished deserializing from + * JSON/XML. * * @alias Blockly.Events.FinishedLoading */ @@ -37,12 +35,10 @@ export class FinishedLoading extends AbstractEvent { */ constructor(opt_workspace?: Workspace) { super(); - /** Whether or not the event is blank (to be populated by fromJson). */ this.isBlank = !!opt_workspace; if (!opt_workspace) return; - /** The workspace identifier for this event. */ this.workspaceId = opt_workspace.id; }