Canvas

Overview

The Canvas class represents a Pure Data patch’s visual canvas. It manages object creation, connections, selection, viewport, and rendering. Each canvas corresponds to one Pure Data patch (pd::Patch) and provides the interactive editing environment. Location: Source/Canvas.h and Source/Canvas.cpp

Class Hierarchy

class Canvas final : public Component
                   , public Value::Listener
                   , public SettingsFileListener
                   , public LassoSource<WeakReference<Component>>
                   , public ModifierKeyListener
                   , public pd::MessageListener
                   , public AsyncUpdater
                   , public NVGComponent
                   , public ChangeListener

Constructor

Canvas(PluginEditor* parent, pd::Patch::Ptr patch, Component* parentGraph = nullptr);

parent

PluginEditor*

The plugin editor that owns this canvas.

patch

pd::Patch::Ptr

The Pure Data patch this canvas represents.

parentGraph

Component*

default:"nullptr"

Optional parent graph component (for graph-on-parent subpatches).

Key Properties

editor

PluginEditor*

Parent plugin editor.

PluginProcessor*

Reference to the plugin processor/Pure Data instance.

patch

pd::Patch&

The underlying Pure Data patch.

viewport

std::unique_ptr<CanvasViewport>

Viewport for scrolling and zooming the canvas.

objects

PooledPtrArray<Object>

All objects on this canvas.

connections

PooledPtrArray<Connection>

All patch connections on this canvas.

selectedComponents

SelectedItemSet<WeakReference<Component>>

Currently selected objects and connections.

locked

Value

Whether the canvas is in locked (run) mode vs edit mode.

presentationMode

Value

Whether the canvas is in presentation mode (showing only GUI objects).

zoomScale

Value

Current zoom level (1.0 = 100%).

Object Management

synchronise

void

void synchronise();
void performSynchronise();
void synchroniseAllCanvases();

Synchronize the visual canvas with the underlying Pure Data patch structure. Called after patch modifications to update the GUI.

updateDrawables

void

void updateDrawables();

Update all drawable components on the canvas.

Selection and Editing

setSelected

void

void setSelected(Component* component, bool shouldNowBeSelected, 
                 bool updateCommandStatus = true, bool broadcastChange = true);

Select or deselect a component on the canvas.

deselectAll

void

void deselectAll(bool broadcastChange = true);

Clear all selections.

getSelectionOfType

SmallArray<T*>

template<typename T>
SmallArray<T*> getSelectionOfType();

Get all selected components of a specific type.Example:

auto selectedObjects = canvas->getSelectionOfType<Object>();
for (auto* obj : selectedObjects) {
    // Process each selected object
}

Clipboard Operations

copySelection

void

void copySelection();

Copy selected objects to clipboard.

pasteSelection

void

void pasteSelection();

Paste objects from clipboard.

duplicateSelection

void

void duplicateSelection();

Duplicate selected objects in place.

removeSelection

void

void removeSelection();
void removeSelectedConnections();

Delete selected objects or connections.

dragAndDropPaste

void

void dragAndDropPaste(String const& patchString, Point<int> mousePos, 
                      int patchWidth, int patchHeight, String const& name = String());

Paste objects at a specific position (used for drag-and-drop).

Advanced Editing

encapsulateSelection

void

void encapsulateSelection();

Wrap selected objects in a subpatch.

tidySelection

void

void tidySelection();

Auto-arrange selected objects neatly.

alignObjects

void

void alignObjects(Align alignment);

Align selected objects (left, right, top, bottom, center).

connectSelection

void

void connectSelection();

Auto-connect selected objects where possible.

Undo/Redo

undo

void

void undo();
void redo();

Undo or redo the last action on this canvas.

zoomToFitAll

void

void zoomToFitAll();

Zoom to fit all objects in the viewport.

jumpToOrigin

void

void jumpToOrigin();

Reset viewport to origin (0, 0).

saveViewportState

void

void saveViewportState();
void restoreViewportState();

Save and restore viewport position and zoom.

Rendering

performRender

void

void performRender(NVGcontext* nvg, Rectangle<int> invalidRegion);
void renderAllObjects(NVGcontext* nvg, Rectangle<int> area);
void renderAllConnections(NVGcontext* nvg, Rectangle<int> area);

Render the canvas using NanoVG. Called automatically by the rendering system.

Overlays and Display Options

shouldShowObjectActivity

bool

bool shouldShowObjectActivity() const;
bool shouldShowIndex() const;
bool shouldShowConnectionDirection() const;
bool shouldShowConnectionActivity() const;

Query current overlay display settings.

File Operations

save

void

void save(std::function<void()> const& nestedCallback = [] { });
void saveAs(std::function<void()> const& nestedCallback = [] { });

Save the patch to disk. Optionally provide a callback to execute after save completes.

Message Handling

receiveMessage

void

void receiveMessage(t_symbol* symbol, SmallArray<pd::Atom> const& atoms) override;

Receive messages from Pure Data (implements pd::MessageListener).

Suggestions and Autocomplete

showSuggestions

void

void showSuggestions(Object* object, TextEditor* textEditor);
void hideSuggestions();

Show or hide object name suggestions while typing.

Inspector Integration

getInspectorParameters

ObjectParameters&

ObjectParameters& getInspectorParameters();

Get parameters for the inspector panel.

Constants

infiniteCanvasSize

static constexpr int

Maximum canvas size: 128,000 pixels

Usage Example

// Create a canvas for a patch
auto patch = pd->openPatch(File("/path/to/patch.pd"));
auto* canvas = new Canvas(editor, patch);

// Lock/unlock the canvas
canvas->locked.setValue(true);  // Lock (run mode)
canvas->locked.setValue(false); // Unlock (edit mode)

// Work with selections
canvas->selectAll();
auto selectedObjs = canvas->getSelectionOfType<Object>();
canvas->alignObjects(Align::Left);
canvas->tidySelection();

// Clipboard operations
canvas->copySelection();
canvas->pasteSelection();

// Viewport control
canvas->zoomToFitAll();
canvas->saveViewportState();

// Undo/redo
canvas->undo();
canvas->redo();

// Save the patch
canvas->save([](){ 
    DBG("Save complete!"); 
});

Plugin Objects

Core Classes

Overview

Class Hierarchy

Constructor

Key Properties

Object Management

Selection and Editing

Clipboard Operations

Advanced Editing

Undo/Redo

Viewport and Navigation

Rendering

Overlays and Display Options

File Operations

Message Handling

Suggestions and Autocomplete

Inspector Integration

Constants

Usage Example

See Also

Build docs developers (and LLMs) love

Plugin Objects

Core Classes

​Overview

​Class Hierarchy

​Constructor

​Key Properties

​Object Management

​Selection and Editing

​Clipboard Operations

​Advanced Editing

​Undo/Redo

​Viewport and Navigation

​Rendering

​Overlays and Display Options

​File Operations

​Message Handling

​Suggestions and Autocomplete

​Inspector Integration

​Constants

​Usage Example

​See Also

Build docs developers (and LLMs) love

Overview

Class Hierarchy

Constructor

Key Properties

Object Management

Selection and Editing

Clipboard Operations

Advanced Editing

Undo/Redo

Viewport and Navigation

Rendering

Overlays and Display Options

File Operations

Message Handling

Suggestions and Autocomplete

Inspector Integration

Constants

Usage Example

See Also