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.
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.
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.
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.
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.
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.
The three possible outside connections are shown below.
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.
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.
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.
When the cursor is on a field, press Enter to edit it.
Connecting Blocks On The Workspace
- Navigate to your target connection using the WASD keys
- Mark the connection using the Enter key
- Navigate to a valid connection point using the WASD keys
- Connect the two blocks using the I key (for insert)
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.
- Navigate to a position on the workspace using the Shift + WASD keys
- Mark that location on the workspace using the Enter key
- Navigate to the block you want to move using the WASD keys
- Move the block to the marked location using the I key
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.
- Navigate to the connection you want to break using the WASD keys
- Break the connection with X
Inserting A Block From The Toolbox
- Press the T key to open the toolbox
- Use the W & S keys to move through the categories
- Press the D key to move over to the blocks in the flyout
- Navigate through the blocks using the W & S keys
- Press the Enter key to insert a block from the flyout
We believe there are four main areas that people might be interested in experimenting with:
- Key Mappings: What keys should map to what actions.
- Text for screen readers/Logging/Warnings: How a screen reader should read out cursors locations as well as any errors or warnings.
- Workspace Navigation: How a user navigates the different blocks, fields, inputs, and connections on the workspace.
- 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 (Coming Soon) 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.
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.
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.