gum-tool-copy-paste

# Gum Copy/Paste Reference

## In-Memory, Not System Clipboard

Gum's copy/paste does **not** use the system clipboard. Copied data lives in `CopyPasteLogic.CopiedData` (an in-memory instance). `MonoGameGum/Clipboard/ClipboardImplementation.cs` is a separate text-only clipboard used elsewhere in the app — not part of this system.

## CopyType Dispatch

`CopyType` drives the entire operation:
- `InstanceOrElement` — copies selected instances within an element, or a whole element if nothing is selected
- `State` — copies the selected state within a state category

Copy, cut, and paste each accept a `CopyType` parameter and bail out early if it doesn't match what's stored.

## TopOrRecursive

Paste offers two modes: `Recursive` (instances + all descendants) vs `Top` (only top-level instances). The UI exposes both as separate "Paste" and "Paste Top Level Instance(s)" menu items.

## Cut Is Immediate

Cut calls `StoreCopiedObject()` (same as copy) then immediately deletes the source instances via `IDeleteLogic.RemoveInstance()`. The deletion happens at cut time, not deferred to paste. This means cutting and then not pasting still destroys the original.

## Multi-Paste Selection Tracking

`_hasChangedSelectionSinceCopy` is the key flag for multi-paste behavior. It starts `false` after a copy and flips `true` when `SelectionChangedMessage` fires (unless the selection change was triggered by the paste itself — `isSelectionCausedByPaste` guards against that false-positive).

During paste, this flag drives parent assignment:
- `false` — re-use the parent from `lastPasteOriginalToParentAssociation` (repeat-paste to same location)
- `true` — attach to current selection (user moved to a new target)

## Paste Creates New Instances, Does Not Clone

`PasteInstanceSaves()` creates fresh `InstanceSave` objects and assigns properties from the copied states. It does **not** simply clone the stored instances. Name uniqueness is enforced via `StringFunctions.MakeStringUnique()`, and an `oldNewNameDictionary` is built to remap parent references throughout the copied hierarchy.

## Undo Integration

Only paste acquires an undo lock (`_undoManager.RequestLock()`). The entire paste — all instances, state variable copies, parent assignments — records as a single undo action. Cut's deletion goes through `IDeleteLogic.RemoveInstance()` which handles its own undo internally.

## State Paste Validation

Pasting a state runs `ValidateStatePaste()` first. It checks that all variables in the copied state exist in the target category and are supported by the target element. Paste is silently blocked (or shows a dialog) if incompatible.

## Plugin Hook

`PluginManager.InstanceAdd()` is called for each newly pasted instance, allowing plugins to react to paste-created instances the same way they react to manually added ones.

## Animation Copy/Paste

`AnimationCopyPasteManager.cs` is a **separate, independent** copy/paste system for animations. It has its own `CopiedData` class, stores a single `AnimationViewModel`, and does not interact with `CopyPasteLogic`.

## Entry Points

All copy/paste is triggered through:
- `HotkeyManager` — routes `Ctrl+C / Ctrl+X / Ctrl+V` → `ICopyPasteLogic.OnCopy / OnCut / OnPaste`
- `ElementTreeViewManager.RightClick` — right-click context menu items

Do not call `CopyPasteLogic` methods directly from outside these entry points.

## Key Files

| File | Purpose |
|------|---------|
| `Gum/Logic/CopyPasteLogic.cs` | All copy/paste orchestration; `CopiedData` nested class defined here |
| `Gum/Logic/ICopyPasteLogic.cs` | Interface |
| `Gum/Commands/EditCommands.cs` | Thin wrappers that delegate to `ICopyPasteLogic` |
| `Gum/Managers/HotkeyManager.cs` | Keyboard entry point |
| `Gum/Plugins/InternalPlugins/TreeView/ElementTreeViewManager.RightClick.cs` | Context menu entry point |
| `Gum/StateAnimationPlugin/Managers/AnimationCopyPasteManager.cs` | Separate animation copy/paste |
| `Tool/Tests/GumToolUnitTests/Logic/CopyPasteLogicTests.cs` | Unit tests |