Diagram - Drawing

#Usage

import { Diagram } from '@primeui/vue-diagram';
import DrawEllipse from './DrawEllipse.vue';

<Diagram.Root :store="store" page-id="page">
    <DrawEllipse />
    <Diagram.Viewport label="Workflow editor" style="height: 24rem" />
</Diagram.Root>

The destination layer must exist on the active page. Activate the tool from a mounted control, then draw in the viewport; cancelled previews do not change the model.

Create DrawEllipse.vue and mount it under the root as above. The handler reads the current session when activated, including after a page or source change.

<script setup lang="ts">
import { useDiagramContext } from '@primeui/vue-diagram';

const { session } = useDiagramContext();

function run() {
    session.value.setDrawingTool({ type: 'ellipse', layerId: 'layer' });
}
</script>

<template>
    <button type="button" @click="run">Draw ellipse</button>
</template>

This skeleton assumes an initialized store with page page. Use First Diagram for model creation, style imports and store disposal.

Drawing creates a node from a type and a destination. The pointer determines its size; release asks the drawing editor to commit one history step. A palette inserts predefined nodes or a captured graph, which is a separate workflow.

#Draw a shape or supply explicit bounds

Choose Rectangle, Ellipse or Diamond and select Draw on canvas. Drag empty canvas, then release. Press Escape before release to discard the preview. Insert 120 × 80 shape provides a keyboard/control alternative with explicit bounds through the same drawing editor (world and local coordinates coincide for this root-level example).

The following action reads the current session in a child component rendered inside Diagram.Root. In setup, context refs require .value.

import { useDiagramContext } from '@primeui/vue-diagram';

const { session } = useDiagramContext();

session.value.setDrawingTool({
    type: 'ellipse',
    layerId: 'layer',
    data: { title: 'Request' }
});

Drawing remains the active tool for repeated creation. Selecting Select or Pan, or setDrawingTool(null), leaves drawing mode. Changing the shape field in this example applies when you next choose Draw; it does not mutate an active preview.

The initial root/viewport needs no drawing module. Primitive geometry supports rectangle, ellipse and diamond; other types use registered node templates with the existing fallback behavior. A type name by itself does not register artwork or a notation's semantics.

#Keep destination rejection visible

The Request tray starts locked. Try drawing or explicit insertion into the tray, then unlock and retry. Its accepted children keep parentId: 'tray'; rejected creation does not change the saved node count.

Pointer start/end are world coordinates. The editor converts them to the destination parent's local bounds, including its rotation. Explicit drawing.execute(spec, bounds) and drawing.availability(spec, bounds) take node bounds already expressed in that parent's local space. Saved dimensions must pass the model and destination's minimum/containment rules.

Read-only, locked/hidden layers or owners, collapsed owners, another preview, pending proposals, invalid fits and unsupported structural destinations can reject creation. Use drawing.availability(spec, bounds) for an explicit request and inspect the returned result; availability does not guarantee a later commit against changed state. Controlled acknowledgement remains host-owned.

#Choose registered artwork

Choose Registered ticket or Rectangle task, select it, then duplicate or edit it. The ticket was created with createDiagramSymbolNode and resolved by the root's DiagramSymbolRegistry.

The current DiagramDrawingSpec has no symbol-reference or extensions member. Setting type: 'symbol' cannot by itself select registered artwork. Use Palette for new registered symbol insertion, or Symbols for typed symbol-node creation. For an application-specific node type, register a node template and draw that type; this does not turn it into a registry symbol. The example deliberately selects existing artwork rather than patching a primitive after drawing.

#Preview, cancellation and history

The portable drawing editor exposes begin, update, finish, cancel, availability and getSnapshot. A custom gesture owner uses the transaction ID returned by begin as its token. Preview is transient. Finish validates again and creates one transaction; Escape, lost capture or blur cancels the viewport's unfinished gesture. Drawing state reports idle/preview/pending/committed/cancelled/ rejected and a reason; it is not a saved node list.

After an accepted commit, Undo removes the created node through current policy. Reset remounts the example, restores the original model/history and resets its local controls. Native selects and text fields retain their keyboard behavior. For host-owned proposal handling, see Controlled state.

#Related Docs

• Palette
• Symbols
• Snapping
• Overlays