Tools and their options

Blockwright has 25 tools. This page takes them in the Toolbox's order: where each one is, what each of its settings in the Tool Options dock does, with its range and where it starts, the mouse buttons and keys it takes, and its limits. Selections, the Library and mirror mode have pages of their own, and this page points to them rather than repeating them.

The tutorials teach the tools in use; each section below links to the one that does.

Where they are

The Toolbox puts the tools in ten groups, each a button. A group of one tool is a plain button. A group of several shows the tool picked from it last, starting with its first; click the button's arrow, or right-click the button, for the rest (its tooltip says Click the arrow or right-click for the rest of the group). The groups, in order:

1. Keyboard
2. Select
3. Move/Transform
4. Laying a colour or a glyph down: Half-Block Brush, Shade Brush, Glyph Brush, Colorize Brush
5. Walking a ramp: Ramp Shade Brush, Form Brush, Soft Brush, Despeckle Brush, Smudge Brush
6. Detail: Outline Brush, Rim Light Brush, Texture Stamp, Clone Stamp, Glyph Spray
7. Shapes: Line, Rectangle, Ellipse, Frame
8. Fill, Ramp Gradient
9. Eyedropper
10. Text

The Tool Options dock shows the active tool's name, then About this tool: a picture of the tool at work and a few lines on what it does and what its options change, ending with a link to every shortcut (Help > Keyboard Shortcuts). Click About this tool to hide or show them; it starts shown, and Blockwright remembers the choice. Below them are the tool's options, the ones this page pictures.

Three things work across the tools:

• Alt and a left-drag on the canvas moves the active layer, with any tool, as Move/Transform does (Moving a layer).
• With a brush, a shape, Fill or Ramp Gradient, Esc during a drag drops it: the stroke or shape in progress goes, and nothing is written.
• Keys a tool doesn't use go to keyboard mode, so typing at the cell cursor works with most tools active (Keyboard mode).

The left mouse button and the right do different things in most tools; each section says what.

Options the brushes share

The brushes are the tools in groups 4 to 6 other than the Half-Block Brush. They share these settings, and one setting holds for all of them: a size picked with the Shade Brush is the size the Glyph Brush has.

Each ramp is a run of colours from black up:

Between each pair of colours the ramp has three shaded steps, ░, ▒ and ▓, so each colour is four rungs: steel's rungs run from 0, black, to 12, white. Tutorial 04's Ramps builds them up, and Strength, Pressure and Alpha lock show the rest.

The Light setting is shared by the Form Brush, the Rim Light Brush and the Texture Stamp: N, NE, E, SE, S, SW, W or NW, the side the light comes from, starting at NW.

The size, tip, pressure, strength, ramp, light, form and hardness start where this page says each time Blockwright starts. The settings of the Texture Stamp, Glyph Spray, Clone Stamp, Rim Light Brush's lint check, Ramp Gradient and Frame are kept from one session to the next, and so are the pen and the F-key set.

Keyboard

Tools > Keyboard, Ctrl+K, the Toolbox's first button.

Types at the cell cursor in the pen's colours, as a text editor does. Click a cell to put the cursor there; the arrows, Home, End and Enter move it, Backspace and Delete clear a cell, and F1 to F10 type the glyphs of the current F-key set. The dock says This tool has no options.

The keys, the F-key sets and the pen are on their own page, Keyboard mode. Tutorial 02's Keyboard mode teaches it.

Select

Tools > Select, Ctrl+E.

Selects a rectangle of cells to copy, move, flip or turn. While there is a selection, the brushes, the shapes, Fill and Ramp Gradient paint only inside it; typing with Keyboard or Text doesn't keep to it.

Dragging, the float, the arrow keys, Enter, Esc, Delete, the paste modes, the flips and turns, and a Library frame's handles are on Selections, clipboard and paste modes. Tutorial 08's Selecting and moving teaches it.

Move/Transform

Tools > Move/Transform, Ctrl+Shift+J.

Drag on the canvas to move the active layer: an art layer by whole cells, a Reference layer by canvas pixels. Alt+drag does the same with any tool. On a Reference layer, a corner handle resizes the picture from the opposite corner, keeping its aspect unless Shift is held. Esc drops a drag; each move or resize is one undo step; a locked or hidden layer doesn't move.

