Skip to main content

Crate bench_api

Crate bench_api 

Source
Expand description

What a WebAssembly workbench and printCAD say to each other.

The component interface (wit/workbench.wit) carries these types as JSON text; this crate is their one definition, used by the host (wb_wasm) and by the guest SDK. Ids (features, bodies) travel as UUID strings, lengths in millimetres, angles in degrees unless a field says otherwise, and every position is in world space.

§Versions

The crate’s major and minor version are the contract’s: 0.1.x speaks printcad:workbench@0.1. A patch release only adds, so a package written against an earlier 0.1.x keeps building and running:

  • Enums the host sends and a package matches on (Event, PanelEvent, MenuScope, PanelSlot, Button) are #[non_exhaustive], as are kernel_api’s FaceSurface and ProfileSegment: a match on them needs a wildcard arm, so a new variant does not break it, and binds a variant’s fields with .., so a new field does not either. (The exhaustive feature lifts this for printCAD itself, which makes every variant it sends; a package leaves it off.)
  • Structs a package fills in derive Default; fill them with ..Default::default() and a new field does not break the literal.
  • Struct-like variants a package builds (Widget, Request, Cell, DiagramShape, MarkKind, Plan, and kernel_api’s SolidOp and the enums inside it) never gain a field within a minor version: a new option comes as a new variant, or as a new struct that derives Default.
  • A field added to a struct carries #[serde(default)], so what an earlier package sends still reads.

A new minor version (0.2) is a new contract, which a host of 0.1 does not load.

Re-exports§

pub use kernel_api;

Modules§

calls
panel
The document commands a bench calls through host.call. Each is an ordinary recorded edit: one undo step per gesture, sent to peers. Functions building a declared panel’s blocks: layout, fields, words and colours, each a block with the common settings filled in and the rest at its default. The SDK re-exports them beside its section and item-list builders; printCAD’s own panels use them too.

Structs§

