Keyboard Navigation

This guide focuses on how to use the default keyboard navigation as it is currently implemented in Blockly.

Using Keyboard Navigation

For keyboard navigation to be successful a user must be able to complete the following tasks:

  • Move around the workspace
  • Connect blocks on a workspace
  • Add a block to the workspace
  • Detach blocks
  • Navigate the toolbox
  • Navigate the flyout
  • Insert blocks from the flyout

The below explains how Blockly's default keyboard navigation accomplishes these tasks.

Enabling Keyboard Navigation

A user can enable and disable keyboard navigation by hitting Shift + Ctrl + k. When keyboard navigation is first enabled a flashing red line appears on the workspace. This is the cursor. It shows the user's current location and updates as the user navigates the workspace.
When a user hits shift control k a flashing red line appears on the screen. This is the cursor.

Hitting Enter creates a blue line at the current location that depicts a user's marker. A marker displays a target location for block insertion. It does not update as you move the cursor around the workspace.
When a user hits enter a blue line appears on the screen. This is the marker.

Using the Default Cursor

The workspace is made up of inputs, fields, connections, blocks, and workspace coordinates. The default cursor moves around the workspace by dividing up all the components into different levels.

To navigate between levels use the A and D keys. To navigate within a level use the W and S keys.

Workspace Level

Enter into keyboard navigation mode by hitting Shift + Ctrl + k. This places the cursor on the workspace or on the first block on the workspace. If the cursor is on a block move it to the workspace level by pressing A twice. To move the cursor on the workspace use Shift + WASD. To move to the stack level use the D key.
The cursor on the blockly workspace moves when the user presses the Shift and W A S D keys. When the user hits d the cursor appears as a rectangle around the first stack of blocks

Stack Level

At the stack level you can navigate between stacks of blocks on the workspace using the W and S keys. At this level the cursor is represented by a solid red rectangle around all the blocks in a stack. To go to the first block in the selected stack use the D key.
When the user presses s the cursor moves to the next stack of blocks. When the user hits d the cursor appears as a flashing red line above the first block in the selected stack.

Block and Connections Level

This level holds a block and all the outside connections on the block. The default cursor is set to skip the block if there is a previous or output connection. If neither exist then the cursor will move to the block, as shown below.

When the user presses d the cursor moves from being a red rectangle around the stack of blocks to being half of a rectangle surrounding the first block in the stack.

The three possible outside connections are shown below.
A red line highlights the three possible outside connections. These are the previous, next and output connections on a block.

At the block and connection level you can navigate through the outside connections using the W and S keys. At this level the cursor is represented by a flashing red outline of the current connection. To go to the first field or input on a block press D.
When the user presses the S key the cursor appears as a red flashing line on the next connection of a block. When a user presses the d key the cursor appears as a red rectangle around the first field on the block.

Fields and Input Level

This level holds all the fields and inputs that are on the block. Examples of what fields and inputs look like are shown below.
A red rectangle highlights examples of inputs and fields on a block.
At this level you can navigate across the current block's editable fields and inputs with W and S. For a field, the cursor is a solid red rectangle. For an input, the cursor is a flashing red puzzle piece. When the cursor is on an input press D to move to the connected block.

The cursor moves through the block's inputs and fields when a user hits the S key. When a user hits d while on an input with a connected block the cursor appears as a flashing red line on top of the connected block.

When the cursor is on a field, press Enter to edit it.

The cursor is displayed as a red rectangle around a field. When the user hits enter a dropdown opens. The user hits the S key to select a value in the dropdown and then hits enter to close the dropdown.

Connecting Blocks On The Workspace

  1. Navigate to your target connection using the WASD keys
  2. Mark the connection using the Enter key
  3. Navigate to a valid connection point using the WASD keys
  4. Connect the two blocks using the I key (for insert)

An input connection has a blue point showing it is marked. When the user hits i on a valid connection the block moves to the marked connection point.

Moving a Block on the Workspace

Normally in Blockly you move a block to the workspace by picking it up, dragging it to the desired position, and releasing it. With keyboard shortcuts you mark your target location, navigate to the block you want to move and then tell it to move.

  1. Navigate to a position on the workspace using the Shift + WASD keys
  2. Mark that location on the workspace using the Enter key
  3. Navigate to the block you want to move using the WASD keys
  4. Move the block to the marked location using the I key

A cursor is shown on the blockly workspace. When the user hits enter they mark their location and a blue line appears at this position. Using the WASD keys they move the cursor to the outside connection of a block. When the user hits i the block moves to the marked location.

Detaching Blocks

Normally in Blockly you disconnect two blocks by picking up the inferior block and dragging it away from the parent block. With keyboard shortcuts you disconnect blocks by pressing X with the cursor on the connection that you want to break.

  1. Navigate to the connection you want to break using the WASD keys
  2. Break the connection with X

Two blocks are connected on the screen with the cursor shown in the middle of them. When the user hits the x key the blocks become disconnected.

Inserting A Block From The Toolbox

  1. Press the T key to open the toolbox
  2. Use the W & S keys to move through the categories
  3. Press the D key to move over to the blocks in the flyout
  4. Navigate through the blocks using the W & S keys
  5. Press the Enter key to insert a block from the flyout

When a user presses t a toolbox opens showing different categories of blocks. Hitting s moves through the different categories. When a user hits d the first block in the category is highlighted. Hitting Enter places the block on the workspace and closes the toolbox.

Experimentation

We believe there are four main areas that people might be interested in experimenting with:

  1. Key Mappings: What keys should map to what actions.
  2. Text for screen readers/Logging/Warnings: How a screen reader should read out cursors locations as well as any errors or warnings.
  3. Workspace Navigation: How a user navigates the different blocks, fields, inputs, and connections on the workspace.
  4. Cursor Appearance: What the cursor and marker should look like.

For more information on how to use these APIs please look at the Blockly Keyboard Navigation code lab.

If you have any other areas that you want to experiment with that we might be able to help with, please fill out the form.

FAQ

Q: Why did you not use the arrow keys for keyboard navigation?
A: Screen readers generally use the arrow keys. We didn't want to interfere with this and so chose to use the WASD keys.
However, we recognize that everyone has different needs and so we highly recommend creating an easy way to change the key mappings.

Q: It seems pretty complicated, why do we need different layers?
A: When thinking about keyboard navigation we needed a structured way to move around the different blocks, connections, fields, inputs and workspace coordinates.
Internally we represent this with an abstract syntax tree (AST). The default cursor implementation doesn't stray far from this model.This is intentional to give developers a better understanding of the underlying architecture. There are other cursors that might be easier for an end user to understand.

Limitations

We do not yet support navigating to non-block components (e.g. trash can, zoom buttons, and flyout buttons). For more information on limitations please see the list of open keyboard navigation bugs.