Class: WorkspaceSvg

Blockly.WorkspaceSvg

class   static

Constructor

WorkspaceSvg

new WorkspaceSvg(options, opt_blockDragSurface, opt_wsDragSurface)

Class for a workspace. This is an onscreen area with optional trashcan, scrollbars, bubbles, and dragging.

Parameter
options	Blockly.Options Dictionary of options. Value must not be null.
opt_blockDragSurface	Optional Blockly.BlockDragSurfaceSvg Drag surface for blocks.
opt_wsDragSurface	Optional Blockly.WorkspaceDragSurfaceSvg Drag surface for the workspace.

Extends

Blockly.Workspace

Properties

configureContextMenu

Developers may define this function to add custom menu options to the workspace's context menu or edit the workspace-created set of menu options.

Parameter
options	Array of non-null Object List of menu options to add to. Value must not be null.

horizontalLayout

unknown

Inherited from

Blockly.Workspace#horizontalLayout

id

unknown

Inherited from

Blockly.Workspace#id

isClearing

unknown

Returns true if the workspace is currently in the process of a bulk clear.

Inherited from

Blockly.Workspace#isClearing

isFlyout

boolean

Is this workspace the surface for a flyout?

isMutator

boolean

Is this workspace the surface for a mutator?

MAX_UNDO

unknown

Maximum number of undo events in stack. 0 turns off undo, Infinity sets it to unlimited.

Inherited from

Blockly.Workspace#MAX_UNDO

options

unknown

Inherited from

Blockly.Workspace#options

redoStack_

protected

unknown

Inherited from

Blockly.Workspace#redoStack_

rendered

boolean

The render status of an SVG workspace. Returns false for headless workspaces and true for instances of Blockly.WorkspaceSvg.

resizeHandlerWrapper_

Array of non-null Array

A wrapper function called when a resize event occurs. You can pass the result to unbindEvent_.

RTL

unknown

Inherited from

Blockly.Workspace#RTL

scale

number

Current scale.

scrollbar

Blockly.ScrollbarPair

This workspace's scrollbars, if they exist.

scrollX

number

Current horizontal scrolling offset in pixel units.

scrollY

number

Current vertical scrolling offset in pixel units.

startScrollX

number

Horizontal scroll value when scrolling started in pixel units.

startScrollY

number

Vertical scroll value when scrolling started in pixel units.

svgBackground_

SVGElement

svgBlockCanvas_

SVGElement

svgBubbleCanvas_

SVGElement

svgGroup_

SVGElement

[Trashcan and/or flyout may go here]

targetWorkspace

nullable Blockly.WorkspaceSvg

In a flyout, the target workspace where blocks should be placed after a drag. Otherwise null.

toolboxPosition

unknown

Inherited from

Blockly.Workspace#toolboxPosition

trashcan

Blockly.Trashcan

trashcan

Blockly.Trashcan

The workspace's trashcan (if any).

undoStack_

protected

unknown

Inherited from

Blockly.Workspace#undoStack_

zoomControls_

Blockly.ZoomControls

Methods

addChangeListener

addChangeListener(func) returns function()

When something in this workspace changes, call a function.

Parameter
func	Function to call. Value must not be null.

Inherited from

Blockly.Workspace#addChangeListener

Returns

Function that can be passed to removeChangeListener.

addTopBlock

addTopBlock(block)

Add a block to the list of top blocks.

Parameter
block	Block to add. Value must not be null.

Inherited from

Blockly.Workspace#addTopBlock

addTopComment

addTopComment(comment)

Add a comment to the list of top comments.

Parameter
comment	comment to add. Value must not be null.

Inherited from

Blockly.Workspace#addTopComment

addTypedBlock

addTypedBlock(block)

Add a block to the list of blocks keyed by type.

Parameter
block	Block to add. Value must not be null.

Inherited from

Blockly.Workspace#addTypedBlock

allInputsFilled

allInputsFilled(opt_shadowBlocksAreFilled) returns boolean

Checks whether all value and statement inputs in the workspace are filled with blocks.

Parameter
opt_shadowBlocksAreFilled	Optional An optional argument controlling whether shadow blocks are counted as filled. Defaults to true.

Inherited from

Blockly.Workspace#allInputsFilled

Returns

True if all inputs are filled, false otherwise.

beginCanvasTransition

beginCanvasTransition()

Add a transition class to the block and bubble canvas, to animate any transform changes.

cancelCurrentGesture

cancelCurrentGesture()

Cancel the current gesture, if one exists.

centerOnBlock

public

centerOnBlock(id)

Scroll the workspace to center on the given block.