Action
Alert
A Widget::Alert: a note as Widget::Note draws it; with an id, a click on it comes back as PanelEvent::Button.
Badge
A glyph badge at an item’s end: a constraint on an element. A click comes back as PanelEvent::Badge.
Bind
A number field’s parameter: feature feature’s parameter key.
Body
BodyHistory
Callout
A note of a Widget::Diagram pointing at a feature of it: a dot at anchor, a leader to at, and text there.
Capabilities
What a package asks to reach beyond itself. The user grants each.
Caption
A Widget::Caption: words in the panel’s text size, or the small one, in a tone (Neutral is the panel’s secondary text, Muted dimmer still), or in the primary text colour.
Card
A Widget::Card: a raised card, its icon and title on the first line, then its children.
Cells
A Widget::Cells: children in rows of columns cells, left to right, each column as wide as its widest cell; rows sit close and columns a little apart. Column titles as strong captions, then a caption per reading, make a table that reads as the panel’s text.
Check
A Widget::Check: text beside its box, in its section’s label column under label when that is not empty. Told as PanelEvent::Toggle.
ColorField
A Widget::Color: a button showing color that opens the system’s colour picker; each change is PanelEvent::Color.
Command
CosmeticThread
A thread drawn on a round face, never modelled: the face keeps its size (a bore its tap drill, a shank its major diameter) and a helix of the thread’s pitch is drawn just off it, inside a bore and outside a shank, in every bench and never exported. A thread with a designation is also named where the app lists threads: a callout at the face’s end, the parts list, and a STEP export’s callouts.
Dimension
A measure of a Widget::Diagram: the distance from from to to, drawn as a dimension line offset away from them (to the left of the way from from to to; negative for the right), its ends led out to the points, with text on it.
EdgeCircle
A circular edge’s centre and axis (world space) and radius, mm.
EdgeRef
Entry
A Widget::Entry: told once typing ends (PanelEvent::Text).
Example
A working use of a command.
FaceLoops
What geom.face_loops answers.
FaceRef
FeatureInfo
How a feature shows in the tree, the property panel and the hover card.
FeatureStatus
How a feature’s work stands: a setup run, an operation checked.
FieldGrid
A Widget::Grid: two columns, a field’s label in the first and its control in the second, the column as wide as the grid’s longest label. A widget with no label takes one cell, so two of them make a row. Rows sit close, or a little apart when roomy.
Fields
A Widget::Fields: its fields’ labels in one column as wide as the longest, within the theme’s limits, apart from the section’s; or label_width wide.
FileKind
A kind of file a dialog offers: its label and extensions, without the dot.
FileToWrite
A file to write into the folder Request::SaveFiles asks for: a plain file name, no folder in it.
Fill
A Widget::Fill.
FilterField
A Widget::Filter: a search field narrowing the item lists that name it, by their label, secondary words and tags, and a kind selector when kinds names any (the first, “All” say, passes every item; the others pass items of that kind). The host filters as the user types; with by_bench it leaves the lists whole and tells the bench (PanelEvent::Filter) instead.
FloatingCard
A card over the view, next to what it edits: a quick edit of a value or two (a dimension, a corner’s size). Anything with more to it is a task in the right panel. The host draws widgets as it draws a task panel’s, with OK and Cancel under them; Enter is OK and Escape Cancel. OK and Cancel reach the bench as PanelEvent::CardClose. Edits wait in the bench until OK: the host makes what OK writes one undo step, and takes back anything written while the card was open on Cancel. A click in the view elsewhere is OK, while OK is allowed.
Flow
A Widget::Flow: side by side, going on to the next line when the panel is narrow unless no_wrap. A Widget::Fill among them takes what the others leave.
Frame
Everything a bench shows. The host keeps it and asks again only after an event reached the bench, the document changed, the selection changed, or the bench asked (redraw); world-space drawing is projected by the host every frame, so the view moves freely without asking.
Gallery
A Widget::Gallery: small square pictures side by side, going on to the next line, each over its name; the selected one ringed in the accent. A click is PanelEvent::Choice with the tile’s place.
Gap
A Widget::Gap.
Hud
Inline
A Widget::Inline.
Input
Something the user did while the bench is active, with what was under the cursor.
Item
One row of a list: what an ItemList holds, or alone as a Widget::Item.
ItemList
A Widget::Items: rows a click selects (PanelEvent::Select), or with multi a click with Ctrl adds to (PanelEvent::Selection), a double click opens (PanelEvent::Activate); the pointer over one is told as PanelEvent::Hover, so the bench lights it in the view.
KeptMesh
A kept mesh as a frame draws it: its handle and how.
Label
ListItem
LoopEdge
Manifest
bench.toml: what a package is and what it may reach.
Mark
MenuItem
Mesh
A mesh drawn in the scene, never picked.
Node
A feature of the document as a bench sees it.
OpenedFile
A file the user picked to open: its name, without the folder, and its bytes.
PanelAction
A small icon button: in a section’s title, on its own (Widget::Action: a cross at a row’s end that takes it out), or an entry of an item’s menu (label then names it). A click comes back as PanelEvent::Button (a section’s or one on its own) or PanelEvent::ContextMenu (a menu’s) with id.
PanelSection
A Widget::Section: a fold the user opens and closes, its title in small capitals, the count of what it holds, a one-line summary while closed, icon actions at its right end, and its children, whose fields share one label column.
Param
Parameter
A number of a feature that a formula may set.
PickChip
A Widget::PickChip: a click arms it (PanelEvent::Pick), its cross clears it (PanelEvent::Clear).
Picture
A picture a panel shows, as rows of sRGB pixels with their alpha. The host keeps it by key, so a picture shown again under the same key is not sent to the screen again: a key names one picture.
Plot
A Widget::Plot: lines along a strip height points tall, each series scaled to its own largest value, all on one x range from zero.
PlotSeries
A line of a Plot: its points as [x, y], in its tone.
Pointer
Where the cursor is and what it is over.
Polyline
A line through world points, drawn a constant width pixels wide over the scene.
Quantity
A Widget::Quantity: a number as a Widget::Number says it, with how it drags and how wide it is. Bound to a parameter (bind), it takes formulas as a bound Number does. Changes come back as PanelEvent::Number; a stepper’s buttons as the value one up or down.
Range
A Widget::Range: a slider over min to max, its value written beside it with decimals and suffix ( %); told as PanelEvent::Number.
Rebuild
One body’s plan.
RebuildRequest
The bodies to rebuild, each with its features of this bench in history order.
Region
A flat region in world space: an outline and the holes in it, all on one plane, filled and, with hatch, hatched in lines that far apart.
Registration
What a bench declares once, when it is loaded (describe).
RowButton
A Widget::RowButton: text at the left of a frameless button the panel’s width, told as PanelEvent::Button. The current one (where what the panel moves stands) is in the accent, strong, and takes no click.
Section
What geom.section answers.
SectionCurve
SectionLoop
Curves of a section end to end: closed round a solid’s cut, open where a sheet’s edge stops it.
Select
A Widget::Select: one of options, told as PanelEvent::Choice.
Selectable
A Widget::Selectable: words that light up while selected, told as PanelEvent::Button when clicked; a few in a Widget::Flow pick one of them.
SettingsGroup
A Widget::Settings: under its overline title (none when empty), a bordered group with one row per child, the child’s label at the left and its control at the right, a line between rows. A Widget::Hinted child’s hint shows under its label; a Widget::Check with no label is a switch, its text the label. The Preferences search narrows the rows by label and hint.
Stack
A Widget::Stack: its children the panel’s spacing apart, or close together when tight, as a task’s lines of text and fields sit.
Status
StatusLine
A Widget::Status, and a task header’s state (TaskHeader).
Stepper
A Quantity drawn as a stepper: text (the value when empty) between a down and an up button, each with its state and its words on hover.
Swatch
A colour of a Swatches block, as sRGB.
Swatches
A Widget::Swatches: small squares of colour, side by side and going on to the next line; a click is PanelEvent::Choice with the swatch’s place.
Tag
A small rounded name in an item’s row: an element a constraint ties. A click comes back as PanelEvent::Tag.
Task
TaskHeader
A Widget::TaskHeader: in a task’s panel, the header above it shows subtitle under the title and status as a pill beside it, as the app’s own tasks do; anywhere else they draw in the panel.
Tile
A choice of a Gallery: its picture over its name.
ToggleButton
One button of Toggles.
Toggles
A Widget::Toggles: icon buttons in a row under one label, each lit while on and its words shown on hover, the way an editor shows its alignment and wrapping. A click comes back as PanelEvent::Button with the button’s id; whether lighting one puts the others out is the bench’s to decide.
Tool
ToolHint
TriMesh
Triangular mesh generated from kernel bodies for viewports and export.
VertexRef
A vertex of a body’s solid, where it sits.

