Control

Main controller class for managing annotations. It manages rendering and editing of annotations.

Extends

EventEmitter<FeatureEvents>

Constructors

Constructor

new Control(ogma, options): Control;

Parameters

ogma

Ogma

options

Partial<ControllerOptions> = {}

Returns

Control

Properties

prefixed

static prefixed: string | boolean;

Methods

add()

add(annotation): this;

Add an annotation to the controller

Parameters

annotation

The annotation to add

Annotation | AnnotationCollection

Returns

this

addListener()

addListener<T>(
   event, 
   fn, 
   context?): this;

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn

(...args) => void

context?

any

Returns

this

cancelDrawing()

cancelDrawing(): Control;

Cancel the current drawing operation

Returns

Control

this for chaining

canRedo()

canRedo(): boolean;

Check if there are changes to redo

Returns

boolean

true if redo is possible

canUndo()

canUndo(): boolean;

Check if there are changes to undo

Returns

boolean

true if undo is possible

clearHistory()

clearHistory(): void;

Clear the undo/redo history

Returns

void

destroy()

destroy(): void;

Destroy the controller and its elements

Returns

void

emit()

emit<T>(event, ...args): boolean;

Calls each of the listeners registered for a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

args

...ArgumentMap<FeatureEvents>[Extract<T, keyof FeatureEvents>]

Returns

boolean

enableArrowDrawing()

enableArrowDrawing(style?): this;

Enable arrow drawing mode - the recommended way to add arrows.

Call this method when the user clicks an "Add Arrow" button. The control will:

Wait for the next mousedown event
Create an arrow at that position with the specified style
Start the interactive drawing process
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startArrow() if you need to implement custom mouse handling or positioning logic.

Parameters

style?

Partial<ArrowStyles | undefined>

Arrow style options

Returns

this

this for chaining

Example

addArrowButton.addEventListener('click', () => {
  control.enableArrowDrawing({ strokeColor: '#3A03CF', strokeWidth: 2 });
});

See

startArrow for low-level programmatic control

enableBoxDrawing()

enableBoxDrawing(style?): this;

Enable box drawing mode - the recommended way to add boxes.

Call this method when the user clicks an "Add Box" button. The control will:

Wait for the next mousedown event
Create a box at that position with the specified style
Start the interactive drawing process (drag to size)
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startBox() if you need to implement custom mouse handling or positioning logic.

Parameters

style?

Partial<BoxStyle | undefined>

Box style options

Returns

this

this for chaining

Example

addBoxButton.addEventListener('click', () => {
  control.enableBoxDrawing({ background: '#EDE6FF', borderRadius: 8 });
});

See

startBox for low-level programmatic control

enableCommentDrawing()

enableCommentDrawing(options): this;

Enable comment drawing mode - the recommended way to add comments.

Call this method when the user clicks an "Add Comment" button. The control will:

Wait for the next mousedown event
Create a comment with an arrow pointing to that position
Smart positioning: automatically finds the best placement for the comment box
Start the interactive editing process
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startComment() if you need to implement custom mouse handling or positioning logic.

Parameters

options

Drawing options including offsets and styles

arrowStyle?

Partial<ArrowProperties>

Style options for the arrow

commentStyle?

Partial<CommentProps>

Style options for the comment box

offsetX?

number

Manual X offset for comment placement (overrides smart positioning)

offsetY?

number

Manual Y offset for comment placement (overrides smart positioning)

Returns

this

this for chaining

Example

addCommentButton.addEventListener('click', () => {
  control.enableCommentDrawing({
    commentStyle: { color: '#3A03CF', background: '#EDE6FF' },
    arrowStyle: { strokeColor: '#3A03CF', head: 'halo-dot' }
  });
});

See

startComment for low-level programmatic control

enablePolygonDrawing()

enablePolygonDrawing(style?): this;

Enable polygon drawing mode - the recommended way to add polygons.

Call this method when the user clicks an "Add Polygon" button. The control will:

Wait for the next mousedown event
Create a polygon starting at that position with the specified style
Start the interactive drawing process (click points to draw shape)
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startPolygon() if you need to implement custom mouse handling or positioning logic.

Parameters

style?

Partial<PolygonStyle | undefined>

Polygon style options

Returns

this

this for chaining

Example

addPolygonButton.addEventListener('click', () => {
  control.enablePolygonDrawing({ strokeColor: '#3A03CF', background: 'rgba(58, 3, 207, 0.15)' });
});

See

startPolygon for low-level programmatic control

enableTextDrawing()

enableTextDrawing(style?): this;

Enable text drawing mode - the recommended way to add text annotations.

Call this method when the user clicks an "Add Text" button. The control will:

Wait for the next mousedown event
Create a text box at that position with the specified style
Start the interactive drawing/editing process
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startText() if you need to implement custom mouse handling or positioning logic.

Parameters

style?

Partial<TextStyle | undefined>

Text style options

Returns

this

this for chaining

Example

addTextButton.addEventListener('click', () => {
  control.enableTextDrawing({ color: '#3A03CF', fontSize: 24 });
});

See

startText for low-level programmatic control

eventNames()

eventNames(): keyof FeatureEvents[];

