Vocabulary

The API uses a small set of nouns and verbs, and the same word always means the same thing. Once you know them, most calls read like a sentence:

import 'package:vyuh_diagram_flutter/extension_api.dart';
import 'package:vyuh_diagram_flutter/vyuh_diagram_flutter.dart';

final service = ShapeDefinition.labeled(
  'acme.service',
  name: 'Service',
  size: const DiagramSize(180, 100),
);

final controller = DiagramController(
  configuration: DiagramConfiguration(
    extensions: [
      DiagramExtension(
        id: 'library.acme',
        shapes: [service],
        tools: DiagramToolDefinition.forShapes([service], group: 'acme'),
      ),
    ],
  ),
);

final api = controller.createShape('acme.service', at: DiagramPoint.zero);
final db = controller.createShape('acme.service', at: const DiagramPoint(300, 0));
controller.connect(api, db);
controller.move(const DiagramPoint(0, 40), ids: [db]);
controller.select([api, db]);

Nouns

Word	Meaning
Document	The saved content: shapes, text and connectors. It never changes in place.
Diagram	The shared, committed document with its one undo history, installed extensions and rules.
Controller	One actor editing a diagram, with its own selection, tool and camera. Every change goes through a controller.
Canvas	The Flutter widget that shows a controller's diagram; with the editor installed, people edit it there.
View	The visible part of a mounted canvas; controller.view moves it.
Effects	Short-lived visuals on a canvas, such as a flowing path; controller.effects plays them.
Element	Anything in a document: a shape, standalone text or a connector.
Shape	An element with a registered type, a frame and optional text.
Connector	An element joining two endpoints, optionally through ports, along a route.
Port	A named attachment point declared on a shape.
Route	How a connector's path is drawn: straight, orthogonal (elbow), quadratic or Bezier.
Label	Text owned by a connector.
Definition	Describes one shape type as its anatomy: outline, body, values, connection and behavior, plus its size and style.
Library	A named set of definitions you can install together.
Extension	A bundle of definitions, tools and behavior, installed in the configuration's extensions list. It brings its own configuration.
Options	An extension's runtime configuration, such as the grid's GridOptions, read with controller.options<T>() and changed with controller.setOptions.
Rules	The application's decisions about which changes, creations and connections to admit (DiagramRules).
Theme	Colors and styles for a canvas and the chrome around it.
Batch	Several verbs made one atomic, undoable change with controller.batch.
Verb	A named, typed edit, performed with controller.perform(ids, name, args) or a typed method such as controller.move. See verbs.
Result	The EditResult returned by calls through controller.edits: allowed, or denied with a code and reason; a creating verb's new ID is its id.
View state	Selection, camera, tool and extension options: state that is not document content, changed through plain controller methods such as select, setCamera, setTool and setOptions, which are not undoable.
Interaction	A continuous edit, such as a slider drag, started with controller.beginInteraction.

Shape anatomy

A shape definition is made of these parts. See shape anatomy.

Word	Meaning
Outline	The shape's own surface: the contour it paints, hit-tests and attaches connectors to. A shape without one paints no surface of its own.
Body	The parts laid out inside or beside the outline.
Part	One piece of a body: a layout part (row, column, stack, sized, padding, outside) or a leaf (text, surface, divider, image, widget or content such as a table).
Slot	The name of a text part; text in a shape's story belongs to a slot, such as title or body.
Surface	A painted region inside the body with its own outline and fixed style, or an unpainted interactive area.
Values	An instance's typed data, declared by value fields: a path, an image, a polygon's sides or a domain field.
Adjustment	An on-canvas handle bound to a numeric value.
Container	A shape that owns child elements, and may clip or scale them.
Behavior	What a person may do to a shape: select, move, resize, rotate, delete and edit its text.
Layers	What a body compiles to, in paint order; read by renderers, never authored.

Verbs

Verb	Meaning
create…	Make a new element of a registered type, starting from its definition's size, style and text.
add	Insert an element you built yourself, exactly as given.
connect	Join two elements with a new connector.
move, resize, rotate, reparent, delete	Change or delete the elements you name, together with what they contain.
select	Choose what is selected. Selection is not a verb and not part of undo history.
set…	Replace one setting, such as setLocked, setStyle or setConnectorRoute. Performing it with the previous value reverses it.
reroute, layout, align, distribute	Compute new positions or paths for many elements at once.
show	Move the view to a target.
play	Start an effect.

Conventions

• Methods do not repeat what the receiver already says: a controller moves elements with controller.move(delta, ids: …).
• A parameter has the same name everywhere: at for where a new element is centred, from and to for a connection's ends, fromPort and toPort for its ports, route for its route, and name, size, style and connection on every definition.
• Verbs read the same inside and outside a batch, so controller.createShape(type, at: …) and controller.connect(from, to) are the same calls either way.
• Calls through controller.edits return an EditResult; call requireAllowed() to turn a refusal into an exception.
• There are no toggles: a control that toggles performs the setter with the opposite value, such as setLocked(!locked, ids: ids). Undo is history, not a reverse verb.
• Each setting has one place to set it. A canvas theme, for example, is set on DiagramCanvas(theme: …) or on the app's Theme, and the grid only through GridExtension and its GridOptions.