Enums§

Button
ButtonStyle
Cell
A cell of a Widget::Sheet.
DiagramShape
A shape of a Widget::Diagram, in its coordinates.
DiagramStroke
A line of a Widget::Diagram: what it stands for, not its colour, so the host draws it in the design’s own.
Dim
Event
FeatureState
GapSize
How much room a Widget::Gap leaves.
MarkKind
What a Mark draws.
MenuScope
NoteKind
PanelEvent
What the user did to a panel widget, by the widget’s id.
PanelSlot
Which declared panel an event came from.
ParamKind
Plan
What a Rebuild asks of the kernel.
Request
Something a bench asks the host to do once its call returns.
SolidOp
One step in a body’s build history. Shape-producing steps (Sweep, Loft, Pipe, Primitive) carry a BooleanOp; the remaining steps modify or combine the running solid directly.
Tone
How a mark, a tag or a status reads: what it means, not its colour.
ToolBehavior
Widget
One element of a declared panel. The host draws it with the app’s widgets and sends back a PanelEvent when the user changes it.

Constants§

API_VERSION
The version of this contract, as a package’s manifest names it in api. A host loads packages of its own major version.
CONTRACT_VERSION
The full version of the contract this build speaks, patch included: what a manifest’s min_contract is held against.
WIT
The component interface: the WIT world workbench of package printcad:workbench, whose values cross as JSON of this crate’s types.

Functions§

api_compatible
Whether a package built against api runs on this host.
contract_satisfies
Whether this build’s contract is at least min, a version such as 0.1.4 (a printcad:workbench@ prefix is read past). Only the numbers it names count, so 0.1 asks for any 0.1.x.
retain_widgets
widgets keeping only those keep holds to, at any depth: a widget left out goes with what it holds. A widget held alone (a hint’s, a fill’s) stays whatever keep says of it.
walk_widgets
Every widget of widgets, at any depth, each before its children.

Type Aliases§

Rgb
Linear RGB in 0..=1.