From 362ec011ce6885419e51068f84abfcedf7f19e89 Mon Sep 17 00:00:00 2001 From: Beka Westberg Date: Mon, 27 Jun 2022 15:00:44 +0000 Subject: [PATCH] fix: re-add `@package` annotations as `@internal` annotations (#6232) * fix: add ~70% of internal attributes * fix: work on manually adding more @internal annotations * fix: add more manual internal annotations * fix: rename package typos to internal * fix: final manual fixes for internal annotations * chore: format * chore: make unnecessary multiline jsdoc a single line * fix: fix internal tags in serialization exceptions --- core/block.ts | 21 ++++- core/block_animations.ts | 4 + core/block_dragger.ts | 5 +- core/block_svg.ts | 41 +++++++++- core/bubble.ts | 12 ++- core/bubble_dragger.ts | 4 + core/clipboard.ts | 3 + core/comment.ts | 5 +- core/common.ts | 1 + core/connection.ts | 24 +++++- core/connection_db.ts | 1 + core/contextmenu.ts | 3 + core/contextmenu_items.ts | 1 + core/dropdowndiv.ts | 8 +- core/events/events_block_change.ts | 1 + core/events/utils.ts | 1 + core/extensions.ts | 1 + core/field.ts | 38 +++++++++- core/field_angle.ts | 6 +- core/field_checkbox.ts | 7 +- core/field_colour.ts | 6 +- core/field_dropdown.ts | 15 +++- core/field_image.ts | 6 +- core/field_label.ts | 6 +- core/field_label_serializable.ts | 1 + core/field_multilineinput.ts | 10 ++- core/field_number.ts | 1 + core/field_registry.ts | 1 + core/field_textinput.ts | 7 +- core/field_variable.ts | 7 ++ core/flyout_base.ts | 9 ++- core/flyout_button.ts | 2 + core/flyout_horizontal.ts | 1 + core/flyout_vertical.ts | 1 + core/gesture.ts | 21 ++++- core/grid.ts | 7 ++ core/input.ts | 6 +- core/insertion_marker_manager.ts | 11 ++- core/interfaces/i_copyable.ts | 1 + core/interfaces/i_metrics_manager.ts | 1 + core/interfaces/i_toolbox_item.ts | 1 + core/internal_constants.ts | 5 ++ core/keyboard_nav/ast_node.ts | 1 + core/keyboard_nav/marker.ts | 5 +- core/marker_manager.ts | 13 +++- core/menu.ts | 12 ++- core/menuitem.ts | 12 +++ core/metrics_manager.ts | 1 + core/mutator.ts | 2 + core/positionable_helpers.ts | 7 ++ core/procedures.ts | 1 + core/registry.ts | 1 + core/rendered_connection.ts | 8 ++ core/renderers/common/block_rendering.ts | 4 + core/renderers/common/constants.ts | 65 +++++++++++++--- core/renderers/common/debug.ts | 3 + core/renderers/common/debugger.ts | 19 ++++- core/renderers/common/drawer.ts | 2 + core/renderers/common/i_path_object.ts | 17 ++++- core/renderers/common/info.ts | 13 +++- core/renderers/common/marker_svg.ts | 1 + core/renderers/common/path_object.ts | 31 +++++++- core/renderers/common/renderer.ts | 29 ++++++- core/renderers/geras/constants.ts | 1 + core/renderers/geras/drawer.ts | 1 + core/renderers/geras/highlight_constants.ts | 13 +++- core/renderers/geras/highlighter.ts | 14 +++- core/renderers/geras/info.ts | 2 + .../geras/measurables/inline_input.ts | 1 + .../geras/measurables/statement_input.ts | 1 + core/renderers/geras/path_object.ts | 9 ++- core/renderers/geras/renderer.ts | 8 +- core/renderers/measurables/base.ts | 5 +- core/renderers/measurables/bottom_row.ts | 16 +++- core/renderers/measurables/connection.ts | 1 + .../measurables/external_value_input.ts | 1 + core/renderers/measurables/field.ts | 1 + core/renderers/measurables/hat.ts | 5 +- core/renderers/measurables/icon.ts | 1 + core/renderers/measurables/in_row_spacer.ts | 1 + core/renderers/measurables/inline_input.ts | 1 + .../renderers/measurables/input_connection.ts | 1 + core/renderers/measurables/input_row.ts | 11 ++- core/renderers/measurables/jagged_edge.ts | 5 +- core/renderers/measurables/next_connection.ts | 1 + .../measurables/output_connection.ts | 1 + .../measurables/previous_connection.ts | 1 + core/renderers/measurables/round_corner.ts | 1 + core/renderers/measurables/row.ts | 62 ++++++++++++--- core/renderers/measurables/spacer_row.ts | 1 + core/renderers/measurables/square_corner.ts | 1 + core/renderers/measurables/statement_input.ts | 1 + core/renderers/measurables/top_row.ts | 7 +- core/renderers/measurables/types.ts | 35 ++++++++- core/renderers/minimalist/constants.ts | 1 + core/renderers/minimalist/drawer.ts | 1 + core/renderers/minimalist/info.ts | 2 + core/renderers/minimalist/renderer.ts | 5 +- core/renderers/thrasos/info.ts | 2 + core/renderers/thrasos/renderer.ts | 5 +- core/renderers/zelos/constants.ts | 12 ++- core/renderers/zelos/drawer.ts | 1 + core/renderers/zelos/info.ts | 2 + .../renderers/zelos/measurables/bottom_row.ts | 5 +- core/renderers/zelos/measurables/inputs.ts | 1 + .../zelos/measurables/row_elements.ts | 5 +- core/renderers/zelos/measurables/top_row.ts | 5 +- core/renderers/zelos/path_object.ts | 20 ++++- core/renderers/zelos/renderer.ts | 7 +- core/scrollbar.ts | 5 ++ core/scrollbar_pair.ts | 1 + core/serialization/blocks.ts | 1 + core/serialization/exceptions.ts | 12 ++- core/shortcut_items.ts | 1 + core/theme.ts | 6 ++ core/theme_manager.ts | 8 ++ core/toolbox/toolbox.ts | 9 ++- core/toolbox/toolbox_item.ts | 1 + core/tooltip.ts | 3 + core/touch.ts | 2 + core/touch_gesture.ts | 15 +++- core/trashcan.ts | 6 +- core/utils.ts | 2 + core/utils/array.ts | 1 + core/utils/colour.ts | 4 + core/utils/svg.ts | 28 ++++++- core/utils/svg_math.ts | 1 + core/utils/toolbox.ts | 4 + core/variable_map.ts | 3 + core/variable_model.ts | 1 + core/variables.ts | 1 + core/widgetdiv.ts | 1 + core/workspace.ts | 22 +++++- core/workspace_audio.ts | 10 ++- core/workspace_comment.ts | 23 +++++- core/workspace_comment_svg.ts | 76 ++++++++++++++++--- core/workspace_drag_surface_svg.ts | 4 + core/workspace_dragger.ts | 8 +- core/workspace_svg.ts | 68 +++++++++++++++-- 139 files changed, 1050 insertions(+), 121 deletions(-) diff --git a/core/block.ts b/core/block.ts index 230767f90..38a607810 100644 --- a/core/block.ts +++ b/core/block.ts @@ -85,7 +85,10 @@ export class Block implements IASTNodeLocation, IDeletable { */ data: string|null = null; - /** Has this block been disposed of? */ + /** + * Has this block been disposed of? + * @internal + */ disposed = false; /** @@ -193,6 +196,7 @@ export class Block implements IASTNodeLocation, IDeletable { * @deprecated August 2019. Use getCommentText instead. */ comment: string|Comment|null = null; + /** @internal */ commentModel: CommentModel; private readonly xy_: Coordinate; isInFlyout: boolean; @@ -217,7 +221,10 @@ export class Block implements IASTNodeLocation, IDeletable { /** A bound callback function to use when the parent workspace changes. */ private onchangeWrapper_: ((p1: Abstract) => AnyDuringMigration)|null = null; - /** A count of statement inputs on the block. */ + /** + * A count of statement inputs on the block. + * @internal + */ statementInputCount = 0; // TODO(b/109816955): remove '!', see go/strict-prop-init-fix. type!: string; @@ -493,6 +500,7 @@ 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. + * @internal */ getConnections_(_all: boolean): Connection[] { const myConnections = []; @@ -520,6 +528,7 @@ export class Block implements IASTNodeLocation, IDeletable { * be returned. If false, this will follow shadows to find the last * connection. * @return The last next connection on the stack, or null. + * @internal */ lastConnectionInStack(ignoreShadows: boolean): Connection|null { let nextConnection = this.nextConnection; @@ -609,6 +618,7 @@ 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. + * @internal */ getFirstStatementConnection(): Connection|null { for (let i = 0, input; input = this.inputList[i]; i++) { @@ -640,6 +650,7 @@ export class Block implements IASTNodeLocation, IDeletable { * 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. + * @internal */ getTopStackBlock(): this { let block = this; @@ -684,6 +695,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 */ setParent(newParent: this|null) { if (newParent === this.parentBlock_) { @@ -809,6 +821,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether this block is a shadow block or not. * @param shadow True if a shadow. + * @internal */ setShadow(shadow: boolean) { this.isShadow_ = shadow; @@ -826,6 +839,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 */ setInsertionMarker(insertionMarker: boolean) { this.isInsertionMarker_ = insertionMarker; @@ -868,6 +882,7 @@ export class Block implements IASTNodeLocation, IDeletable { * @param otherBlock The other block to match against. * @param conn The other connection to match. * @return The matching connection on this block, or null. + * @internal */ getMatchingConnection(otherBlock: Block, conn: Connection): Connection|null { const connections = this.getConnections_(true); @@ -1015,6 +1030,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Return all variables referenced by this block. * @return List of variable models. + * @internal */ getVarModels(): VariableModel[] { const vars = []; @@ -1038,6 +1054,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 */ updateVarName(variable: VariableModel) { for (let i = 0, input; input = this.inputList[i]; i++) { diff --git a/core/block_animations.ts b/core/block_animations.ts index 7466bffc2..8201f38fd 100644 --- a/core/block_animations.ts +++ b/core/block_animations.ts @@ -40,6 +40,7 @@ let disconnectGroup: Element = null as AnyDuringMigration; * Play some UI effects (sound, animation) when disposing of a block. * @param block The block being disposed of. * @alias Blockly.blockAnimations.disposeUiEffect + * @internal */ export function disposeUiEffect(block: BlockSvg) { const workspace = block.workspace; @@ -97,6 +98,7 @@ function disposeUiStep( * Play some UI effects (sound, ripple) after a connection has been established. * @param block The block being connected. * @alias Blockly.blockAnimations.connectionUiEffect + * @internal */ export function connectionUiEffect(block: BlockSvg) { const workspace = block.workspace; @@ -154,6 +156,7 @@ function connectionUiStep(ripple: SVGElement, start: Date, scale: number) { * Play some UI effects (sound, animation) when disconnecting a block. * @param block The block being disconnected. * @alias Blockly.blockAnimations.disconnectUiEffect + * @internal */ export function disconnectUiEffect(block: BlockSvg) { block.workspace.getAudioManager().play('disconnect'); @@ -206,6 +209,7 @@ function disconnectUiStep(group: SVGElement, magnitude: number, start: Date) { /** * Stop the disconnect UI animation immediately. * @alias Blockly.blockAnimations.disconnectUiStop + * @internal */ export function disconnectUiStop() { if (disconnectGroup) { diff --git a/core/block_dragger.ts b/core/block_dragger.ts index 7483c8ec2..1ae394695 100644 --- a/core/block_dragger.ts +++ b/core/block_dragger.ts @@ -80,7 +80,10 @@ export class BlockDragger implements IBlockDragger { this.dragIconData_ = initIconData(block); } - /** Sever all links from this object. */ + /** + * Sever all links from this object. + * @internal + */ dispose() { this.dragIconData_.length = 0; diff --git a/core/block_svg.ts b/core/block_svg.ts index 05f76ae69..c5e67c0e3 100644 --- a/core/block_svg.ts +++ b/core/block_svg.ts @@ -109,6 +109,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * An property used internally to reference the block's rendering debugger. + * @internal */ renderingDebugger: BlockRenderingDebug|null = null; @@ -144,6 +145,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, // Create core elements for the block. private svgGroup_: SVGGElement; style: BlockStyle; + /** @internal */ pathObject: IPathObject; override rendered = false; @@ -342,6 +344,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 */ override setParent(newParent: this|null) { const oldParent = this.parentBlock_; @@ -458,6 +461,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() { if (!this.useDragSurface_) { @@ -492,6 +496,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Does nothing if useDragSurface_ is false. * @param newXY The position the block should take on on the workspace canvas, * in workspace coordinates. + * @internal */ moveOffDragSurface(newXY: Coordinate) { if (!this.useDragSurface_) { @@ -508,6 +513,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * drag surface to translate blocks. * This block must be a top-level block. * @param newLoc The location to translate to, in workspace coordinates. + * @internal */ moveDuringDrag(newLoc: Coordinate) { if (this.useDragSurface_) { @@ -696,7 +702,10 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, } } - /** Load the block's help page in a new window. */ + /** + * Load the block's help page in a new window. + * @internal + */ showHelp() { const url = typeof this.helpUrl === 'function' ? this.helpUrl() : this.helpUrl; @@ -731,6 +740,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Show the context menu for this block. * @param e Mouse event. + * @internal */ showContextMenu(e: Event) { const menuOptions = this.generateContextMenu(); @@ -748,6 +758,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * 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 */ moveConnections(dx: number, dy: number) { if (!this.rendered) { @@ -774,6 +785,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 */ setDragging(adding: boolean) { if (adding) { @@ -816,6 +828,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 */ override setShadow(shadow: boolean) { super.setShadow(shadow); @@ -826,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 */ override setInsertionMarker(insertionMarker: boolean) { if (this.isInsertionMarker_ === insertionMarker) { @@ -944,6 +958,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Encode a block for copying. * @return Copy metadata, or null if the block is an insertion marker. + * @internal */ toCopyData(): CopyData|null { if (this.isInsertionMarker_) { @@ -962,7 +977,10 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, }; } - /** Updates the colour of the block to match the block's state. */ + /** + * Updates the colour of the block to match the block's state. + * @internal + */ applyColour() { this.pathObject.applyColour(this); @@ -981,6 +999,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Updates the color of the block (and children) to match the current disabled * state. + * @internal */ updateDisabled() { const children = (this.getChildren(false)); @@ -1191,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 */ setDeleteStyle(enable: boolean) { this.pathObject.updateDraggingDelete(enable); @@ -1254,6 +1274,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * 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 , it will render on top of any other blocks. + * @internal */ bringToFront() { let block = this; @@ -1391,6 +1412,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * 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 */ setConnectionTracking(track: boolean) { if (this.previousConnection) { @@ -1434,6 +1456,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Otherwise, for a non-rendered block return an empty list, and for a * collapsed block don't return inputs connections. * @return Array of connections. + * @internal */ override getConnections_(all: boolean): RenderedConnection[] { const myConnections = []; @@ -1465,6 +1488,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * be returned. If false, this will follow shadows to find the last * connection. * @return The last next connection on the stack, or null. + * @internal */ override lastConnectionInStack(ignoreShadows: boolean): RenderedConnection |null { @@ -1478,6 +1502,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * @param otherBlock The other block to match against. * @param conn The other connection to match. * @return The matching connection on this block, or null. + * @internal */ override getMatchingConnection(otherBlock: Block, conn: Connection): RenderedConnection|null { @@ -1559,6 +1584,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Schedule snapping to grid and bumping neighbours to occur after a brief * delay. + * @internal */ scheduleSnapAndBump() { const block = this; @@ -1585,6 +1611,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * @param sourceConnection The connection on the moving block's stack. * @param targetConnection The connection that should stay stationary as this * block is positioned. + * @internal */ positionNearConnection( sourceConnection: RenderedConnection, @@ -1600,7 +1627,10 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, } } - /** @return The first statement connection or null. */ + /** + * @return The first statement connection or null. + * @internal + */ override getFirstStatementConnection(): RenderedConnection|null { return super.getFirstStatementConnection() as RenderedConnection | null; } @@ -1704,6 +1734,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 */ setCursorSvg(cursorSvg: SVGElement) { this.pathObject.setCursorSvg(cursorSvg); @@ -1713,6 +1744,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 */ setMarkerSvg(markerSvg: SVGElement) { this.pathObject.setMarkerSvg(markerSvg); @@ -1722,6 +1754,7 @@ 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. + * @internal */ getHeightWidth(): {height: number, width: number} { let height = this.height; @@ -1743,6 +1776,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * will be replaced. If a shadow block, it will disappear. Otherwise it will * bump. * @param add True if highlighting should be added. + * @internal */ fadeForReplacement(add: boolean) { this.pathObject.updateReplacementFade(add); @@ -1753,6 +1787,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * to this input. * @param conn The connection on the input to highlight. * @param add True if highlighting should be added. + * @internal */ highlightShapeForInput(conn: Connection, add: boolean) { this.pathObject.updateShapeForInputHighlight(conn, add); diff --git a/core/bubble.ts b/core/bubble.ts index aff2ccd32..1a321861c 100644 --- a/core/bubble.ts +++ b/core/bubble.ts @@ -143,9 +143,10 @@ 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; - arrow_radians_: AnyDuringMigration; + private arrow_radians_: AnyDuringMigration; /** * @param workspace The workspace on which to draw the bubble. @@ -310,6 +311,7 @@ export class Bubble implements IBubble { /** * Show the context menu for this bubble. * @param _e Mouse event. + * @internal */ showContextMenu(_e: Event) {} // NOP on bubbles, but used by the bubble dragger to pass events to @@ -318,6 +320,7 @@ export class Bubble implements IBubble { /** * Get whether this bubble is deletable or not. * @return True if deletable. + * @internal */ isDeletable(): boolean { return false; @@ -394,6 +397,7 @@ export class Bubble implements IBubble { /** * Move this bubble to the top of the stack. * @return Whether or not the bubble has been moved. + * @internal */ promote(): boolean { const svgGroup = this.bubbleGroup_.parentNode; @@ -626,6 +630,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 */ moveTo(x: number, y: number) { this.bubbleGroup_.setAttribute( @@ -635,6 +640,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 */ setDragging(adding: boolean) { if (!adding && this.moveCallback_) { @@ -793,6 +799,7 @@ export class Bubble implements IBubble { * @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. + * @internal */ moveDuringDrag(dragSurface: BlockDragSurfaceSvg, newLoc: Coordinate) { if (dragSurface) { @@ -827,6 +834,7 @@ export class Bubble implements IBubble { * 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 */ setAutoLayout(enable: boolean) { this.autoLayout_ = enable; @@ -857,6 +865,7 @@ 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. + * @internal */ static textToDom(text: string): SVGTextElement { const paragraph = dom.createSvgElement(Svg.TEXT, { @@ -879,6 +888,7 @@ export class Bubble implements IBubble { * @param block The block that the bubble is attached to. * @param iconXY The coordinate of the icon. * @return The non editable bubble. + * @internal */ static createNonEditableBubble( paragraphElement: SVGTextElement, block: BlockSvg, diff --git a/core/bubble_dragger.ts b/core/bubble_dragger.ts index 2066fdfa9..a404ffd34 100644 --- a/core/bubble_dragger.ts +++ b/core/bubble_dragger.ts @@ -80,6 +80,7 @@ export class BubbleDragger { /** * Sever all links from this object. * @suppress {checkTypes} + * @internal */ dispose() { // AnyDuringMigration because: Type 'null' is not assignable to type @@ -95,6 +96,7 @@ export class BubbleDragger { /** * Start dragging a bubble. This includes moving it to the drag surface. + * @internal */ startBubbleDrag() { if (!eventUtils.getGroup()) { @@ -116,6 +118,7 @@ export class BubbleDragger { * @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. + * @internal */ dragBubble(e: Event, currentDragDeltaXY: Coordinate) { const delta = this.pixelsToWorkspaceUnits_(currentDragDeltaXY); @@ -170,6 +173,7 @@ export class BubbleDragger { * @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. + * @internal */ endBubbleDrag(e: Event, currentDragDeltaXY: Coordinate) { // Make sure internal state is fresh. diff --git a/core/clipboard.ts b/core/clipboard.ts index 3474b9310..2788f90ed 100644 --- a/core/clipboard.ts +++ b/core/clipboard.ts @@ -25,6 +25,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 */ export function copy(toCopy: ICopyable) { copyData = toCopy.toCopyData(); @@ -34,6 +35,7 @@ export function copy(toCopy: ICopyable) { * Paste a block or workspace comment on to the main workspace. * @return The pasted thing if the paste was successful, null otherwise. * @alias Blockly.clipboard.paste + * @internal */ export function paste(): ICopyable|null { if (!copyData) { @@ -58,6 +60,7 @@ export function paste(): ICopyable|null { * @return The block or workspace comment that was duplicated, or null if the * duplication failed. * @alias Blockly.clipboard.duplicate + * @internal */ export function duplicate(toDuplicate: ICopyable): ICopyable|null { const oldCopyData = copyData; diff --git a/core/comment.ts b/core/comment.ts index d8a03ed09..bd039963c 100644 --- a/core/comment.ts +++ b/core/comment.ts @@ -365,7 +365,10 @@ export class Comment extends Icon { } } - /** Update the comment's view to match the model. */ + /** + * Update the comment's view to match the model. + * @internal + */ updateText() { if (this.textarea_) { // AnyDuringMigration because: Type 'string | null' is not assignable to diff --git a/core/common.ts b/core/common.ts index 2abbc4a50..edbf2a6fb 100644 --- a/core/common.ts +++ b/core/common.ts @@ -77,6 +77,7 @@ export function getSelected(): ICopyable|null { * programmatically select a block, use `BlockSvg#select`. * @param newSelection The newly selected block. * @alias Blockly.common.setSelected + * @internal */ export function setSelected(newSelection: ICopyable|null) { selected = newSelection; diff --git a/core/connection.ts b/core/connection.ts index 3f0e96875..f65e90966 100644 --- a/core/connection.ts +++ b/core/connection.ts @@ -53,7 +53,10 @@ export class Connection implements IASTNodeLocationWithBlock { /** Connection this connection connects to. Null if not connected. */ targetConnection: Connection|null = null; - /** Has this connection been disposed of? */ + /** + * Has this connection been disposed of? + * @internal + */ disposed = false; /** List of compatible value types. Null if all types are compatible. */ @@ -65,10 +68,16 @@ export class Connection implements IASTNodeLocationWithBlock { // 'Element'. private shadowDom_: Element = null as AnyDuringMigration; - /** Horizontal location of this connection. */ + /** + * Horizontal location of this connection. + * @internal + */ x = 0; - /** Vertical location of this connection. */ + /** + * Vertical location of this connection. + * @internal + */ y = 0; private shadowState_: blocks.State|null = null; @@ -137,7 +146,10 @@ export class Connection implements IASTNodeLocationWithBlock { } } - /** Dispose of this connection and deal with connected blocks. */ + /** + * Dispose of this connection and deal with connected blocks. + * @internal + */ dispose() { // isConnected returns true for shadows and non-shadows. if (this.isConnected()) { @@ -183,6 +195,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Get the workspace's connection type checker object. * @return The connection type checker for the source block's workspace. + * @internal */ getConnectionChecker(): IConnectionChecker { return this.source.workspace.connectionChecker; @@ -193,6 +206,7 @@ export class Connection implements IASTNodeLocationWithBlock { * headless workspaces). * @param _otherConnection Connection that this connection failed to connect * to. + * @internal */ onFailedConnect(_otherConnection: Connection) {} // NOP @@ -411,6 +425,7 @@ export class Connection implements IASTNodeLocationWithBlock { * computed from the rendered positioning. * @param _maxLimit The maximum radius to another connection. * @return List of connections. + * @internal */ neighbours(_maxLimit: number): Connection[] { return []; @@ -420,6 +435,7 @@ 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 * exists. + * @internal */ getParentInput(): Input|null { let parentInput = null; diff --git a/core/connection_db.ts b/core/connection_db.ts index 28a7135a7..458704f74 100644 --- a/core/connection_db.ts +++ b/core/connection_db.ts @@ -51,6 +51,7 @@ export class ConnectionDB { * Add a connection to the database. Should not already exist in the database. * @param connection The connection to be added. * @param yPos The y position used to decide where to insert the connection. + * @internal */ addConnection(connection: RenderedConnection, yPos: number) { const index = this.calculateIndexForYPos_(yPos); diff --git a/core/contextmenu.ts b/core/contextmenu.ts index df67e6776..cf146be6f 100644 --- a/core/contextmenu.ts +++ b/core/contextmenu.ts @@ -260,6 +260,7 @@ export function callbackFactory(block: Block, xml: Element): Function { * @return A menu option, * containing text, enabled, and a callback. * @alias Blockly.ContextMenu.commentDeleteOption + * @internal */ export function commentDeleteOption(comment: WorkspaceCommentSvg): LegacyContextMenuOption { @@ -282,6 +283,7 @@ export function commentDeleteOption(comment: WorkspaceCommentSvg): * @return A menu option, * containing text, enabled, and a callback. * @alias Blockly.ContextMenu.commentDuplicateOption + * @internal */ export function commentDuplicateOption(comment: WorkspaceCommentSvg): LegacyContextMenuOption { @@ -304,6 +306,7 @@ export function commentDuplicateOption(comment: WorkspaceCommentSvg): * @suppress {strictModuleDepCheck,checkTypes} Suppress checks while workspace * comments are not bundled in. * @alias Blockly.ContextMenu.workspaceCommentOption + * @internal */ export function workspaceCommentOption( ws: WorkspaceSvg, e: Event): ContextMenuOption { diff --git a/core/contextmenu_items.ts b/core/contextmenu_items.ts index 1372e65dc..6d840ab41 100644 --- a/core/contextmenu_items.ts +++ b/core/contextmenu_items.ts @@ -576,6 +576,7 @@ function registerBlockOptions_() { * Registers all default context menu items. This should be called once per * instance of ContextMenuRegistry. * @alias Blockly.ContextMenuItems.registerDefaultOptions + * @internal */ export function registerDefaultOptions() { registerWorkspaceOptions_(); diff --git a/core/dropdowndiv.ts b/core/dropdowndiv.ts index 0b5d350e8..1af109545 100644 --- a/core/dropdowndiv.ts +++ b/core/dropdowndiv.ts @@ -117,7 +117,10 @@ export interface PositionMetrics { arrowVisible: boolean; } -/** Create and insert the DOM element for this div. */ +/** + * Create and insert the DOM element for this div. + * @internal + */ export function createDom() { if (div) { return; @@ -296,6 +299,7 @@ function showPositionedByRect( * @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. + * @internal */ export function show( newOwner: AnyDuringMigration|null, rtl: boolean, primaryX: number, @@ -490,6 +494,7 @@ function getPositionTopOfPageMetrics( * @param divWidth The width of the div in px. * @return An object containing metrics for the x positions of the left side of * the DropDownDiv and the arrow. + * @internal */ export function getPositionX( sourceX: number, boundsLeft: number, boundsRight: number, @@ -656,6 +661,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() { // This condition mainly catches the dropdown div when it is being used as a diff --git a/core/events/events_block_change.ts b/core/events/events_block_change.ts index 81e167458..ccd16ae12 100644 --- a/core/events/events_block_change.ts +++ b/core/events/events_block_change.ts @@ -161,6 +161,7 @@ export class BlockChange extends BlockBase { * depending on the block's definition). * @param block The block to get the extra state of. * @return A stringified version of the extra state of the given block. + * @internal */ static getExtraBlockState_(block: BlockSvg): string { if (block.saveExtraState) { diff --git a/core/events/utils.ts b/core/events/utils.ts index e62eb92ec..6f41cf67f 100644 --- a/core/events/utils.ts +++ b/core/events/utils.ts @@ -431,6 +431,7 @@ export function setGroup(state: boolean|string) { * @param block The root block. * @return List of block IDs. * @alias Blockly.Events.utils.getDescendantIds + * @internal */ export function getDescendantIds(block: Block): string[] { const ids = []; diff --git a/core/extensions.ts b/core/extensions.ts index bb78978fe..11af5e8c8 100644 --- a/core/extensions.ts +++ b/core/extensions.ts @@ -345,6 +345,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 */ export function runAfterPageLoad(fn: () => AnyDuringMigration) { if (typeof document !== 'object') { diff --git a/core/field.ts b/core/field.ts index c1803246e..f7253e42a 100644 --- a/core/field.ts +++ b/core/field.ts @@ -148,7 +148,10 @@ export abstract class Field implements IASTNodeLocationSvg, // 'ConstantProvider'. protected constants_: ConstantProvider = null as AnyDuringMigration; - /** Has this field been disposed of? */ + /** + * Has this field been disposed of? + * @internal + */ disposed = false; /** Maximum characters of text to display before adding an ellipsis. */ @@ -174,10 +177,16 @@ export abstract class Field implements IASTNodeLocationSvg, // 'Element'. protected clickTarget_: Element = null as AnyDuringMigration; - /** The prefix field. */ + /** + * The prefix field. + * @internal + */ prefixField: string|null = null; - /** The suffix field. */ + /** + * The suffix field. + * @internal + */ suffixField: string|null = null; /** @@ -286,6 +295,7 @@ export abstract class Field implements IASTNodeLocationSvg, * Initialize everything to render this field. Override * methods initModel and initView rather than this method. * @final + * @internal */ init() { if (this.fieldGroup_) { @@ -305,7 +315,10 @@ export abstract class Field implements IASTNodeLocationSvg, this.initModel(); } - /** Create the block UI for this field. */ + /** + * Create the block UI for this field. + * @internal + */ initView() { this.createBorderRect_(); this.createTextElement_(); @@ -314,6 +327,7 @@ export abstract class Field implements IASTNodeLocationSvg, /** * Initializes the model of the field after it has been installed on a block. * No-op by default. + * @internal */ initModel() {} @@ -368,6 +382,7 @@ export abstract class Field implements IASTNodeLocationSvg, * Sets the field's value based on the given XML element. Should only be * called by Blockly.Xml. * @param fieldElement The element containing info about the field's state. + * @internal */ fromXml(fieldElement: Element) { this.setValue(fieldElement.textContent); @@ -378,6 +393,7 @@ export abstract class Field implements IASTNodeLocationSvg, * @param fieldElement The element to populate with info about the field's * state. * @return The element containing info about the field's state. + * @internal */ toXml(fieldElement: Element): Element { fieldElement.textContent = this.getValue(); @@ -391,6 +407,7 @@ export abstract class Field implements IASTNodeLocationSvg, * normally just saves a reference to some state (eg variable fields) it * should instead serialize the full state of the thing being referenced. * @return JSON serializable state. + * @internal */ saveState(_doFullSerialization?: boolean): AnyDuringMigration { const legacyState = this.saveLegacyState(Field); @@ -404,6 +421,7 @@ export abstract class Field implements IASTNodeLocationSvg, * Sets the field's state based on the given state value. Should only be * called by the serialization system. * @param state The state we want to apply to the field. + * @internal */ loadState(state: AnyDuringMigration) { if (this.loadLegacyState(Field, state)) { @@ -456,6 +474,7 @@ export abstract class Field implements IASTNodeLocationSvg, /** * Dispose of all DOM objects and events belonging to this editable field. + * @internal */ dispose() { dropDownDiv.hideIfOwner(this); @@ -562,6 +581,7 @@ export abstract class Field implements IASTNodeLocationSvg, * Sets whether this editable field is visible or not. Should only be called * by input.setVisible. * @param visible True if visible. + * @internal */ setVisible(visible: boolean) { if (this.visible_ === visible) { @@ -613,6 +633,7 @@ export abstract class Field implements IASTNodeLocationSvg, /** * Updates the field to match the colour/style of the block. Should only be * called by BlockSvg.applyColour(). + * @internal */ applyColour() {} // Non-abstract sub-classes may wish to implement this. See FieldDropdown. @@ -636,6 +657,7 @@ export abstract class Field implements IASTNodeLocationSvg, * @param opt_e Optional mouse event that triggered the field to open, or * undefined if triggered programmatically. * @final + * @internal */ showEditor(opt_e?: Event) { if (this.isClickable()) { @@ -766,6 +788,7 @@ export abstract class Field implements IASTNodeLocationSvg, * scaling. * @return An object with top, bottom, left, and right in pixels relative to * the top left corner of the page (window coordinates). + * @internal */ getScaledBBox(): Rect { let scaledWidth; @@ -860,6 +883,7 @@ export abstract class Field implements IASTNodeLocationSvg, * rerender this field and adjust for any sizing changes. * Other fields on the same block will not rerender, because their sizes have * already been recorded. + * @internal */ markDirty() { this.isDirty_ = true; @@ -873,6 +897,7 @@ export abstract class Field implements IASTNodeLocationSvg, * rerender this field and adjust for any sizing changes. * Other fields on the same block will not rerender, because their sizes have * already been recorded. + * @internal */ forceRerender() { this.isDirty_ = true; @@ -1075,6 +1100,7 @@ export abstract class Field implements IASTNodeLocationSvg, * to be handled differently during serialization and deserialization. * Subclasses may override this. * @return True if this field has any variable references. + * @internal */ referencesVariables(): boolean { return false; @@ -1083,6 +1109,7 @@ export abstract class Field implements IASTNodeLocationSvg, /** * Refresh the variable name referenced by this field if this field references * variables. + * @internal */ refreshVariableName() {} // NOP @@ -1091,6 +1118,7 @@ export abstract class Field implements IASTNodeLocationSvg, * Search through the list of inputs and their fields in order to find the * parent input of a field. * @return The input that the field belongs to. + * @internal */ getParentInput(): Input { let parentInput = null; @@ -1140,6 +1168,7 @@ export abstract class Field implements IASTNodeLocationSvg, /** * Add the cursor SVG to this fields SVG group. * @param cursorSvg The SVG root of the cursor to be added to the field group. + * @internal */ setCursorSvg(cursorSvg: SVGElement) { if (!cursorSvg) { @@ -1156,6 +1185,7 @@ export abstract class Field implements IASTNodeLocationSvg, /** * Add the marker SVG to this fields SVG group. * @param markerSvg The SVG root of the marker to be added to the field group. + * @internal */ setMarkerSvg(markerSvg: SVGElement) { if (!markerSvg) { diff --git a/core/field_angle.ts b/core/field_angle.ts index 9686d2627..bd61b0a0a 100644 --- a/core/field_angle.ts +++ b/core/field_angle.ts @@ -212,7 +212,10 @@ export class FieldAngle extends FieldTextInput { } } - /** Create the block UI for this field. */ + /** + * Create the block UI for this field. + * @internal + */ override initView() { super.initView(); // Add the degree symbol to the left of the number, even in RTL (issue @@ -505,6 +508,7 @@ export class FieldAngle extends FieldTextInput { * @param options A JSON object with options (angle). * @return The new field instance. * @nocollapse + * @internal */ static override fromJson(options: AnyDuringMigration): FieldAngle { // `this` might be a subclass of FieldAngle if that class doesn't override diff --git a/core/field_checkbox.ts b/core/field_checkbox.ts index 1b5b4f6b7..76673b4e1 100644 --- a/core/field_checkbox.ts +++ b/core/field_checkbox.ts @@ -100,6 +100,7 @@ export class FieldCheckbox extends Field { /** * Saves this field's value. * @return The boolean value held by this field. + * @internal */ override saveState(): AnyDuringMigration { const legacyState = this.saveLegacyState(FieldCheckbox); @@ -109,7 +110,10 @@ export class FieldCheckbox extends Field { return this.getValueBoolean(); } - /** Create the block UI for this checkbox. */ + /** + * Create the block UI for this checkbox. + * @internal + */ override initView() { super.initView(); @@ -217,6 +221,7 @@ export class FieldCheckbox extends Field { * @param options A JSON object with options (checked). * @return The new field instance. * @nocollapse + * @internal */ static fromJson(options: AnyDuringMigration): FieldCheckbox { // `this` might be a subclass of FieldCheckbox if that class doesn't diff --git a/core/field_colour.ts b/core/field_colour.ts index c61df51f3..1a6664a59 100644 --- a/core/field_colour.ts +++ b/core/field_colour.ts @@ -187,7 +187,10 @@ export class FieldColour extends Field { } } - /** Create the block UI for this colour field. */ + /** + * Create the block UI for this colour field. + * @internal + */ override initView() { this.size_ = new Size( this.getConstants()!.FIELD_COLOUR_DEFAULT_WIDTH, @@ -569,6 +572,7 @@ export class FieldColour extends Field { * @param options A JSON object with options (colour). * @return The new field instance. * @nocollapse + * @internal */ static fromJson(options: AnyDuringMigration): FieldColour { // `this` might be a subclass of FieldColour if that class doesn't override diff --git a/core/field_dropdown.ts b/core/field_dropdown.ts index 1b450cdd2..cc4e8fbd2 100644 --- a/core/field_dropdown.ts +++ b/core/field_dropdown.ts @@ -88,11 +88,13 @@ export class FieldDropdown extends Field { /** * The prefix field label, of common words set after options are trimmed. + * @internal */ override prefixField: string|null = null; /** * The suffix field label, of common words set after options are trimmed. + * @internal */ override suffixField: string|null = null; // TODO(b/109816955): remove '!', see go/strict-prop-init-fix. @@ -157,6 +159,7 @@ export class FieldDropdown extends Field { * Sets the field's value based on the given XML element. Should only be * called by Blockly.Xml. * @param fieldElement The element containing info about the field's state. + * @internal */ override fromXml(fieldElement: Element) { if (this.isOptionListDynamic()) { @@ -168,6 +171,7 @@ export class FieldDropdown extends Field { /** * Sets the field's value based on the given state. * @param state The state to apply to the dropdown field. + * @internal */ override loadState(state: AnyDuringMigration) { if (this.loadLegacyState(FieldDropdown, state)) { @@ -179,7 +183,10 @@ export class FieldDropdown extends Field { this.setValue(state); } - /** Create the block UI for this dropdown. */ + /** + * Create the block UI for this dropdown. + * @internal + */ override initView() { if (this.shouldAddBorderRect_()) { this.createBorderRect_(); @@ -481,7 +488,10 @@ export class FieldDropdown extends Field { } } - /** Updates the dropdown arrow to match the colour/style of the block. */ + /** + * Updates the dropdown arrow to match the colour/style of the block. + * @internal + */ override applyColour() { const style = (this.sourceBlock_ as BlockSvg).style; if (this.borderRect_) { @@ -649,6 +659,7 @@ export class FieldDropdown extends Field { * @param options A JSON object with options (options). * @return The new field instance. * @nocollapse + * @internal */ static fromJson(options: AnyDuringMigration): FieldDropdown { // `this` might be a subclass of FieldDropdown if that class doesn't diff --git a/core/field_image.ts b/core/field_image.ts index 7fd935f97..9ff494550 100644 --- a/core/field_image.ts +++ b/core/field_image.ts @@ -143,7 +143,10 @@ export class FieldImage extends Field { this.altText_ = parsing.replaceMessageReferences(config['alt']) || ''; } - /** Create the block UI for this image. */ + /** + * Create the block UI for this image. + * @internal + */ override initView() { this.imageElement_ = dom.createSvgElement( Svg.IMAGE, { @@ -247,6 +250,7 @@ export class FieldImage extends Field { * flipRtl). * @return The new field instance. * @nocollapse + * @internal */ static fromJson(options: AnyDuringMigration): FieldImage { // `this` might be a subclass of FieldImage if that class doesn't override diff --git a/core/field_label.ts b/core/field_label.ts index b770f80c6..bc47a1505 100644 --- a/core/field_label.ts +++ b/core/field_label.ts @@ -75,7 +75,10 @@ export class FieldLabel extends Field { this.class_ = config['class']; } - /** Create block UI for this label. */ + /** + * Create block UI for this label. + * @internal + */ override initView() { this.createTextElement_(); if (this.class_) { @@ -120,6 +123,7 @@ export class FieldLabel extends Field { * @param options A JSON object with options (text, and class). * @return The new field instance. * @nocollapse + * @internal */ static fromJson(options: AnyDuringMigration): FieldLabel { const text = parsing.replaceMessageReferences(options['text']); diff --git a/core/field_label_serializable.ts b/core/field_label_serializable.ts index 2f45cfef5..51b300b05 100644 --- a/core/field_label_serializable.ts +++ b/core/field_label_serializable.ts @@ -62,6 +62,7 @@ export class FieldLabelSerializable extends FieldLabel { * @param options A JSON object with options (text, and class). * @return The new field instance. * @nocollapse + * @internal */ static override fromJson(options: AnyDuringMigration): FieldLabelSerializable { diff --git a/core/field_multilineinput.ts b/core/field_multilineinput.ts index 063ec9b96..505ad58ca 100644 --- a/core/field_multilineinput.ts +++ b/core/field_multilineinput.ts @@ -94,6 +94,7 @@ export class FieldMultilineInput extends FieldTextInput { * @param fieldElement The element to populate with info about the field's * state. * @return The element containing info about the field's state. + * @internal */ override toXml(fieldElement: Element): Element { // Replace '\n' characters with HTML-escaped equivalent ' '. This is @@ -109,6 +110,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 */ override fromXml(fieldElement: Element) { this.setValue(fieldElement.textContent!.replace(/ /g, '\n')); @@ -117,6 +119,7 @@ export class FieldMultilineInput extends FieldTextInput { /** * Saves this field's value. * @return The state of this field. + * @internal */ override saveState(): AnyDuringMigration { const legacyState = this.saveLegacyState(FieldMultilineInput); @@ -129,6 +132,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 */ override loadState(state: AnyDuringMigration) { if (this.loadLegacyState(Field, state)) { @@ -137,7 +141,10 @@ export class FieldMultilineInput extends FieldTextInput { this.setValue(state); } - /** Create the block UI for this field. */ + /** + * Create the block UI for this field. + * @internal + */ override initView() { this.createBorderRect_(); this.textGroup_ = dom.createSvgElement( @@ -416,6 +423,7 @@ export class FieldMultilineInput extends FieldTextInput { * @param options A JSON object with options (text, and spellcheck). * @return The new field instance. * @nocollapse + * @internal */ static override fromJson(options: AnyDuringMigration): FieldMultilineInput { const text = parsing.replaceMessageReferences(options['text']); diff --git a/core/field_number.ts b/core/field_number.ts index 9951aae98..c4f037441 100644 --- a/core/field_number.ts +++ b/core/field_number.ts @@ -300,6 +300,7 @@ export class FieldNumber extends FieldTextInput { * @param options A JSON object with options (value, min, max, and precision). * @return The new field instance. * @nocollapse + * @internal */ static override fromJson(options: AnyDuringMigration): FieldNumber { // `this` might be a subclass of FieldNumber if that class doesn't override diff --git a/core/field_registry.ts b/core/field_registry.ts index 4f09b9802..54e0a6d96 100644 --- a/core/field_registry.ts +++ b/core/field_registry.ts @@ -59,6 +59,7 @@ export function unregister(type: string) { * @return The new field instance or null if a field wasn't found with the given * type name * @alias Blockly.fieldRegistry.fromJson + * @internal */ export function fromJson(options: AnyDuringMigration): Field|null { const fieldObject = diff --git a/core/field_textinput.ts b/core/field_textinput.ts index cecd92135..79c657291 100644 --- a/core/field_textinput.ts +++ b/core/field_textinput.ts @@ -133,6 +133,7 @@ export class FieldTextInput extends Field { } } + /** @internal */ override initView() { if (this.getConstants()!.FULL_BLOCK_FIELDS) { // Step one: figure out if this is the only field on this block. @@ -215,7 +216,10 @@ export class FieldTextInput extends Field { } } - /** Updates text field to match the colour/style of the block. */ + /** + * Updates text field to match the colour/style of the block. + * @internal + */ override applyColour() { if (this.sourceBlock_ && this.getConstants()!.FULL_BLOCK_FIELDS) { if (this.borderRect_) { @@ -564,6 +568,7 @@ export class FieldTextInput extends Field { * @param options A JSON object with options (text, and spellcheck). * @return The new field instance. * @nocollapse + * @internal */ static fromJson(options: AnyDuringMigration): FieldTextInput { const text = parsing.replaceMessageReferences(options['text']); diff --git a/core/field_variable.ts b/core/field_variable.ts index e3816c983..c4f4741d9 100644 --- a/core/field_variable.ts +++ b/core/field_variable.ts @@ -136,6 +136,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() { if (this.variable_) { @@ -210,6 +211,7 @@ export class FieldVariable extends FieldDropdown { * 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. + * @internal */ override saveState(doFullSerialization?: boolean): AnyDuringMigration { const legacyState = this.saveLegacyState(FieldVariable); @@ -229,6 +231,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 */ override loadState(state: AnyDuringMigration) { if (this.loadLegacyState(FieldVariable, state)) { @@ -274,6 +277,7 @@ export class FieldVariable extends FieldDropdown { * 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. + * @internal */ getVariable(): VariableModel|null { return this.variable_; @@ -426,6 +430,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() { this.forceRerender(); @@ -461,6 +466,7 @@ export class FieldVariable extends FieldDropdown { * Overrides referencesVariables(), indicating this field refers to a * variable. * @return True. + * @internal */ override referencesVariables(): boolean { return true; @@ -473,6 +479,7 @@ export class FieldVariable extends FieldDropdown { * defaultType). * @return The new field instance. * @nocollapse + * @internal */ static override fromJson(options: AnyDuringMigration): FieldVariable { const varName = parsing.replaceMessageReferences(options['variable']); diff --git a/core/flyout_base.ts b/core/flyout_base.ts index 169d3415c..37a579ded 100644 --- a/core/flyout_base.ts +++ b/core/flyout_base.ts @@ -130,6 +130,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout { RTL: boolean; /** * Whether the flyout should be laid out horizontally or not. + * @internal */ horizontalLayout: boolean = false; protected toolboxPosition_: number; @@ -173,7 +174,8 @@ export abstract class Flyout extends DeleteArea implements IFlyout { protected readonly tabWidth_: number; /** - * The target workspace + * The target workspace. + * @internal */ targetWorkspace!: WorkspaceSvg; /** @@ -287,6 +289,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout { /** * A map from blocks to the rects which are beneath them to act as input * targets. + * @internal */ this.rectMap_ = new WeakMap(); @@ -440,6 +443,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout { /** * Get the workspace inside the flyout. * @return The workspace inside the flyout. + * @internal */ getWorkspace(): WorkspaceSvg { return this.workspace_; @@ -932,6 +936,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout { * @param block The block to copy from the flyout. * @return True if you can create a new instance of the block, false * otherwise. + * @internal */ isBlockCreatable(block: BlockSvg): boolean { return block.isEnabled(); @@ -942,6 +947,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout { * @param originalBlock The block to copy from the flyout. * @return The newly created block. * @throws {Error} if something went wrong with deserialization. + * @internal */ createBlock(originalBlock: BlockSvg): BlockSvg { let newBlock = null; @@ -1087,6 +1093,7 @@ export abstract class Flyout extends DeleteArea implements IFlyout { /** * @return True if this flyout may be scrolled with a scrollbar or * by dragging. + * @internal */ isScrollable(): boolean { return this.workspace_.scrollbar ? this.workspace_.scrollbar.isVisible() : diff --git a/core/flyout_button.ts b/core/flyout_button.ts index ae7f9eb26..8136cfb85 100644 --- a/core/flyout_button.ts +++ b/core/flyout_button.ts @@ -64,6 +64,7 @@ export class FlyoutButton { * @param targetWorkspace The flyout's target workspace. * @param json The JSON specifying the label/button. * @param isLabel Whether this button should be styled as a label. + * @internal */ constructor( private readonly workspace: WorkspaceSvg, @@ -208,6 +209,7 @@ export class FlyoutButton { /** * Location of the button. * @return x, y coordinates. + * @internal */ getPosition(): Coordinate { return this.position_; diff --git a/core/flyout_horizontal.ts b/core/flyout_horizontal.ts index 859f65cde..c0a08752c 100644 --- a/core/flyout_horizontal.ts +++ b/core/flyout_horizontal.ts @@ -287,6 +287,7 @@ export class HorizontalFlyout extends Flyout { * @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. + * @internal */ override isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean { const dx = currentDragDeltaXY.x; diff --git a/core/flyout_vertical.ts b/core/flyout_vertical.ts index 1545eef84..9286ccba8 100644 --- a/core/flyout_vertical.ts +++ b/core/flyout_vertical.ts @@ -270,6 +270,7 @@ export class VerticalFlyout extends Flyout { * @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. + * @internal */ override isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean { const dx = currentDragDeltaXY.x; diff --git a/core/gesture.ts b/core/gesture.ts index 6bba2dd67..368b66431 100644 --- a/core/gesture.ts +++ b/core/gesture.ts @@ -192,7 +192,10 @@ export class Gesture { this.healStack_ = !internalConstants.DRAG_STACK; } - /** Sever all links from this object. */ + /** + * Sever all links from this object. + * @internal + */ dispose() { Touch.clearTouchIdentifier(); Tooltip.unblock(); @@ -415,6 +418,7 @@ export class Gesture { * Start a gesture: update the workspace to indicate that a gesture is in * progress and bind mousemove and mouseup handlers. * @param e A mouse down or touch start event. + * @internal */ doStart(e: Event) { if (browserEvents.isTargetInput(e)) { @@ -474,6 +478,7 @@ export class Gesture { /** * Bind gesture events. * @param e A mouse down or touch start event. + * @internal */ bindMouseEvents(e: Event) { this.onMoveWrapper_ = browserEvents.conditionalBind( @@ -488,6 +493,7 @@ export class Gesture { /** * Handle a mouse move or touch move event. * @param e A mouse move or touch move event. + * @internal */ handleMove(e: Event) { this.updateFromEvent_(e); @@ -505,6 +511,7 @@ export class Gesture { /** * Handle a mouse up or touch end event. * @param e A mouse up or touch end event. + * @internal */ handleUp(e: Event) { this.updateFromEvent_(e); @@ -546,6 +553,7 @@ export class Gesture { /** * Cancel an in-progress gesture. If a workspace or block drag is in * progress, end the drag at the most recent location. + * @internal */ cancel() { // Disposing of a block cancels in-progress drags, but dragging to a delete @@ -568,6 +576,7 @@ export class Gesture { /** * Handle a real or faked right-click event by showing a context menu. * @param e A mouse move or touch move event. + * @internal */ handleRightClick(e: Event) { if (this.targetBlock_) { @@ -592,6 +601,7 @@ export class Gesture { * Handle a mousedown/touchstart event on a workspace. * @param e A mouse down or touch start event. * @param ws The workspace the event hit. + * @internal */ handleWsStart(e: Event, ws: WorkspaceSvg) { if (this.hasStarted_) { @@ -617,6 +627,7 @@ export class Gesture { * Handle a mousedown/touchstart event on a flyout. * @param e A mouse down or touch start event. * @param flyout The flyout the event hit. + * @internal */ handleFlyoutStart(e: Event, flyout: IFlyout) { if (this.hasStarted_) { @@ -632,6 +643,7 @@ export class Gesture { * Handle a mousedown/touchstart event on a block. * @param e A mouse down or touch start event. * @param block The block the event hit. + * @internal */ handleBlockStart(e: Event, block: BlockSvg) { if (this.hasStarted_) { @@ -647,6 +659,7 @@ export class Gesture { * Handle a mousedown/touchstart event on a bubble. * @param e A mouse down or touch start event. * @param bubble The bubble the event hit. + * @internal */ handleBubbleStart(e: Event, bubble: IBubble) { if (this.hasStarted_) { @@ -732,6 +745,7 @@ export class Gesture { /** * Record the field that a gesture started on. * @param field The field the gesture started on. + * @internal */ setStartField(field: Field) { if (this.hasStarted_) { @@ -747,6 +761,7 @@ export class Gesture { /** * Record the bubble that a gesture started on * @param bubble The bubble the gesture started on. + * @internal */ setStartBubble(bubble: IBubble) { if (!this.startBubble_) { @@ -758,6 +773,7 @@ export class Gesture { * Record the block that a gesture started on, and set the target block * appropriately. * @param block The block the gesture started on. + * @internal */ setStartBlock(block: BlockSvg) { // If the gesture already went through a bubble, don't set the start block. @@ -866,6 +882,7 @@ export class Gesture { * This function is called externally to block actions that cannot be taken * mid-drag (e.g. using the keyboard to delete the selected blocks). * @return True if this gesture is a drag of a workspace or block. + * @internal */ isDragging(): boolean { return this.isDraggingWorkspace_ || this.isDraggingBlock_ || @@ -877,6 +894,7 @@ export class Gesture { * has a corresponding mouse up, but in reality it is possible to lose a * mouse up, leaving an in-process gesture hanging. * @return Whether this gesture was a click on a workspace. + * @internal */ hasStarted(): boolean { return this.hasStarted_; @@ -886,6 +904,7 @@ export class Gesture { * Get a list of the insertion markers that currently exist. Block drags have * 0, 1, or 2 insertion markers. * @return A possibly empty list of insertion marker blocks. + * @internal */ getInsertionMarkers(): BlockSvg[] { if (this.blockDragger_) { diff --git a/core/grid.ts b/core/grid.ts index 57102f059..2ccd37473 100644 --- a/core/grid.ts +++ b/core/grid.ts @@ -64,6 +64,7 @@ export class Grid { /** * Dispose of this grid and unlink from the DOM. * @suppress {checkTypes} + * @internal */ dispose() { // AnyDuringMigration because: Type 'null' is not assignable to type @@ -74,6 +75,7 @@ export class Grid { /** * Whether blocks should snap to the grid, based on the initial configuration. * @return True if blocks should snap, false otherwise. + * @internal */ shouldSnap(): boolean { return this.snapToGrid_; @@ -82,6 +84,7 @@ export class Grid { /** * Get the spacing of the grid points (in px). * @return The spacing of the grid points. + * @internal */ getSpacing(): number { return this.spacing_; @@ -91,6 +94,7 @@ export class Grid { * Get the ID of the pattern element, which should be randomized to avoid * conflicts with other Blockly instances on the page. * @return The pattern ID. + * @internal */ getPatternId(): string { return this.pattern.id; @@ -99,6 +103,7 @@ export class Grid { /** * Update the grid with a new scale. * @param scale The new workspace scale. + * @internal */ update(scale: number) { this.scale_ = scale; @@ -161,6 +166,7 @@ export class Grid { * visible. * @param x The new x position of the grid (in px). * @param y The new y position of the grid (in px). + * @internal */ moveTo(x: number, y: number) { // AnyDuringMigration because: Argument of type 'number' is not assignable @@ -183,6 +189,7 @@ export class Grid { * @param gridOptions The object containing grid configuration. * @param defs The root SVG element for this workspace's defs. * @return The SVG element for the grid pattern. + * @internal */ static createDom( rnd: string, gridOptions: AnyDuringMigration, diff --git a/core/input.ts b/core/input.ts index 2ce0d47c7..ce83d6b42 100644 --- a/core/input.ts +++ b/core/input.ts @@ -181,6 +181,7 @@ export class Input { * Should only be used to collapse/uncollapse a block. * @param visible True if visible. * @return List of blocks to render. + * @internal */ setVisible(visible: boolean): BlockSvg[] { // Note: Currently there are only unit tests for block.setCollapsed() @@ -211,7 +212,10 @@ export class Input { return renderList; } - /** Mark all fields on this input as dirty. */ + /** + * Mark all fields on this input as dirty. + * @internal + */ markDirty() { for (let y = 0, field; field = this.fieldRow[y]; y++) { field.markDirty(); diff --git a/core/insertion_marker_manager.ts b/core/insertion_marker_manager.ts index abbc06e71..c7b13ff24 100644 --- a/core/insertion_marker_manager.ts +++ b/core/insertion_marker_manager.ts @@ -167,7 +167,10 @@ export class InsertionMarkerManager { this.availableConnections_ = this.initAvailableConnections_(); } - /** Sever all links from this object. */ + /** + * Sever all links from this object. + * @internal + */ dispose() { this.availableConnections_.length = 0; @@ -187,6 +190,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() { this.availableConnections_ = this.initAvailableConnections_(); @@ -196,6 +200,7 @@ 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. + * @internal */ wouldDeleteBlock(): boolean { return this.wouldDeleteBlock_; @@ -205,6 +210,7 @@ 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. + * @internal */ wouldConnectBlock(): boolean { return !!this.closestConnection_; @@ -213,6 +219,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() { if (this.closestConnection_) { @@ -243,6 +250,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 */ update(dxy: Coordinate, dragTarget: IDragTarget|null) { const candidate = this.getCandidate_(dxy); @@ -769,6 +777,7 @@ 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. + * @internal */ getInsertionMarkers(): BlockSvg[] { const result = []; diff --git a/core/interfaces/i_copyable.ts b/core/interfaces/i_copyable.ts index 7cd224485..a5a82028d 100644 --- a/core/interfaces/i_copyable.ts +++ b/core/interfaces/i_copyable.ts @@ -27,6 +27,7 @@ export interface ICopyable extends ISelectable { /** * Encode for copying. * @return Copy metadata. + * @internal */ toCopyData: AnyDuringMigration; } diff --git a/core/interfaces/i_metrics_manager.ts b/core/interfaces/i_metrics_manager.ts index dd267ac10..f94532ba7 100644 --- a/core/interfaces/i_metrics_manager.ts +++ b/core/interfaces/i_metrics_manager.ts @@ -34,6 +34,7 @@ export interface IMetricsManager { /** * Returns whether the scroll area has fixed edges. * @return Whether the scroll area has fixed edges. + * @internal */ hasFixedEdges: AnyDuringMigration; diff --git a/core/interfaces/i_toolbox_item.ts b/core/interfaces/i_toolbox_item.ts index 2353f7598..7827444ab 100644 --- a/core/interfaces/i_toolbox_item.ts +++ b/core/interfaces/i_toolbox_item.ts @@ -50,6 +50,7 @@ export interface IToolboxItem { /** * Gets the nested level of the category. * @return The nested level of the category. + * @internal */ getLevel(): number; diff --git a/core/internal_constants.ts b/core/internal_constants.ts index 3668b91e8..3a53ee55e 100644 --- a/core/internal_constants.ts +++ b/core/internal_constants.ts @@ -23,6 +23,7 @@ import {ConnectionType} from './connection_type.js'; /** * Number of characters to truncate a collapsed block to. * @alias Blockly.internalConstants.COLLAPSE_CHARS + * @internal */ export const COLLAPSE_CHARS = 30; @@ -30,12 +31,14 @@ export const COLLAPSE_CHARS = 30; * When dragging a block out of a stack, split the stack in two (true), or drag * out the block healing the stack (false). * @alias Blockly.internalConstants.DRAG_STACK + * @internal */ export const DRAG_STACK = true; /** * Lookup table for determining the opposite type of a connection. * @alias Blockly.internalConstants.OPPOSITE_TYPE + * @internal */ export const OPPOSITE_TYPE: number[] = []; OPPOSITE_TYPE[ConnectionType.INPUT_VALUE] = ConnectionType.OUTPUT_VALUE; @@ -50,6 +53,7 @@ OPPOSITE_TYPE[ConnectionType.PREVIOUS_STATEMENT] = * This string indicates that this option in the dropdown is 'Rename * variable...' and if selected, should trigger the prompt to rename a variable. * @alias Blockly.internalConstants.RENAME_VARIABLE_ID + * @internal */ export const RENAME_VARIABLE_ID = 'RENAME_VARIABLE_ID'; @@ -58,5 +62,6 @@ export const RENAME_VARIABLE_ID = 'RENAME_VARIABLE_ID'; * This string indicates that this option in the dropdown is 'Delete the "%1" * variable' and if selected, should trigger the prompt to delete a variable. * @alias Blockly.internalConstants.DELETE_VARIABLE_ID + * @internal */ export const DELETE_VARIABLE_ID = 'DELETE_VARIABLE_ID'; diff --git a/core/keyboard_nav/ast_node.ts b/core/keyboard_nav/ast_node.ts index 5a55cc816..dfc49dcc4 100644 --- a/core/keyboard_nav/ast_node.ts +++ b/core/keyboard_nav/ast_node.ts @@ -145,6 +145,7 @@ export class ASTNode { /** * Whether the node points to a connection. * @return [description] + * @internal */ isConnection(): boolean { return this.isConnection_; diff --git a/core/keyboard_nav/marker.ts b/core/keyboard_nav/marker.ts index db1c6bc60..292e3816f 100644 --- a/core/keyboard_nav/marker.ts +++ b/core/keyboard_nav/marker.ts @@ -90,7 +90,10 @@ export class Marker { } } - /** Redraw the current marker. */ + /** + * Redraw the current marker. + * @internal + */ draw() { if (this.drawer_) { this.drawer_.draw(this.curNode_, this.curNode_); diff --git a/core/marker_manager.ts b/core/marker_manager.ts index 37f92dc28..f092fb424 100644 --- a/core/marker_manager.ts +++ b/core/marker_manager.ts @@ -41,7 +41,10 @@ export class MarkerManager { /** The marker's SVG element. */ private markerSvg_: SVGElement|null = null; - /** @param workspace The workspace for the marker manager. */ + /** + * @param workspace The workspace for the marker manager. + * @internal + */ constructor(private readonly workspace: WorkspaceSvg) { /** The map of markers for the workspace. */ this.markers_ = Object.create(null); @@ -118,6 +121,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 */ setCursorSvg(cursorSvg: SVGElement|null) { if (!cursorSvg) { @@ -133,6 +137,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 */ setMarkerSvg(markerSvg: SVGElement|null) { if (!markerSvg) { @@ -150,7 +155,10 @@ export class MarkerManager { } } - /** Redraw the attached cursor SVG if needed. */ + /** + * Redraw the attached cursor SVG if needed. + * @internal + */ updateMarkers() { if (this.workspace.keyboardAccessibilityMode && this.cursorSvg_) { this.workspace.getCursor()!.draw(); @@ -161,6 +169,7 @@ export class MarkerManager { * Dispose of the marker manager. * Go through and delete all markers associated with this marker manager. * @suppress {checkTypes} + * @internal */ dispose() { const markerIds = Object.keys(this.markers_); diff --git a/core/menu.ts b/core/menu.ts index 8ffecd1c8..7dc72a895 100644 --- a/core/menu.ts +++ b/core/menu.ts @@ -79,6 +79,7 @@ export class Menu { /** * Add a new menu item to the bottom of this menu. * @param menuItem Menu item to append. + * @internal */ addChild(menuItem: MenuItem) { this.menuItems_.push(menuItem); @@ -121,12 +122,16 @@ export class Menu { /** * Gets the menu's element. * @return The DOM element. + * @internal */ getElement(): Element|null { return this.element_; } - /** Focus the menu element. */ + /** + * Focus the menu element. + * @internal + */ focus() { const el = this.getElement(); if (el) { @@ -151,6 +156,7 @@ export class Menu { /** * Set the menu accessibility role. * @param roleName role name. + * @internal */ setRole(roleName: aria.Role) { this.roleName_ = roleName; @@ -222,6 +228,7 @@ export class Menu { /** * Highlights the given menu item, or clears highlighting if null. * @param item Item to highlight, or null. + * @internal */ setHighlighted(item: MenuItem|null) { const currentHighlighted = this.highlightedItem_; @@ -244,6 +251,7 @@ export class Menu { /** * Highlights the next highlightable item (or the first if nothing is * currently highlighted). + * @internal */ highlightNext() { // AnyDuringMigration because: Argument of type 'MenuItem | null' is not @@ -256,6 +264,7 @@ export class Menu { /** * Highlights the previous highlightable item (or the last if nothing is * currently highlighted). + * @internal */ highlightPrevious() { // AnyDuringMigration because: Argument of type 'MenuItem | null' is not @@ -430,6 +439,7 @@ export class Menu { /** * Get the size of a rendered menu. * @return Object with width and height properties. + * @internal */ getSize(): Size { const menuDom = this.getElement(); diff --git a/core/menuitem.ts b/core/menuitem.ts index 4798c9f36..c85e649a7 100644 --- a/core/menuitem.ts +++ b/core/menuitem.ts @@ -113,6 +113,7 @@ export class MenuItem { /** * Gets the menu item's element. * @return The DOM element. + * @internal */ getElement(): Element|null { return this.element_; @@ -121,6 +122,7 @@ export class MenuItem { /** * Gets the unique ID for this menu item. * @return Unique component ID. + * @internal */ getId(): string { return this.element_!.id; @@ -129,6 +131,7 @@ export class MenuItem { /** * Gets the value associated with the menu item. * @return value Value associated with the menu item. + * @internal */ getValue(): AnyDuringMigration { return this.opt_value; @@ -137,6 +140,7 @@ export class MenuItem { /** * Set menu item's rendering direction. * @param rtl True if RTL, false if LTR. + * @internal */ setRightToLeft(rtl: boolean) { this.rightToLeft_ = rtl; @@ -145,6 +149,7 @@ export class MenuItem { /** * Set the menu item's accessibility role. * @param roleName Role name. + * @internal */ setRole(roleName: aria.Role) { this.roleName_ = roleName; @@ -154,6 +159,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 */ setCheckable(checkable: boolean) { this.checkable_ = checkable; @@ -162,6 +168,7 @@ export class MenuItem { /** * Checks or unchecks the component. * @param checked Whether to check or uncheck the component. + * @internal */ setChecked(checked: boolean) { this.checked_ = checked; @@ -170,6 +177,7 @@ export class MenuItem { /** * Highlights or unhighlights the component. * @param highlight Whether to highlight or unhighlight the component. + * @internal */ setHighlighted(highlight: boolean) { this.highlight_ = highlight; @@ -193,6 +201,7 @@ export class MenuItem { /** * Returns true if the menu item is enabled, false otherwise. * @return Whether the menu item is enabled. + * @internal */ isEnabled(): boolean { return this.enabled_; @@ -201,6 +210,7 @@ export class MenuItem { /** * Enables or disables the menu item. * @param enabled Whether to enable or disable the menu item. + * @internal */ setEnabled(enabled: boolean) { this.enabled_ = enabled; @@ -209,6 +219,7 @@ export class MenuItem { /** * Performs the appropriate action when the menu item is activated * by the user. + * @internal */ performAction() { if (this.isEnabled() && this.actionHandler_) { @@ -221,6 +232,7 @@ export class MenuItem { * `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 */ onAction(fn: (p1: MenuItem) => AnyDuringMigration, obj: AnyDuringMigration) { this.actionHandler_ = fn.bind(obj); diff --git a/core/metrics_manager.ts b/core/metrics_manager.ts index f5b158c4f..69551e368 100644 --- a/core/metrics_manager.ts +++ b/core/metrics_manager.ts @@ -203,6 +203,7 @@ export class MetricsManager implements IMetricsManager { /** * Returns whether the scroll area has fixed edges. * @return Whether the scroll area has fixed edges. + * @internal */ hasFixedEdges(): boolean { // This exists for optimization of bump logic. diff --git a/core/mutator.ts b/core/mutator.ts index ca57cb457..d7fb37303 100644 --- a/core/mutator.ts +++ b/core/mutator.ts @@ -94,6 +94,7 @@ export class Mutator extends Icon { /** * Set the block this mutator is associated with. * @param block The block associated with this mutator. + * @internal */ setBlock(block: BlockSvg) { this.block_ = block; @@ -103,6 +104,7 @@ 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 * mutator isn't open. + * @internal */ getWorkspace(): WorkspaceSvg|null { return this.workspace_; diff --git a/core/positionable_helpers.ts b/core/positionable_helpers.ts index f752c8405..7d0b771f1 100644 --- a/core/positionable_helpers.ts +++ b/core/positionable_helpers.ts @@ -32,6 +32,7 @@ import {WorkspaceSvg} from './workspace_svg.js'; /** * Enum for vertical positioning. * @alias Blockly.uiPosition.verticalPosition + * @internal */ export enum verticalPosition { TOP, @@ -41,6 +42,7 @@ export enum verticalPosition { /** * Enum for horizontal positioning. * @alias Blockly.uiPosition.horizontalPosition + * @internal */ export enum horizontalPosition { LEFT, @@ -50,6 +52,7 @@ export enum horizontalPosition { /** * An object defining a horizontal and vertical positioning. * @alias Blockly.uiPosition.Position + * @internal */ export interface Position { horizontal: horizontalPosition; @@ -59,6 +62,7 @@ export interface Position { /** * Enum for bump rules to use for dealing with collisions. * @alias Blockly.uiPosition.bumpDirection + * @internal */ export enum bumpDirection { UP, @@ -78,6 +82,7 @@ export enum bumpDirection { * @param workspace The workspace. * @return The suggested start position. * @alias Blockly.uiPosition.getStartPositionRect + * @internal */ export function getStartPositionRect( position: Position, size: Size, horizontalPadding: number, @@ -125,6 +130,7 @@ export function getStartPositionRect( * @param metrics The workspace metrics. * @return The suggested corner position. * @alias Blockly.uiPosition.getCornerOppositeToolbox + * @internal */ export function getCornerOppositeToolbox( workspace: WorkspaceSvg, metrics: UiMetrics): Position { @@ -150,6 +156,7 @@ export function getCornerOppositeToolbox( * elements already placed. * @return The suggested position rectangle. * @alias Blockly.uiPosition.bumpPositionRect + * @internal */ export function bumpPositionRect( startRect: Rect, margin: number, bumpDir: bumpDirection, diff --git a/core/procedures.ts b/core/procedures.ts index 5f4267d6e..d9ed46668 100644 --- a/core/procedures.ts +++ b/core/procedures.ts @@ -327,6 +327,7 @@ function updateMutatorFlyout(workspace: WorkspaceSvg) { * update and adds a mutator change listener to the mutator workspace. * @param e The event that triggered this listener. * @alias Blockly.Procedures.mutatorOpenListener + * @internal */ export function mutatorOpenListener(e: Abstract) { if (e.type !== eventUtils.BUBBLE_OPEN) { diff --git a/core/registry.ts b/core/registry.ts index 9327f8a3a..c4d5c4594 100644 --- a/core/registry.ts +++ b/core/registry.ts @@ -87,6 +87,7 @@ export class Type { new Type('flyoutsHorizontalToolbox'); static METRICS_MANAGER = new Type('metricsManager'); static BLOCK_DRAGGER = new Type('blockDragger'); + /** @internal */ static SERIALIZER = new Type('serializer'); /** @param name The name of the registry type. */ diff --git a/core/rendered_connection.ts b/core/rendered_connection.ts index 0c9df83ec..c218f0dbb 100644 --- a/core/rendered_connection.ts +++ b/core/rendered_connection.ts @@ -112,6 +112,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() { super.dispose(); @@ -152,6 +153,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 */ bumpAwayFrom(staticConnection: RenderedConnection) { if (this.sourceBlock_.workspace.isDragging()) { @@ -245,6 +247,7 @@ 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. + * @internal */ getOffsetInBlock(): Coordinate { return this.offsetInBlock_; @@ -252,6 +255,7 @@ export class RenderedConnection extends Connection { /** * Move the blocks on either side of this connection right next to each other. + * @internal */ tighten() { const dx = this.targetConnection!.x - this.x; @@ -334,6 +338,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 */ setTracking(doTracking: boolean) { if (doTracking && @@ -363,6 +368,7 @@ export class RenderedConnection extends Connection { * collapsed. * * Also closes down-stream icons/bubbles. + * @internal */ stopTrackingAll() { this.setTracking(false); @@ -432,6 +438,7 @@ export class RenderedConnection extends Connection { * attempted connection fails. * @param otherConnection Connection that this connection failed to connect * to. + * @internal */ override onFailedConnect(otherConnection: Connection) { const block = this.getSourceBlock(); @@ -494,6 +501,7 @@ export class RenderedConnection extends Connection { * @param maxLimit The maximum radius to another connection, in workspace * units. * @return List of connections. + * @internal */ override neighbours(maxLimit: number): Connection[] { return this.dbOpposite_.getNeighbours(this, maxLimit); diff --git a/core/renderers/common/block_rendering.ts b/core/renderers/common/block_rendering.ts index cf09f07c6..21f5c64b1 100644 --- a/core/renderers/common/block_rendering.ts +++ b/core/renderers/common/block_rendering.ts @@ -58,6 +58,7 @@ import {Renderer} from './renderer.js'; * @return Whether the debugger is turned on. * @alias Blockly.blockRendering.isDebuggerEnabled * @deprecated + * @internal */ export function isDebuggerEnabled(): boolean { deprecation.warn( @@ -90,6 +91,7 @@ export function unregister(name: string) { * Turn on the blocks debugger. * @alias Blockly.blockRendering.startDebugger * @deprecated + * @internal */ export function startDebugger() { deprecation.warn( @@ -103,6 +105,7 @@ export function startDebugger() { * Turn off the blocks debugger. * @alias Blockly.blockRendering.stopDebugger * @deprecated + * @internal */ export function stopDebugger() { deprecation.warn( @@ -120,6 +123,7 @@ export function stopDebugger() { * @return The new instance of a renderer. * Already initialized. * @alias Blockly.blockRendering.init + * @internal */ export function init( name: string, theme: Theme, opt_rendererOverrides?: object): Renderer { diff --git a/core/renderers/common/constants.ts b/core/renderers/common/constants.ts index c65bd8e8f..68940e7e6 100644 --- a/core/renderers/common/constants.ts +++ b/core/renderers/common/constants.ts @@ -244,7 +244,10 @@ export class ConstantProvider { /** A field's border rect Y padding. */ FIELD_BORDER_RECT_Y_PADDING = 3; - /** The backing colour of a field's border rect. */ + /** + * The backing colour of a field's border rect. + * @internal + */ FIELD_BORDER_RECT_COLOUR = '#fff'; FIELD_TEXT_BASELINE_CENTER: boolean; FIELD_DROPDOWN_BORDER_RECT_HEIGHT: number; @@ -285,6 +288,7 @@ export class ConstantProvider { FIELD_COLOUR_DEFAULT_WIDTH = 26; FIELD_COLOUR_DEFAULT_HEIGHT: number; FIELD_CHECKBOX_X_OFFSET: number; + /** @internal */ randomIdentifier: string; /** @@ -295,6 +299,7 @@ export class ConstantProvider { /** * The ID of the emboss filter, or the empty string if no filter is set. + * @internal */ embossFilterId = ''; @@ -305,6 +310,7 @@ export class ConstantProvider { /** * The ID of the disabled pattern, or the empty string if no pattern is set. + * @internal */ disabledPatternId = ''; @@ -332,39 +338,65 @@ export class ConstantProvider { // 'HTMLStyleElement'. private cssNode_: HTMLStyleElement = null as AnyDuringMigration; - /** Cursor colour. */ + /** + * Cursor colour. + * @internal + */ CURSOR_COLOUR = '#cc0a0a'; - /** Immovable marker colour. */ + /** + * Immovable marker colour. + * @internal + */ MARKER_COLOUR = '#4286f4'; - /** Width of the horizontal cursor. */ + /** + * Width of the horizontal cursor. + * @internal + */ CURSOR_WS_WIDTH = 100; - /** Height of the horizontal cursor. */ + /** + * Height of the horizontal cursor. + * @internal + */ WS_CURSOR_HEIGHT = 5; - /** Padding around a stack. */ + /** + * Padding around a stack. + * @internal + */ CURSOR_STACK_PADDING = 10; - /** Padding around a block. */ + /** + * Padding around a block. + * @internal + */ CURSOR_BLOCK_PADDING = 2; - /** Stroke of the cursor. */ + /** + * 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; /** * 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. */ + /** + * The insertion marker opacity. + * @internal + */ INSERTION_MARKER_OPACITY = 0.2; /** Enum for connection shapes. */ @@ -382,8 +414,10 @@ export class ConstantProvider { // TODO(b/109816955): remove '!', see go/strict-prop-init-fix. OUTSIDE_CORNERS!: OutsideCorners; // TODO(b/109816955): remove '!', see go/strict-prop-init-fix. + /** @internal */ blockStyles!: {[key: string]: BlockStyle}; + /** @internal */ constructor() { /** * Offset from the top of the row for placing fields on inline input rows @@ -463,12 +497,14 @@ 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); } /** * Initialize shape objects based on the constants set in the constructor. + * @internal */ init() { /** @@ -502,6 +538,7 @@ export class ConstantProvider { /** * Refresh constants properties that depend on the theme. * @param theme The current workspace theme. + * @internal */ setTheme(theme: Theme) { /** The block styles map. */ @@ -575,6 +612,7 @@ export class ConstantProvider { * @param colour #RRGGBB colour string. * @return An object containing the style and an autogenerated name for that * style. + * @internal */ getBlockStyleForColour(colour: string): {style: BlockStyle, name: string} { const name = 'auto_' + colour; @@ -659,6 +697,7 @@ export class ConstantProvider { /** * Dispose of this constants provider. * Delete all DOM elements that this provider created. + * @internal */ dispose() { if (this.embossFilter_) { @@ -678,6 +717,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about collapsed * block indicators. + * @internal */ makeJaggedTeeth(): JaggedTeeth { const height = this.JAGGED_TEETH_HEIGHT; @@ -693,6 +733,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about start hats. + * @internal */ makeStartHat(): StartHat { const height = this.START_HAT_HEIGHT; @@ -708,6 +749,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about puzzle tabs. + * @internal */ makePuzzleTab(): PuzzleTab { const width = this.TAB_WIDTH; @@ -764,6 +806,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about notches. + * @internal */ makeNotch(): Notch { const width = this.NOTCH_WIDTH; @@ -799,6 +842,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about inside * corners. + * @internal */ makeInsideCorners(): InsideCorners { const radius = this.CORNER_RADIUS; @@ -820,6 +864,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about outside * corners. + * @internal */ makeOutsideCorners(): OutsideCorners { const radius = this.CORNER_RADIUS; @@ -853,6 +898,7 @@ export class ConstantProvider { * type of the connection. * @param connection The connection to find a shape object for * @return The shape object for the connection. + * @internal */ shapeFor(connection: RenderedConnection): Shape { switch (connection.type) { @@ -874,6 +920,7 @@ export class ConstantProvider { * @param selector The CSS selector to use. * @suppress {strictModuleDepCheck} Debug renderer only included in * playground. + * @internal */ createDom(svg: SVGElement, tagName: string, selector: string) { this.injectCSS_(tagName, selector); diff --git a/core/renderers/common/debug.ts b/core/renderers/common/debug.ts index 61d830e2a..7b4407fde 100644 --- a/core/renderers/common/debug.ts +++ b/core/renderers/common/debug.ts @@ -24,6 +24,7 @@ let useDebugger = false; * Returns whether the debugger is turned on. * @return Whether the debugger is turned on. * @alias Blockly.blockRendering.debug.isDebuggerEnabled + * @internal */ export function isDebuggerEnabled(): boolean { return useDebugger; @@ -34,6 +35,7 @@ export function isDebuggerEnabled(): boolean { * @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. + * @internal */ export function startDebugger() { deprecation.warn( @@ -48,6 +50,7 @@ export function startDebugger() { * @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. + * @internal */ export function stopDebugger() { deprecation.warn( diff --git a/core/renderers/common/debugger.ts b/core/renderers/common/debugger.ts index 5ddb99164..c23d829e8 100644 --- a/core/renderers/common/debugger.ts +++ b/core/renderers/common/debugger.ts @@ -75,10 +75,16 @@ export class Debug { private randomColour_ = ''; - /** @param constants The renderer's constants. */ + /** + * @param constants The renderer's constants. + * @internal + */ constructor(private readonly constants: ConstantProvider) {} - /** Remove all elements the this object created on the last pass. */ + /** + * Remove all elements the this object created on the last pass. + * @internal + */ clearElems() { for (let i = 0; i < this.debugElements_.length; i++) { const elem = this.debugElements_[i]; @@ -93,6 +99,7 @@ export class Debug { * @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. + * @internal */ drawSpacerRow(row: Row, cursorY: number, isRtl: boolean) { if (!Debug.config.rowSpacers) { @@ -125,6 +132,7 @@ export class Debug { * @param elem The spacer to render. * @param rowHeight The height of the container row. * @param isRtl Whether the block is rendered RTL. + * @internal */ drawSpacerElem(elem: InRowSpacer, rowHeight: number, isRtl: boolean) { if (!Debug.config.elemSpacers) { @@ -157,6 +165,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 */ drawRenderedElem(elem: Measurable, isRtl: boolean) { if (Debug.config.elems) { @@ -209,6 +218,7 @@ export class Debug { * @param conn The connection to circle. * @suppress {visibility} Suppress visibility of conn.offsetInBlock_ since * this is a debug module. + * @internal */ drawConnection(conn: RenderedConnection) { if (!Debug.config.connections) { @@ -256,6 +266,7 @@ export class Debug { * @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. + * @internal */ drawRenderedRow(row: Row, cursorY: number, isRtl: boolean) { if (!Debug.config.rows) { @@ -302,6 +313,7 @@ export class Debug { * @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. + * @internal */ drawRowWithElements(row: Row, cursorY: number, isRtl: boolean) { for (let i = 0; i < row.elements.length; i++) { @@ -322,6 +334,7 @@ export class Debug { /** * Draw a debug rectangle around the entire block. * @param info Rendering information about the block to debug. + * @internal */ drawBoundingBox(info: RenderInfo) { if (!Debug.config.blockBounds) { @@ -367,6 +380,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 */ drawDebug(block: BlockSvg, info: RenderInfo) { this.clearElems(); @@ -412,6 +426,7 @@ export class Debug { /** * Show a debug filter to highlight that a block has been rendered. * @param svgPath The block's SVG path. + * @internal */ drawRender(svgPath: SVGElement) { if (!Debug.config.render) { diff --git a/core/renderers/common/drawer.ts b/core/renderers/common/drawer.ts index 83f14134a..6cee9d963 100644 --- a/core/renderers/common/drawer.ts +++ b/core/renderers/common/drawer.ts @@ -56,6 +56,7 @@ export class Drawer { * @param block The block to render. * @param info An object containing all information needed to render this * block. + * @internal */ constructor(block: BlockSvg, info: RenderInfo) { this.block_ = block; @@ -74,6 +75,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() { this.hideHiddenIcons_(); diff --git a/core/renderers/common/i_path_object.ts b/core/renderers/common/i_path_object.ts index 2e6cd7fc4..45a63a126 100644 --- a/core/renderers/common/i_path_object.ts +++ b/core/renderers/common/i_path_object.ts @@ -64,6 +64,7 @@ export interface IPathObject { /** * Set the path generated by the renderer onto the respective SVG element. * @param pathString The path. + * @internal */ setPath: AnyDuringMigration; @@ -71,22 +72,28 @@ 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 */ applyColour: AnyDuringMigration; /** * Update the style. * @param blockStyle The block style to use. + * @internal */ setStyle: AnyDuringMigration; - /** Flip the SVG paths in RTL. */ + /** + * 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 */ setCursorSvg: AnyDuringMigration; @@ -94,6 +101,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 */ setMarkerSvg: AnyDuringMigration; @@ -101,12 +109,14 @@ 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 */ updateHighlighted: AnyDuringMigration; /** * Add or remove styling showing that a block is selected. * @param enable True if selection is enabled, false otherwise. + * @internal */ updateSelected: AnyDuringMigration; @@ -114,18 +124,21 @@ 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 */ updateDraggingDelete: AnyDuringMigration; /** * 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 */ updateInsertionMarker: AnyDuringMigration; /** * Add or remove styling showing that a block is movable. * @param enable True if the block is movable, false otherwise. + * @internal */ updateMovable: AnyDuringMigration; @@ -134,6 +147,7 @@ export interface IPathObject { * 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 */ updateReplacementFade: AnyDuringMigration; @@ -142,6 +156,7 @@ export interface IPathObject { * 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 */ updateShapeForInputHighlight: AnyDuringMigration; } diff --git a/core/renderers/common/info.ts b/core/renderers/common/info.ts index 356417676..fe8191251 100644 --- a/core/renderers/common/info.ts +++ b/core/renderers/common/info.ts @@ -99,6 +99,7 @@ export class RenderInfo { /** * @param renderer The renderer in use. * @param block The block to measure. + * @internal */ constructor(protected readonly renderer: Renderer, block: BlockSvg) { this.block_ = block; @@ -150,6 +151,7 @@ export class RenderInfo { /** * Get the block renderer in use. * @return The block renderer in use. + * @internal */ getRenderer(): Renderer { return this.renderer; @@ -162,6 +164,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() { this.createRows_(); @@ -227,7 +230,10 @@ export class RenderInfo { this.rows.push(this.bottomRow); } - /** Create all non-spacer elements that belong on the top row. */ + /** + * Create all non-spacer elements that belong on the top row. + * @internal + */ populateTopRow_() { const hasPrevious = !!this.block_.previousConnection; const hasHat = (this.block_.hat ? this.block_.hat === 'cap' : @@ -268,7 +274,10 @@ export class RenderInfo { this.topRow.elements.push(new cornerClass(this.constants_, 'right')); } - /** Create all non-spacer elements that belong on the bottom row. */ + /** + * Create all non-spacer elements that belong on the bottom row. + * @internal + */ populateBottomRow_() { this.bottomRow.hasNextConnection = !!this.block_.nextConnection; diff --git a/core/renderers/common/marker_svg.ts b/core/renderers/common/marker_svg.ts index d6bb11596..4f69c4684 100644 --- a/core/renderers/common/marker_svg.ts +++ b/core/renderers/common/marker_svg.ts @@ -126,6 +126,7 @@ export class MarkerSvg { /** * Create the DOM element for the marker. * @return The marker controls SVG group. + * @internal */ createDom(): SVGElement { const className = this.isCursor() ? CURSOR_CLASS : MARKER_CLASS; diff --git a/core/renderers/common/path_object.ts b/core/renderers/common/path_object.ts index 143ee3ad5..d68486796 100644 --- a/core/renderers/common/path_object.ts +++ b/core/renderers/common/path_object.ts @@ -40,11 +40,13 @@ import {IPathObject} from './i_path_object.js'; */ export class PathObject implements IPathObject { svgRoot: AnyDuringMigration; + /** @internal */ svgPath: SVGElement; /** * 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 // 'SVGElement'. @@ -53,19 +55,27 @@ 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 // 'SVGElement'. markerSvg: SVGElement = null as AnyDuringMigration; + /** @internal */ + constants: ConstantProvider; + /** @internal */ + style: BlockStyle; + /** * @param root The root SVG element. * @param style The style object to use for colouring. * @param constants The renderer's constants. + * @internal */ constructor( - root: SVGElement, public style: BlockStyle, - public constants: ConstantProvider) { + root: SVGElement, style: BlockStyle, constants: ConstantProvider) { + this.constants = constants; + this.style = style; this.svgRoot = root; /** The primary path of the block. */ @@ -76,12 +86,16 @@ export class PathObject implements IPathObject { /** * Set the path generated by the renderer onto the respective SVG element. * @param pathString The path. + * @internal */ setPath(pathString: string) { this.svgPath.setAttribute('d', pathString); } - /** Flip the SVG paths in RTL. */ + /** + * Flip the SVG paths in RTL. + * @internal + */ flipRTL() { // Mirror the block's path. this.svgPath.setAttribute('transform', 'scale(-1 1)'); @@ -91,6 +105,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 */ setCursorSvg(cursorSvg: SVGElement) { if (!cursorSvg) { @@ -108,6 +123,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 */ setMarkerSvg(markerSvg: SVGElement) { if (!markerSvg) { @@ -129,6 +145,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 */ applyColour(block: BlockSvg) { this.svgPath.setAttribute('stroke', this.style.colourTertiary); @@ -141,6 +158,7 @@ export class PathObject implements IPathObject { /** * Set the style. * @param blockStyle The block style to use. + * @internal */ setStyle(blockStyle: BlockStyle) { this.style = blockStyle; @@ -164,6 +182,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 */ updateHighlighted(enable: boolean) { if (enable) { @@ -200,6 +219,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 */ updateSelected(enable: boolean) { this.setClass_('blocklySelected', enable); @@ -209,6 +229,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 */ updateDraggingDelete(enable: boolean) { this.setClass_('blocklyDraggingDelete', enable); @@ -217,6 +238,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 */ updateInsertionMarker(enable: boolean) { this.setClass_('blocklyInsertionMarker', enable); @@ -225,6 +247,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 */ updateMovable(enable: boolean) { this.setClass_('blocklyDraggable', enable); @@ -235,6 +258,7 @@ export class PathObject implements IPathObject { * 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 */ updateReplacementFade(enable: boolean) { this.setClass_('blocklyReplaceable', enable); @@ -245,6 +269,7 @@ export class PathObject implements IPathObject { * 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 */ updateShapeForInputHighlight(_conn: Connection, _enable: boolean) {} } diff --git a/core/renderers/common/renderer.ts b/core/renderers/common/renderer.ts index 83375fe34..b8839dcbf 100644 --- a/core/renderers/common/renderer.ts +++ b/core/renderers/common/renderer.ts @@ -52,15 +52,27 @@ export class Renderer implements IRegistrable { /** The renderer's constant provider. */ protected constants_!: ConstantProvider; - /** Rendering constant overrides, passed in through options. */ + /** @internal */ + name: string; + + /** + * Rendering constant overrides, passed in through options. + * @internal + */ overrides: object|null = null; - /** @param name The renderer name. */ - constructor(public name: string) {} + /** + * @param name The renderer name. + * @internal + */ + constructor(name: string) { + this.name = name; + } /** * Gets the class name that identifies this renderer. * @return The CSS class name. + * @internal */ getClassName(): string { return this.name + '-renderer'; @@ -70,6 +82,7 @@ export class Renderer implements IRegistrable { * Initialize the renderer. * @param theme The workspace theme object. * @param opt_rendererOverrides Rendering constant overrides. + * @internal */ init(theme: Theme, opt_rendererOverrides?: object) { this.constants_ = this.makeConstants_(); @@ -85,6 +98,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 */ createDom(svg: SVGElement, theme: Theme) { this.constants_.createDom( @@ -96,6 +110,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 */ refreshDom(svg: SVGElement, theme: Theme) { const previousConstants = this.getConstants(); @@ -114,6 +129,7 @@ export class Renderer implements IRegistrable { /** * Dispose of this renderer. * Delete all DOM elements that this renderer and its constants created. + * @internal */ dispose() { if (this.constants_) { @@ -164,6 +180,7 @@ export class Renderer implements IRegistrable { * @param workspace The workspace the marker belongs to. * @param marker The marker. * @return The object in charge of drawing the marker. + * @internal */ makeMarkerDrawer(workspace: WorkspaceSvg, marker: Marker): MarkerSvg { return new MarkerSvg(workspace, this.getConstants(), marker); @@ -174,6 +191,7 @@ export class Renderer implements IRegistrable { * @param root The root SVG element. * @param style The style object to use for colouring. * @return The renderer path object. + * @internal */ makePathObject(root: SVGElement, style: BlockStyle): IPathObject { return new PathObject(root, style, (this.constants_)); @@ -183,6 +201,7 @@ 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. + * @internal */ getConstants(): ConstantProvider { return this.constants_; @@ -192,6 +211,7 @@ 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. + * @internal */ shouldHighlightConnection(_conn: Connection): boolean { return true; @@ -207,6 +227,7 @@ export class Renderer implements IRegistrable { * @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. + * @internal */ orphanCanConnectAtEnd( topBlock: BlockSvg, orphanBlock: BlockSvg, localType: number): boolean { @@ -224,6 +245,7 @@ export class Renderer implements IRegistrable { * @param local The connection currently being dragged. * @param topBlock The block currently being dragged. * @return The preview type to display. + * @internal */ getConnectionPreviewMethod( closest: RenderedConnection, local: RenderedConnection, @@ -244,6 +266,7 @@ export class Renderer implements IRegistrable { /** * Render the block. * @param block The block to render. + * @internal */ render(block: BlockSvg) { if (debug.isDebuggerEnabled() && !block.renderingDebugger) { diff --git a/core/renderers/geras/constants.ts b/core/renderers/geras/constants.ts index a3ee2f3ef..d4f997a41 100644 --- a/core/renderers/geras/constants.ts +++ b/core/renderers/geras/constants.ts @@ -38,6 +38,7 @@ export class ConstantProvider extends BaseConstantProvider { MAX_BOTTOM_WIDTH = 30; override STATEMENT_BOTTOM_SPACER: AnyDuringMigration; + /** @internal */ constructor() { super(); diff --git a/core/renderers/geras/drawer.ts b/core/renderers/geras/drawer.ts index 074cda967..b4b7a7e59 100644 --- a/core/renderers/geras/drawer.ts +++ b/core/renderers/geras/drawer.ts @@ -46,6 +46,7 @@ export class Drawer extends BaseDrawer { * @param block The block to render. * @param info An object containing all information needed to render this * block. + * @internal */ constructor(block: BlockSvg, info: RenderInfo) { super(block, info); diff --git a/core/renderers/geras/highlight_constants.ts b/core/renderers/geras/highlight_constants.ts index 36bbcbdeb..8f7d8fb32 100644 --- a/core/renderers/geras/highlight_constants.ts +++ b/core/renderers/geras/highlight_constants.ts @@ -89,19 +89,24 @@ export class HighlightConstantProvider { // TODO(b/109816955): remove '!', see go/strict-prop-init-fix. START_HAT!: StartHat; - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(constants: ConstantProvider) { /** The renderer's constant provider. */ this.constantProvider = constants; /** * 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); } /** * Initialize shape objects based on the constants set in the constructor. + * @internal */ init() { /** @@ -143,6 +148,7 @@ export class HighlightConstantProvider { /** * @return An object containing sizing and path information about inside * corner highlights. + * @internal */ makeInsideCorner(): InsideCorner { const radius = this.constantProvider.CORNER_RADIUS; @@ -186,6 +192,7 @@ export class HighlightConstantProvider { /** * @return An object containing sizing and path information about outside * corner highlights. + * @internal */ makeOutsideCorner(): OutsideCorner { const radius = this.constantProvider.CORNER_RADIUS; @@ -234,6 +241,7 @@ export class HighlightConstantProvider { /** * @return An object containing sizing and path information about puzzle tab * highlights. + * @internal */ makePuzzleTab(): PuzzleTab { const width = this.constantProvider.TAB_WIDTH; @@ -283,6 +291,7 @@ export class HighlightConstantProvider { /** * @return An object containing sizing and path information about notch * highlights. + * @internal */ makeNotch(): Notch { // This is only for the previous connection. @@ -294,6 +303,7 @@ export class HighlightConstantProvider { /** * @return An object containing sizing and path information about collapsed * block edge highlights. + * @internal */ makeJaggedTeeth(): JaggedTeeth { const pathLeft = svgPaths.lineTo(5.1, 2.6) + svgPaths.moveBy(-10.2, 6.8) + @@ -304,6 +314,7 @@ export class HighlightConstantProvider { /** * @return An object containing sizing and path information about start * highlights. + * @internal */ makeStartHat(): StartHat { const hatHeight = this.constantProvider.START_HAT.height; diff --git a/core/renderers/geras/highlighter.ts b/core/renderers/geras/highlighter.ts index 24e27cb5d..1246c8cca 100644 --- a/core/renderers/geras/highlighter.ts +++ b/core/renderers/geras/highlighter.ts @@ -70,6 +70,7 @@ export class Highlighter { /** * @param info An object containing all information needed to render this * block. + * @internal */ constructor(info: RenderInfo) { this.info_ = info; @@ -96,6 +97,7 @@ export class Highlighter { /** * Get the steps for the highlight path. * @return The steps for the highlight path. + * @internal */ getPath(): string { return this.steps_ + '\n' + this.inlineSteps_; @@ -104,6 +106,7 @@ export class Highlighter { /** * Add a highlight to the top corner of a block. * @param row The top row of the block. + * @internal */ drawTopCorner(row: TopRow) { this.steps_ += svgPaths.moveBy(row.xPos, this.info_.startY); @@ -133,6 +136,7 @@ export class Highlighter { /** * Add a highlight on a jagged edge for a collapsed block. * @param row The row to highlight. + * @internal */ drawJaggedEdge_(row: Row) { if (this.info_.RTL) { @@ -146,6 +150,7 @@ export class Highlighter { /** * Add a highlight on a value input. * @param row The row the input belongs to. + * @internal */ drawValueInput(row: Row) { const input = row.getLastInput() as InlineInput; @@ -166,6 +171,7 @@ export class Highlighter { /** * Add a highlight on a statement input. * @param row The row to highlight. + * @internal */ drawStatementInput(row: Row) { const input = row.getLastInput(); @@ -188,6 +194,7 @@ export class Highlighter { /** * Add a highlight on the right side of a row. * @param row The row to highlight. + * @internal */ drawRightSideRow(row: Row) { const rightEdge = row.xPos + row.width - this.highlightOffset_; @@ -206,6 +213,7 @@ export class Highlighter { /** * Add a highlight to the bottom row. * @param row The row to highlight. + * @internal */ drawBottomRow(row: BottomRow) { // Highlight the vertical edge of the bottom row on the input side. @@ -226,7 +234,10 @@ export class Highlighter { } } - /** Draw the highlight on the left side of the block. */ + /** + * Draw the highlight on the left side of the block. + * @internal + */ drawLeft() { const outputConnection = this.info_.outputConnection; if (outputConnection) { @@ -259,6 +270,7 @@ export class Highlighter { /** * Add a highlight to an inline input. * @param input The input to highlight. + * @internal */ drawInlineInput(input: InlineInput) { const offset = this.highlightOffset_; diff --git a/core/renderers/geras/info.ts b/core/renderers/geras/info.ts index 589c334db..f85855acc 100644 --- a/core/renderers/geras/info.ts +++ b/core/renderers/geras/info.ts @@ -61,6 +61,7 @@ export class RenderInfo extends BaseRenderInfo { /** * @param renderer The renderer in use. * @param block The block to measure. + * @internal */ constructor(renderer: Renderer, block: BlockSvg) { super(renderer, block); @@ -70,6 +71,7 @@ export class RenderInfo extends BaseRenderInfo { /** * Get the block renderer in use. * @return The block renderer in use. + * @internal */ override getRenderer(): Renderer { return this.renderer; diff --git a/core/renderers/geras/measurables/inline_input.ts b/core/renderers/geras/measurables/inline_input.ts index c4dac4d36..78afbf7ff 100644 --- a/core/renderers/geras/measurables/inline_input.ts +++ b/core/renderers/geras/measurables/inline_input.ts @@ -37,6 +37,7 @@ export class InlineInput extends BaseInlineInput { /** * @param constants The rendering constants provider. * @param input The inline input to measure and store information for. + * @internal */ constructor(constants: BaseConstantProvider, input: Input) { super(constants, input); diff --git a/core/renderers/geras/measurables/statement_input.ts b/core/renderers/geras/measurables/statement_input.ts index f2969ba6b..580f1a06c 100644 --- a/core/renderers/geras/measurables/statement_input.ts +++ b/core/renderers/geras/measurables/statement_input.ts @@ -37,6 +37,7 @@ export class StatementInput extends BaseStatementInput { /** * @param constants The rendering constants provider. * @param input The statement input to measure and store information for. + * @internal */ constructor(constants: BaseConstantProvider, input: Input) { super(constants, input); diff --git a/core/renderers/geras/path_object.ts b/core/renderers/geras/path_object.ts index b6e3445a8..d2a9141f5 100644 --- a/core/renderers/geras/path_object.ts +++ b/core/renderers/geras/path_object.ts @@ -36,10 +36,15 @@ import {ConstantProvider} from './constants.js'; * @alias Blockly.geras.PathObject */ export class PathObject extends BasePathObject { + /** @internal */ svgPathDark: SVGElement; + /** @internal */ svgPathLight: SVGElement; - /** The colour of the dark path on the block in '#RRGGBB' format. */ + /** + * The colour of the dark path on the block in '#RRGGBB' format. + * @internal + */ colourDark = '#000000'; override style: AnyDuringMigration; @@ -47,6 +52,7 @@ export class PathObject extends BasePathObject { * @param root The root SVG element. * @param style The style object to use for colouring. * @param constants The renderer's constants. + * @internal */ constructor( root: SVGElement, style: BlockStyle, @@ -74,6 +80,7 @@ export class PathObject extends BasePathObject { /** * Set the highlight path generated by the renderer onto the SVG element. * @param highlightPath The highlight path. + * @internal */ setHighlightPath(highlightPath: string) { this.svgPathLight.setAttribute('d', highlightPath); diff --git a/core/renderers/geras/renderer.ts b/core/renderers/geras/renderer.ts index 08179fdaa..f90c70eb7 100644 --- a/core/renderers/geras/renderer.ts +++ b/core/renderers/geras/renderer.ts @@ -45,7 +45,10 @@ export class Renderer extends BaseRenderer { private highlightConstants_: HighlightConstantProvider = null as AnyDuringMigration; - /** @param name The renderer name. */ + /** + * @param name The renderer name. + * @internal + */ constructor(name: string) { super(name); } @@ -53,6 +56,7 @@ export class Renderer extends BaseRenderer { /** * Initialize the renderer. Geras has a highlight provider in addition to * the normal constant provider. + * @internal */ override init(theme: Theme, opt_rendererOverrides: AnyDuringMigration) { super.init(theme, opt_rendererOverrides); @@ -95,6 +99,7 @@ export class Renderer extends BaseRenderer { * @param root The root SVG element. * @param style The style object to use for colouring. * @return The renderer path object. + * @internal */ override makePathObject(root: SVGElement, style: BlockStyle): PathObject { return new PathObject( @@ -113,6 +118,7 @@ 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. + * @internal */ getHighlightConstants(): HighlightConstantProvider { return this.highlightConstants_; diff --git a/core/renderers/measurables/base.ts b/core/renderers/measurables/base.ts index 9ce34df69..660d0b17c 100644 --- a/core/renderers/measurables/base.ts +++ b/core/renderers/measurables/base.ts @@ -37,7 +37,10 @@ export class Measurable { centerline = 0; notchOffset: number; - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(protected readonly constants: ConstantProvider) { this.type = Types.NONE; diff --git a/core/renderers/measurables/bottom_row.ts b/core/renderers/measurables/bottom_row.ts index 2fc174707..81c717449 100644 --- a/core/renderers/measurables/bottom_row.ts +++ b/core/renderers/measurables/bottom_row.ts @@ -37,16 +37,23 @@ import {Types} from './types.js'; * @alias Blockly.blockRendering.BottomRow */ export class BottomRow extends Row { - /** Whether this row has a next connection. */ + /** + * Whether this row has a next connection. + * @internal + */ hasNextConnection = false; - /** The next connection on the row, if any. */ + /** + * The next connection on the row, if any. + * @internal + */ connection: NextConnection|null = null; /** * 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; @@ -56,7 +63,10 @@ export class BottomRow extends Row { */ baseline = 0; - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(constants: ConstantProvider) { super(constants); this.type |= Types.BOTTOM_ROW; diff --git a/core/renderers/measurables/connection.ts b/core/renderers/measurables/connection.ts index da62e5331..b26255a76 100644 --- a/core/renderers/measurables/connection.ts +++ b/core/renderers/measurables/connection.ts @@ -39,6 +39,7 @@ export class Connection extends Measurable { * @param constants The rendering constants provider. * @param connectionModel The connection object on the block that this * represents. + * @internal */ constructor( constants: ConstantProvider, public connectionModel: RenderedConnection) { diff --git a/core/renderers/measurables/external_value_input.ts b/core/renderers/measurables/external_value_input.ts index a0f420c42..f81d8e033 100644 --- a/core/renderers/measurables/external_value_input.ts +++ b/core/renderers/measurables/external_value_input.ts @@ -42,6 +42,7 @@ export class ExternalValueInput extends InputConnection { /** * @param constants The rendering constants provider. * @param input The external value input to measure and store information for. + * @internal */ constructor(constants: ConstantProvider, input: Input) { super(constants, input); diff --git a/core/renderers/measurables/field.ts b/core/renderers/measurables/field.ts index 209ab501d..fd3d25862 100644 --- a/core/renderers/measurables/field.ts +++ b/core/renderers/measurables/field.ts @@ -44,6 +44,7 @@ export class Field extends Measurable { * @param constants The rendering constants provider. * @param field The field to measure and store information for. * @param parentInput The parent input for the field. + * @internal */ constructor( constants: ConstantProvider, public field: BlocklyField, diff --git a/core/renderers/measurables/hat.ts b/core/renderers/measurables/hat.ts index e259c790a..c473ec7a4 100644 --- a/core/renderers/measurables/hat.ts +++ b/core/renderers/measurables/hat.ts @@ -33,7 +33,10 @@ import {Types} from './types.js'; export class Hat extends Measurable { ascenderHeight: number; - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(constants: ConstantProvider) { super(constants); this.type |= Types.HAT; diff --git a/core/renderers/measurables/icon.ts b/core/renderers/measurables/icon.ts index 5cb00108d..ad1fea58f 100644 --- a/core/renderers/measurables/icon.ts +++ b/core/renderers/measurables/icon.ts @@ -40,6 +40,7 @@ export class Icon extends Measurable { * rendering * @param constants The rendering constants provider. * @param icon The icon to measure and store information for. + * @internal */ constructor(constants: ConstantProvider, public icon: BlocklyIcon) { super(constants); diff --git a/core/renderers/measurables/in_row_spacer.ts b/core/renderers/measurables/in_row_spacer.ts index 81da62329..69213488e 100644 --- a/core/renderers/measurables/in_row_spacer.ts +++ b/core/renderers/measurables/in_row_spacer.ts @@ -34,6 +34,7 @@ export class InRowSpacer extends Measurable { /** * @param constants The rendering constants provider. * @param width The width of the spacer. + * @internal */ constructor(constants: ConstantProvider, width: number) { super(constants); diff --git a/core/renderers/measurables/inline_input.ts b/core/renderers/measurables/inline_input.ts index 38240e5fa..900cc74f7 100644 --- a/core/renderers/measurables/inline_input.ts +++ b/core/renderers/measurables/inline_input.ts @@ -39,6 +39,7 @@ export class InlineInput extends InputConnection { /** * @param constants The rendering constants provider. * @param input The inline input to measure and store information for. + * @internal */ constructor(constants: ConstantProvider, input: Input) { super(constants, input); diff --git a/core/renderers/measurables/input_connection.ts b/core/renderers/measurables/input_connection.ts index 65fb2e382..659df3ab4 100644 --- a/core/renderers/measurables/input_connection.ts +++ b/core/renderers/measurables/input_connection.ts @@ -44,6 +44,7 @@ export class InputConnection extends Connection { /** * @param constants The rendering constants provider. * @param input The input to measure and store information for. + * @internal */ constructor(constants: ConstantProvider, public input: Input) { super(constants, input.connection as RenderedConnection); diff --git a/core/renderers/measurables/input_row.ts b/core/renderers/measurables/input_row.ts index 2e778edcc..3adaa174c 100644 --- a/core/renderers/measurables/input_row.ts +++ b/core/renderers/measurables/input_row.ts @@ -33,10 +33,16 @@ import {Types} from './types.js'; * @alias Blockly.blockRendering.InputRow */ export class InputRow extends Row { - /** The total width of all blocks connected to this row. */ + /** + * The total width of all blocks connected to this row. + * @internal + */ connectedBlockWidths = 0; - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(constants: ConstantProvider) { super(constants); this.type |= Types.INPUT_ROW; @@ -44,6 +50,7 @@ export class InputRow extends Row { /** * Inspect all subcomponents and populate all size properties on the row. + * @internal */ override measure() { this.width = this.minWidth; diff --git a/core/renderers/measurables/jagged_edge.ts b/core/renderers/measurables/jagged_edge.ts index dbd23defe..94520ff5d 100644 --- a/core/renderers/measurables/jagged_edge.ts +++ b/core/renderers/measurables/jagged_edge.ts @@ -31,7 +31,10 @@ import {Types} from './types.js'; * @alias Blockly.blockRendering.JaggedEdge */ export class JaggedEdge extends Measurable { - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(constants: ConstantProvider) { super(constants); this.type |= Types.JAGGED_EDGE; diff --git a/core/renderers/measurables/next_connection.ts b/core/renderers/measurables/next_connection.ts index 80ef3d95b..05238eb65 100644 --- a/core/renderers/measurables/next_connection.ts +++ b/core/renderers/measurables/next_connection.ts @@ -37,6 +37,7 @@ export class NextConnection extends Connection { * @param constants The rendering constants provider. * @param connectionModel The connection object on the block that this * represents. + * @internal */ constructor( constants: ConstantProvider, connectionModel: RenderedConnection) { diff --git a/core/renderers/measurables/output_connection.ts b/core/renderers/measurables/output_connection.ts index 6e410a219..b944d3b7d 100644 --- a/core/renderers/measurables/output_connection.ts +++ b/core/renderers/measurables/output_connection.ts @@ -41,6 +41,7 @@ export class OutputConnection extends Connection { * @param constants The rendering constants provider. * @param connectionModel The connection object on the block that this * represents. + * @internal */ constructor( constants: ConstantProvider, connectionModel: RenderedConnection) { diff --git a/core/renderers/measurables/previous_connection.ts b/core/renderers/measurables/previous_connection.ts index bc95db3cc..5fe9d5a88 100644 --- a/core/renderers/measurables/previous_connection.ts +++ b/core/renderers/measurables/previous_connection.ts @@ -37,6 +37,7 @@ export class PreviousConnection extends Connection { * @param constants The rendering constants provider. * @param connectionModel The connection object on the block that this * represents. + * @internal */ constructor( constants: ConstantProvider, connectionModel: RenderedConnection) { diff --git a/core/renderers/measurables/round_corner.ts b/core/renderers/measurables/round_corner.ts index 531540af8..503cedbe2 100644 --- a/core/renderers/measurables/round_corner.ts +++ b/core/renderers/measurables/round_corner.ts @@ -34,6 +34,7 @@ export class RoundCorner extends Measurable { /** * @param constants The rendering constants provider. * @param opt_position The position of this corner. + * @internal */ constructor(constants: ConstantProvider, opt_position?: string) { super(constants); diff --git a/core/renderers/measurables/row.ts b/core/renderers/measurables/row.ts index efd0ccc9e..b0108dbef 100644 --- a/core/renderers/measurables/row.ts +++ b/core/renderers/measurables/row.ts @@ -33,51 +33,72 @@ import {Types} from './types.js'; * @alias Blockly.blockRendering.Row */ export class Row { + /** @internal */ type: number; - /** An array of elements contained in this row. */ + /** + * An array of elements contained in this row. + * @internal + */ elements: Measurable[] = []; - /** The height of the row. */ + /** + * The height of the row. + * @internal + */ height = 0; /** * 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. */ + /** + * The minimum height of the row. + * @internal + */ minHeight = 0; /** * 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; /** * 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; /** * The Y position of the row relative to the origin of the block's svg * group. + * @internal */ yPos = 0; /** * 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. */ + /** + * Whether the row has any external inputs. + * @internal + */ hasExternalInput = false; - /** Whether the row has any statement inputs. */ + /** + * Whether the row has any statement inputs. + * @internal + */ hasStatement = false; /** @@ -87,20 +108,35 @@ export class Row { */ statementEdge = 0; - /** Whether the row has any inline inputs. */ + /** + * Whether the row has any inline inputs. + * @internal + */ hasInlineInput = false; - /** Whether the row has any dummy inputs. */ + /** + * Whether the row has any dummy inputs. + * @internal + */ hasDummyInput = false; - /** Whether the row has a jagged edge. */ + /** + * Whether the row has a jagged edge. + * @internal + */ hasJaggedEdge = false; notchOffset: number; - /** Alignment of the row. */ + /** + * Alignment of the row. + * @internal + */ align: number|null = null; - /** @param constants_ The rendering constants provider. */ + /** + * @param constants_ The rendering constants provider. + * @internal + */ constructor(protected readonly constants_: ConstantProvider) { /** The type of this rendering object. */ this.type = Types.ROW; @@ -111,6 +147,7 @@ export class Row { /** * Get the last input on this row, if it has one. * @return The last input on the row, or null. + * @internal */ getLastInput(): InputConnection { // TODO: Consider moving this to InputRow, if possible. @@ -127,6 +164,7 @@ export class Row { /** * Inspect all subcomponents and populate all size properties on the row. + * @internal */ measure() { throw Error('Unexpected attempt to measure a base Row.'); @@ -135,6 +173,7 @@ export class Row { /** * Determines whether this row should start with an element spacer. * @return Whether the row should start with a spacer. + * @internal */ startsWithElemSpacer(): boolean { return true; @@ -143,6 +182,7 @@ export class Row { /** * Determines whether this row should end with an element spacer. * @return Whether the row should end with a spacer. + * @internal */ endsWithElemSpacer(): boolean { return true; @@ -151,6 +191,7 @@ export class Row { /** * Convenience method to get the first spacer element on this row. * @return The first spacer element on this row. + * @internal */ getFirstSpacer(): InRowSpacer { for (let i = 0; i < this.elements.length; i++) { @@ -167,6 +208,7 @@ export class Row { /** * Convenience method to get the last spacer element on this row. * @return The last spacer element on this row. + * @internal */ getLastSpacer(): InRowSpacer { for (let i = this.elements.length - 1; i >= 0; i--) { diff --git a/core/renderers/measurables/spacer_row.ts b/core/renderers/measurables/spacer_row.ts index 1c9fee6da..68b93c43c 100644 --- a/core/renderers/measurables/spacer_row.ts +++ b/core/renderers/measurables/spacer_row.ts @@ -40,6 +40,7 @@ export class SpacerRow extends Row { * @param constants The rendering constants provider. * @param height The height of the spacer. * @param width The width of the spacer. + * @internal */ constructor( constants: ConstantProvider, public override height: number, diff --git a/core/renderers/measurables/square_corner.ts b/core/renderers/measurables/square_corner.ts index 2fac2846d..363c53060 100644 --- a/core/renderers/measurables/square_corner.ts +++ b/core/renderers/measurables/square_corner.ts @@ -34,6 +34,7 @@ export class SquareCorner extends Measurable { /** * @param constants The rendering constants provider. * @param opt_position The position of this corner. + * @internal */ constructor(constants: ConstantProvider, opt_position?: string) { super(constants); diff --git a/core/renderers/measurables/statement_input.ts b/core/renderers/measurables/statement_input.ts index 253a83ed1..d803c0ca2 100644 --- a/core/renderers/measurables/statement_input.ts +++ b/core/renderers/measurables/statement_input.ts @@ -36,6 +36,7 @@ export class StatementInput extends InputConnection { /** * @param constants The rendering constants provider. * @param input The statement input to measure and store information for. + * @internal */ constructor(constants: ConstantProvider, input: Input) { super(constants, input); diff --git a/core/renderers/measurables/top_row.ts b/core/renderers/measurables/top_row.ts index 3c5d0bdc3..9a404d889 100644 --- a/core/renderers/measurables/top_row.ts +++ b/core/renderers/measurables/top_row.ts @@ -42,6 +42,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; @@ -55,7 +56,10 @@ export class TopRow extends Row { connection: PreviousConnection|null = null; override widthWithConnectedBlocks: AnyDuringMigration; - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(constants: ConstantProvider) { super(constants); @@ -66,6 +70,7 @@ 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. + * @internal */ hasLeftSquareCorner(block: BlockSvg): boolean { const hasHat = diff --git a/core/renderers/measurables/types.ts b/core/renderers/measurables/types.ts index 2bcb9fb99..39406e2cc 100644 --- a/core/renderers/measurables/types.ts +++ b/core/renderers/measurables/types.ts @@ -79,10 +79,16 @@ class TypesContainer { INPUT_ROW = 1 << 23; // Input Row. - /** A Left Corner Union Type. */ + /** + * A Left Corner Union Type. + * @internal + */ LEFT_CORNER = this.LEFT_SQUARE_CORNER | this.LEFT_ROUND_CORNER; - /** A Right Corner Union Type. */ + /** + * A Right Corner Union Type. + * @internal + */ RIGHT_CORNER = this.RIGHT_SQUARE_CORNER | this.RIGHT_ROUND_CORNER; /** @@ -97,6 +103,7 @@ 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. + * @internal */ getType(type: string): number { if (!Object.prototype.hasOwnProperty.call(this, type)) { @@ -110,6 +117,7 @@ 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. + * @internal */ isField(elem: Measurable): number { return elem.type & this.FIELD; @@ -119,6 +127,7 @@ 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. + * @internal */ isHat(elem: Measurable): number { return elem.type & this.HAT; @@ -128,6 +137,7 @@ 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. + * @internal */ isIcon(elem: Measurable): number { return elem.type & this.ICON; @@ -137,6 +147,7 @@ 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. + * @internal */ isSpacer(elem: Measurable|Row): number { return elem.type & this.SPACER; @@ -146,6 +157,7 @@ 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. + * @internal */ isInRowSpacer(elem: Measurable): number { return elem.type & this.IN_ROW_SPACER; @@ -155,6 +167,7 @@ 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. + * @internal */ isInput(elem: Measurable): number { return elem.type & this.INPUT; @@ -164,6 +177,7 @@ 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. + * @internal */ isExternalInput(elem: Measurable): number { return elem.type & this.EXTERNAL_VALUE_INPUT; @@ -173,6 +187,7 @@ 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. + * @internal */ isInlineInput(elem: Measurable): number { return elem.type & this.INLINE_INPUT; @@ -182,6 +197,7 @@ 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. + * @internal */ isStatementInput(elem: Measurable): number { return elem.type & this.STATEMENT_INPUT; @@ -191,6 +207,7 @@ 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. + * @internal */ isPreviousConnection(elem: Measurable): number { return elem.type & this.PREVIOUS_CONNECTION; @@ -200,6 +217,7 @@ 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. + * @internal */ isNextConnection(elem: Measurable): number { return elem.type & this.NEXT_CONNECTION; @@ -211,6 +229,7 @@ class TypesContainer { * @param elem The element to check. * @return 1 if the object stores information about a previous or next * connection. + * @internal */ isPreviousOrNextConnection(elem: Measurable): number { return elem.type & (this.PREVIOUS_CONNECTION | this.NEXT_CONNECTION); @@ -220,6 +239,7 @@ 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. + * @internal */ isLeftRoundedCorner(elem: Measurable): number { return elem.type & this.LEFT_ROUND_CORNER; @@ -229,6 +249,7 @@ 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. + * @internal */ isRightRoundedCorner(elem: Measurable): number { return elem.type & this.RIGHT_ROUND_CORNER; @@ -238,6 +259,7 @@ 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. + * @internal */ isLeftSquareCorner(elem: Measurable): number { return elem.type & this.LEFT_SQUARE_CORNER; @@ -247,6 +269,7 @@ 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. + * @internal */ isRightSquareCorner(elem: Measurable): number { return elem.type & this.RIGHT_SQUARE_CORNER; @@ -256,6 +279,7 @@ 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. + * @internal */ isCorner(elem: Measurable): number { return elem.type & this.CORNER; @@ -265,6 +289,7 @@ 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. + * @internal */ isJaggedEdge(elem: Measurable): number { return elem.type & this.JAGGED_EDGE; @@ -274,6 +299,7 @@ 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. + * @internal */ isRow(row: Row): number { return row.type & this.ROW; @@ -283,6 +309,7 @@ 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. + * @internal */ isBetweenRowSpacer(row: Row): number { return row.type & this.BETWEEN_ROW_SPACER; @@ -292,6 +319,7 @@ 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. + * @internal */ isTopRow(row: Row): number { return row.type & this.TOP_ROW; @@ -301,6 +329,7 @@ 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. + * @internal */ isBottomRow(row: Row): number { return row.type & this.BOTTOM_ROW; @@ -310,6 +339,7 @@ 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. + * @internal */ isTopOrBottomRow(row: Row): number { return row.type & (this.TOP_ROW | this.BOTTOM_ROW); @@ -319,6 +349,7 @@ 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. + * @internal */ isInputRow(row: Row): number { return row.type & this.INPUT_ROW; diff --git a/core/renderers/minimalist/constants.ts b/core/renderers/minimalist/constants.ts index af1f45589..2db269754 100644 --- a/core/renderers/minimalist/constants.ts +++ b/core/renderers/minimalist/constants.ts @@ -25,6 +25,7 @@ import {ConstantProvider as BaseConstantProvider} from '../common/constants.js'; * @alias Blockly.minimalist.ConstantProvider */ export class ConstantProvider extends BaseConstantProvider { + /** @internal */ constructor() { super(); } diff --git a/core/renderers/minimalist/drawer.ts b/core/renderers/minimalist/drawer.ts index 2cd3c026a..230d60aa2 100644 --- a/core/renderers/minimalist/drawer.ts +++ b/core/renderers/minimalist/drawer.ts @@ -32,6 +32,7 @@ export class Drawer extends BaseDrawer { * @param block The block to render. * @param info An object containing all information needed to render this * block. + * @internal */ constructor(block: BlockSvg, info: RenderInfo) { super(block, info); diff --git a/core/renderers/minimalist/info.ts b/core/renderers/minimalist/info.ts index 44cb90aa9..1256230a6 100644 --- a/core/renderers/minimalist/info.ts +++ b/core/renderers/minimalist/info.ts @@ -35,6 +35,7 @@ export class RenderInfo extends BaseRenderInfo { /** * @param renderer The renderer in use. * @param block The block to measure. + * @internal */ constructor(renderer: Renderer, block: BlockSvg) { super(renderer, block); @@ -43,6 +44,7 @@ export class RenderInfo extends BaseRenderInfo { /** * Get the block renderer in use. * @return The block renderer in use. + * @internal */ override getRenderer(): Renderer { // AnyDuringMigration because: Property 'renderer_' does not exist on type diff --git a/core/renderers/minimalist/renderer.ts b/core/renderers/minimalist/renderer.ts index 7914be96e..24c956b33 100644 --- a/core/renderers/minimalist/renderer.ts +++ b/core/renderers/minimalist/renderer.ts @@ -32,7 +32,10 @@ import {RenderInfo} from './info.js'; * @alias Blockly.minimalist.Renderer */ export class Renderer extends BaseRenderer { - /** @param name The renderer name. */ + /** + * @param name The renderer name. + * @internal + */ constructor(name: string) { super(name); } diff --git a/core/renderers/thrasos/info.ts b/core/renderers/thrasos/info.ts index 397fb9b58..7168bf613 100644 --- a/core/renderers/thrasos/info.ts +++ b/core/renderers/thrasos/info.ts @@ -51,6 +51,7 @@ export class RenderInfo extends BaseRenderInfo { /** * @param renderer The renderer in use. * @param block The block to measure. + * @internal */ constructor(renderer: Renderer, block: BlockSvg) { super(renderer, block); @@ -59,6 +60,7 @@ export class RenderInfo extends BaseRenderInfo { /** * Get the block renderer in use. * @return The block renderer in use. + * @internal */ override getRenderer(): Renderer { // AnyDuringMigration because: Property 'renderer_' does not exist on type diff --git a/core/renderers/thrasos/renderer.ts b/core/renderers/thrasos/renderer.ts index af2695b77..7bacb9406 100644 --- a/core/renderers/thrasos/renderer.ts +++ b/core/renderers/thrasos/renderer.ts @@ -28,7 +28,10 @@ import {RenderInfo} from './info.js'; * @alias Blockly.thrasos.Renderer */ export class Renderer extends BaseRenderer { - /** @param name The renderer name. */ + /** + * @param name The renderer name. + * @internal + */ constructor(name: string) { super(name); } diff --git a/core/renderers/zelos/constants.ts b/core/renderers/zelos/constants.ts index 7cee8884b..cb665b919 100644 --- a/core/renderers/zelos/constants.ts +++ b/core/renderers/zelos/constants.ts @@ -75,7 +75,10 @@ export class ConstantProvider extends BaseConstantProvider { override CURSOR_COLOUR = '#ffa200'; - /** Radius of the cursor for input and output connections. */ + /** + * Radius of the cursor for input and output connections. + * @internal + */ CURSOR_RADIUS = 5; override JAGGED_TEETH_HEIGHT = 0; @@ -130,6 +133,7 @@ export class ConstantProvider extends BaseConstantProvider { /** * The ID of the selected glow filter, or the empty string if no filter is * set. + * @internal */ selectedGlowFilterId = ''; @@ -143,6 +147,7 @@ export class ConstantProvider extends BaseConstantProvider { /** * The ID of the replacement glow filter, or the empty string if no filter * is set. + * @internal */ replacementGlowFilterId = ''; @@ -171,6 +176,7 @@ export class ConstantProvider extends BaseConstantProvider { */ SQUARED: Shape|null = null; + /** @internal */ constructor() { super(); @@ -229,6 +235,7 @@ export class ConstantProvider extends BaseConstantProvider { * When a block with the outer shape contains an input block with the inner * shape on its left or right edge, the block elements are aligned such that * the padding specified is reached. + * @internal */ this.SHAPE_IN_SHAPE_PADDING = { 1: { @@ -344,6 +351,7 @@ export class ConstantProvider extends BaseConstantProvider { * Create sizing and path information about a hexagonal shape. * @return An object containing sizing and path information about a hexagonal * shape for connections. + * @internal */ makeHexagonal(): Shape { const maxWidth = this.MAX_DYNAMIC_CONNECTION_SHAPE_WIDTH; @@ -405,6 +413,7 @@ export class ConstantProvider extends BaseConstantProvider { * Create sizing and path information about a rounded shape. * @return An object containing sizing and path information about a rounded * shape for connections. + * @internal */ makeRounded(): Shape { const maxWidth = this.MAX_DYNAMIC_CONNECTION_SHAPE_WIDTH; @@ -475,6 +484,7 @@ export class ConstantProvider extends BaseConstantProvider { * Create sizing and path information about a squared shape. * @return An object containing sizing and path information about a squared * shape for connections. + * @internal */ makeSquared(): Shape { const radius = this.CORNER_RADIUS; diff --git a/core/renderers/zelos/drawer.ts b/core/renderers/zelos/drawer.ts index f03efdb4a..deb7f0d41 100644 --- a/core/renderers/zelos/drawer.ts +++ b/core/renderers/zelos/drawer.ts @@ -51,6 +51,7 @@ export class Drawer extends BaseDrawer { * @param block The block to render. * @param info An object containing all information needed to render this * block. + * @internal */ constructor(block: BlockSvg, info: RenderInfo) { // AnyDuringMigration because: Argument of type diff --git a/core/renderers/zelos/info.ts b/core/renderers/zelos/info.ts index 35ea9cbcb..3f742d5ba 100644 --- a/core/renderers/zelos/info.ts +++ b/core/renderers/zelos/info.ts @@ -71,6 +71,7 @@ export class RenderInfo extends BaseRenderInfo { /** * @param renderer The renderer in use. * @param block The block to measure. + * @internal */ constructor(renderer: Renderer, block: BlockSvg) { super(renderer, block); @@ -117,6 +118,7 @@ export class RenderInfo extends BaseRenderInfo { /** * Get the block renderer in use. * @return The block renderer in use. + * @internal */ override getRenderer(): Renderer { return this.renderer as Renderer; diff --git a/core/renderers/zelos/measurables/bottom_row.ts b/core/renderers/zelos/measurables/bottom_row.ts index a562ac600..df0741281 100644 --- a/core/renderers/zelos/measurables/bottom_row.ts +++ b/core/renderers/zelos/measurables/bottom_row.ts @@ -29,7 +29,10 @@ import {BottomRow as BaseBottomRow} from '../../../renderers/measurables/bottom_ * @alias Blockly.zelos.BottomRow */ export class BottomRow extends BaseBottomRow { - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(constants: ConstantProvider) { super(constants); } diff --git a/core/renderers/zelos/measurables/inputs.ts b/core/renderers/zelos/measurables/inputs.ts index d53baa21b..e0e7fcea2 100644 --- a/core/renderers/zelos/measurables/inputs.ts +++ b/core/renderers/zelos/measurables/inputs.ts @@ -36,6 +36,7 @@ export class StatementInput extends BaseStatementInput { /** * @param constants The rendering constants provider. * @param input The statement input to measure and store information for. + * @internal */ constructor(constants: ConstantProvider, input: Input) { super(constants, input); diff --git a/core/renderers/zelos/measurables/row_elements.ts b/core/renderers/zelos/measurables/row_elements.ts index a1c22dcdf..78cc4f844 100644 --- a/core/renderers/zelos/measurables/row_elements.ts +++ b/core/renderers/zelos/measurables/row_elements.ts @@ -33,7 +33,10 @@ export class RightConnectionShape extends Measurable { override height = 0; override width = 0; - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(constants: ConstantProvider) { super(constants); // AnyDuringMigration because: Property 'getType' does not exist on type diff --git a/core/renderers/zelos/measurables/top_row.ts b/core/renderers/zelos/measurables/top_row.ts index 1e25b77ba..ad9ae9e37 100644 --- a/core/renderers/zelos/measurables/top_row.ts +++ b/core/renderers/zelos/measurables/top_row.ts @@ -31,7 +31,10 @@ import {TopRow as BaseTopRow} from '../../../renderers/measurables/top_row.js'; * @alias Blockly.zelos.TopRow */ export class TopRow extends BaseTopRow { - /** @param constants The rendering constants provider. */ + /** + * @param constants The rendering constants provider. + * @internal + */ constructor(constants: ConstantProvider) { super(constants); } diff --git a/core/renderers/zelos/path_object.ts b/core/renderers/zelos/path_object.ts index 762d9c88a..390000ec2 100644 --- a/core/renderers/zelos/path_object.ts +++ b/core/renderers/zelos/path_object.ts @@ -57,16 +57,21 @@ export class PathObject extends BasePathObject { */ outputShapeType = null; + /** @internal */ + public override constants: ConstantProvider; + /** * @param root The root SVG element. * @param style The style object to use for colouring. * @param constants The renderer's constants. + * @internal */ constructor( - root: SVGElement, style: BlockStyle, - public override constants: ConstantProvider) { + root: SVGElement, style: BlockStyle, constants: ConstantProvider) { super(root, style, constants); + this.constants = constants; + /** The outline paths on the block. */ this.outlines_ = Object.create(null); } @@ -142,7 +147,10 @@ export class PathObject extends BasePathObject { } } - /** Method that's called when the drawer is about to draw the block. */ + /** + * Method that's called when the drawer is about to draw the block. + * @internal + */ beginDrawing() { this.remainingOutlines_ = Object.create(null); for (const key in this.outlines_) { @@ -152,7 +160,10 @@ export class PathObject extends BasePathObject { } } - /** Method that's called when the drawer is done drawing. */ + /** + * Method that's called when the drawer is done drawing. + * @internal + */ endDrawing() { // Go through all remaining outlines that were not used this draw pass, and // remove them. @@ -171,6 +182,7 @@ export class PathObject extends BasePathObject { * respective outline path SVG element. * @param name The input name. * @param pathString The path. + * @internal */ setOutlinePath(name: string, pathString: string) { const outline = this.getOutlinePath_(name); diff --git a/core/renderers/zelos/renderer.ts b/core/renderers/zelos/renderer.ts index 61b7a9431..1a6f582d9 100644 --- a/core/renderers/zelos/renderer.ts +++ b/core/renderers/zelos/renderer.ts @@ -49,7 +49,10 @@ import {PathObject} from './path_object.js'; export class Renderer extends BaseRenderer { protected override constants_!: ConstantProvider; - /** @param name The renderer name. */ + /** + * @param name The renderer name. + * @internal + */ constructor(name: string) { super(name); } @@ -88,6 +91,7 @@ export class Renderer extends BaseRenderer { * @param workspace The workspace the cursor belongs to. * @param marker The marker. * @return The object in charge of drawing the marker. + * @internal */ override makeMarkerDrawer(workspace: WorkspaceSvg, marker: Marker): MarkerSvg { @@ -99,6 +103,7 @@ export class Renderer extends BaseRenderer { * @param root The root SVG element. * @param style The style object to use for colouring. * @return The renderer path object. + * @internal */ override makePathObject(root: SVGElement, style: BlockStyle): PathObject { return new PathObject( diff --git a/core/scrollbar.ts b/core/scrollbar.ts index fe40af371..826298981 100644 --- a/core/scrollbar.ts +++ b/core/scrollbar.ts @@ -48,6 +48,7 @@ export class Scrollbar { /** * Default margin around the scrollbar (between the scrollbar and the edge of * the viewport in pixels). + * @internal */ static readonly DEFAULT_SCROLLBAR_MARGIN = 0.5; private readonly pair_: boolean; @@ -58,6 +59,7 @@ export class Scrollbar { /** * The ratio of handle position offset to workspace content displacement. + * @internal */ ratio = 1; private origin_: Coordinate; @@ -142,6 +144,7 @@ export class Scrollbar { * The upper left corner of the scrollbar's SVG group in CSS pixels relative * to the scrollbar's origin. This is usually relative to the injection div * origin. + * @internal */ this.position = new Coordinate(0, 0); @@ -286,6 +289,7 @@ export class Scrollbar { * workspace. * @param x The new x coordinate. * @param y The new y coordinate. + * @internal */ setPosition(x: number, y: number) { this.position.x = x; @@ -792,6 +796,7 @@ export class Scrollbar { /** * Helper to calculate the ratio of handle position to scrollbar view size. * @return Ratio. + * @internal */ getRatio_(): number { const scrollHandleRange = this.scrollbarLength_ - this.handleLength_; diff --git a/core/scrollbar_pair.ts b/core/scrollbar_pair.ts index ba4511914..883846d3f 100644 --- a/core/scrollbar_pair.ts +++ b/core/scrollbar_pair.ts @@ -188,6 +188,7 @@ export class ScrollbarPair { * (e.g. in a flyout.) * @param x The x coordinate of the scrollbar's origin, in CSS pixels. * @param y The y coordinate of the scrollbar's origin, in CSS pixels. + * @internal */ setOrigin(x: number, y: number) { if (this.hScroll) { diff --git a/core/serialization/blocks.ts b/core/serialization/blocks.ts index 8a3416c6d..b7f56590d 100644 --- a/core/serialization/blocks.ts +++ b/core/serialization/blocks.ts @@ -337,6 +337,7 @@ export function append( * this function will be undo-able by the user. False by default. * @return The block that was just appended. * @alias Blockly.serialization.blocks.appendInternal + * @internal */ export function appendInternal( state: State, workspace: Workspace, diff --git a/core/serialization/exceptions.ts b/core/serialization/exceptions.ts index d86a00dda..cadd0372f 100644 --- a/core/serialization/exceptions.ts +++ b/core/serialization/exceptions.ts @@ -31,7 +31,10 @@ export class DeserializationError extends Error {} * @alias Blockly.serialization.exceptions.MissingBlockType */ export class MissingBlockType extends DeserializationError { - /** @param state The state object which is missing the block type. */ + /** + * @param state The state object which is missing the block type. + * @internal + */ constructor(public state: State) { super(`Expected to find a 'type' property, defining the block type`); } @@ -48,6 +51,7 @@ export class MissingConnection extends DeserializationError { * 'IF0', or 'next'. * @param block The block missing the connection. * @param state The state object containing the bad connection. + * @internal */ constructor(connection: string, public block: Block, public state: State) { super(`The block ${block.toDevString()} is missing a(n) ${connection} @@ -67,6 +71,7 @@ export class BadConnectionCheck extends DeserializationError { * 'output' or 'previous'. * @param childBlock The child block that could not connect to its parent. * @param childState The state object representing the child block. + * @internal */ constructor( reason: string, childConnection: string, public childBlock: Block, @@ -84,7 +89,10 @@ ${childConnection} to its parent, because: ${reason}`); * @alias Blockly.serialization.exceptions.RealChildOfShadow */ export class RealChildOfShadow extends DeserializationError { - /** @param state The state object representing the real block. */ + /** + * @param state The state object representing the real block. + * @internal + */ constructor(public state: State) { super(`Encountered a real block which is defined as a child of a shadow block. It is an invariant of Blockly that shadow blocks only have shadow diff --git a/core/shortcut_items.ts b/core/shortcut_items.ts index 247df7086..c01875720 100644 --- a/core/shortcut_items.ts +++ b/core/shortcut_items.ts @@ -251,6 +251,7 @@ export function registerRedo() { * Registers all default keyboard shortcut item. This should be called once per * instance of KeyboardShortcutRegistry. * @alias Blockly.ShortcutItems.registerDefaultShortcuts + * @internal */ export function registerDefaultShortcuts() { registerEscape(); diff --git a/core/theme.ts b/core/theme.ts index 93f7a8720..f106abce1 100644 --- a/core/theme.ts +++ b/core/theme.ts @@ -24,14 +24,19 @@ import * as object from './utils/object.js'; * @alias Blockly.Theme */ export class Theme { + /** @internal */ blockStyles: {[key: string]: BlockStyle}; + /** @internal */ categoryStyles: {[key: string]: CategoryStyle}; + /** @internal */ componentStyles: ComponentStyle; + /** @internal */ fontStyle: FontStyle; /** * Whether or not to add a 'hat' on top of all blocks with no previous or * output connections. + * @internal */ startHats: boolean|null = null; @@ -67,6 +72,7 @@ export class Theme { /** * Gets the class name that identifies this theme. * @return The CSS class name. + * @internal */ getClassName(): string { return this.name + '-theme'; diff --git a/core/theme_manager.ts b/core/theme_manager.ts index 5d7cd8928..48aea7e76 100644 --- a/core/theme_manager.ts +++ b/core/theme_manager.ts @@ -40,6 +40,7 @@ export class ThemeManager { /** * @param workspace The main workspace. * @param theme The workspace theme. + * @internal */ constructor(private readonly workspace: WorkspaceSvg, private theme: Theme) { /** A map of subscribed UI components, keyed by component name. */ @@ -49,6 +50,7 @@ export class ThemeManager { /** * Get the workspace theme. * @return The workspace theme. + * @internal */ getTheme(): Theme { return this.theme; @@ -57,6 +59,7 @@ export class ThemeManager { /** * Set the workspace theme, and refresh the workspace and all components. * @param theme The workspace theme. + * @internal */ setTheme(theme: Theme) { const prevTheme = this.theme; @@ -97,6 +100,7 @@ export class ThemeManager { * Subscribe a workspace to changes to the selected theme. If a new theme is * set, the workspace is called to refresh its blocks. * @param workspace The workspace to subscribe. + * @internal */ subscribeWorkspace(workspace: Workspace) { this.subscribedWorkspaces_.push(workspace); @@ -105,6 +109,7 @@ export class ThemeManager { /** * Unsubscribe a workspace to changes to the selected theme. * @param workspace The workspace to unsubscribe. + * @internal */ unsubscribeWorkspace(workspace: Workspace) { if (!arrayUtils.removeElem(this.subscribedWorkspaces_, workspace)) { @@ -120,6 +125,7 @@ export class ThemeManager { * @param componentName The name used to identify the component. This must be * the same name used to configure the style in the Theme object. * @param propertyName The inline style property name to update. + * @internal */ subscribe(element: Element, componentName: string, propertyName: string) { if (!this.componentDB_[componentName]) { @@ -139,6 +145,7 @@ export class ThemeManager { /** * Unsubscribe an element to changes to the selected theme. * @param element The element to unsubscribe. + * @internal */ unsubscribe(element: Element) { if (!element) { @@ -163,6 +170,7 @@ export class ThemeManager { /** * Dispose of this theme manager. * @suppress {checkTypes} + * @internal */ dispose() { this.owner_ = null; diff --git a/core/toolbox/toolbox.ts b/core/toolbox/toolbox.ts index 395a672c9..170eaaefe 100644 --- a/core/toolbox/toolbox.ts +++ b/core/toolbox/toolbox.ts @@ -352,6 +352,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Fills the toolbox with new toolbox items and removes any old contents. * @param toolboxDef Object holding information for creating a toolbox. + * @internal */ render(toolboxDef: toolbox.ToolboxInfo) { this.toolboxDef_ = toolboxDef; @@ -447,6 +448,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Adds a style on the toolbox. Usually used to change the cursor. * @param style The name of the class to add. + * @internal */ addStyle(style: string) { dom.addClass(this.HtmlDiv as Element, style); @@ -455,6 +457,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Removes a style from the toolbox. Usually used to change the cursor. * @param style The name of the class to remove. + * @internal */ removeStyle(style: string) { dom.removeClass(this.HtmlDiv as Element, style); @@ -680,7 +683,10 @@ export class Toolbox extends DeleteArea implements IAutoHideable, this.flyout_!.position(); } - /** Handles resizing the toolbox when a toolbox item resizes. */ + /** + * Handles resizing the toolbox when a toolbox item resizes. + * @internal + */ handleToolboxItemResize() { // Reposition the workspace so that (0,0) is in the correct position // relative to the new absolute edge (ie toolbox edge). @@ -706,6 +712,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Updates the category colours and background colour of selected categories. + * @internal */ refreshTheme() { for (let i = 0; i < this.contents_.length; i++) { diff --git a/core/toolbox/toolbox_item.ts b/core/toolbox/toolbox_item.ts index c98727bd1..73fbddfc0 100644 --- a/core/toolbox/toolbox_item.ts +++ b/core/toolbox/toolbox_item.ts @@ -114,6 +114,7 @@ export class ToolboxItem implements IToolboxItem { /** * Gets the nested level of the category. * @return The nested level of the category. + * @internal */ getLevel(): number { return this.level_; diff --git a/core/tooltip.ts b/core/tooltip.ts index e46b2c3ee..5735c789d 100644 --- a/core/tooltip.ts +++ b/core/tooltip.ts @@ -327,6 +327,7 @@ function onMouseMove(e: Event) { /** * Dispose of the tooltip. * @alias Blockly.Tooltip.dispose + * @internal */ export function dispose() { element = null; @@ -354,6 +355,7 @@ export function hide() { * Hide any in-progress tooltips and block showing new tooltips until the next * call to unblock(). * @alias Blockly.Tooltip.block + * @internal */ export function block() { hide(); @@ -364,6 +366,7 @@ export function block() { * Unblock tooltips: allow them to be scheduled and shown according to their own * logic. * @alias Blockly.Tooltip.unblock + * @internal */ export function unblock() { blocked = false; diff --git a/core/touch.ts b/core/touch.ts index 68247a006..1e7eb0e6e 100644 --- a/core/touch.ts +++ b/core/touch.ts @@ -85,6 +85,7 @@ let longPid_ = 0; * @param e Touch start event. * @param gesture The gesture that triggered this longStart. * @alias Blockly.Touch.longStart + * @internal */ export function longStart(e: Event, gesture: Gesture) { longStop(); @@ -117,6 +118,7 @@ export function longStart(e: Event, gesture: Gesture) { * Nope, that's not a long-press. Either touchend or touchcancel was fired, * or a drag hath begun. Kill the queued long-press task. * @alias Blockly.Touch.longStop + * @internal */ export function longStop() { if (longPid_) { diff --git a/core/touch_gesture.ts b/core/touch_gesture.ts index 00d074b6c..fa038e11f 100644 --- a/core/touch_gesture.ts +++ b/core/touch_gesture.ts @@ -84,6 +84,7 @@ export class TouchGesture extends Gesture { * Start a gesture: update the workspace to indicate that a gesture is in * progress and bind mousemove and mouseup handlers. * @param e A mouse down, touch start or pointer down event. + * @internal */ override doStart(e: Event) { this.isPinchZoomEnabled_ = this.startWorkspace_.options.zoomOptions && @@ -102,6 +103,7 @@ export class TouchGesture extends Gesture { * In addition, binding a second mouse down event to detect multi-touch * events. * @param e A mouse down or touch start event. + * @internal */ override bindMouseEvents(e: Event) { this.onStartWrapper_ = browserEvents.conditionalBind( @@ -121,6 +123,7 @@ export class TouchGesture extends Gesture { /** * Handle a mouse down, touch start, or pointer down event. * @param e A mouse down, touch start, or pointer down event. + * @internal */ handleStart(e: Event) { if (this.isDragging()) { @@ -139,6 +142,7 @@ export class TouchGesture extends Gesture { /** * Handle a mouse move, touch move, or pointer move event. * @param e A mouse move, touch move, or pointer move event. + * @internal */ override handleMove(e: Event) { if (this.isDragging()) { @@ -161,6 +165,7 @@ export class TouchGesture extends Gesture { /** * Handle a mouse up, touch end, or pointer up event. * @param e A mouse up, touch end, or pointer up event. + * @internal */ override handleUp(e: Event) { if (Touch.isTouchEvent(e) && !this.isDragging()) { @@ -182,12 +187,16 @@ export class TouchGesture extends Gesture { /** * Whether this gesture is part of a multi-touch gesture. * @return Whether this gesture is part of a multi-touch gesture. + * @internal */ isMultiTouch(): boolean { return this.isMultiTouch_; } - /** Sever all links from this object. */ + /** + * Sever all links from this object. + * @internal + */ override dispose() { super.dispose(); @@ -200,6 +209,7 @@ export class TouchGesture extends Gesture { * Handle a touch start or pointer down event and keep track of current * pointers. * @param e A touch start, or pointer down event. + * @internal */ handleTouchStart(e: Event) { const pointerId = Touch.getTouchIdentifierFromEvent(e); @@ -222,6 +232,7 @@ export class TouchGesture extends Gesture { * Handle a touch move or pointer move event and zoom in/out if two pointers * are on the screen. * @param e A touch move, or pointer move event. + * @internal */ handleTouchMove(e: Event) { const pointerId = Touch.getTouchIdentifierFromEvent(e); @@ -266,6 +277,7 @@ export class TouchGesture extends Gesture { /** * Handle a touch end or pointer end event and end the gesture. * @param e A touch end, or pointer end event. + * @internal */ handleTouchEnd(e: Event) { const pointerId = Touch.getTouchIdentifierFromEvent(e); @@ -282,6 +294,7 @@ export class TouchGesture extends Gesture { * Helper function returning the current touch point coordinate. * @param e A touch or pointer event. * @return The current touch point coordinate + * @internal */ getTouchPoint(e: Event): Coordinate|null { if (!this.startWorkspace_) { diff --git a/core/trashcan.ts b/core/trashcan.ts index 05fb4c12c..a70ecadc3 100644 --- a/core/trashcan.ts +++ b/core/trashcan.ts @@ -72,7 +72,10 @@ export class Trashcan extends DeleteArea implements IAutoHideable, */ private readonly contents_: string[] = []; - /** The trashcan flyout. */ + /** + * The trashcan flyout. + * @internal + */ // AnyDuringMigration because: Type 'null' is not assignable to type // 'IFlyout'. flyout: IFlyout = null as AnyDuringMigration; @@ -425,6 +428,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Flip the lid open or shut. * @param state True if open. + * @internal */ setLidOpen(state: boolean) { if (this.isLidOpen === state) { diff --git a/core/utils.ts b/core/utils.ts index 2730f9712..ee9c97178 100644 --- a/core/utils.ts +++ b/core/utils.ts @@ -303,6 +303,7 @@ export function is3dSupported(): boolean { * window coordinates. * @alias Blockly.utils.getViewportBBox * @deprecated + * @internal */ export function getViewportBBox(): Rect { // AnyDuringMigration because: Property 'warn' does not exist on type 'void'. @@ -322,6 +323,7 @@ export function getViewportBBox(): Rect { * @return True if an element was removed. * @alias Blockly.utils.arrayRemove * @deprecated + * @internal */ export function arrayRemove( arr: AnyDuringMigration[], value: AnyDuringMigration): boolean { diff --git a/core/utils/array.ts b/core/utils/array.ts index 38b3481be..12a0cadda 100644 --- a/core/utils/array.ts +++ b/core/utils/array.ts @@ -19,6 +19,7 @@ goog.declareModuleId('Blockly.utils.array'); * @param value Value to remove. * @return True if an element was removed. * @alias Blockly.array.removeElem + * @internal */ export function removeElem( arr: AnyDuringMigration[], value: AnyDuringMigration): boolean { diff --git a/core/utils/colour.ts b/core/utils/colour.ts index df19454ba..a669bce65 100644 --- a/core/utils/colour.ts +++ b/core/utils/colour.ts @@ -27,6 +27,7 @@ let hsvSaturation = 0.45; * Get the richness of block colours, regardless of the hue. * @alias Blockly.utils.colour.getHsvSaturation * @return The current richness. + * @internal */ export function getHsvSaturation(): number { return hsvSaturation; @@ -37,6 +38,7 @@ export function getHsvSaturation(): number { * @param newSaturation The new richness, in the range of 0 (inclusive) to 1 * (exclusive) * @alias Blockly.utils.colour.setHsvSaturation + * @internal */ export function setHsvSaturation(newSaturation: number) { hsvSaturation = newSaturation; @@ -53,6 +55,7 @@ let hsvValue = 0.65; * Get the intensity of block colours, regardless of the hue. * @alias Blockly.utils.colour.getHsvValue * @return The current intensity. + * @internal */ export function getHsvValue(): number { return hsvValue; @@ -63,6 +66,7 @@ export function getHsvValue(): number { * @param newValue The new intensity, in the range of 0 (inclusive) to 1 * (exclusive) * @alias Blockly.utils.colour.setHsvValue + * @internal */ export function setHsvValue(newValue: number) { hsvValue = newValue; diff --git a/core/utils/svg.ts b/core/utils/svg.ts index d91ac7724..aa7ae7eb6 100644 --- a/core/utils/svg.ts +++ b/core/utils/svg.ts @@ -23,33 +23,59 @@ goog.declareModuleId('Blockly.utils.Svg'); * @alias Blockly.utils.Svg */ export class Svg { + /** @internal */ static ANIMATE = new Svg('animate'); + /** @internal */ static CIRCLE = new Svg('circle'); + /** @internal */ static CLIPPATH = new Svg('clipPath'); + /** @internal */ static DEFS = new Svg('defs'); + /** @internal */ static FECOMPOSITE = new Svg('feComposite'); + /** @internal */ static FECOMPONENTTRANSFER = new Svg('feComponentTransfer'); + /** @internal */ static FEFLOOD = new Svg('feFlood'); + /** @internal */ static FEFUNCA = new Svg('feFuncA'); + /** @internal */ static FEGAUSSIANBLUR = new Svg('feGaussianBlur'); + /** @internal */ static FEPOINTLIGHT = new Svg('fePointLight'); + /** @internal */ static FESPECULARLIGHTING = new Svg('feSpecularLighting'); + /** @internal */ static FILTER = new Svg('filter'); + /** @internal */ static FOREIGNOBJECT = new Svg('foreignObject'); + /** @internal */ static G = new Svg('g'); + /** @internal */ static IMAGE = new Svg('image'); + /** @internal */ static LINE = new Svg('line'); + /** @internal */ static PATH = new Svg('path'); + /** @internal */ static PATTERN = new Svg('pattern'); + /** @internal */ static POLYGON = new Svg('polygon'); + /** @internal */ static RECT = new Svg('rect'); + /** @internal */ static SVG = new Svg('svg'); + /** @internal */ static TEXT = new Svg('text'); + /** @internal */ static TSPAN = new Svg('tspan'); - /** @param tagName The SVG element tag name. */ + /** + * @param tagName The SVG element tag name. + * @internal + */ constructor(private readonly tagName: string) {} /** diff --git a/core/utils/svg_math.ts b/core/utils/svg_math.ts index f5c867376..4692b2c20 100644 --- a/core/utils/svg_math.ts +++ b/core/utils/svg_math.ts @@ -178,6 +178,7 @@ export function is3dSupported(): boolean { * @return An object containing window width, height, and scroll position in * window coordinates. * @alias Blockly.utils.svgMath.getViewportBBox + * @internal */ export function getViewportBBox(): Rect { // Pixels, in window coordinates. diff --git a/core/utils/toolbox.ts b/core/utils/toolbox.ts index 4ace275aa..ca21d5d54 100644 --- a/core/utils/toolbox.ts +++ b/core/utils/toolbox.ts @@ -197,6 +197,7 @@ export enum Position { * @param toolboxDef The definition of the toolbox in one of its many forms. * @return Object holding information for creating a toolbox. * @alias Blockly.utils.toolbox.convertToolboxDefToJson + * @internal */ export function convertToolboxDefToJson(toolboxDef: ToolboxDefinition| null): ToolboxInfo|null { @@ -244,6 +245,7 @@ function validateToolbox(toolboxJson: ToolboxInfo) { * @param flyoutDef The definition of the flyout in one of its many forms. * @return A list of flyout items. * @alias Blockly.utils.toolbox.convertFlyoutDefToJsonArray + * @internal */ export function convertFlyoutDefToJsonArray(flyoutDef: FlyoutDefinition| null): FlyoutItemInfoArray { @@ -274,6 +276,7 @@ export function convertFlyoutDefToJsonArray(flyoutDef: FlyoutDefinition| * @param toolboxJson Object holding information for creating a toolbox. * @return True if the toolbox has categories. * @alias Blockly.utils.toolbox.hasCategories + * @internal */ export function hasCategories(toolboxJson: ToolboxInfo|null): boolean { if (!toolboxJson) { @@ -296,6 +299,7 @@ export function hasCategories(toolboxJson: ToolboxInfo|null): boolean { * @param categoryInfo Object holing information for creating a category. * @return True if the category has subcategories. * @alias Blockly.utils.toolbox.isCategoryCollapsible + * @internal */ export function isCategoryCollapsible(categoryInfo: CategoryInfo): boolean { if (!categoryInfo || !(categoryInfo as AnyDuringMigration)['contents']) { diff --git a/core/variable_map.ts b/core/variable_map.ts index b661ce95b..5149b2a5e 100644 --- a/core/variable_map.ts +++ b/core/variable_map.ts @@ -61,6 +61,7 @@ export class VariableMap { * Rename the given variable by updating its name in the variable map. * @param variable Variable to rename. * @param newName New variable name. + * @internal */ renameVariable(variable: VariableModel, newName: string) { const type = variable.type; @@ -252,6 +253,7 @@ export class VariableMap { * the user for confirmation. * @param variable Variable to delete. * @param uses An array of uses of the variable. + * @internal */ deleteVariableInternal(variable: VariableModel, uses: Block[]) { const existingGroup = eventUtils.getGroup(); @@ -332,6 +334,7 @@ export class VariableMap { * different than the workspace stored on this object if the passed in ws * is a flyout workspace. * @return List of variable types. + * @internal */ getVariableTypes(ws: Workspace|null): string[] { const variableMap = {}; diff --git a/core/variable_model.ts b/core/variable_model.ts index d60cefef5..4d4cf3642 100644 --- a/core/variable_model.ts +++ b/core/variable_model.ts @@ -75,6 +75,7 @@ export class VariableModel { * @param var2 Second variable to compare. * @return -1 if name of var1 is less than name of var2, 0 if equal, and 1 if * greater. + * @internal */ static compareByName(var1: VariableModel, var2: VariableModel): number { return var1.name.localeCompare(var2.name, undefined, {sensitivity: 'base'}); diff --git a/core/variables.ts b/core/variables.ts index f3bc3a9f5..27771d9da 100644 --- a/core/variables.ts +++ b/core/variables.ts @@ -563,6 +563,7 @@ function createVariable( * after creating the new block, or [] if no new variables were added to the * workspace. * @alias Blockly.Variables.getAddedVariables + * @internal */ export function getAddedVariables( workspace: Workspace, originalVariables: VariableModel[]): VariableModel[] { diff --git a/core/widgetdiv.ts b/core/widgetdiv.ts index 6a7f57235..8aa75d8f7 100644 --- a/core/widgetdiv.ts +++ b/core/widgetdiv.ts @@ -191,6 +191,7 @@ function positionInternal(x: number, y: number, height: number) { * @param rtl Whether the workspace is in RTL mode. This determines horizontal * alignment. * @alias Blockly.WidgetDiv.positionWithAnchor + * @internal */ export function positionWithAnchor( viewportBBox: Rect, anchorBBox: Rect, widgetSize: Size, rtl: boolean) { diff --git a/core/workspace.ts b/core/workspace.ts index 83c5a05a9..f6daf8439 100644 --- a/core/workspace.ts +++ b/core/workspace.ts @@ -75,12 +75,16 @@ export class Workspace implements IASTNodeLocation { /** Is this workspace the surface for a flyout? */ isFlyout = false; - /** Is this workspace the surface for a mutator? */ + /** + * Is this workspace the surface for a mutator? + * @internal + */ isMutator = false; /** * Returns `true` if the workspace is currently in the process of a bulk * clear. + * @internal */ isClearing = false; @@ -280,6 +284,7 @@ export class Workspace implements IASTNodeLocation { /** * Adds a comment to the list of top comments. * @param comment comment to add. + * @internal */ addTopComment(comment: WorkspaceComment) { this.topComments_.push(comment); @@ -297,6 +302,7 @@ export class Workspace implements IASTNodeLocation { /** * Removes a comment from the list of top comments. * @param comment comment to remove. + * @internal */ removeTopComment(comment: WorkspaceComment) { if (!arrayUtils.removeElem(this.topComments_, comment)) { @@ -314,6 +320,7 @@ export class Workspace implements IASTNodeLocation { * sorted by position; top to bottom (with slight LTR or RTL bias). * @param ordered Sort the list if true. * @return The top-level comment objects. + * @internal */ getTopComments(ordered: boolean): WorkspaceComment[] { // Copy the topComments_ list. @@ -472,6 +479,7 @@ export class Workspace implements IASTNodeLocation { /** * Return all variable types. * @return List of variable types. + * @internal */ getVariableTypes(): string[] { return this.variableMap_.getVariableTypes(this); @@ -584,6 +592,7 @@ export class Workspace implements IASTNodeLocation { /** * Gets the undo stack for workplace. * @return undo stack + * @internal */ getUndoStack(): Abstract[] { return this.undoStack_; @@ -592,6 +601,7 @@ export class Workspace implements IASTNodeLocation { /** * Gets the redo stack for workplace. * @return redo stack + * @internal */ getRedoStack(): Abstract[] { return this.redoStack_; @@ -693,6 +703,7 @@ export class Workspace implements IASTNodeLocation { * Set a block on this workspace with the specified ID. * @param id ID of block to set. * @param block The block to set. + * @internal */ setBlockById(id: string, block: Block) { this.blockDB_[id] = block; @@ -701,6 +712,7 @@ export class Workspace implements IASTNodeLocation { /** * Delete a block off this workspace with the specified ID. * @param id ID of block to delete. + * @internal */ removeBlockById(id: string) { delete this.blockDB_[id]; @@ -710,6 +722,7 @@ export class Workspace implements IASTNodeLocation { * Find the comment on this workspace with the specified ID. * @param id ID of comment to find. * @return The sought after comment, or null if not found. + * @internal */ getCommentById(id: string): WorkspaceComment|null { return this.commentDB_[id] || null; @@ -737,12 +750,16 @@ export class Workspace implements IASTNodeLocation { * Return the variable map that contains "potential" variables. * These exist in the flyout but not in the workspace. * @return The potential variable map. + * @internal */ getPotentialVariableMap(): VariableMap|null { return this.potentialVariableMap_; } - /** Create and store the potential variable map for this workspace. */ + /** + * Create and store the potential variable map for this workspace. + * @internal + */ createPotentialVariableMap() { this.potentialVariableMap_ = new VariableMap(this); } @@ -758,6 +775,7 @@ export class Workspace implements IASTNodeLocation { /** * Set the map of all variables on the workspace. * @param variableMap The variable map. + * @internal */ setVariableMap(variableMap: VariableMap) { this.variableMap_ = variableMap; diff --git a/core/workspace_audio.ts b/core/workspace_audio.ts index f09bab36f..44a3d68d0 100644 --- a/core/workspace_audio.ts +++ b/core/workspace_audio.ts @@ -48,7 +48,10 @@ export class WorkspaceAudio { this.SOUNDS_ = Object.create(null); } - /** Dispose of this audio manager. */ + /** + * Dispose of this audio manager. + * @internal + */ dispose() { // AnyDuringMigration because: Type 'null' is not assignable to type // 'WorkspaceSvg'. @@ -90,7 +93,10 @@ export class WorkspaceAudio { } } - /** Preload all the audio files so that they play quickly when asked for. */ + /** + * Preload all the audio files so that they play quickly when asked for. + * @internal + */ preload() { for (const name in this.SOUNDS_) { const sound = this.SOUNDS_[name]; diff --git a/core/workspace_comment.ts b/core/workspace_comment.ts index e7b2d320e..94b2949ce 100644 --- a/core/workspace_comment.ts +++ b/core/workspace_comment.ts @@ -52,6 +52,7 @@ export class WorkspaceComment { /** Whether this comment has been disposed. */ protected disposed_ = false; + /** @internal */ isComment = true; /** @@ -96,7 +97,10 @@ export class WorkspaceComment { WorkspaceComment.fireCreateEvent(this); } - /** Dispose of this comment. */ + /** + * Dispose of this comment. + * @internal + */ dispose() { if (this.disposed_) { return; @@ -116,6 +120,7 @@ export class WorkspaceComment { /** * Get comment height. * @return Comment height. + * @internal */ getHeight(): number { return this.height_; @@ -124,6 +129,7 @@ export class WorkspaceComment { /** * Set comment height. * @param height Comment height. + * @internal */ setHeight(height: number) { this.height_ = height; @@ -132,6 +138,7 @@ export class WorkspaceComment { /** * Get comment width. * @return Comment width. + * @internal */ getWidth(): number { return this.width_; @@ -140,6 +147,7 @@ export class WorkspaceComment { /** * Set comment width. * @param width comment width. + * @internal */ setWidth(width: number) { this.width_ = width; @@ -149,6 +157,7 @@ export class WorkspaceComment { * Get stored location. * @return The comment's stored location. * This is not valid if the comment is currently being dragged. + * @internal */ getXY(): Coordinate { return new Coordinate(this.xy_.x, this.xy_.y); @@ -158,6 +167,7 @@ export class WorkspaceComment { * Move a comment by a relative offset. * @param dx Horizontal offset, in workspace units. * @param dy Vertical offset, in workspace units. + * @internal */ moveBy(dx: number, dy: number) { const event = @@ -170,6 +180,7 @@ export class WorkspaceComment { /** * Get whether this comment is deletable or not. * @return True if deletable. + * @internal */ isDeletable(): boolean { return this.deletable_ && @@ -179,6 +190,7 @@ export class WorkspaceComment { /** * Set whether this comment is deletable or not. * @param deletable True if deletable. + * @internal */ setDeletable(deletable: boolean) { this.deletable_ = deletable; @@ -187,6 +199,7 @@ export class WorkspaceComment { /** * Get whether this comment is movable or not. * @return True if movable. + * @internal */ isMovable(): boolean { return this.movable_ && @@ -196,6 +209,7 @@ export class WorkspaceComment { /** * Set whether this comment is movable or not. * @param movable True if movable. + * @internal */ setMovable(movable: boolean) { this.movable_ = movable; @@ -221,6 +235,7 @@ export class WorkspaceComment { /** * Returns this comment's text. * @return Comment text. + * @internal */ getContent(): string { return this.content_; @@ -229,6 +244,7 @@ export class WorkspaceComment { /** * Set this comment's content. * @param content Comment content. + * @internal */ setContent(content: string) { if (this.content_ !== content) { @@ -242,6 +258,7 @@ export class WorkspaceComment { * Encode a comment subtree as XML with XY coordinates. * @param opt_noId True if the encoder should skip the comment ID. * @return Tree of XML elements. + * @internal */ toXmlWithXY(opt_noId?: boolean): Element { const element = this.toXml(opt_noId); @@ -266,6 +283,7 @@ export class WorkspaceComment { * toXmlWithXY(). * @param opt_noId True if the encoder should skip the comment ID. * @return Tree of XML elements. + * @internal */ toXml(opt_noId?: boolean): Element { const commentElement = xml.createElement('comment'); @@ -280,6 +298,7 @@ export class WorkspaceComment { * Fire a create event for the given workspace comment, if comments are * enabled. * @param comment The comment that was just created. + * @internal */ static fireCreateEvent(comment: WorkspaceComment) { if (eventUtils.isEnabled()) { @@ -303,6 +322,7 @@ export class WorkspaceComment { * @param xmlComment XML comment element. * @param workspace The workspace. * @return The created workspace comment. + * @internal */ static fromXml(xmlComment: Element, workspace: Workspace): WorkspaceComment { const info = WorkspaceComment.parseAttributes(xmlComment); @@ -330,6 +350,7 @@ export class WorkspaceComment { * Decode an XML comment tag and return the results in an object. * @param xml XML comment element. * @return An object containing the id, size, position, and comment string. + * @internal */ static parseAttributes(xml: Element): { id: string, diff --git a/core/workspace_comment_svg.ts b/core/workspace_comment_svg.ts index 506b43320..8fefb16a8 100644 --- a/core/workspace_comment_svg.ts +++ b/core/workspace_comment_svg.ts @@ -65,6 +65,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * The width and height to use to size a workspace comment when it is first * added, before it has been edited by the user. + * @internal */ static DEFAULT_SIZE = 100; @@ -139,7 +140,10 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements this.render(); } - /** Dispose of this comment. */ + /** + * Dispose of this comment. + * @internal + */ override dispose() { if (this.disposed_) { return; @@ -168,6 +172,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * May be called more than once. * * @param opt_noSelect Text inside text area will be selected if false + * @internal */ initSvg(opt_noSelect?: boolean) { if (!this.workspace.rendered) { @@ -207,6 +212,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Show the context menu for this workspace comment. * @param e Mouse event. + * @internal */ showContextMenu(e: Event) { if (this.workspace.options.readOnly) { @@ -224,7 +230,10 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements ContextMenu.show(e, menuOptions, this.RTL); } - /** Select this comment. Highlight it visually. */ + /** + * Select this comment. Highlight it visually. + * @internal + */ select() { if (common.getSelected() === this) { return; @@ -247,7 +256,10 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements this.addSelect(); } - /** Unselect this comment. Remove its highlighting. */ + /** + * Unselect this comment. Remove its highlighting. + * @internal + */ unselect() { if (common.getSelected() !== this) { return; @@ -260,24 +272,36 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements this.blurFocus(); } - /** Select this comment. Highlight it visually. */ + /** + * Select this comment. Highlight it visually. + * @internal + */ addSelect() { dom.addClass(this.svgGroup_ as Element, 'blocklySelected'); this.setFocus(); } - /** Unselect this comment. Remove its highlighting. */ + /** + * Unselect this comment. Remove its highlighting. + * @internal + */ removeSelect() { dom.removeClass(this.svgGroup_ as Element, 'blocklySelected'); this.blurFocus(); } - /** Focus this comment. Highlight it visually. */ + /** + * Focus this comment. Highlight it visually. + * @internal + */ addFocus() { dom.addClass(this.svgGroup_ as Element, 'blocklyFocused'); } - /** Unfocus this comment. Remove its highlighting. */ + /** + * Unfocus this comment. Remove its highlighting. + * @internal + */ removeFocus() { dom.removeClass(this.svgGroup_ as Element, 'blocklyFocused'); } @@ -289,6 +313,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * coordinate system. * This does not change with workspace scale. * @return Object with .x and .y properties in workspace coordinates. + * @internal */ getRelativeToSurfaceXY(): Coordinate { let x = 0; @@ -329,6 +354,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * Move a comment by a relative offset. * @param dx Horizontal offset, in workspace units. * @param dy Vertical offset, in workspace units. + * @internal */ override moveBy(dx: number, dy: number) { const event = @@ -347,6 +373,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * 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. + * @internal */ translate(x: number, y: number) { this.xy_ = new Coordinate(x, y); @@ -358,6 +385,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * Move this comment 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() { if (!this.useDragSurface_) { @@ -380,6 +408,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * @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. + * @internal */ moveDuringDrag(dragSurface: BlockDragSurfaceSvg, newLoc: Coordinate) { if (dragSurface) { @@ -399,6 +428,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * 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 */ moveTo(x: number, y: number) { this.translate(x, y); @@ -417,6 +447,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * comment. * Coordinate system: workspace coordinates. * @return Object with coordinates of the bounding box. + * @internal */ getBoundingRectangle(): Rect { const blockXY = this.getRelativeToSurfaceXY(); @@ -439,7 +470,10 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements return new Rect(top, bottom, left, right); } - /** Add or remove the UI indicating if this comment is movable or not. */ + /** + * Add or remove the UI indicating if this comment is movable or not. + * @internal + */ updateMovable() { if (this.isMovable()) { dom.addClass(this.svgGroup_ as Element, 'blocklyDraggable'); @@ -451,6 +485,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Set whether this comment is movable or not. * @param movable True if movable. + * @internal */ override setMovable(movable: boolean) { super.setMovable(movable); @@ -472,6 +507,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * Recursively adds or removes the dragging class to this node and its * children. * @param adding True if adding, false if removing. + * @internal */ setDragging(adding: boolean) { if (adding) { @@ -487,6 +523,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Return the root node of the SVG or null if none exists. * @return The root SVG node (probably a group). + * @internal */ getSvgRoot(): SVGElement { return this.svgGroup_; @@ -495,6 +532,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Returns this comment's text. * @return Comment text. + * @internal */ override getContent(): string { return this.textarea_ ? this.textarea_.value : this.content_; @@ -503,6 +541,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Set this comment's content. * @param content Comment content. + * @internal */ override setContent(content: string) { super.setContent(content); @@ -514,6 +553,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Update the cursor over this comment by adding or removing a class. * @param enable True if the delete cursor should be shown, false otherwise. + * @internal */ setDeleteStyle(enable: boolean) { if (enable) { @@ -528,6 +568,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * 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 */ setAutoLayout(_enable: boolean) {} // NOP for compatibility with the bubble dragger. @@ -536,6 +577,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * Encode a comment subtree as XML with XY coordinates. * @param opt_noId True if the encoder should skip the comment ID. * @return Tree of XML elements. + * @internal */ override toXmlWithXY(opt_noId?: boolean): Element { let width = 0; @@ -567,6 +609,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Encode a comment for copying. * @return Copy metadata. + * @internal */ toCopyData(): CopyData { return { @@ -579,12 +622,16 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Returns a bounding box describing the dimensions of this comment. * @return Object with height and width properties in workspace units. + * @internal */ getHeightWidth(): {height: number, width: number} { return {width: this.getWidth(), height: this.getHeight()}; } - /** Renders the workspace comment. */ + /** + * Renders the workspace comment. + * @internal + */ render() { if (this.rendered_) { return; @@ -945,7 +992,10 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements this.disposed_ = true; } - /** Set the focus on the text area. */ + /** + * Set the focus on the text area. + * @internal + */ setFocus() { const comment = this; this.focused_ = true; @@ -965,7 +1015,10 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements }, 0); } - /** Remove focus from the text area. */ + /** + * Remove focus from the text area. + * @internal + */ blurFocus() { const comment = this; this.focused_ = false; @@ -993,6 +1046,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * @param opt_wsWidth The width of the workspace, which is used to position * comments correctly in RTL. * @return The created workspace comment. + * @internal */ static fromXmlRendered( xmlComment: Element, workspace: WorkspaceSvg, diff --git a/core/workspace_drag_surface_svg.ts b/core/workspace_drag_surface_svg.ts index d6f8fb613..5756ef156 100644 --- a/core/workspace_drag_surface_svg.ts +++ b/core/workspace_drag_surface_svg.ts @@ -86,6 +86,7 @@ export class WorkspaceDragSurfaceSvg { * 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 + * @internal */ translateSurface(x: number, y: number) { // Make sure the svg exists on a pixel boundary so that it is not fuzzy. @@ -101,6 +102,7 @@ export class WorkspaceDragSurfaceSvg { * 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 + * @internal */ getSurfaceTranslation(): Coordinate { return svgMath.getRelativeXY((this.SVG_)); @@ -110,6 +112,7 @@ export class WorkspaceDragSurfaceSvg { * Move the blockCanvas and bubbleCanvas out of the surface SVG and on to * newSurface. * @param newSurface The element to put the drag surface contents into. + * @internal */ clearAndHide(newSurface: SVGElement) { if (!newSurface) { @@ -159,6 +162,7 @@ export class WorkspaceDragSurfaceSvg { * @param width The width of the workspace SVG element. * @param height The height of the workspace SVG element. * @param scale The scale of the workspace being dragged. + * @internal */ setContentsAndShow( blockCanvas: SVGElement, bubbleCanvas: SVGElement, diff --git a/core/workspace_dragger.ts b/core/workspace_dragger.ts index 052106564..abdfbb6f6 100644 --- a/core/workspace_dragger.ts +++ b/core/workspace_dragger.ts @@ -52,6 +52,7 @@ export class WorkspaceDragger { /** * Sever all links from this object. * @suppress {checkTypes} + * @internal */ dispose() { // AnyDuringMigration because: Type 'null' is not assignable to type @@ -59,7 +60,10 @@ export class WorkspaceDragger { this.workspace = null as AnyDuringMigration; } - /** Start dragging the workspace. */ + /** + * Start dragging the workspace. + * @internal + */ startDrag() { if (common.getSelected()) { common.getSelected()!.unselect(); @@ -71,6 +75,7 @@ export class WorkspaceDragger { * Finish dragging the workspace and put everything back where it belongs. * @param currentDragDeltaXY How far the pointer has moved from the position * at the start of the drag, in pixel coordinates. + * @internal */ endDrag(currentDragDeltaXY: Coordinate) { // Make sure everything is up to date. @@ -82,6 +87,7 @@ export class WorkspaceDragger { * Move the workspace based on the most recent mouse movements. * @param currentDragDeltaXY How far the pointer has moved from the position * at the start of the drag, in pixel coordinates. + * @internal */ drag(currentDragDeltaXY: Coordinate) { const newXY = Coordinate.sum(this.startScrollXY_, currentDragDeltaXY); diff --git a/core/workspace_svg.ts b/core/workspace_svg.ts index ebf3cc269..580ffdde2 100644 --- a/core/workspace_svg.ts +++ b/core/workspace_svg.ts @@ -272,7 +272,10 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { // 'IToolbox'. private toolbox_: IToolbox = null as AnyDuringMigration; - /** The current gesture in progress on this workspace, if any. */ + /** + * The current gesture in progress on this workspace, if any. + * @internal + */ // AnyDuringMigration because: Type 'null' is not assignable to type // 'TouchGesture'. currentGesture_: TouchGesture = null as AnyDuringMigration; @@ -332,6 +335,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * In a flyout, the target workspace where blocks should be placed after a * drag. Otherwise null. + * @internal */ // AnyDuringMigration because: Type 'null' is not assignable to type // 'WorkspaceSvg'. @@ -343,7 +347,9 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** Inverted screen CTM is dirty, recalculate it. */ private inverseScreenCTMDirty_ = true; private metricsManager_: IMetricsManager; + /** @internal */ getMetrics: () => Metrics; + /** @internal */ setMetrics: (p1: {x: number, y: number}) => void; private readonly componentManager_: ComponentManager; @@ -508,6 +514,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Sets the metrics manager for the workspace. * @param metricsManager The metrics manager. + * @internal */ setMetricsManager(metricsManager: IMetricsManager) { this.metricsManager_ = metricsManager; @@ -527,6 +534,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * Add the cursor SVG to this workspaces SVG group. * @param cursorSvg The SVG root of the cursor to be added to the workspace * SVG group. + * @internal */ setCursorSvg(cursorSvg: SVGElement) { this.markerManager_.setCursorSvg(cursorSvg); @@ -536,6 +544,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * 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 */ setMarkerSvg(markerSvg: SVGElement) { this.markerManager_.setMarkerSvg(markerSvg); @@ -546,6 +555,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * @param id The ID of the marker. * @return The marker with the given ID or null if no marker with the given ID * exists. + * @internal */ getMarker(id: string): Marker|null { if (this.markerManager_) { @@ -576,6 +586,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Get the theme manager for this workspace. * @return The theme manager for this workspace. + * @internal */ getThemeManager(): ThemeManager { return this.themeManager_; @@ -601,7 +612,9 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { this.themeManager_.setTheme(theme); } - /** Refresh all blocks on the workspace after a theme update. */ + /** + * Refresh all blocks on the workspace after a theme update. + */ refreshTheme() { if (this.svgGroup_) { this.renderer_.refreshDom(this.svgGroup_, this.getTheme()); @@ -685,6 +698,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * The origin (0,0) is the top-left corner of the Blockly SVG. * @param element SVG element to find the coordinates of. * @return Object with .x and .y properties. + * @internal */ getSvgXY(element: SVGElement): Coordinate { let x = 0; @@ -712,6 +726,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Gets the size of the workspace's parent SVG element. * @return The cached width and height of the workspace's parent SVG element. + * @internal */ getCachedParentSvgSize(): Size { const size = this.cachedParentSvgSize_; @@ -724,6 +739,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * The workspace origin is where a block would render at position (0, 0). * It is not the upper left corner of the workspace SVG. * @return Offset in pixels. + * @internal */ getOriginOffsetInPixels(): Coordinate { return svgMath.getInjectionDivXY(this.getCanvas()); @@ -735,6 +751,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * Note: We assume this is only called after the workspace has been injected * into the DOM. * @return The first parent div with 'injectionDiv' in the name. + * @internal */ getInjectionDiv(): Element { // NB: it would be better to pass this in at createDom, but is more likely @@ -756,6 +773,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Get the SVG block canvas for the workspace. * @return The SVG group for the workspace. + * @internal */ getBlockCanvas(): SVGElement|null { return this.svgBlockCanvas_; @@ -953,14 +971,20 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { } } - /** Add a trashcan. */ + /** + * Add a trashcan. + * @internal + */ addTrashcan() { this.trashcan = new Trashcan(this); const svgTrashcan = this.trashcan.createDom(); this.svgGroup_.insertBefore(svgTrashcan, this.svgBlockCanvas_); } - /** Add zoom controls. */ + /** + * Add zoom controls. + * @internal + */ addZoomControls() { this.zoomControls_ = new ZoomControls(this); const svgZoomControls = this.zoomControls_.createDom(); @@ -971,6 +995,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * Add a flyout element in an element with the given tag name. * @param tagName What type of tag the flyout belongs in. * @return The element containing the flyout DOM. + * @internal */ addFlyout(tagName: string|Svg|Svg): Element { const workspaceOptions = new Options(({ @@ -1009,6 +1034,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * configuration. It will be null if there is no flyout. * @param opt_own Whether to only return the workspace's own flyout. * @return The flyout on this workspace. + * @internal */ getFlyout(opt_own?: boolean): IFlyout|null { if (this.flyout_ || opt_own) { @@ -1023,6 +1049,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Getter for the toolbox associated with this workspace, if one exists. * @return The toolbox on this workspace. + * @internal */ getToolbox(): IToolbox|null { return this.toolbox_; @@ -1041,6 +1068,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * If enabled, resize the parts of the workspace that change when the * workspace contents (e.g. block positions) change. This will also scroll * the workspace contents if needed. + * @internal */ resizeContents() { if (!this.resizesEnabled_ || !this.rendered) { @@ -1088,6 +1116,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Resizes and repositions workspace chrome if the page has a new * scroll position. + * @internal */ updateScreenCalculationsIfScrolled() { /* eslint-disable indent */ @@ -1112,6 +1141,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * with getSvgMetrics. * @param width The width of the parent SVG element. * @param height The height of the parent SVG element + * @internal */ setCachedParentSvgSize(width: number|null, height: number|null) { const svg = this.getParentSvg(); @@ -1164,6 +1194,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Fires a viewport event if events are enabled and there is a change in * viewport values. + * @internal */ maybeFireViewportChangeEvent() { if (!eventUtils.isEnabled()) { @@ -1218,6 +1249,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * Called at the end of a workspace drag to take the contents * out of the drag surface and put them back into the workspace SVG. * Does nothing if the workspace drag surface is not enabled. + * @internal */ resetDragSurface() { // Don't do anything if we aren't using a drag surface. @@ -1239,6 +1271,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * Called at the beginning of a workspace drag to move contents of * the workspace to the drag surface. * Does nothing if the drag surface is not enabled. + * @internal */ setupDragSurface() { // Don't do anything if we aren't using a drag surface. @@ -1278,6 +1311,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Gets the drag surface blocks are moved to when a drag is started. * @return This workspace's block drag surface, if one is in use. + * @internal */ getBlockDragSurface(): BlockDragSurfaceSvg|null { return this.blockDragSurface_; @@ -1561,7 +1595,10 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { return comment; } - /** Refresh the toolbox unless there's a drag in progress. */ + /** + * Refresh the toolbox unless there's a drag in progress. + * @internal + */ refreshToolboxSelection() { const ws = this.isFlyout ? this.targetWorkspace : this; if (ws && !ws.currentGesture_ && ws.toolbox_ && ws.toolbox_.getFlyout()) { @@ -1886,6 +1923,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Show the context menu for the workspace. * @param e Mouse event. + * @internal */ showContextMenu(e: Event) { if (this.options.readOnly || this.isFlyout) { @@ -2118,13 +2156,17 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Add a transition class to the block and bubble canvas, to animate any * transform changes. + * @internal */ beginCanvasTransition() { dom.addClass((this.svgBlockCanvas_), 'blocklyCanvasTransitioning'); dom.addClass((this.svgBubbleCanvas_), 'blocklyCanvasTransitioning'); } - /** Remove transition class from the block and bubble canvas. */ + /** + * Remove transition class from the block and bubble canvas. + * @internal + */ endCanvasTransition() { dom.removeClass((this.svgBlockCanvas_), 'blocklyCanvasTransitioning'); dom.removeClass((this.svgBubbleCanvas_), 'blocklyCanvasTransitioning'); @@ -2271,6 +2313,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * the meaning of these values. * @param x Target X to scroll to. * @param y Target Y to scroll to. + * @internal */ scroll(x: number, y: number) { this.hideChaff(/* opt_onlyClosePopups= */ @@ -2506,6 +2549,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * @param e Mouse event or touch event. * @return The gesture that is tracking this touch stream, or null if no valid * gesture exists. + * @internal */ getGesture(e: Event): TouchGesture|null { const isStart = e.type === 'mousedown' || e.type === 'touchstart' || @@ -2533,14 +2577,20 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { return null; } - /** Clear the reference to the current gesture. */ + /** + * Clear the reference to the current gesture. + * @internal + */ clearGesture() { // AnyDuringMigration because: Type 'null' is not assignable to type // 'TouchGesture'. this.currentGesture_ = null as AnyDuringMigration; } - /** Cancel the current gesture, if one exists. */ + /** + * Cancel the current gesture, if one exists. + * @internal + */ cancelCurrentGesture() { if (this.currentGesture_) { this.currentGesture_.cancel(); @@ -2558,6 +2608,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { /** * Get the grid object for this workspace, or null if there is none. * @return The grid object for this workspace. + * @internal */ getGrid(): Grid|null { return this.grid_; @@ -2612,6 +2663,7 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg { * scrollbars accordingly. * @param workspace The workspace to resize. * @alias Blockly.WorkspaceSvg.resizeSvgContents + * @internal */ export function resizeSvgContents(workspace: WorkspaceSvg) { workspace.resizeContents();