Parameter
id	string ID of block center on. Value may be null.

cleanUp

cleanUp()

Clean up the workspace by ordering all the blocks in a column.

clear

clear()

Dispose of all blocks in workspace, with an optimization to prevent resizes.

clearGesture

clearGesture()

Clear the reference to the current gesture.

clearUndo

clearUndo()

Clear the undo/redo stacks.

Inherited from

Blockly.Workspace#clearUndo

createDom

createDom(opt_backgroundClass) returns Element

Create the workspace DOM elements.

Parameter
opt_backgroundClass	Optional string Either 'blocklyMainBackground' or 'blocklyMutatorBackground'.

Returns

non-null Element The workspace's SVG group.

createPotentialVariableMap

createPotentialVariableMap()

Create and store the potential variable map for this workspace.

Inherited from

Blockly.Workspace#createPotentialVariableMap

createVariable

createVariable(name, opt_type, opt_id) returns Blockly.VariableModel

Create a new variable with the given name. Update the flyout to show the new variable immediately.

Parameter
name	string The new variable's name.
opt_type	Optional string The type of the variable like 'int' or 'string'. Does not need to be unique. Field_variable can filter variables based on their type. This will default to '' which is a specific type.
opt_id	Optional string The unique ID of the variable. This will default to a UUID.

Returns

nullable Blockly.VariableModel The newly created variable.

deleteVariableById

deleteVariableById(id)

Delete a variable by the passed in ID. Update the flyout to show immediately that the variable is deleted.

Parameter
id	string ID of variable to delete.

dispose

dispose()

Dispose of this workspace. Unlink from all DOM elements to prevent memory leaks.

endCanvasTransition

endCanvasTransition()

Remove transition class from the block and bubble canvas.

fireChangeListener

fireChangeListener(event)

Fire a change event.

Parameter
event	Event to fire. Value must not be null.

Inherited from

Blockly.Workspace#fireChangeListener

getAllBlocks

getAllBlocks(ordered) returns Array of non-null Blockly.Block

Find all blocks in workspace. Blocks are optionally sorted by position; top to bottom (with slight LTR or RTL bias).

Parameter
ordered	Sort the list if true.

Inherited from

Blockly.Workspace#getAllBlocks

Returns

Array of blocks.

getAllVariables

getAllVariables() returns Array of Blockly.VariableModel

Return all variables of all types.

Inherited from

Blockly.Workspace#getAllVariables

Returns

List of variable models.

getAudioManager

getAudioManager() returns Blockly.WorkspaceAudio

Get the audio manager for this workspace.

Returns

Blockly.WorkspaceAudio The audio manager for this workspace.

getBlockById

getBlockById(id) returns Blockly.Block

Find the block on this workspace with the specified ID.

Parameter
id	ID of block to find.

Inherited from

Blockly.Workspace#getBlockById

Returns

The sought after block or null if not found.

getBlockDragSurface

getBlockDragSurface() returns Blockly.BlockDragSurfaceSvg

Returns

nullable Blockly.BlockDragSurfaceSvg This workspace's block drag surface, if one is in use.

getBlocksBoundingBox

getBlocksBoundingBox() returns Object

Calculate the bounding box for the blocks on the workspace. Coordinate system: workspace coordinates.

Returns

Object Contains the position and size of the bounding box containing the blocks on the workspace.

getBlocksByType

getBlocksByType(type, ordered) returns Array of non-null Blockly.Block

Finds the blocks with the associated type and returns them. Blocks are optionally sorted by position; top to bottom (with slight LTR or RTL bias).

Parameter
type	The type of block to search for.
ordered	Sort the list if true.

Inherited from

Blockly.Workspace#getBlocksByType

Returns

The blocks of the given type.

getBubbleCanvas

getBubbleCanvas() returns SVGGElement

Get the SVG element that forms the bubble surface.

Returns

non-null SVGGElement SVG element.

getButtonCallback

getButtonCallback(key) returns function()

Get the callback function associated with a given key, for clicks on buttons and labels in the flyout.

Parameter
key	string The name to use to look up the function.

Returns

nullable function(non-null Blockly.FlyoutButton) The function corresponding to the given key for this workspace; null if no callback is registered.

getCanvas

getCanvas() returns Element

Get the SVG element that forms the drawing surface.

Returns

non-null Element SVG element.

getCommentById

getCommentById(id) returns Blockly.WorkspaceComment

Find the comment on this workspace with the specified ID.

Parameter
id	ID of comment to find.

Inherited from

Blockly.Workspace#getCommentById

Returns

The sought after comment or null if not found.

getFlyout_