Return an array listing the events for which the emitter has registered listeners.

Returns

keyof FeatureEvents[]

getAnnotation()

getAnnotation<T>(id): T | undefined;

Get a specific annotation by id

Type Parameters

T

T = Annotation

Parameters

id

Id

The id of the annotation to retrieve

Returns

T | undefined

The annotation with the given id, or undefined if not found

getAnnotations()

getAnnotations(): AnnotationCollection;

Get all annotations in the controller

Returns

AnnotationCollection

A FeatureCollection containing all annotations

getSelected()

getSelected(): Annotation | null;

Get the first selected annotation (for backwards compatibility)

Returns

Annotation | null

The currently selected annotation, or null if none selected

getSelectedAnnotations()

getSelectedAnnotations(): AnnotationCollection;

Get the currently selected annotations as a collection

Returns

AnnotationCollection

A FeatureCollection of selected annotations

isDrawing()

isDrawing(): boolean;

Returns

boolean

link()

Call Signature

link(
   arrowId, 
   targetNode, 
   side): this;

Attach an arrow to a node at the specified side

Parameters

arrowId

Id

targetNode

Node$1

side

Side

Returns

this

Call Signature

link(
   arrowId, 
   target, 
   side): this;

Attach an arrow to an annotation at the specified side

Parameters

Returns

this

listenerCount()

listenerCount(event): number;

Return the number of listeners listening to a given event.

Parameters

event

keyof FeatureEvents

Returns

number

listeners()

listeners<T>(event): (...args) => void[];

Return the listeners registered for a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

Returns

(...args) => void[]

off()

off<T>(
   event, 
   fn?, 
   context?, 
   once?): this;

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn?

(...args) => void

context?

any

once?

boolean

Returns

this

on()

on<T>(
   event, 
   fn, 
   context?): this;

Add a listener for a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn

(...args) => void

context?

any

Returns

this

once()

once<T>(
   event, 
   fn, 
   context?): this;

Add a one-time listener for a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn

(...args) => void

context?

any

Returns

this

redo()

redo(): boolean;

Redo the last undone change

Returns

boolean

true if redo was successful, false if no changes to redo

remove()

remove(annotation): this;

Remove an annotation or an array of annotations from the controller

Parameters

annotation

The annotation(s) to remove

Annotation | AnnotationCollection

Returns

this

removeAllListeners()

removeAllListeners(event?): this;

Remove all listeners, or those of the specified event.

Parameters

event?

keyof FeatureEvents

Returns

this

removeListener()

removeListener<T>(
   event, 
   fn?, 
   context?, 
   once?): this;

Remove the listeners of a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn?

(...args) => void

context?

any

once?

boolean

Returns

this

select()

select(annotations): this;

Select one or more annotations by id

Parameters

annotations

The id(s) of the annotation(s) to select

Id | Id[]

Returns

this

this for chaining

setOptions()

setOptions(options): object;

Set the options for the controller

Parameters

options

Partial<ControllerOptions> = {}

new Options

Returns

object

the updated options

detectMargin

detectMargin: number;

magnetHandleRadius

magnetHandleRadius: number;

magnetRadius

magnetRadius: number;

maxArrowHeight

maxArrowHeight: number;

minArrowHeight

minArrowHeight: number;

sendButtonIcon

sendButtonIcon: string;

showSendButton

showSendButton: boolean;

textPlaceholder

textPlaceholder: string;

setScale()

setScale(
   id, 
   scale, 
   ox, 
   oy): this;

Scale an annotation by a given factor around an origin point

Parameters

id

Id

The id of the annotation to scale

scale

number

The scale factor

ox

number

Origin x coordinate

oy

number

Origin y coordinate

Returns

this

this for chaining

startArrow()

startArrow(
   x, 
   y, 
   arrow?): Control;

Advanced API: Programmatically start drawing an arrow at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and optionally create the arrow object yourself.

For most use cases, use enableArrowDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate for the arrow start

y

number

Y coordinate for the arrow start

arrow?

Arrow

The arrow annotation to add (optional, will be created if not provided)

Returns

Control

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const arrow = createArrow(x, y, x, y, { strokeColor: '#3A03CF' });
  control.startArrow(x, y, arrow);
});

See

enableArrowDrawing for the recommended high-level API

startBox()

startBox(
   x, 
   y, 
   box?): Control;

Advanced API: Programmatically start drawing a box at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and optionally create the box object yourself.

For most use cases, use enableBoxDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate for the box origin

y

number

Y coordinate for the box origin

box?

Box

The box annotation to add (optional, will be created if not provided)

Returns

Control

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const box = createBox(x, y, 100, 50, { background: '#EDE6FF' });
  control.startBox(x, y, box);
});

See

enableBoxDrawing for the recommended high-level API

startComment()

startComment(
   x, 
   y, 
   comment, 
   options?): this;

Advanced API: Programmatically start drawing a comment at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and create the comment object yourself.

For most use cases, use enableCommentDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate to start drawing

y

number

Y coordinate to start drawing

comment

Comment

The comment annotation to add

options?

Drawing options including offsets and styles

arrowStyle?

