diff --git a/core/block.ts b/core/block.ts index 2823f752b5b..7927f776c3c 100644 --- a/core/block.ts +++ b/core/block.ts @@ -82,7 +82,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; /** @@ -190,6 +193,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; @@ -214,7 +218,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; @@ -490,6 +497,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 = []; @@ -517,6 +525,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; @@ -606,6 +615,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++) { @@ -637,6 +647,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; @@ -681,6 +692,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_) { @@ -807,6 +819,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; @@ -824,6 +837,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; @@ -866,6 +880,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); @@ -1013,6 +1028,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Return all variables referenced by this block. * @return List of variable models. + * @internal */ getVarModels(): VariableModel[] { const vars = []; @@ -1036,6 +1052,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 4033bb3d6f7..fb4c1c56e01 100644 --- a/core/block_animations.ts +++ b/core/block_animations.ts @@ -36,6 +36,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; @@ -93,6 +94,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; @@ -150,6 +152,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'); @@ -202,6 +205,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 189ea71505d..7dc862bc3bc 100644 --- a/core/block_dragger.ts +++ b/core/block_dragger.ts @@ -77,7 +77,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 c9cc9468b65..9074e2e5591 100644 --- a/core/block_svg.ts +++ b/core/block_svg.ts @@ -105,6 +105,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * An property used internally to reference the block's rendering debugger. + * @internal */ renderingDebugger: BlockRenderingDebug|null = null; @@ -140,6 +141,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; @@ -338,6 +340,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_; @@ -454,6 +457,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_) { @@ -488,6 +492,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_) { @@ -504,6 +509,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_) { @@ -692,7 +698,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; @@ -727,6 +736,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(); @@ -744,6 +754,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) { @@ -770,6 +781,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Recursively adds or removes the dragging class to this node and its * children. * @param adding True if adding, false if removing. + * @internal */ setDragging(adding: boolean) { if (adding) { @@ -812,6 +824,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); @@ -822,6 +835,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) { @@ -940,6 +954,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_) { @@ -958,7 +973,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); @@ -977,6 +995,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)); @@ -1187,6 +1206,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); @@ -1250,6 +1270,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; @@ -1387,6 +1408,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) { @@ -1430,6 +1452,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 = []; @@ -1461,6 +1484,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 { @@ -1474,6 +1498,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 { @@ -1555,6 +1580,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; @@ -1581,6 +1607,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, @@ -1596,7 +1623,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; } @@ -1700,6 +1730,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); @@ -1709,6 +1740,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); @@ -1718,6 +1750,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; @@ -1739,6 +1772,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); @@ -1749,6 +1783,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 c631399c3b6..6bc9100e6a9 100644 --- a/core/bubble.ts +++ b/core/bubble.ts @@ -139,9 +139,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. @@ -306,6 +307,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 @@ -314,6 +316,7 @@ export class Bubble implements IBubble { /** * Get whether this bubble is deletable or not. * @return True if deletable. + * @internal */ isDeletable(): boolean { return false; @@ -390,6 +393,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; @@ -622,6 +626,7 @@ export class Bubble implements IBubble { * Move the bubble group to the specified location in workspace coordinates. * @param x The x position to move to. * @param y The y position to move to. + * @internal */ moveTo(x: number, y: number) { this.bubbleGroup_.setAttribute( @@ -631,6 +636,7 @@ export class Bubble implements IBubble { /** * Triggers a move callback if one exists at the end of a drag. * @param adding True if adding, false if removing. + * @internal */ setDragging(adding: boolean) { if (!adding && this.moveCallback_) { @@ -789,6 +795,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) { @@ -823,6 +830,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; @@ -853,6 +861,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, { @@ -875,6 +884,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 8fe8fe143eb..577ba17e1b3 100644 --- a/core/bubble_dragger.ts +++ b/core/bubble_dragger.ts @@ -77,6 +77,7 @@ export class BubbleDragger { /** * Sever all links from this object. * @suppress {checkTypes} + * @internal */ dispose() { // AnyDuringMigration because: Type 'null' is not assignable to type @@ -92,6 +93,7 @@ export class BubbleDragger { /** * Start dragging a bubble. This includes moving it to the drag surface. + * @internal */ startBubbleDrag() { if (!eventUtils.getGroup()) { @@ -113,6 +115,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); @@ -167,6 +170,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 1030c2318ce..f36e84654f8 100644 --- a/core/clipboard.ts +++ b/core/clipboard.ts @@ -21,6 +21,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(); @@ -30,6 +31,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) { @@ -54,6 +56,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 17e920fe077..e8d3941fc99 100644 --- a/core/comment.ts +++ b/core/comment.ts @@ -361,7 +361,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 f77a64b5db3..5f0c0ca563f 100644 --- a/core/common.ts +++ b/core/common.ts @@ -95,6 +95,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 0102e6c17e4..5186f0e0525 100644 --- a/core/connection.ts +++ b/core/connection.ts @@ -50,7 +50,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. */ @@ -62,10 +65,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; @@ -134,7 +143,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()) { @@ -180,6 +192,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; @@ -190,6 +203,7 @@ export class Connection implements IASTNodeLocationWithBlock { * headless workspaces). * @param _otherConnection Connection that this connection failed to connect * to. + * @internal */ onFailedConnect(_otherConnection: Connection) {} // NOP @@ -408,6 +422,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 []; @@ -417,6 +432,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 e88a7281b92..9b334405c7d 100644 --- a/core/connection_db.ts +++ b/core/connection_db.ts @@ -50,6 +50,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 9ebb217fa16..fa7e857f7b4 100644 --- a/core/contextmenu.ts +++ b/core/contextmenu.ts @@ -277,6 +277,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 { @@ -299,6 +300,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 { @@ -321,6 +323,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 ee1fdcce4b8..9486a136058 100644 --- a/core/contextmenu_items.ts +++ b/core/contextmenu_items.ts @@ -572,6 +572,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 0d89fffb4d3..52c584ff566 100644 --- a/core/dropdowndiv.ts +++ b/core/dropdowndiv.ts @@ -116,7 +116,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; @@ -295,6 +298,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, @@ -489,6 +493,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, @@ -655,6 +660,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 b0463e590b9..c3287702bd7 100644 --- a/core/events/events_block_change.ts +++ b/core/events/events_block_change.ts @@ -158,6 +158,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 a6f4202e612..2161395e30d 100644 --- a/core/events/utils.ts +++ b/core/events/utils.ts @@ -430,6 +430,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 02548e4f464..09ead5bb1e5 100644 --- a/core/extensions.ts +++ b/core/extensions.ts @@ -343,6 +343,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 1fa9a5761ea..518684b159f 100644 --- a/core/field.ts +++ b/core/field.ts @@ -146,7 +146,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. */ @@ -172,10 +175,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; /** @@ -284,6 +293,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_) { @@ -303,7 +313,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_(); @@ -312,6 +325,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() {} @@ -366,6 +380,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); @@ -376,6 +391,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(); @@ -389,6 +405,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); @@ -402,6 +419,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)) { @@ -454,6 +472,7 @@ export abstract class Field implements IASTNodeLocationSvg, /** * Dispose of all DOM objects and events belonging to this editable field. + * @internal */ dispose() { dropDownDiv.hideIfOwner(this); @@ -560,6 +579,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) { @@ -611,6 +631,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. @@ -634,6 +655,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()) { @@ -764,6 +786,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; @@ -858,6 +881,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; @@ -871,6 +895,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; @@ -1073,6 +1098,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; @@ -1081,6 +1107,7 @@ export abstract class Field implements IASTNodeLocationSvg, /** * Refresh the variable name referenced by this field if this field references * variables. + * @internal */ refreshVariableName() {} // NOP @@ -1089,6 +1116,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; @@ -1138,6 +1166,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) { @@ -1154,6 +1183,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 1e13b0193be..502e86d2da9 100644 --- a/core/field_angle.ts +++ b/core/field_angle.ts @@ -209,7 +209,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 @@ -502,6 +505,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 707efbd2597..0b397c22e1a 100644 --- a/core/field_checkbox.ts +++ b/core/field_checkbox.ts @@ -97,6 +97,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); @@ -106,7 +107,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(); @@ -214,6 +218,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 21807ee4efb..cdc8c657e7c 100644 --- a/core/field_colour.ts +++ b/core/field_colour.ts @@ -184,7 +184,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, @@ -566,6 +569,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 963ef5b94ff..e126a78e37b 100644 --- a/core/field_dropdown.ts +++ b/core/field_dropdown.ts @@ -87,11 +87,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 0afc1cdc839..cb58665bb7b 100644 --- a/core/field_image.ts +++ b/core/field_image.ts @@ -140,7 +140,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, { @@ -244,6 +247,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 bc5b42328ba..cef7bc13f08 100644 --- a/core/field_label.ts +++ b/core/field_label.ts @@ -74,7 +74,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_) { @@ -119,6 +122,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 bd3b3507604..edfb2da8275 100644 --- a/core/field_label_serializable.ts +++ b/core/field_label_serializable.ts @@ -61,6 +61,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 b6a61a324cb..ea8a3405b46 100644 --- a/core/field_multilineinput.ts +++ b/core/field_multilineinput.ts @@ -91,6 +91,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 @@ -106,6 +107,7 @@ export class FieldMultilineInput extends FieldTextInput { * Sets the field's value based on the given XML element. Should only be * called by Blockly.Xml. * @param fieldElement The element containing info about the field's state. + * @internal */ override fromXml(fieldElement: Element) { this.setValue(fieldElement.textContent!.replace(/ /g, '\n')); @@ -114,6 +116,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); @@ -126,6 +129,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)) { @@ -134,7 +138,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( @@ -413,6 +420,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 d3e582413bc..aa6dc3db7de 100644 --- a/core/field_number.ts +++ b/core/field_number.ts @@ -297,6 +297,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 012e4d1ac68..45c2b674a08 100644 --- a/core/field_registry.ts +++ b/core/field_registry.ts @@ -58,6 +58,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 10945c8b022..83cd4df9735 100644 --- a/core/field_textinput.ts +++ b/core/field_textinput.ts @@ -130,6 +130,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. @@ -212,7 +213,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_) { @@ -561,6 +565,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 bff75a755af..feab8a243df 100644 --- a/core/field_variable.ts +++ b/core/field_variable.ts @@ -132,6 +132,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_) { @@ -206,6 +207,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); @@ -225,6 +227,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)) { @@ -270,6 +273,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_; @@ -422,6 +426,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(); @@ -457,6 +462,7 @@ export class FieldVariable extends FieldDropdown { * Overrides referencesVariables(), indicating this field refers to a * variable. * @return True. + * @internal */ override referencesVariables(): boolean { return true; @@ -469,6 +475,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 0efc7fd5bb4..18b1bdee6fe 100644 --- a/core/flyout_base.ts +++ b/core/flyout_base.ts @@ -148,6 +148,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; @@ -191,7 +192,8 @@ export abstract class Flyout extends DeleteArea implements IFlyout { protected readonly tabWidth_: number; /** - * The target workspace + * The target workspace. + * @internal */ targetWorkspace!: WorkspaceSvg; /** @@ -305,6 +307,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(); @@ -458,6 +461,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_; @@ -950,6 +954,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(); @@ -960,6 +965,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; @@ -1105,6 +1111,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 9d0a41a3f62..c2ebe78fdb8 100644 --- a/core/flyout_button.ts +++ b/core/flyout_button.ts @@ -61,6 +61,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, @@ -205,6 +206,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 2fae3fd6503..ac9bc904ec5 100644 --- a/core/flyout_horizontal.ts +++ b/core/flyout_horizontal.ts @@ -286,6 +286,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 2faa2f11d8e..57749b21d0e 100644 --- a/core/flyout_vertical.ts +++ b/core/flyout_vertical.ts @@ -267,6 +267,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 d147d9e1e26..b2bb5519a59 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 c9f8a713f1d..13953e04995 100644 --- a/core/grid.ts +++ b/core/grid.ts @@ -63,6 +63,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 @@ -73,6 +74,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_; @@ -81,6 +83,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_; @@ -90,6 +93,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; @@ -98,6 +102,7 @@ export class Grid { /** * Update the grid with a new scale. * @param scale The new workspace scale. + * @internal */ update(scale: number) { this.scale_ = scale; @@ -160,6 +165,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 @@ -182,6 +188,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 ff5fe94f6c4..6b6edd67f4a 100644 --- a/core/input.ts +++ b/core/input.ts @@ -178,6 +178,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() @@ -208,7 +209,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 d99776557df..03a0c859972 100644 --- a/core/insertion_marker_manager.ts +++ b/core/insertion_marker_manager.ts @@ -165,7 +165,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; @@ -185,6 +188,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_(); @@ -194,6 +198,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_; @@ -203,6 +208,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_; @@ -211,6 +217,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_) { @@ -241,6 +248,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); @@ -767,6 +775,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 a047808bf9a..5c9cdb868c3 100644 --- a/core/interfaces/i_copyable.ts +++ b/core/interfaces/i_copyable.ts @@ -25,6 +25,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 bac62f208ab..3094bca3de5 100644 --- a/core/interfaces/i_metrics_manager.ts +++ b/core/interfaces/i_metrics_manager.ts @@ -32,6 +32,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 06744f2f188..ba621158ce6 100644 --- a/core/interfaces/i_toolbox_item.ts +++ b/core/interfaces/i_toolbox_item.ts @@ -48,6 +48,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 946e4d7c87e..31362687a2f 100644 --- a/core/internal_constants.ts +++ b/core/internal_constants.ts @@ -22,6 +22,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; @@ -29,12 +30,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; @@ -49,6 +52,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'; @@ -57,5 +61,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 95fe4305b89..79b1f5220c9 100644 --- a/core/keyboard_nav/ast_node.ts +++ b/core/keyboard_nav/ast_node.ts @@ -144,6 +144,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 fb58117d99c..be93bc74b5b 100644 --- a/core/keyboard_nav/marker.ts +++ b/core/keyboard_nav/marker.ts @@ -89,7 +89,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 2f74ae6d798..caabbac10d9 100644 --- a/core/marker_manager.ts +++ b/core/marker_manager.ts @@ -37,7 +37,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); @@ -114,6 +117,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) { @@ -129,6 +133,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) { @@ -146,7 +151,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(); @@ -157,6 +165,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 38cd61711df..03c7dfa6623 100644 --- a/core/menu.ts +++ b/core/menu.ts @@ -76,6 +76,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); @@ -118,12 +119,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) { @@ -148,6 +153,7 @@ export class Menu { /** * Set the menu accessibility role. * @param roleName role name. + * @internal */ setRole(roleName: aria.Role) { this.roleName_ = roleName; @@ -219,6 +225,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_; @@ -241,6 +248,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 @@ -253,6 +261,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 @@ -427,6 +436,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 5406d2c340d..4d0a1ccedb0 100644 --- a/core/menuitem.ts +++ b/core/menuitem.ts @@ -110,6 +110,7 @@ export class MenuItem { /** * Gets the menu item's element. * @return The DOM element. + * @internal */ getElement(): Element|null { return this.element_; @@ -118,6 +119,7 @@ export class MenuItem { /** * Gets the unique ID for this menu item. * @return Unique component ID. + * @internal */ getId(): string { return this.element_!.id; @@ -126,6 +128,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; @@ -134,6 +137,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; @@ -142,6 +146,7 @@ export class MenuItem { /** * Set the menu item's accessibility role. * @param roleName Role name. + * @internal */ setRole(roleName: aria.Role) { this.roleName_ = roleName; @@ -151,6 +156,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; @@ -159,6 +165,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; @@ -167,6 +174,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; @@ -190,6 +198,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_; @@ -198,6 +207,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; @@ -206,6 +216,7 @@ export class MenuItem { /** * Performs the appropriate action when the menu item is activated * by the user. + * @internal */ performAction() { if (this.isEnabled() && this.actionHandler_) { @@ -218,6 +229,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 7248343863e..92248899624 100644 --- a/core/metrics_manager.ts +++ b/core/metrics_manager.ts @@ -200,6 +200,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 2c3b5fb3127..59464309604 100644 --- a/core/mutator.ts +++ b/core/mutator.ts @@ -93,6 +93,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; @@ -102,6 +103,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 dfc7ce648e9..003dff95b18 100644 --- a/core/positionable_helpers.ts +++ b/core/positionable_helpers.ts @@ -28,6 +28,7 @@ import {WorkspaceSvg} from './workspace_svg.js'; /** * Enum for vertical positioning. * @alias Blockly.uiPosition.verticalPosition + * @internal */ export enum verticalPosition { TOP, @@ -37,6 +38,7 @@ export enum verticalPosition { /** * Enum for horizontal positioning. * @alias Blockly.uiPosition.horizontalPosition + * @internal */ export enum horizontalPosition { LEFT, @@ -46,6 +48,7 @@ export enum horizontalPosition { /** * An object defining a horizontal and vertical positioning. * @alias Blockly.uiPosition.Position + * @internal */ export interface Position { horizontal: horizontalPosition; @@ -55,6 +58,7 @@ export interface Position { /** * Enum for bump rules to use for dealing with collisions. * @alias Blockly.uiPosition.bumpDirection + * @internal */ export enum bumpDirection { UP, @@ -74,6 +78,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, @@ -121,6 +126,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 { @@ -146,6 +152,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 0d12b890256..a57e7a2411e 100644 --- a/core/procedures.ts +++ b/core/procedures.ts @@ -323,6 +323,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 8b9df288c3f..8a89f6aa7c9 100644 --- a/core/registry.ts +++ b/core/registry.ts @@ -86,6 +86,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 00e1f1fe3b2..01f3e972ade 100644 --- a/core/rendered_connection.ts +++ b/core/rendered_connection.ts @@ -108,6 +108,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(); @@ -148,6 +149,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()) { @@ -241,6 +243,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_; @@ -248,6 +251,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; @@ -330,6 +334,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 && @@ -359,6 +364,7 @@ export class RenderedConnection extends Connection { * collapsed. * * Also closes down-stream icons/bubbles. + * @internal */ stopTrackingAll() { this.setTracking(false); @@ -428,6 +434,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(); @@ -490,6 +497,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 f8910069098..ab582c73829 100644 --- a/core/renderers/common/block_rendering.ts +++ b/core/renderers/common/block_rendering.ts @@ -54,6 +54,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( @@ -86,6 +87,7 @@ export function unregister(name: string) { * Turn on the blocks debugger. * @alias Blockly.blockRendering.startDebugger * @deprecated + * @internal */ export function startDebugger() { deprecation.warn( @@ -99,6 +101,7 @@ export function startDebugger() { * Turn off the blocks debugger. * @alias Blockly.blockRendering.stopDebugger * @deprecated + * @internal */ export function stopDebugger() { deprecation.warn( @@ -116,6 +119,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 9297c04e39d..0d0decb6f1f 100644 --- a/core/renderers/common/constants.ts +++ b/core/renderers/common/constants.ts @@ -239,7 +239,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; @@ -280,6 +283,7 @@ export class ConstantProvider { FIELD_COLOUR_DEFAULT_WIDTH = 26; FIELD_COLOUR_DEFAULT_HEIGHT: number; FIELD_CHECKBOX_X_OFFSET: number; + /** @internal */ randomIdentifier: string; /** @@ -290,6 +294,7 @@ export class ConstantProvider { /** * The ID of the emboss filter, or the empty string if no filter is set. + * @internal */ embossFilterId = ''; @@ -300,6 +305,7 @@ export class ConstantProvider { /** * The ID of the disabled pattern, or the empty string if no pattern is set. + * @internal */ disabledPatternId = ''; @@ -327,39 +333,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. */ @@ -377,8 +409,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 @@ -458,12 +492,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() { /** @@ -497,6 +533,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. */ @@ -570,6 +607,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; @@ -654,6 +692,7 @@ export class ConstantProvider { /** * Dispose of this constants provider. * Delete all DOM elements that this provider created. + * @internal */ dispose() { if (this.embossFilter_) { @@ -673,6 +712,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; @@ -688,6 +728,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about start hats. + * @internal */ makeStartHat(): StartHat { const height = this.START_HAT_HEIGHT; @@ -703,6 +744,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about puzzle tabs. + * @internal */ makePuzzleTab(): PuzzleTab { const width = this.TAB_WIDTH; @@ -759,6 +801,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about notches. + * @internal */ makeNotch(): Notch { const width = this.NOTCH_WIDTH; @@ -794,6 +837,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about inside * corners. + * @internal */ makeInsideCorners(): InsideCorners { const radius = this.CORNER_RADIUS; @@ -815,6 +859,7 @@ export class ConstantProvider { /** * @return An object containing sizing and path information about outside * corners. + * @internal */ makeOutsideCorners(): OutsideCorners { const radius = this.CORNER_RADIUS; @@ -848,6 +893,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) { @@ -869,6 +915,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 c4b4fa38534..0bbc946b7c9 100644 --- a/core/renderers/common/debug.ts +++ b/core/renderers/common/debug.ts @@ -21,6 +21,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; @@ -31,6 +32,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( @@ -45,6 +47,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 d240f801295..37289b05a9b 100644 --- a/core/renderers/common/debugger.ts +++ b/core/renderers/common/debugger.ts @@ -73,10 +73,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]; @@ -91,6 +97,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) { @@ -123,6 +130,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) { @@ -155,6 +163,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) { @@ -208,6 +217,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) { @@ -255,6 +265,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) { @@ -301,6 +312,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++) { @@ -321,6 +333,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) { @@ -366,6 +379,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(); @@ -411,6 +425,7 @@ export class Debug { /** * Show a debug filter to highlight that a block has been rendered. * @param svgPath The block's SVG path. + * @internal */ drawRender(svgPath: SVGElement) { if (!Debug.config.render) { diff --git a/core/renderers/common/drawer.ts b/core/renderers/common/drawer.ts index 8c174688adb..41bc36b405f 100644 --- a/core/renderers/common/drawer.ts +++ b/core/renderers/common/drawer.ts @@ -53,6 +53,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; @@ -71,6 +72,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 76081b10b48..4da3363a2ec 100644 --- a/core/renderers/common/i_path_object.ts +++ b/core/renderers/common/i_path_object.ts @@ -63,6 +63,7 @@ export interface IPathObject { /** * Set the path generated by the renderer onto the respective SVG element. * @param pathString The path. + * @internal */ setPath: AnyDuringMigration; @@ -70,22 +71,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; @@ -93,6 +100,7 @@ export interface IPathObject { * Add the marker SVG to this block's SVG group. * @param markerSvg The SVG root of the marker to be added to the block SVG * group. + * @internal */ setMarkerSvg: AnyDuringMigration; @@ -100,12 +108,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; @@ -113,18 +123,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; @@ -133,6 +146,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; @@ -141,6 +155,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 381f37464e7..fdfea8ff0be 100644 --- a/core/renderers/common/info.ts +++ b/core/renderers/common/info.ts @@ -96,6 +96,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; @@ -147,6 +148,7 @@ export class RenderInfo { /** * Get the block renderer in use. * @return The block renderer in use. + * @internal */ getRenderer(): Renderer { return this.renderer; @@ -159,6 +161,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_(); @@ -224,7 +227,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' : @@ -265,7 +271,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 d41721041cb..1a5314734ef 100644 --- a/core/renderers/common/marker_svg.ts +++ b/core/renderers/common/marker_svg.ts @@ -124,6 +124,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 bab4523bd02..c16a6d51bd4 100644 --- a/core/renderers/common/path_object.ts +++ b/core/renderers/common/path_object.ts @@ -37,11 +37,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'. @@ -50,19 +52,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. */ @@ -73,12 +83,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)'); @@ -88,6 +102,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) { @@ -105,6 +120,7 @@ export class PathObject implements IPathObject { * Add the marker SVG to this block's SVG group. * @param markerSvg The SVG root of the marker to be added to the block SVG * group. + * @internal */ setMarkerSvg(markerSvg: SVGElement) { if (!markerSvg) { @@ -126,6 +142,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); @@ -138,6 +155,7 @@ export class PathObject implements IPathObject { /** * Set the style. * @param blockStyle The block style to use. + * @internal */ setStyle(blockStyle: BlockStyle) { this.style = blockStyle; @@ -161,6 +179,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) { @@ -197,6 +216,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); @@ -206,6 +226,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); @@ -214,6 +235,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); @@ -222,6 +244,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); @@ -232,6 +255,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); @@ -242,6 +266,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 3121cca74e7..91f72da82e8 100644 --- a/core/renderers/common/renderer.ts +++ b/core/renderers/common/renderer.ts @@ -48,15 +48,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'; @@ -66,6 +78,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_(); @@ -81,6 +94,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( @@ -92,6 +106,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(); @@ -110,6 +125,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_) { @@ -160,6 +176,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); @@ -170,6 +187,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_)); @@ -179,6 +197,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_; @@ -188,6 +207,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; @@ -203,6 +223,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 { @@ -220,6 +241,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, @@ -240,6 +262,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 51c56836549..4d128814cb3 100644 --- a/core/renderers/geras/constants.ts +++ b/core/renderers/geras/constants.ts @@ -37,6 +37,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 11ee9d68001..e734cd651e5 100644 --- a/core/renderers/geras/drawer.ts +++ b/core/renderers/geras/drawer.ts @@ -45,6 +45,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 05cd7c41d07..5f0d7c1139b 100644 --- a/core/renderers/geras/highlight_constants.ts +++ b/core/renderers/geras/highlight_constants.ts @@ -84,19 +84,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() { /** @@ -138,6 +143,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; @@ -181,6 +187,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; @@ -229,6 +236,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; @@ -278,6 +286,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. @@ -289,6 +298,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) + @@ -299,6 +309,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 9a07c58afcf..29a446ee993 100644 --- a/core/renderers/geras/highlighter.ts +++ b/core/renderers/geras/highlighter.ts @@ -69,6 +69,7 @@ export class Highlighter { /** * @param info An object containing all information needed to render this * block. + * @internal */ constructor(info: RenderInfo) { this.info_ = info; @@ -95,6 +96,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_; @@ -103,6 +105,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); @@ -132,6 +135,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) { @@ -145,6 +149,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; @@ -165,6 +170,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(); @@ -187,6 +193,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_; @@ -205,6 +212,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. @@ -225,7 +233,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) { @@ -258,6 +269,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 17157543411..48d4163b1fb 100644 --- a/core/renderers/geras/info.ts +++ b/core/renderers/geras/info.ts @@ -60,6 +60,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); @@ -69,6 +70,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 931a9f66f1c..3a438831332 100644 --- a/core/renderers/geras/measurables/inline_input.ts +++ b/core/renderers/geras/measurables/inline_input.ts @@ -35,6 +35,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 ae9b1c86691..5e7fabd671c 100644 --- a/core/renderers/geras/measurables/statement_input.ts +++ b/core/renderers/geras/measurables/statement_input.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: BaseConstantProvider, input: Input) { super(constants, input); diff --git a/core/renderers/geras/path_object.ts b/core/renderers/geras/path_object.ts index 144f4db0a31..14896d6e469 100644 --- a/core/renderers/geras/path_object.ts +++ b/core/renderers/geras/path_object.ts @@ -33,10 +33,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; @@ -44,6 +49,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, @@ -71,6 +77,7 @@ export class PathObject extends BasePathObject { /** * Set the highlight path generated by the renderer onto the SVG element. * @param highlightPath The highlight path. + * @internal */ setHighlightPath(highlightPath: string) { this.svgPathLight.setAttribute('d', highlightPath); diff --git a/core/renderers/geras/renderer.ts b/core/renderers/geras/renderer.ts index dd88754d806..8df8aa3cc67 100644 --- a/core/renderers/geras/renderer.ts +++ b/core/renderers/geras/renderer.ts @@ -41,7 +41,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); } @@ -49,6 +52,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); @@ -91,6 +95,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( @@ -109,6 +114,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 a2ec1d4f77f..3f6123f3f9c 100644 --- a/core/renderers/measurables/base.ts +++ b/core/renderers/measurables/base.ts @@ -34,7 +34,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 140c3cbeb33..25c6a1ece50 100644 --- a/core/renderers/measurables/bottom_row.ts +++ b/core/renderers/measurables/bottom_row.ts @@ -36,16 +36,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; @@ -55,7 +62,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 33e3fa0b778..5952aed35fd 100644 --- a/core/renderers/measurables/connection.ts +++ b/core/renderers/measurables/connection.ts @@ -37,6 +37,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 bae5d71e7db..27cec8f0071 100644 --- a/core/renderers/measurables/external_value_input.ts +++ b/core/renderers/measurables/external_value_input.ts @@ -41,6 +41,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 ea515b56b8d..37edbfd75e8 100644 --- a/core/renderers/measurables/field.ts +++ b/core/renderers/measurables/field.ts @@ -43,6 +43,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 f97b4621bf3..6b616c39a2a 100644 --- a/core/renderers/measurables/hat.ts +++ b/core/renderers/measurables/hat.ts @@ -32,7 +32,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 4582fd0de36..9c435269117 100644 --- a/core/renderers/measurables/icon.ts +++ b/core/renderers/measurables/icon.ts @@ -39,6 +39,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 2e056629558..3de6f8f1aea 100644 --- a/core/renderers/measurables/in_row_spacer.ts +++ b/core/renderers/measurables/in_row_spacer.ts @@ -33,6 +33,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 7298dca51cc..2ad505f52c7 100644 --- a/core/renderers/measurables/inline_input.ts +++ b/core/renderers/measurables/inline_input.ts @@ -38,6 +38,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 912086a7628..eb50943b948 100644 --- a/core/renderers/measurables/input_connection.ts +++ b/core/renderers/measurables/input_connection.ts @@ -43,6 +43,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 7b14546a94c..fb4a8ac8edf 100644 --- a/core/renderers/measurables/input_row.ts +++ b/core/renderers/measurables/input_row.ts @@ -31,10 +31,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; @@ -42,6 +48,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 871308757b8..f7d4ddea9eb 100644 --- a/core/renderers/measurables/jagged_edge.ts +++ b/core/renderers/measurables/jagged_edge.ts @@ -30,7 +30,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 a73b780601d..a1b76aec252 100644 --- a/core/renderers/measurables/next_connection.ts +++ b/core/renderers/measurables/next_connection.ts @@ -35,6 +35,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 2b7d1280013..ce36e1c1714 100644 --- a/core/renderers/measurables/output_connection.ts +++ b/core/renderers/measurables/output_connection.ts @@ -62,6 +62,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 802ea15bd81..17621811d85 100644 --- a/core/renderers/measurables/previous_connection.ts +++ b/core/renderers/measurables/previous_connection.ts @@ -36,6 +36,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 610b252ab7d..4c453ea9c87 100644 --- a/core/renderers/measurables/round_corner.ts +++ b/core/renderers/measurables/round_corner.ts @@ -33,6 +33,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 3232135f8b4..b32d3ed906a 100644 --- a/core/renderers/measurables/row.ts +++ b/core/renderers/measurables/row.ts @@ -30,51 +30,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; /** @@ -84,20 +105,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; @@ -108,6 +144,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. @@ -124,6 +161,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.'); @@ -132,6 +170,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; @@ -140,6 +179,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; @@ -148,6 +188,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++) { @@ -164,6 +205,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 c2de76a6df3..b1fb01e008b 100644 --- a/core/renderers/measurables/spacer_row.ts +++ b/core/renderers/measurables/spacer_row.ts @@ -37,6 +37,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 a42c8d9be81..809d0b4b1e4 100644 --- a/core/renderers/measurables/square_corner.ts +++ b/core/renderers/measurables/square_corner.ts @@ -33,6 +33,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 3b655758d44..fcfc69a0e66 100644 --- a/core/renderers/measurables/statement_input.ts +++ b/core/renderers/measurables/statement_input.ts @@ -34,6 +34,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 2fed200c142..ac3f7e2bb58 100644 --- a/core/renderers/measurables/top_row.ts +++ b/core/renderers/measurables/top_row.ts @@ -39,6 +39,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; @@ -52,7 +53,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); @@ -63,6 +67,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 f2c66c09736..7d33eb98578 100644 --- a/core/renderers/measurables/types.ts +++ b/core/renderers/measurables/types.ts @@ -76,10 +76,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; /** @@ -94,6 +100,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)) { @@ -107,6 +114,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; @@ -116,6 +124,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; @@ -125,6 +134,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; @@ -134,6 +144,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; @@ -143,6 +154,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; @@ -152,6 +164,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; @@ -161,6 +174,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; @@ -170,6 +184,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; @@ -179,6 +194,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; @@ -188,6 +204,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; @@ -197,6 +214,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; @@ -208,6 +226,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); @@ -217,6 +236,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; @@ -226,6 +246,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; @@ -235,6 +256,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; @@ -244,6 +266,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; @@ -253,6 +276,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; @@ -262,6 +286,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; @@ -271,6 +296,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; @@ -280,6 +306,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; @@ -289,6 +316,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; @@ -298,6 +326,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; @@ -307,6 +336,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); @@ -316,6 +346,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 878e81b88f5..ef5c4ff378b 100644 --- a/core/renderers/minimalist/constants.ts +++ b/core/renderers/minimalist/constants.ts @@ -24,6 +24,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 a971fdd5c66..a64bc0d4e8c 100644 --- a/core/renderers/minimalist/drawer.ts +++ b/core/renderers/minimalist/drawer.ts @@ -29,6 +29,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 6215e1e2b15..1ee8e296cda 100644 --- a/core/renderers/minimalist/info.ts +++ b/core/renderers/minimalist/info.ts @@ -32,6 +32,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); @@ -40,6 +41,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 15998fe9d1a..3feb2fa645e 100644 --- a/core/renderers/minimalist/renderer.ts +++ b/core/renderers/minimalist/renderer.ts @@ -29,7 +29,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 3cc724bdf08..3d00ff13172 100644 --- a/core/renderers/thrasos/info.ts +++ b/core/renderers/thrasos/info.ts @@ -50,6 +50,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); @@ -58,6 +59,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 d4414239015..d60d815219c 100644 --- a/core/renderers/thrasos/renderer.ts +++ b/core/renderers/thrasos/renderer.ts @@ -25,7 +25,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 c5a44141216..65e1ba702cf 100644 --- a/core/renderers/zelos/constants.ts +++ b/core/renderers/zelos/constants.ts @@ -73,7 +73,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; @@ -128,6 +131,7 @@ export class ConstantProvider extends BaseConstantProvider { /** * The ID of the selected glow filter, or the empty string if no filter is * set. + * @internal */ selectedGlowFilterId = ''; @@ -141,6 +145,7 @@ export class ConstantProvider extends BaseConstantProvider { /** * The ID of the replacement glow filter, or the empty string if no filter * is set. + * @internal */ replacementGlowFilterId = ''; @@ -169,6 +174,7 @@ export class ConstantProvider extends BaseConstantProvider { */ SQUARED: Shape|null = null; + /** @internal */ constructor() { super(); @@ -227,6 +233,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: { @@ -342,6 +349,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; @@ -403,6 +411,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; @@ -473,6 +482,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 c6b51987c21..2a311da0ed4 100644 --- a/core/renderers/zelos/drawer.ts +++ b/core/renderers/zelos/drawer.ts @@ -48,6 +48,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 b8af223f2e2..abdec65da79 100644 --- a/core/renderers/zelos/info.ts +++ b/core/renderers/zelos/info.ts @@ -70,6 +70,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); @@ -116,6 +117,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 60cbae65e91..54a8c4d1fad 100644 --- a/core/renderers/zelos/measurables/bottom_row.ts +++ b/core/renderers/zelos/measurables/bottom_row.ts @@ -26,7 +26,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 2046a124a87..dfd164db1de 100644 --- a/core/renderers/zelos/measurables/inputs.ts +++ b/core/renderers/zelos/measurables/inputs.ts @@ -35,6 +35,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 085914952d5..0a10977549e 100644 --- a/core/renderers/zelos/measurables/row_elements.ts +++ b/core/renderers/zelos/measurables/row_elements.ts @@ -32,7 +32,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 de9d9e5f5ea..6ae4513850e 100644 --- a/core/renderers/zelos/measurables/top_row.ts +++ b/core/renderers/zelos/measurables/top_row.ts @@ -28,7 +28,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 25dc0653b10..0f8fee63fe6 100644 --- a/core/renderers/zelos/path_object.ts +++ b/core/renderers/zelos/path_object.ts @@ -54,16 +54,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); } @@ -139,7 +144,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_) { @@ -149,7 +157,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. @@ -168,6 +179,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 99e738070a8..b4d017fcb23 100644 --- a/core/renderers/zelos/renderer.ts +++ b/core/renderers/zelos/renderer.ts @@ -45,7 +45,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); } @@ -84,6 +87,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 { @@ -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( diff --git a/core/scrollbar.ts b/core/scrollbar.ts index 07e8ec3a5b5..89d77c17508 100644 --- a/core/scrollbar.ts +++ b/core/scrollbar.ts @@ -43,6 +43,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; @@ -53,6 +54,7 @@ export class Scrollbar { /** * The ratio of handle position offset to workspace content displacement. + * @internal */ ratio = 1; private origin_: Coordinate; @@ -137,6 +139,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); @@ -281,6 +284,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; @@ -787,6 +791,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 1ca09a0c8de..8e30002b66d 100644 --- a/core/scrollbar_pair.ts +++ b/core/scrollbar_pair.ts @@ -185,6 +185,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 2a00a1f7943..b52ebd59c3b 100644 --- a/core/serialization/blocks.ts +++ b/core/serialization/blocks.ts @@ -336,6 +336,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 d8bf8af9a3c..3b3a66ef05d 100644 --- a/core/serialization/exceptions.ts +++ b/core/serialization/exceptions.ts @@ -50,7 +50,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`); } @@ -67,6 +70,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} @@ -86,6 +90,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, @@ -103,7 +108,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 75fdffbeae0..c5b411d747e 100644 --- a/core/shortcut_items.ts +++ b/core/shortcut_items.ts @@ -247,6 +247,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 d1b8b07212f..71d6979ce4c 100644 --- a/core/theme.ts +++ b/core/theme.ts @@ -21,14 +21,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; @@ -64,6 +69,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 dbe47ae33c4..0c9798e3df9 100644 --- a/core/theme_manager.ts +++ b/core/theme_manager.ts @@ -39,6 +39,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. */ @@ -48,6 +49,7 @@ export class ThemeManager { /** * Get the workspace theme. * @return The workspace theme. + * @internal */ getTheme(): Theme { return this.theme; @@ -56,6 +58,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; @@ -96,6 +99,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); @@ -104,6 +108,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)) { @@ -119,6 +124,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]) { @@ -138,6 +144,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) { @@ -162,6 +169,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 45df255464a..8557eb76955 100644 --- a/core/toolbox/toolbox.ts +++ b/core/toolbox/toolbox.ts @@ -348,6 +348,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; @@ -443,6 +444,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); @@ -451,6 +453,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); @@ -676,7 +679,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). @@ -702,6 +708,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 efc84b067d7..496ff9ab230 100644 --- a/core/toolbox/toolbox_item.ts +++ b/core/toolbox/toolbox_item.ts @@ -111,6 +111,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 203e8addc9a..ea2a09aef29 100644 --- a/core/tooltip.ts +++ b/core/tooltip.ts @@ -347,6 +347,7 @@ function onMouseMove(e: Event) { /** * Dispose of the tooltip. * @alias Blockly.Tooltip.dispose + * @internal */ export function dispose() { element = null; @@ -374,6 +375,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(); @@ -384,6 +386,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 5e04ae32370..7ccc838f151 100644 --- a/core/touch.ts +++ b/core/touch.ts @@ -82,6 +82,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(); @@ -114,6 +115,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 82f4ead2837..4853ae1a3d7 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 2ad18ce80fe..253841d55bb 100644 --- a/core/trashcan.ts +++ b/core/trashcan.ts @@ -68,7 +68,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; @@ -421,6 +424,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 6698157984d..18f06810b41 100644 --- a/core/utils.ts +++ b/core/utils.ts @@ -299,6 +299,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'. @@ -318,6 +319,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 93c48330ce3..ff9a0b37d3a 100644 --- a/core/utils/array.ts +++ b/core/utils/array.ts @@ -16,6 +16,7 @@ * @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 817c0829852..743ce92dfd6 100644 --- a/core/utils/colour.ts +++ b/core/utils/colour.ts @@ -23,6 +23,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; @@ -33,6 +34,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; @@ -49,6 +51,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; @@ -59,6 +62,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 4c0cdc49623..02c426bf505 100644 --- a/core/utils/svg.ts +++ b/core/utils/svg.ts @@ -22,33 +22,59 @@ * @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 795fdf52044..5a0bc54d4d6 100644 --- a/core/utils/svg_math.ts +++ b/core/utils/svg_math.ts @@ -176,6 +176,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 cdf9b2e0df6..c5ed3b9061e 100644 --- a/core/utils/toolbox.ts +++ b/core/utils/toolbox.ts @@ -193,6 +193,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 { @@ -240,6 +241,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 { @@ -270,6 +272,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) { @@ -292,6 +295,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 250878541cd..f7fcb9c344a 100644 --- a/core/variable_map.ts +++ b/core/variable_map.ts @@ -58,6 +58,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; @@ -249,6 +250,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(); @@ -329,6 +331,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 40a08f8f2a0..67f3109c116 100644 --- a/core/variable_model.ts +++ b/core/variable_model.ts @@ -72,6 +72,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 50411994716..5f19536c74f 100644 --- a/core/variables.ts +++ b/core/variables.ts @@ -559,6 +559,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 42f42b1c257..9bc3e92ad86 100644 --- a/core/widgetdiv.ts +++ b/core/widgetdiv.ts @@ -190,6 +190,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 0507d852894..2a389329810 100644 --- a/core/workspace.ts +++ b/core/workspace.ts @@ -72,12 +72,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; @@ -277,6 +281,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); @@ -294,6 +299,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)) { @@ -311,6 +317,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. @@ -469,6 +476,7 @@ export class Workspace implements IASTNodeLocation { /** * Return all variable types. * @return List of variable types. + * @internal */ getVariableTypes(): string[] { return this.variableMap_.getVariableTypes(this); @@ -581,6 +589,7 @@ export class Workspace implements IASTNodeLocation { /** * Gets the undo stack for workplace. * @return undo stack + * @internal */ getUndoStack(): Abstract[] { return this.undoStack_; @@ -589,6 +598,7 @@ export class Workspace implements IASTNodeLocation { /** * Gets the redo stack for workplace. * @return redo stack + * @internal */ getRedoStack(): Abstract[] { return this.redoStack_; @@ -690,6 +700,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; @@ -698,6 +709,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]; @@ -707,6 +719,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; @@ -734,12 +747,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); } @@ -755,6 +772,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 2f55dfe304f..b408133cf39 100644 --- a/core/workspace_audio.ts +++ b/core/workspace_audio.ts @@ -47,7 +47,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'. @@ -89,7 +92,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 521ddb30949..751790fb675 100644 --- a/core/workspace_comment.ts +++ b/core/workspace_comment.ts @@ -49,6 +49,7 @@ export class WorkspaceComment { /** Whether this comment has been disposed. */ protected disposed_ = false; + /** @internal */ isComment = true; /** @@ -93,7 +94,10 @@ export class WorkspaceComment { WorkspaceComment.fireCreateEvent(this); } - /** Dispose of this comment. */ + /** + * Dispose of this comment. + * @internal + */ dispose() { if (this.disposed_) { return; @@ -113,6 +117,7 @@ export class WorkspaceComment { /** * Get comment height. * @return Comment height. + * @internal */ getHeight(): number { return this.height_; @@ -121,6 +126,7 @@ export class WorkspaceComment { /** * Set comment height. * @param height Comment height. + * @internal */ setHeight(height: number) { this.height_ = height; @@ -129,6 +135,7 @@ export class WorkspaceComment { /** * Get comment width. * @return Comment width. + * @internal */ getWidth(): number { return this.width_; @@ -137,6 +144,7 @@ export class WorkspaceComment { /** * Set comment width. * @param width comment width. + * @internal */ setWidth(width: number) { this.width_ = width; @@ -146,6 +154,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); @@ -155,6 +164,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 = @@ -167,6 +177,7 @@ export class WorkspaceComment { /** * Get whether this comment is deletable or not. * @return True if deletable. + * @internal */ isDeletable(): boolean { return this.deletable_ && @@ -176,6 +187,7 @@ export class WorkspaceComment { /** * Set whether this comment is deletable or not. * @param deletable True if deletable. + * @internal */ setDeletable(deletable: boolean) { this.deletable_ = deletable; @@ -184,6 +196,7 @@ export class WorkspaceComment { /** * Get whether this comment is movable or not. * @return True if movable. + * @internal */ isMovable(): boolean { return this.movable_ && @@ -193,6 +206,7 @@ export class WorkspaceComment { /** * Set whether this comment is movable or not. * @param movable True if movable. + * @internal */ setMovable(movable: boolean) { this.movable_ = movable; @@ -218,6 +232,7 @@ export class WorkspaceComment { /** * Returns this comment's text. * @return Comment text. + * @internal */ getContent(): string { return this.content_; @@ -226,6 +241,7 @@ export class WorkspaceComment { /** * Set this comment's content. * @param content Comment content. + * @internal */ setContent(content: string) { if (this.content_ !== content) { @@ -239,6 +255,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); @@ -263,6 +280,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'); @@ -277,6 +295,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()) { @@ -300,6 +319,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); @@ -327,6 +347,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 f00d2210f02..97bc74bfdb4 100644 --- a/core/workspace_comment_svg.ts +++ b/core/workspace_comment_svg.ts @@ -61,6 +61,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; @@ -135,7 +136,10 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements this.render(); } - /** Dispose of this comment. */ + /** + * Dispose of this comment. + * @internal + */ override dispose() { if (this.disposed_) { return; @@ -164,6 +168,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) { @@ -203,6 +208,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) { @@ -220,7 +226,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; @@ -243,7 +252,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; @@ -256,24 +268,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'); } @@ -285,6 +309,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; @@ -325,6 +350,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 = @@ -343,6 +369,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); @@ -354,6 +381,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_) { @@ -376,6 +404,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) { @@ -395,6 +424,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); @@ -413,6 +443,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(); @@ -435,7 +466,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'); @@ -447,6 +481,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); @@ -468,6 +503,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) { @@ -483,6 +519,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_; @@ -491,6 +528,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_; @@ -499,6 +537,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Set this comment's content. * @param content Comment content. + * @internal */ override setContent(content: string) { super.setContent(content); @@ -510,6 +549,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) { @@ -524,6 +564,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. @@ -532,6 +573,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; @@ -563,6 +605,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Encode a comment for copying. * @return Copy metadata. + * @internal */ toCopyData(): CopyData { return { @@ -575,12 +618,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; @@ -941,7 +988,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; @@ -961,7 +1011,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; @@ -989,6 +1042,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 b5485fbbe83..b0443f727d4 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 8b3d377dadc..6ca262b56e0 100644 --- a/core/workspace_dragger.ts +++ b/core/workspace_dragger.ts @@ -49,6 +49,7 @@ export class WorkspaceDragger { /** * Sever all links from this object. * @suppress {checkTypes} + * @internal */ dispose() { // AnyDuringMigration because: Type 'null' is not assignable to type @@ -56,7 +57,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(); @@ -68,6 +72,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. @@ -79,6 +84,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 1463ad0e1ab..88573845379 100644 --- a/core/workspace_svg.ts +++ b/core/workspace_svg.ts @@ -269,7 +269,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; @@ -329,6 +332,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'. @@ -340,7 +344,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; @@ -505,6 +511,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; @@ -524,6 +531,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); @@ -533,6 +541,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); @@ -543,6 +552,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_) { @@ -573,6 +583,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_; @@ -598,7 +609,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()); @@ -682,6 +695,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; @@ -709,6 +723,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_; @@ -721,6 +736,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()); @@ -732,6 +748,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 @@ -753,6 +770,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_; @@ -950,14 +968,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(); @@ -968,6 +992,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(({ @@ -1006,6 +1031,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) { @@ -1020,6 +1046,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_; @@ -1038,6 +1065,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) { @@ -1085,6 +1113,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 */ @@ -1109,6 +1138,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(); @@ -1161,6 +1191,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()) { @@ -1215,6 +1246,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. @@ -1236,6 +1268,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. @@ -1275,6 +1308,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_; @@ -1558,7 +1592,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()) { @@ -1883,6 +1920,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) { @@ -2115,13 +2153,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'); @@ -2268,6 +2310,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= */ @@ -2503,6 +2546,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' || @@ -2530,14 +2574,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(); @@ -2555,6 +2605,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_; @@ -2609,6 +2660,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();