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

The workspace's trashcan (if any).

trashcan

Blockly.Trashcan

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

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.

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.

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.

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.

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

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.