Clipboard

Clipboard implements the ability to copy and paste cells. It extends mvc.Collection.

Learn more about the Clipboard plugin.

constructor

constructor(opt?: Clipboard.Options);

The Clipboard constructor accepts several parameters:

addCellOptions

[optional] Options that will be passed to the graph.addCell() method during paste operations (pasteCells(), pasteCellsAtPoint()).

cloneCells()

cloneCells: (cells: Array<dia.Cell>) => Array<dia.Cell>;

[optional] A callback function that is called whenever the clipboard needs a copy of the cells (copyElements(), cutElements()).

The function is expected to return an array of copied cells. An error is thrown when this is not the case: ui.Clipboard: the `cloneCells` function must return an array of cells.'

The function can be used to update the copied cells with additional information. For example, you can add a reference to the original cell to the copied cell.

const clipboard = new ui.Clipboard({
  cloneCells: (cells) => {
    const clonesMap = util.cloneCells(cells);
    const clones = Object.values(clonesMap);
    /* update the clones using the references to the original cell */
    cells.forEach(cell => {
       clonesMap[cell.id].set('originalId', cell.get('originalId') || cell.id);
    });
    return clones;
  }
});

deep

[optional] Set to true if you want the clipboard to automatically add all cells embedded to the provided cells when copying or cutting. It defaults to false.

link

[optional] An object specifying attributes to be set on each copied link on every pasteCells() or pasteCellsAtPoint() call, e.g. { z: 1 }.

origin

[optional] The position in a cell's bbox which is used for determining the origin on every pasteCellsAtPoint() call. It is a string representing bbox positions (e.g. 'top-left', 'bottom' etc.). It defaults to 'center'.

removeCellOptions

[optional] Options that will be passed to the cell.remove() method during the cut operation.

translate

[optional] An object with dx and dy attributes which specify the increments that should be added to the x and y position of pasted elements on every pasteCells() call. It defaults to { dx: 20, dy: 20 }.

useLocalStorage

[optional] Set to false if you don't want to use window.localStorage for storing copied cells. It defaults to true.

Methods

clear()

clipboard.clear(opt?: Clipboard.BaseOptions): void;

Clear all stored cells. Also clears window.localStorage if useLocalStorage is true.

The opt object allows you to override global options.

copyElements()

clipboard.copyElements(
    selection: mvc.Collection<dia.Cell> | Array<dia.Cell>,
    graph: dia.Graph,
    opt?: Clipboard.BaseOptions
): Array<dia.Cell>;

Store the elements from the selection, plus all links which are connected by both source and target to these elements.

The selection can either be an mvc.Collection or an array of cells.

The opt object allows you to override global options.

cutElements()

clipboard.cutElements(
    selection: mvc.Collection<dia.Cell> | Array<dia.Cell>,
    graph: dia.Graph,
    opt?: Clipboard.CutElementsOptions
): Array<dia.Cell>;

Similar to copyElements() but it also removes all copied cells from the graph.

fetchCellsFromLocalStorage()

clipboard.fetchCellsFromLocalStorage(cellNamespace: any): dia.Cell[];

Fetch the cells from window.localStorage and return them as an array of cells.

isEmpty()

clipboard.isEmpty(opt?: Clipboard.BaseOptions): boolean;

Return true when no cells are stored on the Clipboard instance. Also checks window.localStorage if useLocalStorage is true, and returns true only if no cells are stored there either.

Return false otherwise.

pasteCells()

clipboard.pasteCells(
    graph: dia.Graph,
    opt?: Clipboard.PasteCellsOptions
): Array<dia.Cell>;

Add copies of stored cells to the graph. The method can be called multiple times, and it always produces new copies.

The opt object allows you to override the global options (e.g. translate).

pasteCellsAtPoint()

clipboard.pasteCellsAtPoint(
    graph: dia.Graph,
    point: dia.Point,
    opt?: Clipboard.PasteCellsAtPointOptions
): Array<dia.Cell>;

Add copies of stored cells to the graph at a specific point, specified as an object with x and y attributes. The method can be called multiple times, and it always produces new copies.

The opt object allows you to override the global options (e.g. origin).

saveToLocalStorage()

clipboard.saveToLocalStorage(): void;

Store the the current cells to window.localStorage.

Types

BaseOptions

interface BaseOptions {
    useLocalStorage?: boolean;
    deep?: boolean;
    [key: string]: any;
}

CutElementsOptions

interface CutElementsOptions extends BaseOptions {
    removeCellOptions?: dia.Cell.DisconnectableOptions;
}

Options

interface Options extends BaseOptions {
    link?: { [key: string]: any };
    origin?: dia.PositionName;
    translate?: { dx: number, dy: number };
    removeCellOptions?: dia.Cell.DisconnectableOptions;
    addCellOptions?: dia.CollectionAddOptions;
    cloneCells?: (cells: Array<dia.Cell>) => Array<dia.Cell>;
}

PasteCellsOptions

interface PasteCellsOptions extends BaseOptions {
    translate?: { dx: number, dy: number };
    link?: { [key: string]: any };
    addCellOptions?: dia.CollectionAddOptions;
}

PasteCellsAtPointOptions

interface PasteCellsAtPointOptions extends BaseOptions {
    origin?: dia.PositionName;
    link?: { [key: string]: any };
    addCellOptions?: dia.CollectionAddOptions;
}