Partial<ArrowProperties>

commentStyle?

Partial<CommentProps>

offsetX?

number

offsetY?

number

Returns

this

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const comment = createComment(x, y, 'My comment', { color: '#3A03CF' });
  control.startComment(x, y, comment);
});

See

enableCommentDrawing for the recommended high-level API

startPolygon()

startPolygon(
   x, 
   y, 
   polygon): this;

Advanced API: Programmatically start drawing a polygon at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and create the polygon object yourself.

For most use cases, use enablePolygonDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate to start drawing

y

number

Y coordinate to start drawing

polygon

Polygon

The polygon annotation to add

Returns

this

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const polygon = createPolygon([[[x, y]]], { strokeColor: '#3A03CF' });
  control.startPolygon(x, y, polygon);
});

See

enablePolygonDrawing for the recommended high-level API

startText()

startText(
   x, 
   y, 
   text?): Control;

Advanced API: Programmatically start drawing a text annotation at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and optionally create the text object yourself.

For most use cases, use enableTextDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate for the text

y

number

Y coordinate for the text

text?

Text

The text annotation to add (optional, will be created if not provided)

Returns

Control

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const text = createText(x, y, 0, 0, 'Hello', { color: '#3A03CF' });
  control.startText(x, y, text);
});

See

enableTextDrawing for the recommended high-level API

toggleComment()

toggleComment(id): this;

Toggle a comment between collapsed and expanded mode

Parameters

id

Id

The id of the comment to toggle

Returns

this

this for chaining

undo()

undo(): boolean;

Undo the last change

Returns

boolean

true if undo was successful, false if no changes to undo

unselect()

unselect(annotations?): this;

Unselect one or more annotations, or all if no ids provided

Parameters

annotations?

The id(s) of the annotation(s) to unselect, or undefined to unselect all

Id | Id[]

Returns

this

this for chaining

update()

update<A>(annotation): this;

Update an annotation with partial updates

This method allows you to update any properties of an annotation, including geometry, properties, and style. Updates are merged with existing data.

Type Parameters

A

A extends Annotation

Parameters

annotation

DeepPartial<A> & object

Partial annotation object with id and properties to update

Returns

this

this for chaining

Example

// Update arrow geometry
controller.update({
  id: arrowId,
  geometry: {
    type: 'LineString',
    coordinates: [[0, 0], [200, 200]]
  }
});

// Update text content and position
controller.update({
  id: textId,
  geometry: {
    type: 'Point',
    coordinates: [100, 100]
  },
  properties: {
    content: 'Updated text'
  }
});

// Update style only (prefer updateStyle for style-only updates)
controller.update({
  id: boxId,
  properties: {
    style: {
      background: '#ff0000'
    }
  }
});

updateStyle()

updateStyle<A>(id, style): this;

Update the style of the annotation with the given id

Type Parameters

A

A extends Annotation

Parameters

id

Id

The id of the annotation to update

style

A["properties"]["style"]

The new style

Returns

this

Events

Control ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

ogma ​

options ​

Returns ​

Properties ​

prefixed ​

Methods ​

add() ​

Parameters ​

annotation ​

Returns ​

addListener() ​

Type Parameters ​

T ​

Parameters ​

event ​

fn ​

context? ​

Returns ​

cancelDrawing() ​

Returns ​

canRedo() ​

Returns ​

canUndo() ​

Returns ​

clearHistory() ​

Returns ​

destroy() ​

Returns ​

emit() ​

Type Parameters ​

T ​

Parameters ​

event ​

args ​

Returns ​

enableArrowDrawing() ​

Parameters ​

style? ​

Returns ​

Example ​

See ​

enableBoxDrawing() ​

Parameters ​

style? ​

Returns ​

Example ​

See ​

enableCommentDrawing() ​

Parameters ​

options ​

arrowStyle? ​

commentStyle? ​

offsetX? ​

offsetY? ​

Returns ​

Example ​

See ​

enablePolygonDrawing() ​

Parameters ​

style? ​

Returns ​

Example ​

See ​

enableTextDrawing() ​

Parameters ​

style? ​

Returns ​

Example ​

See ​

eventNames() ​

Returns ​

getAnnotation() ​

Type Parameters ​

T ​

Control

Extends

Constructors

Constructor

Parameters

ogma

options

Returns

Properties

prefixed

Methods

add()

Parameters

annotation

Returns

addListener()

Type Parameters

T

Parameters

event

fn

context?

Returns

cancelDrawing()

Returns

canRedo()

Returns

canUndo()

Returns

clearHistory()

Returns

destroy()

Returns

emit()

Type Parameters

T

Parameters

event

args

Returns

enableArrowDrawing()

Parameters

style?

Returns

Example

See

enableBoxDrawing()

Parameters

style?

Returns

Example

See

enableCommentDrawing()

Parameters

options

arrowStyle?

commentStyle?

offsetX?

offsetY?

Returns

Example

See

enablePolygonDrawing()

Parameters

style?

Returns

Example

See

enableTextDrawing()

Parameters

style?

Returns

Example

See

eventNames()

Returns

getAnnotation()

Type Parameters

T

Parameters