Customize Blockly Editor

The following guide explores different ways in which you can customize and use WorkbenchViewController.

Style

There are two styles you can use when initializing a WorkbenchViewController:

StyleExampleDescription
Default Workbench with Default Style
  • Toolbox is positioned vertically along the leading edge
  • Undo/redo buttons are in the bottom-leading edge corner
  • Trash can is in the bottom-trailing edge corner
  • Trash folder opens from the bottom
Alternate Workbench with Alternate Style
  • Toolbox is positioned horizontally along the bottom edge
  • Undo/redo buttons are in the top-leading edge corner
  • Trash can is located in the top-trailing edge corner
  • Trash folder opens from the trailing edge of the screen

This code example shows how to instantiate both types:

Swift

let defaultWorkbench = WorkbenchViewController(style: .defaultStyle)
let alternateWorkbench = WorkbenchViewController(style: .alternate)

Objective-C

BKYWorkbenchViewController *defaultWorkbench =
  [[BKYWorkbenchViewController alloc] initWithStyle:BKYWorkbenchViewControllerStyleDefaultStyle];
BKYWorkbenchViewController *alternateWorkbench =
  [[BKYWorkbenchViewController alloc] initWithStyle:BKYWorkbenchViewControllerStyleAlternate];

Properties

You can set the following properties on the WorkbenchViewController to change its behavior.

Name Type Description
allowInteractivePopGestureRecognizer Bool Enables or disables the "backswipe gesture" on its current navigationController (if available). Defaults to false.
allowUndoRedo Bool Enables or disables the ability to undo/redo actions in the workspace. Defaults to true.
allowZoom Bool Enables or disables pinch zooming of the workspace. Defaults to true.
enableTrashCan Bool Displays or hides a trash can. Defaults to true.
toolboxDrawerStaysOpen Bool When the toolbox drawer loses focus, specifies whether it should stay open or if it should automatically close. Defaults to false.
workspaceBackgroundColor UIColor The background color to use for the main workspace.

Layout Config

Each WorkbenchViewController is initialized with a LayoutEngine that is responsible for UI scaling and layout configuration. The LayoutEngine owns an instance of a LayoutConfig object, which contains values used for configuring the look-and-feel of Blockly.

Here's an example of how to configure the LayoutConfig:

Swift

let workbench = WorkbenchViewController(style: .defaultStyle)

// Set the maximum width for text fields to be 200 Workspace units
workbench.engine.config.setUnit(LayoutConfig.Unit(200),
                                for: LayoutConfig.FieldTextFieldMaximumWidth)
// Set the size of the color button size to be (64, 64) Workspace units
workbench.engine.config.setSize(LayoutConfig.Size(64, 64),
                                for: LayoutConfig.FieldColorButtonSize)
// Set the duration of view animations to be 1.0 seconds
workbench.engine.config.setDouble(1.0, for: LayoutConfig.ViewAnimationDuration)
// Set the scalable font creator for all text used in Blockly
workbench.engine.config.setFontCreator({ scale in
  return UIFont.systemFont(ofSize: 18.0 * scale)
}, for: LayoutConfig.GlobalFont)

Objective-C

BKYWorkbenchViewController *workbench =
  [[BKYWorkbenchViewController alloc] initWithStyle:BKYWorkbenchViewControllerStyleDefaultStyle];

// Set the maximum width for text fields to be 200 Workspace units
[workbench.engine.config setUnit:BKYLayoutConfigUnitMake(200)
                             for:BKYLayoutConfig.FieldTextFieldMaximumWidth];
// Set the size of the color button size to be (64, 64) Workspace units
[workbench.engine.config setSize:BKYLayoutConfigSizeMake(64, 64)
                             for:BKYLayoutConfig.FieldColorButtonSize];
// Set the duration of view animations to be 1.0 seconds
[workbench.engine.config setDouble:1.0 for:BKYLayoutConfig.ViewAnimationDuration];
// Set the scalable font creator for all text used in Blockly
[workbench.engine.config setFontCreator:^UIFont*(CGFloat scale) {
  return [UIFont systemFontOfSize: 18.0 * scale];
} for:BKYLayoutConfig.GlobalFont];

Value Types

LayoutConfig supports both scalable and non-scalable values.

Scalable values automatically change when the LayoutEngine scale changes, which typically happens as the user zooms in/out of the workspace. These values should be initialized relative to Blockly's Workspace coordinate system and not iOS' UIView coordinate system.

Non-scalable values do not change as the LayoutEngine scale changes.

These are all the types of values that LayoutConfig supports:

Swift Type Objective-C Type Description Scalable?
Bool BOOL Boolean value. No
Double double Double value. No
Float CGFloat Floating-point value. No
FontCreator FontCreator Closure that creates a UIFont based on the current scale. Yes
LayoutConfig.Unit BKYLayoutConfigUnit Floating-point value. Yes
LayoutConfig.Size BKYLayoutConfigSize Size representing width and height. Yes
LayoutConfig.ScaledEdgeInsets BKYLayoutConfigEdgeInsets Amount of padding an element should be inset from its parent container. Yes
String NSString String value. No
UIColor UIColor Color value. No

Keys

Here's a sample of some commonly-used keys defined by LayoutConfig:

Key Value Type Description
BlockBumpDistance LayoutConfig.Unit The distance to bump blocks away from each other.
BlockSnapDistance LayoutConfig.Unit The maximum distance allowed for blocks to "snap" toward each other at the end of drags, if they have compatible connections near each other.
FieldCornerRadius LayoutConfig.Unit If necessary, the rounded corner radius of a field.
FieldEditableTextColor UIColor The default color for editable text in fields.
FieldLabelTextColor UIColor The default color for text in field labels.
FieldLineWidth LayoutConfig.Unit If necessary, the line stroke width of a field.
FieldMinimumHeight LayoutConfig.Unit Minimum height of field rows.
FieldTextFieldInsetPadding EdgeInsets For fields that use an InsetTextField, this is the insetPadding that should be used for each one.
FieldTextFieldMaximumWidth LayoutConfig.Unit For fields that use a UITextField, this is the maximum width that should be used for each one.
GlobalFont FontCreator The default font creator to use for all text inside Blockly.
InlineXPadding LayoutConfig.Unit Horizontal padding around inline elements (such as fields or inputs).
InlineYPadding LayoutConfig.Unit Vertical padding around inline elements (such as fields or inputs).
ViewAnimationDuration Double The animation duration to use when running animatable code inside a LayoutView.
WorkspaceFlowXSeparatorSpace LayoutConfig.Unit Horizontal space between blocks for WorkspaceFlowLayout.
WorkspaceFlowYSeparatorSpace LayoutConfig.Unit Vertical space between blocks for WorkspaceFlowLayout.

Click here to see the complete list of LayoutConfig's keys.

On initialization, WorkbenchViewController is actually created with a DefaultLayoutConfig instance, which adds more keys to the base LayoutConfig.

Here's a sample of some commonly-used keys defined by DefaultLayoutConfig:

Key Value Type Description
BlockConnectionLineWidthHighlight Unit Width of the line stroke for a highlighted connection.
BlockConnectionHighlightStrokeColor UIColor The stroke color to use when rendering a highlighted connection on a block.
BlockCornerRadius Unit Rounded corner radius of a block.
BlockDefaultAlpha Float The default alpha value to use when rendering a block.
BlockDisabledAlpha Float The alpha value to use when rendering a disabled block.
BlockDraggingFillColorAlpha Float The alpha value to use when rendering the stroke color of a dragged block.
BlockLineWidthRegular Unit Width of a regular line stroke for a block.
BlockLineWidthHighlight Unit Width of a highlighted line stroke for a block.
BlockHat String Default "hat" type that should be rendered on top of blocks with no output or previous connection (eg. Block.Style.hatCap or Block.Style.hatNone).
BlockStrokeDefaultColor UIColor The default stroke color to use when rendering a block.
BlockStrokeHighlightColor UIColor The stroke color to use when rendering a highlighted block.
InlineConnectorMinimumSize Size Minimum size of an empty connector drawn inside a block.

Click here to see the complete list of DefaultLayoutConfig's keys.

Scrolling Blocks into View

You may find it useful to scroll a particular block into view, especially if the user is executing code associated with that block. To do this for a given Block, you would call the following:

Swift

workbench.scrollBlockIntoView(blockUUID: block.uuid, animated: true)

Objective-C

[workbench scrollBlockIntoViewWithBlockUUID:block.uuid animated:YES];

Highlighting Blocks

To highlight a given Block in the workspace, call:

Swift

workbench.highlightBlock(blockUUID: block.uuid)

Objective-C

[workbench highlightBlockWithUUID:block.uuid];

To unhighlight a given Block in the workspace, call:

Swift

workbench.unhighlightBlock(blockUUID: block.uuid)

Objective-C

[workbench unhighlightBlockWithUUID:block.uuid];

To unhighlight all blocks in the workspace, call:

Swift

workbench.unhighlightAllBlocks()

Objective-C

[workbench unhighlightAllBlocks];