From 0572408803f366af4d054d994c2ad259a8271786 Mon Sep 17 00:00:00 2001 From: Keavon Chambers Date: Fri, 13 Mar 2026 02:55:59 -0700 Subject: [PATCH] Add the editing tools to the user manual --- node-graph/nodes/path-bool/src/lib.rs | 6 +- website/content/learn/tools/_index.md | 51 ++++++ website/content/learn/tools/artboard.md | 80 +++++++++ website/content/learn/tools/navigate.md | 98 +++++++++++ website/content/learn/tools/select.md | 208 ++++++++++++++++++++++++ website/sass/base.scss | 8 +- 6 files changed, 446 insertions(+), 5 deletions(-) create mode 100644 website/content/learn/tools/_index.md create mode 100644 website/content/learn/tools/artboard.md create mode 100644 website/content/learn/tools/navigate.md create mode 100644 website/content/learn/tools/select.md diff --git a/node-graph/nodes/path-bool/src/lib.rs b/node-graph/nodes/path-bool/src/lib.rs index 14c0025d52..a44bdf5363 100644 --- a/node-graph/nodes/path-bool/src/lib.rs +++ b/node-graph/nodes/path-bool/src/lib.rs @@ -26,10 +26,10 @@ async fn boolean_operation List { let content = content.into_graphic_list(); diff --git a/website/content/learn/tools/_index.md b/website/content/learn/tools/_index.md new file mode 100644 index 0000000000..f226bd96e7 --- /dev/null +++ b/website/content/learn/tools/_index.md @@ -0,0 +1,51 @@ ++++ +title = "Tools" +template = "book.html" +page_template = "book.html" + +[extra] +order = 4 ++++ + +Tools are the primary means of interacting with and creating content in the Graphite editor. Each tool is purpose-built for a specific kind of creation or editing task. Tools are activated from the **tool shelf** on the left side of the editor, or with their keyboard shortcut. + +## Tool categories + + + +### General tools + +Tools for selecting, navigating, and applying colors and styles to content. + +| Tool | Shortcut | Description | +|:-|:-:|:-| +| [Select](./select) | V | Select and transform layers and objects — move, resize, rotate, and skew by manipulating bounding box handles or using keyboard-driven grab/rotate/scale transforms. | +| [Artboard](./artboard) | | Create and manage artboard regions that define the bounds of exportable artwork areas. | +| [Navigate](./navigate) | Z | Pan and zoom the viewport. | +| [Eyedropper](./eyedropper) | I | Sample a color from anywhere on the canvas and set it as the active fill or stroke color. | +| [Fill](./fill) | F | Apply the active fill or stroke color to the clicked layer. | +| [Gradient](./gradient) | H | Create and interactively edit linear and radial gradient fills on layers. | + +### Vector tools + +Tools for drawing and editing vector paths and shapes. + +| Tool | Shortcut | Description | +|:-|:-:|:-| +| [Path](./path) | A | Edit the anchor points and handles of existing vector paths — select, move, add, delete, and modify the curvature of individual points and segments. | +| [Pen](./pen) | P | Draw new bezier paths point by point, placing anchor points and dragging out handles to define the curvature of each segment. | +| [Freehand](./freehand) | N | Draw freehand strokes that are recorded as vector paths. | +| [Spline](./spline) | | Draw smooth Catmull-Rom spline curves by placing points that the curve passes through naturally. | +| [Line](./line) | L | Draw straight line segments. This is the Line variant of the Shape tool. | +| [Rectangle](./rectangle) | M | Draw rectangles and squares, optionally with rounded corners. This is the Rectangle variant of the Shape tool. | +| [Ellipse](./ellipse) | E | Draw ellipses and circles. This is the Ellipse variant of the Shape tool. | +| [Shape](./shape) | Y | Draw parametric shapes — polygon, star, circle, arc, spiral, grid, and arrow — with tool options to configure their geometry. Also encompasses the Line, Rectangle, and Ellipse variants. | +| [Text](./text) | T | Create and edit text layers by clicking to place a text frame and typing. | + +### Raster tools + +Tools for painting and editing raster (pixel-based) content. + +| Tool | Shortcut | Description | +|:-|:-:|:-| +| [Brush](./brush) | B | Paint brush strokes onto raster layers. | diff --git a/website/content/learn/tools/artboard.md b/website/content/learn/tools/artboard.md new file mode 100644 index 0000000000..de68229dd5 --- /dev/null +++ b/website/content/learn/tools/artboard.md @@ -0,0 +1,80 @@ ++++ +title = "Artboard tool" +template = "book.html" +page_template = "book.html" + +[extra] +order = 2 ++++ + +The **Artboard tool** creates and manages artboards: named rectangular regions that define the bounds of exportable artwork areas on the canvas. Activate it by clicking its icon in the tool shelf. + + + +## Creating artboards + +Click and drag on any empty area of the canvas to draw a new artboard. When the mouse is released, the artboard is created with a white background and given a default label. + + + +| Input | Result | +|:-|:-| +| **Drag** | Create a new artboard with the dragged dimensions | +| **Shift Drag** | Constrain the new artboard to a square | +| **Alt Drag** | Draw from the center outward rather than from corner to corner | + +## Transform cage + +When an artboard is selected, its **transform cage** appears around it. This works similarly to the Select tool's transform cage but is limited to moving and resizing; artboards cannot be rotated or skewed. + + + +### Selecting + +Click any artboard to select it, which displays its transform cage and makes its properties editable. Only one can be selected at a time. + +| Input | Result | +|:-|:-| +| **Click an Artboard** | Select that artboard | +| **Delete or Backspace** | Delete the selected artboard, including its inner artwork contents | + + +### Moving + +Click and drag anywhere in the artboard to move it. The artboard's inner artwork contents move with it, maintaining relative positions to the artboard container. + +| Input | Result | +|:-|:-| +| **Drag** | Move the artboard freely | +| **Shift Drag** | Constrain movement to the horizontal or vertical axis (whichever is dominant) | + +### Resizing + +Drag an **edge midpoint handle** or **corner handle** on the transform cage to resize the artboard. Its inner artwork contents are repositioned to match the new bounds if the top/left edges are dragged. + +| Input | Result | +|:-|:-| +| **Drag an Edge or
Corner Handle** | Resize the artboard while the opposite edge or corner stays fixed | +| **Alt Drag** | Resize from the center rather than the opposite edge or corner | +| **Shift Drag** | Preserve the original aspect ratio | + +## Nudging + +Arrow keys move or resize the artboard in small increments without starting a drag. + +| Input | Result | +|:-|:-| +| **Arrows** | Move the artboard by 1 px | +| **Shift Arrows** | Move the artboard by 10 px | +| **Alt Arrows** | Resize the artboard by moving its bottom/right edges | +| **CtrlAlt Arrows** | Resize the artboard by moving its top/left edges | + +## Snapping + +While creating, moving, or resizing an artboard, it snaps to nearby artboards, layers, grid lines, and alignment guides. The edge midpoints, corners, and center of the artboard are all used as snap points. + +## Quick measurement + +Press and hold the Alt key anytime while hovering the pointer over an unselected artboard to display the offset distances, in pixels, between that and the selected artboard. + + diff --git a/website/content/learn/tools/navigate.md b/website/content/learn/tools/navigate.md new file mode 100644 index 0000000000..de3935a12d --- /dev/null +++ b/website/content/learn/tools/navigate.md @@ -0,0 +1,98 @@ ++++ +title = "Navigate tool" +template = "book.html" +page_template = "book.html" + +[extra] +order = 3 ++++ + +The **Navigate tool** provides dedicated controls for zooming and tilting the view of the canvas within the viewport. Most of these navigation actions are also available as global shortcuts that work while any other tool is active, which are documented as "Any tool" alongside the tool-specific controls below. Activate it by clicking its icon in the tool shelf or pressing Z (for "zoom"). + +## Panning + +Panning shifts the visible portion of the canvas within the viewport. + +### Free panning + +| Input | Result | Any tool | +|:-|:-|:-:| +| **Space Drag**

**Middle-Click Drag**

**Trackpad Scroll Gesture** | Pan the canvas | ✓ | + +### Directional scroll panning + +| Input | Result | Any tool | +|:-|:-|:-:| +| **Scroll Wheel** | Pan vertically
(default, see [preference](#scroll-wheel-preference)) | ✓ | +| **Shift Scroll Wheel** | Pan horizontally | ✓ | + +### Paginated scroll panning + +| Input | Result | Any tool | +|:-|:-|:-:| +| **Page Up** | (↑) Pan up by one viewport height | ✓ | +| **Page Down** | (↓) Pan down by one viewport height | ✓ | +| **Shift Page Up** | (←) Pan left by one viewport width | ✓ | +| **Shift Page Down** | (→) Pan right by one viewport width | ✓ | + +## Zooming + +Zooming magnifies or reduces the visible portion of the canvas within the viewport. + +### Free zooming + +| Input | Result | Any tool | +|:-|:-|:-:| +| **Ctrl Scroll Wheel

Trackpad Pinch Gesture** | Zoom toward or away from the pointer
(default, see [preference](#scroll-wheel-preference)) | ✓ | + +### Step zooming + +| Input | Result | Any tool | +|:-|:-|:-:| +| **Click** | Zoom in a step toward the pointer | | +| **Shift Click** | Zoom out a step from the pointer | | +| **Ctrl+
(macOS: ⌘+)** | Zoom in a step toward the viewport center | ✓ | +| **Ctrl-
(macOS: ⌘-)** | Zoom out a step from the viewport center | ✓ | + +### Smooth zooming + +| Input | Result | Any tool | +|:-|:-|:-:| +| **Drag** | Drag up to zoom in or down to zoom out | | +| **Ctrl Middle-Click Drag** | Drag up to zoom in or down to zoom out | ✓ | + +Hold Shift to snap to preset zoom levels while dragging. + +### Preset zooming + +| Input | Result | Any tool | +|:-|:-|:-:| +| **.** | Fit the current selection in the viewport | ✓ | +| **Ctrl0** | Fit the entire document in the viewport center | ✓ | +| **Ctrl1
(macOS: ⌘1)** | Zoom to 100% | ✓ | +| **Ctrl2
(macOS: ⌘2)** | Zoom to 200% | ✓ | + +#### Scroll wheel preference + +By default, the scroll wheel pans the canvas and Ctrl Scroll zooms. The *Zoom with Scroll* setting located in *File* > *Preferences* lets you swap this so the scroll wheel zooms and Ctrl Scroll pans vertically. This is not recommended if a trackpad is in use because it swaps two-finger scroll and pinch gestures. + +#### Zoom rate preference + +The *Zoom Rate* setting located in *File* > *Preferences* controls the speed of magnification while zooming with the scroll wheel (or trackpad scroll or pinch gesture). Relative to a default of 50, lower values reduce the zoom speed while higher values increase it. + +## Tilting + +Tilting rotates the entire canvas within the viewport. This does not rotate the actual document content, just the current view of it. + +| Input | Result | Any tool | +|:-|:-|:-:| +| **Alt Drag** | Tilt the canvas | | +| **Alt Middle-Click Drag**

**Alt Space Drag** | Tilt the canvas | ✓ | + +Hold Shift to snap to 15° increments while dragging. + +## Flipping + +Flipping reflects the entire canvas within the viewport. Like tilting, this does not affect the actual document content, and it can be toggled off anytime to return to the normal view. + +Use *View* > *Flip* to activate the reflected view mode. While active, an icon to un-flip appears beside the viewport zoom percentage at the right of the control bar. This works with any tool active. diff --git a/website/content/learn/tools/select.md b/website/content/learn/tools/select.md new file mode 100644 index 0000000000..6f5148d44b --- /dev/null +++ b/website/content/learn/tools/select.md @@ -0,0 +1,208 @@ ++++ +title = "Select tool" +template = "book.html" +page_template = "book.html" + +[extra] +order = 1 ++++ + +The **Select tool** is the primary tool for selecting and transforming content. It lets you pick layers, move them around, and resize, rotate, skew, and flip them using interactive bounding box handles or keyboard-driven transforms. Activate it by clicking its icon in the tool shelf or pressing V (for the letter's arrow shape that resembles the tool icon). + + + +## Tool options + +The tool's control bar across the top of the viewport provides controls that apply to the Select tool. + + + +### Selection mode + +The **selection mode** dropdown controls which layer gets chosen when you click on a stack of overlapping layers. + +| Mode | Behavior | +|:-|:-| +| **Shallow Select** | Clicking picks the shallowest (outermost) matching layer. Double-clicking drills down into the hierarchy one level at a time. Press ShiftEsc (or *Select* > *Select Parent* in the menu bar) to go back up one level to the parent. | +| **Deep Select** | Clicking immediately picks the deepest (innermost) layer beneath the cursor. | + +Regardless of mode, holding Ctrl (macOS: ⌘) while clicking always selects the deepest layer directly. + +### Pivot + +The **pivot** is the point in space used by the tools for rotation and scale manipulation. When enabled, it is visualized by a gizmo drawn at that point. Specifically, it is the center point for: + +- Rotating with the transform cage rotation handles +- Scaling with the transform cage edge/corner handles when Alt is held +- Rotating and scaling via the G/R/S keyboard-driven transforms + +It is important to understand that the pivot is purely a **tool-level concept**; it is not stored as part of the layer's data. When the pivot does not coincide with the layer's own local origin, the tool achieves the correct visual result by combining a rotation or scale with a compensating translation, so that the layer appears to transform around the pivot. The layer's actual transform (as seen in its Transform node) reflects only the net result of that math, not the pivot itself. Editing a layer's Transform node values directly always operates around the layer's own local origin, regardless of where the pivot gizmo is placed. + + + +The **pivot gizmo** checkbox toggles the on-canvas circle indicator. When disabled, the center of selection bounds is used as the pivot. When enabled, the **pivot type** dropdown chooses what determines the pivot's location: + +| Type | Meaning | +|:-|:-| +| **Custom Pivot** |

The pivot is a freely draggable point. Drag the on-canvas gizmo to place it anywhere. The **9-point reference grid** widget snaps it to one of nine reference positions on the bounding box: the four edge midpoints, the four corners, or the center.

By default the custom pivot is not persistent; it resets to the last-chosen reference point on the 9-point widget whenever the selection is replaced with a different set of layers. The **pin** button changes this behavior, keeping the pivot fixed at its current canvas position regardless of selection changes.

| +| **Origin (Average Point)** | The pivot is automatically placed at the average of all selected layers' origins. It cannot be moved manually. | +| **Origin (Active Object)** | The pivot is placed at the origin of the most recently selected layer. It cannot be moved manually. | + +### Alignment + +Six **alignment buttons** become active when two or more layers are selected: + + + +- Align left edges +- Align horizontal centers +- Align right edges +- Align top edges +- Align vertical centers +- Align bottom edges + +Each button aligns all selected layers relative to the combined bounding box of the entire selection. This means a center alignment, for example, places every object at the midpoint between the outermost edges of the whole group, not the center of any individual object. + +A useful consequence of this is a two-step technique for centering objects onto the largest one: first apply an edge alignment (e.g. align left edges), which collapses all objects so their edges coincide and shrinks the combined bounding box down to the size of the widest or tallest object. Then apply a center alignment; because the combined bounds now match the largest object, everything centers onto it rather than onto some point in empty space between them. + +To align the selected object(s) with an artboard, include the artboard in the selection by Ctrl-clicking (macOS: ⌘-clicking) the artboard in the Layers panel. + +### Flip and turn + +Two **flip buttons** mirror the selection horizontally or vertically. Two **turn buttons** rotate the selection by exactly −90° or +90°. Like alignment, both operations are performed relative to the combined bounding box of the entire selection, so all selected layers move together as a group rather than each being flipped or rotated independently in place. + +### Boolean operations + +Boolean operations combine or subtract the filled regions of vector shapes to produce new geometry. Five operations are available: + +| Operation | Result | +|:-|:-| +| **Union** | Merges all shapes into one, keeping the area covered by any of them. When applied to a single self-intersecting path, all enclosed regions are filled regardless of how many times the path winds over them. | +| **Subtract Front** | Removes the area of the frontmost shape from all shapes behind it. | +| **Subtract Back** | Removes the area of the backmost shape from all shapes in front of it. | +| **Intersect** | Keeps only the area where all shapes overlap, discarding everything else. | +| **Difference** | Keeps only the areas covered by an odd number of overlapping shapes. | + + + +**Union** and **Difference** are also useful when applied to a single self-intersecting path. Union fills every enclosed region regardless of winding, producing a fully solid shape. Difference applies the even-odd rule, alternating between filled and unfilled regions each time the path crosses itself, which can produce rings, cutouts, or other effects from a single complex path. + +Clicking a boolean operation button wraps the selected layers into a new group and adds a **Boolean Operation node** to that group's node graph. The operation is non-destructive; the original shapes remain intact inside the group and can be selected, moved, reshaped, or reordered at any time. The boolean result updates live as the contents change. + +If a group already has a Boolean Operation node applied, clicking any of the five buttons switches to that operation instead of creating a new one. This makes it easy to try each option to find the desired result. + +## Selecting layers + +### Clicking + +Click any unselected layer to select it and deselect everything else. The clicked layer gets highlighted with a bounding box. + +| Input | Result | +|:-|:-| +| **Click** | Select the layer under the cursor | +| **Shift Click** | Add/remove the clicked layer to/from the current selection | +| **Alt Click** | Remove the clicked layer from the current selection | +| **Ctrl Click
(macOS:
⌘ Click)** | If the [selection mode](#selection-mode) is set to the default *Shallow Select*, this overrides it and selects the most deeply-nested layer beneath the cursor for that click | +| **Double-Click** | If the [selection mode](#selection-mode) is set to the default *Shallow Select*, this drills down into the layer grouped within the current one | +| **Click an Empty Area** | Deselect everything; alternatively, CtrlShiftA (macOS: Shift⌘A) | + +### Box/lasso selection + +Drag on an empty area of the canvas to draw a rectangular selection box or freehand lasso shape. Releasing the mouse finalizes the selection. + +| Input | Result | +|:-|:-| +| **Drag** | Rectangular box select | +| **Ctrl Drag** | Draw a freehand **lasso** polygon instead of a rectangle | +| **Alt Drag** | Remove layers inside the box from the current selection | +| **Shift Drag** | Add layers inside the box to the current selection | + +Whether a layer must be fully enclosed by the selection area or merely touched by it is controlled by a preference in *File* > *Preferences* (macOS: *Graphite* > *Preferences*) under the **Selection** setting: + +| Mode | Behavior | +|:-|:-| +| **Touched** *(default)* | Selects any layer that the selection area touches or overlaps. | +| **Enclosed** | Selects only layers fully contained within the selection area. | +| **Directional** | Automatically chooses based on drag direction: dragging rightward uses *Enclosed*, dragging leftward uses *Touched*. | + + + + + + +## Transform cage + +Selected layers are surrounded by the **transform cage**: a bounding box with interactive handles for moving, resizing, rotating, skewing, and more. + + + +### Moving + +To move a layer, click and drag it. Or with an existing set of selected layers, drag any of them to move them in unison. When offset, a visualization displays the offset distance from the initial drag position. + +If the clickable area of the intended layer makes targeting difficult, the circular ring of the **transform dial** offers another method of dragging. It appears while placing your pointer within the transform cage and viewing it in a sufficiently zoomed viewport to fit the dial on screen. Red (X) and green (Y) arrows on the dial may also be dragged to translate the selection along the object's local axes. + + + +| Input | Result | +|:-|:-| +| **Drag** | Move freely | +| **Shift Drag** | Constrain movement to the horizontal or vertical axis, whichever is dominant | +| **Alt Drag** | Duplicate the selection and move the copy, leaving the original in place | + +When dragging with Alt held, a duplicate is created and moved instead of the original. While still dragging, pressing CtrlD (macOS: ⌘D) places copies at the current position. + +### Resizing + +Drag an **edge midpoint handle** or **corner handle** of the transform cage to resize the selection. + +| Input | Result | +|:-|:-| +| **Drag an Edge
or Corner Handle** | Resize the selected objects while the opposite edge or corner stays fixed | +| **Alt Drag** | Scale around the center or [pivot point](#pivot) instead of the opposite edge or corner | +| **Shift Drag** | Preserve the initial aspect ratio | + +### Rotating + +Hover just **outside** a transform cage corner until the pointer changes to a rotation cursor, then drag to rotate the selection around the pivot point. + +| Input | Result | +|:-|:-| +| **Drag** | Rotate freely | +| **Shift Drag** | Snap rotation to 15° angle multiples of the initial rotation | + +### Skewing + +**Skew handles** appear as small triangles on either side of each edge midpoint when the edge appears large enough on screen. Drag one to shear the selection along that edge. + + + +| Input | Result | +|:-|:-| +| **Drag a Skew
Triangle** | Skew along the dragged edge | +| **Ctrl Drag** | Allow free movement by dragging the edge anywhere | + +## Keyboard transforms (GRS) + +While the Select tool is active and layers are selected, pressing G (**grab**), R (**rotate**), or S (**scale**) begins a keyboard-driven transform. Moving the pointer then applies the transform interactively. + + + +## Nudging + +Arrow keys move or resize the selected layers in small increments without starting a drag. + +| Input | Result | +|:-|:-| +| **Arrows** | Move the selection by 1 px | +| **Shift Arrows** | Move the selection by 10 px | +| **Alt Arrows** | Resize the selection by moving the bottom/right edges of its bounding box | +| **CtrlAlt Arrows** | Resize the selection by moving the top/left edges of its bounding box | + +## Quick measurement + +Press and hold the Alt key anytime while hovering the pointer over an unselected layer to display the offset distances, in pixels, between the selection bounding box and that hovered layer's bounds. + + diff --git a/website/sass/base.scss b/website/sass/base.scss index 3ad0985807..1d97aa2bb5 100644 --- a/website/sass/base.scss +++ b/website/sass/base.scss @@ -516,6 +516,7 @@ table { thead:not(:has(tr th:not(:empty))) { th { padding: 0; + border-bottom: none; } + tbody tr:first-child td { @@ -523,9 +524,12 @@ table { } } - tr th, + tr th { + border-top: none; + } + tr:last-child td { - border: none; + border-bottom: none; } :is(h1, h2, h3, h4, h5, h6) + & {