The options are a Reference layer's place and size. With any other layer active they are greyed out, and the dock says Drag to move the active layer. Place and size a reference layer here.:

Moving a layer and Reference have the rest. Tutorial 08's A reference image uses it.

Half-Block Brush

Tools > Half-Block Brush, Ctrl+B, the first of the fourth group.

A pencil of half-block pixels: each cell is two square pixels, top and bottom, drawn with ▀ and ▄. The left button draws in the pen's foreground, the right in its background. A drag is joined into an unbroken line. It has no size: a stroke is one pixel wide.

The same yellow diagonal drawn with Pencil 4-connected ticked, on the left, and unticked, on the right:

Tutorial 03, Pixels with half blocks, teaches it, and its 4-connected and 8-connected shows why a line wants the tick.

Shade Brush

Tools > Shade Brush, Ctrl+Shift+B.

Builds a cell up through space, ░, ▒, ▓ and █ in the pen's colours, a step each time the brush passes. The left button builds up; the right takes a step back down towards a space. Glyphs other than the shades, such as text and half blocks, are left alone.

Its options are the shared ones: Size, Tip, Pressure, Alpha lock and Symmetry, pictured there.

Light blue on blue: rows 1 to 4 with one to four passes, and row 6 built to █ and then passed once with the right button, back to ▓:

It can't paint a Pixels layer, which holds no shades. Tutorial 04's The shade brush teaches it.

Glyph Brush

Tools > Glyph Brush, Ctrl+G.

Paints one glyph in the pen's colours wherever it passes. The left button paints the glyph, the right erases to a blank cell. F1 to F10, or a click on the glyph bar, pick the glyph from the current F-key set (The F-key glyph sets).

Light red ♥ at size 5 with the round tip along row 3, then the right button at size 1 along the same row, erasing the middle:

On a Pixels layer it paints only █, ▀, ▄ and blanks; with another glyph picked, the left button does nothing there and the status bar says why. Tutorial 07's Symmetry draws with it.

Colorize Brush

Tools > Colorize Brush, Ctrl+Shift+C.

Recolours the cells it passes and keeps their glyphs. The left button sets each cell's foreground to the pen's foreground; the right sets its background to the pen's background. Its options are the shared ones without strength or ramp.

A dark grey disc of half blocks, then a red stroke at size 3 across its middle with the left button:

The stroke recolours the foreground only, so the cells round the disc, blank and black, look the same. Tutorial 10's Text layers and TheDraw fonts uses the right button on baked letters.

Ramp Shade Brush

Tools > Ramp Shade Brush, Ctrl+T, the first of the fifth group.

Lightens or darkens the cells under it along the ramp, through the ░▒▓ shades between each pair of colours. The left button lightens, the right darkens. Cells whose colours aren't on the ramp are left alone, and it never writes a shade of two colours that aren't neighbours on the ramp.

The dark grey disc from Colorize Brush, then three clicks at 25% with the round tip on the same cell of its upper left, at sizes 13, 9 and 5, with steel:

It can't paint a Pixels layer. Tutorial 04's The ramp shade brush teaches it.

Form Brush

Tools > Form Brush, Ctrl+Shift+T.

Shades a shape as a lit dome, cylinder or flat plane along the ramp, with a lit side, a short fall of shades and a shadow side. The shape is the selection, or, with nothing selected, the cells the stroke covers. Either button.

Two dark grey blocks, each selected and stroked at 100% with the light from NW: a Dome on the left and a Cylinder on the right:

The brush leaves a cell as the stroke had left it where painting it would add a ladder-lint finding along its ramp that the canvas didn't have when the stroke began (a non-neighbour shade, a wide rung, a rung skip, a speck, one glyph or noise); a finding with no painted cell next to it takes back the whole dab (one glyph and noise are placed at the corner of the area they cover, so they usually do). This is always on: the Form Brush has no option for it.

It can't paint a Pixels layer. Tutorial 05's The form brush and Form teach it; tutorial 06's The form brush's light, Glint and Form rim light teach its light.

Soft Brush

Tools > Soft Brush, Ctrl+Shift+N.

The ramp shade brush with a soft edge: it moves the middle of the tip the most and the edge a rung, in bands a cell wide. The left button lightens, the right darkens.

One click at 100% on the dark grey disc, size 12, round tip, Hardness 0%, with steel:

It can't paint a Pixels layer. Tutorial 05's The soft brush and Hardness teach it.

Despeckle Brush

Tools > Despeckle Brush, Ctrl+Shift+D.

Cleans up specks: a lone cell lighter or darker than every neighbour on the ramp takes the rung most of its neighbours share. Either button.

A dark grey disc with three grey specks, and the same disc after one stroke across it:

It leaves alone cells off the ramp, black, the ramp's top rung (a glint), and the cells of a 4×4 Bayer gradient's dither, and skips a fix that would add a new lint finding (Speck). Tutorial 05's The despeckle brush teaches it.

Smudge Brush

Tools > Smudge Brush, Ctrl+Shift+M.

Picks up the ramp colours under the tip and drags them along the stroke, like a finger through paint. Each cell of the tip carries its own value, so a wide tip drags a patch. Results are snapped back to the ramp's rungs. Either button.

A grey bar on a dark grey ground, smudged to the right from the bar along row 2 at 100% and along row 5 at 50%:

The smear stops at a cell off the ramp, a black cell, a transparent cell, or a cell it can't paint; drawn on black, it carries nothing. It can't paint a Pixels layer. Tutorial 05's The smudge brush teaches it.

Outline Brush

Tools > Outline Brush, Ctrl+Shift+E, the first of the sixth group.

Draws a one-cell outline round a shape: each edge cell under the brush aims for the ramp colour one step darker than the darkest of the shape just inside it. Where that would break the shading rules the lint checks, the cell takes a lighter shade instead, or is left as it is. The shape is the cells in the ramp's colours other than black. Where the step below the inside is black, the line is the darkest colour above black. Either button.

A grey disc, and the same disc after a stroke round it with steel:

One stroke draws a line one cell wide, however often it passes. A shape that is all edge is left alone. Tutorial 07's The outline brush teaches it.

Rim Light Brush

Tools > Rim Light Brush, Ctrl+Shift+L.

Lights a shape's edge: edge cells of the ramp's shape that face the light go one rung lighter. Either button.

The dark grey disc after a stroke all round it, the light from NW:

One stroke lights one cell deep, however often it passes. It can't paint a Pixels layer. Tutorial 06's The rim light brush and Keep the lint clean teach it.

Texture Stamp

Tools > Texture Stamp, Ctrl+Shift+P.

Stamps a texture of small lit forms along the ramp. The texture is fixed to the canvas by its seed, so overlapping strokes paint one texture with no seams. It paints over whatever the cells held. Either button.

Scales on the left half and Brick on the right, with steel:

It can't paint a Pixels layer. Tutorial 07's The texture stamp teaches it.

Clone Stamp

Tools > Clone Stamp, Ctrl+Shift+K.

Copies whole cells from one place to another: glyphs, colours and transparency. Ctrl+click (Cmd+click on macOS), with either button, sets the source. A stroke then copies from the source to the cells under the brush, keeping the distance between the source and where the stroke started. The canvas marks the source, and during a stroke the cell being copied. Without a source it paints nothing, and the status bar says Ctrl+click to set the source.

A light cyan disc on the left; the source set at its middle, then one stroke at the right:

A stroke dropped with Esc keeps the old distance. Tutorial 07's The clone stamp teaches it; The clone stamp in the CLI page scripts it.

Glyph Spray

Tools > Glyph Spray, Ctrl+Shift+Y.

Scatters stars, haze or smoke across the cells it passes. Stars are small glyphs in the pen's foreground, placed only on open ground away from shapes; the right button takes them off. Haze and smoke lift the ramp by ░▒, lighter with the left button and darker with the right. The pattern is fixed to the canvas by its seed, so strokes over one another paint the same field.

White Stars on the left and Haze on the right, on black:

Haze and smoke can't paint a Pixels layer, and nor can stars, which are glyphs a Pixels layer doesn't hold. Tutorial 07's The glyph spray teaches it.

Line, Rectangle and Ellipse

Each draws in half-block pixels, from where you press to where you let go: a straight line, a rectangle from corner to corner, or an ellipse inside that box. The left button draws in the pen's foreground, the right in its background. The canvas shows the shape as you drag.

A light green Line, a yellow Rectangle outline and a light magenta Ellipse with Filled ticked:

A shape is one pixel wide; there is no size. Tutorial 03, Pixels with half blocks, teaches them.

Frame

Tools > Frame, Ctrl+Shift+I.

Draws a border to fit the rectangle you drag, from the corner you press to the corner you let go at. Each frame is a small piece cut into corners, edges and a middle: the corners stay as they are and the edges repeat along their length, so a frame draws to any size from its smallest up, and a drag smaller than that grows to it. The middle of most frames is open and leaves what is under it alone. The right button erases the cells the frame would cover.

The built-in styles, in the list's order: Single line, Double line, Double across, single down, Single across, double down, Heavy block, Thin half-block, Shaded, Bevel, Hazard stripes, Dashed line and Double-bevel button. Line, half-block and shaded frames leave the background under their own cells, so they can be dropped onto a coloured scene; the bevel, the hazard stripes and the button paint their own. Your own styles follow the built-in ones: select a small drawn box and choose Selection > Save as Frame Style (Save as Frame Style and Save as Preset).

On a Pixels layer it draws only a style whose glyphs the layer holds, and the status bar says when it can't. No tutorial teaches it yet.

Fill

Tools > Fill, Ctrl+J, the first of the eighth group.

Floods the area of one colour under the click with the pen's colour, a half-block pixel at a time. The left button fills with the pen's foreground, the right with its background. The area is the pixels of the clicked colour joined side by side or up and down, not corner to corner.

A grey ring, and a click inside it with a red pen:

Tutorial 03, Pixels with half blocks, teaches it; Sample merged in the CLI page scripts it.

Ramp Gradient

Tools > Ramp Gradient, Ctrl+Shift+G.

Fills with a gradient along the ramp, in bands of whole cells shaded ░▒▓, from where you press to where you let go. It fills the selection, or the whole layer with nothing selected, and fits the gradient to the cells round it. The left button runs from the From rung to the To rung, the right the other way round.

It takes no Symmetry: it fills every cell it may paint, so mirror mode has nothing to add. A Linear drag across the canvas from rung 0 to 12, and a Radial one from the middle, 12 to 0, 4×4 Bayer:

The lint doesn't call a dither's cells specks while each sits a rung from its neighbours, and a project keeps them that way; saved as .ans and opened again they are plain cells, and the lint calls them specks. Draw over one with another tool and it is an ordinary cell again. It can't paint a Pixels layer. Tutorial 05's The ramp gradient teaches it.

Eyedropper

Tools > Eyedropper, Ctrl+I.

Picks a colour off the canvas into the pen. The left button picks into the pen's foreground, the right into its background. On a half-block cell it picks the colour of the half under the pointer. A transparent cell picks nothing.

The pen is on Keyboard mode and Colour. Tutorial 03, Pixels with half blocks, uses it.

Text

Tools > Text, Ctrl+Shift+X, the Toolbox's last button.

Writes live text in a font: a bundled face or a TheDraw font. The text stays editable on its own Text layer (Text). Click a text layer to edit it, or click anywhere else and type to start a new text layer there. Typing, Backspace, Delete, Enter and the arrows edit at the text cursor; Esc ends the edit.

A change applies to the active text layer and to the next new text. While the cursor waits to start a new text layer, a change applies to that new text only.

"Hi" in the block face, yellow:

Tutorial 10's Text layers and TheDraw fonts teaches it; The text tool in the CLI page scripts it.

Limits

• The brush size, tip, pressure, strength, ramp, light, form, hardness and mirror mode start afresh each time Blockwright starts.
• The Shade, Ramp Shade, Form, Soft, Smudge, Rim Light and Texture brushes, the Glyph Spray and the Ramp Gradient can't paint a Pixels layer, which holds no shades; the Glyph Brush paints only █, ▀, ▄ and blanks there. The status bar says The … can't paint a Pixels layer: it holds no ….
• Pressure needs a stylus: a mouse always presses fully.
• The Half-Block Brush, Line, Rectangle and Ellipse draw one pixel wide; Size is for the brushes.
• The Ramp Gradient takes no mirror mode, and its dither's cells read as specks once saved as .ans and opened again.
• Move/Transform's fields work only on a Reference layer.
• Keyboard and Text don't keep to a selection.
• A steps file for blockwright-cli replay has no action for the Frame tool (replay).

Describes Blockwright 0.1.0 (12ee9ef).