getFlyout_() returns Blockly.Flyout

Getter for the flyout associated with this workspace. This flyout may be owned by either the toolbox or the workspace, depending on toolbox configuration. It will be null if there is no flyout.

Returns

Blockly.Flyout The flyout on this workspace.

getGesture

getGesture(e) returns Blockly.TouchGesture

Look up the gesture that is tracking this touch stream on this workspace. May create a new gesture.

Parameter
e	Event Mouse event or touch event. Value must not be null.

Returns

Blockly.TouchGesture The gesture that is tracking this touch stream, or null if no valid gesture exists.

getGrid

getGrid() returns Blockly.Grid

Get the grid object for this workspace, or null if there is none.

Returns

Blockly.Grid The grid object for this workspace.

getInjectionDiv

getInjectionDiv() returns Element

Return the injection div that is a parent of this workspace. Walks the DOM the first time it's called, then returns a cached value.

Returns

non-null Element The first parent div with 'injectionDiv' in the name.

getInverseScreenCTM

getInverseScreenCTM() returns SVGMatrix

Getter for the inverted screen CTM.

Returns

SVGMatrix The matrix to use in mouseToSvg

getOriginOffsetInPixels

getOriginOffsetInPixels() returns goog.math.Coordinate

Return the position of the workspace origin relative to the injection div origin in pixels. The workspace origin is where a block would render at position (0, 0). It is not the upper left corner of the workspace SVG.

Returns

non-null goog.math.Coordinate Offset in pixels.

getParentSvg

getParentSvg() returns Element

Get the SVG element that contains this workspace.

Returns

Element SVG element.

getPotentialVariableMap

getPotentialVariableMap() returns Blockly.VariableMap

Return the variable map that contains "potential" variables. These exist in the flyout but not in the workspace.

Inherited from

Blockly.Workspace#getPotentialVariableMap

Returns

The potential variable map.

getToolbox

getToolbox() returns Blockly.Toolbox

Getter for the toolbox associated with this workspace, if one exists.

Returns

Blockly.Toolbox The toolbox on this workspace.

getToolboxCategoryCallback

getToolboxCategoryCallback(key) returns function()

Get the callback function associated with a given key, for populating custom toolbox categories in this workspace.

Parameter
key	string The name to use to look up the function.

Returns

nullable function(non-null Blockly.Workspace) returns non-null Array of non-null Element The function corresponding to the given key for this workspace, or null if no function is registered.

getTopBlocks

getTopBlocks(ordered) returns Array of non-null Blockly.Block

Finds the top-level blocks and returns them. Blocks are optionally sorted by position; top to bottom (with slight LTR or RTL bias).

Parameter
ordered	Sort the list if true.

Inherited from

Blockly.Workspace#getTopBlocks

Returns

The top-level block objects.

getTopComments

getTopComments(ordered) returns Array of non-null Blockly.WorkspaceComment

Finds the top-level comments and returns them. Comments are optionally sorted by position; top to bottom (with slight LTR or RTL bias).

Parameter
ordered	Sort the list if true.

Inherited from

Blockly.Workspace#getTopComments

Returns

The top-level comment objects.

getVariable

getVariable(name, opt_type) returns Blockly.VariableModel

Find the variable by the given name and return it. Return null if it is not found.

Parameter
name	The name to check for. Value must not be null.
opt_type	Optional The type of the variable. If not provided it defaults to the empty string, which is a specific type.

Inherited from

Blockly.Workspace#getVariable

Returns

the variable with the given name.

getVariableById

getVariableById(id) returns Blockly.VariableModel

Find the variable by the given ID and return it. Return null if it is not found.

Parameter
id	The ID to check for. Value must not be null.

Inherited from

Blockly.Workspace#getVariableById

Returns

The variable with the given ID.

getVariableMap

getVariableMap() returns Blockly.VariableMap

Return the map of all variables on the workspace.

Inherited from

Blockly.Workspace#getVariableMap

Returns

The variable map.

getVariablesOfType

getVariablesOfType(type) returns Array of Blockly.VariableModel

Find the variable with the specified type. If type is null, return list of variables with empty string type.

Parameter
type	Type of the variables to find. Value may be null.

Inherited from

Blockly.Workspace#getVariablesOfType

Returns

The sought after variables of the passed in type. An empty array if none are found.

getVariableTypes

getVariableTypes() returns Array of string

Return all variable types.

Inherited from

Blockly.Workspace#getVariableTypes

Returns

List of variable types.

getVariableUsesById

getVariableUsesById(id) returns Array of non-null Blockly.Block

Find all the uses of the given variable, which is identified by ID.

Parameter
id	ID of the variable to find.

Inherited from

Blockly.Workspace#getVariableUsesById

Returns

Array of block usages.

getWidth

getWidth() returns number

Returns the horizontal offset of the workspace. Intended for LTR/RTL compatibility in XML.

Returns

number Width.

hasBlockLimits

hasBlockLimits() returns boolean

Checks if the workspace has any limits on the maximum number of blocks, or the maximum number of blocks of specific types.

Inherited from

Blockly.Workspace#hasBlockLimits

Returns

True if it has block limits, false otherwise.

highlightBlock

highlightBlock(id, opt_state)

Highlight or unhighlight a block in the workspace. Block highlighting is often used to visually mark blocks currently being executed.

Parameter
id	string ID of block to highlight/unhighlight, or null for no block (used to unhighlight all blocks). Value may be null.
opt_state	Optional boolean If undefined, highlight specified block and automatically unhighlight all others. If true or false, manually highlight/unhighlight the specified block.

isCapacityAvailable

isCapacityAvailable(typeCountsMap) returns boolean

Check if there is remaining capacity for blocks of the given counts to be created. If the total number of blocks represented by the map is more than the total remaining capacity, it returns false. If a type count is more than the remaining capacity for that type, it returns false.

Parameter
typeCountsMap	A map of types to counts (usually representing blocks to be created). Value must not be null.

Inherited from

Blockly.Workspace#isCapacityAvailable

Returns

True if there is capacity for the given map, false otherwise.

isDeleteArea

isDeleteArea(e) returns number

Is the mouse event over a delete area (toolbox or non-closing flyout)?

Parameter
e	Event Mouse move event. Value must not be null.

Returns

nullable number Null if not over a delete area, or an enum representing which delete area the event is over.

isDraggable

isDraggable() returns boolean

Is this workspace draggable and scrollable?

Returns

boolean True if this workspace may be dragged.

isDragging

isDragging() returns boolean

Is the user currently dragging a block or scrolling the flyout/workspace?

Returns

boolean True if currently dragging or scrolling.

isVisible

isVisible() returns boolean

Getter for isVisible

Returns

boolean Whether the workspace is visible. False if the workspace has been hidden by calling setVisible(false).

markFocused

markFocused()

Mark this workspace as the currently focused main workspace.

moveDrag

moveDrag(e) returns goog.math.Coordinate

Track a drag of an object on this workspace.

Parameter
e	Event Mouse move event. Value must not be null.

Returns

non-null goog.math.Coordinate New location of object.

newBlock

newBlock(prototypeName, opt_id) returns Blockly.BlockSvg

Obtain a newly created block.

Parameter
prototypeName	string Name of the language object containing type-specific functions for this block. Value may be null.
opt_id	Optional string Optional ID. Use this ID if provided, otherwise create a new ID.

Returns

non-null Blockly.BlockSvg The created block.

paste

paste(xmlBlock)

Paste the provided block onto the workspace.

Parameter
xmlBlock	Element XML block element. Value must not be null.

pasteBlock_

pasteBlock_(xmlBlock)

Paste the provided block onto the workspace.

Parameter
xmlBlock	Element XML block element. Value must not be null.

recordDeleteAreas

recordDeleteAreas()

Make a list of all the delete areas for this workspace.

refreshToolboxSelection

refreshToolboxSelection()

Refresh the toolbox unless there's a drag in progress.

registerButtonCallback

registerButtonCallback(key, func)

Register a callback function associated with a given key, for clicks on buttons and labels in the flyout. For instance, a button specified by the XML

should be matched by a call to registerButtonCallback("CREATE_VARIABLE", yourCallbackFunction).

Parameter
key	string The name to use to look up this function.
func	function(non-null Blockly.FlyoutButton) The function to call when the given button is clicked.

registerToolboxCategoryCallback

registerToolboxCategoryCallback(key, func)

Register a callback function associated with a given key, for populating custom toolbox categories in this workspace. See the variable and procedure categories as an example.

Parameter
key	string The name to use to look up this function.
func	function(non-null Blockly.Workspace) The function to call when the given toolbox category is opened.

remainingCapacity

remainingCapacity() returns number

The number of blocks that may be added to the workspace before reaching the maxBlocks.

Inherited from

Blockly.Workspace#remainingCapacity

Returns

Number of blocks left.

remainingCapacityOfType

remainingCapacityOfType(type) returns number

The number of blocks of the given type that may be added to the workspace before reaching the maxInstances allowed for that type.

Parameter
type	Type of block to return capacity for.

Inherited from

Blockly.Workspace#remainingCapacityOfType

Returns

Number of blocks of type left.

removeButtonCallback

removeButtonCallback(key)

Remove a callback for a click on a button in the flyout.

Parameter
key	string The name associated with the callback function.

removeChangeListener

removeChangeListener(func)

Stop listening for this workspace's changes.

Parameter
func	Function to stop calling.

Inherited from

Blockly.Workspace#removeChangeListener

removeToolboxCategoryCallback

removeToolboxCategoryCallback(key)

Remove a callback for a click on a custom category's name in the toolbox.

Parameter
key	string The name associated with the callback function.

removeTopBlock

removeTopBlock(block)

Remove a block from the list of top blocks.

Parameter
block	Block to remove. Value must not be null.

Inherited from

Blockly.Workspace#removeTopBlock

removeTopComment

removeTopComment(comment)

Remove a comment from the list of top comments.

Parameter
comment	comment to remove. Value must not be null.

Inherited from

Blockly.Workspace#removeTopComment

removeTypedBlock

removeTypedBlock(block)

Remove a block from the list of blocks keyed by type.

Parameter
block	Block to remove. Value must not be null.

Inherited from

Blockly.Workspace#removeTypedBlock

renameVariableById

renameVariableById(id, newName)

Rename a variable by updating its name in the variable map. Update the flyout to show the renamed variable immediately.

Parameter
id	string ID of the variable to rename.
newName	string New variable name.

render

render()

Render all blocks in workspace.

resetDragSurface

resetDragSurface()

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.

resize

resize()

Resize and reposition all of the workspace chrome (toolbox, trash, scrollbars etc.) This should be called when something changes that requires recalculating dimensions and positions of the trash, zoom, toolbox, etc. (e.g. window resize).

resizeContents

resizeContents()

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.

scrollCenter

scrollCenter()

Center the workspace.

setResizeHandlerWrapper

setResizeHandlerWrapper(handler)

Save resize handler data so we can delete it later in dispose.

Parameter
handler	Array of non-null Array Data that can be passed to unbindEvent_. Value must not be null.

setResizesEnabled

setResizesEnabled(enabled)

Update whether this workspace has resizes enabled. If enabled, workspace will resize when appropriate. If disabled, workspace will not resize until re-enabled. Use to avoid resizing during a batch operation, for performance.

Parameter
enabled	boolean Whether resizes should be enabled.

setScale

setScale(newScale)

Set the workspace's zoom factor.

Parameter
newScale	number Zoom factor.

setupDragSurface

setupDragSurface()

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.

setVisible

setVisible(isVisible)

Toggles the visibility of the workspace. Currently only intended for main workspace.

Parameter
isVisible	boolean True if workspace should be visible.

startDrag

startDrag(e, xy)

Start tracking a drag of an object on this workspace.

Parameter
e	Event Mouse down event. Value must not be null.
xy	goog.math.Coordinate Starting location of object. Value must not be null.

traceOn

traceOn()

Was used back when block highlighting (for execution) and block selection (for editing) were the same thing. Any calls of this function can be deleted.

Deprecated

October 2016

translate

translate(x, y)

Translate this workspace to new coordinates.

Parameter
x	number Horizontal translation.
y	number Vertical translation.

undo

undo(redo)

Undo or redo the previous action.

Parameter
redo	False if undo, true if redo.

Inherited from

Blockly.Workspace#undo

updateInverseScreenCTM

updateInverseScreenCTM()

Mark the inverse screen CTM as dirty.

updateScreenCalculationsIfScrolled

updateScreenCalculationsIfScrolled()

Resizes and repositions workspace chrome if the page has a new scroll position.

updateToolbox

updateToolbox(tree)

Modify the block tree on the existing toolbox.

Parameter
tree	(Node or string) DOM tree of blocks, or text representation of same.

variableIndexOf

variableIndexOf(_name) returns number

Check whether a variable exists with the given name. The check is case-insensitive.

Parameter
_name	The name to check for.

Inherited from

Blockly.Workspace#variableIndexOf

Deprecated

April 2017

Returns

The index of the name in the variable list, or -1 if it is not present.

zoom

zoom(x, y, amount)

Zooming the blocks centered in (x, y) coordinate with zooming in or out.

Parameter
x	number X coordinate of center.
y	number Y coordinate of center.
amount	number Amount of zooming (negative zooms out and positive zooms in).

zoomCenter

zoomCenter(type)

Zooming the blocks centered in the center of view with zooming in or out.

Parameter
type	number Type of zooming (-1 zooming out and 1 zooming in).

zoomToFit

zoomToFit()

Zoom the blocks to fit in the workspace if possible.