# Clipboard Support

Targetted for release in gEDA 1.8.0.

### Introduction

Currently, if you 'copy' in gschem and 'paste' in another program (or a different instance of gschem), nothing useful happens. We should ideally try and use the system clipboard to enable transparent copying and pasting of schematic data between multiple gschem windows as well as other programs.

It would be nice to be able to:

1. Copy in gschem, paste in text editor. Should it paste schematic file source code equivalent to copied elements?
2. Copy in gschem, paste in another instance of gschem. How should it handle differences in component library settings between programs?
3. Copy in gschem, paste in <program that understands images>. Should paste an image representation of the copied elements.

Consider the use case of "I want this circuit in my OpenOffice presentation, let's try the obvious thing to get it there."

### The X clipboard

The X window system uses the arcane "selection" protocol for copy/paste between X client applications. By taking charge of a "selection", an application is able to advertise a number of different datatypes, from which another application can request the most appropriate. Two selections are usually available:

1. The PRIMARY selection is customarily used to hold the last piece of text the user selected, and many programs paste its contents on middle-click.
2. The CLIPBOARD selection is customarily used with an application's "Copy", "Cut" and "Paste" actions.

Many desktop environments (including GNOME and KDE) run a "clipboard daemon", which copies the CLIPBOARD contents and makes it available even if the original application quits.

Due to the primarily non-textual nature of schematic or symbol data, gschem should use the CLIPBOARD on copy/paste, and ignore the SELECTION.

### The Windows clipboard

Research needed.

### GTK clipboard API

The Gimp Toolkit used by gschem's GUI provides APIs for manipulating the X selection (see the GTK manual). Since gschem already links against GTK, and the GTK clipboard API is considerably simpler than using low-level X library calls (as well as being more portable), gschem should make use of it.

### Buffers in gschem

gschem currently uses "buffers" to store cut or copied objects for pasting. A buffer is simply a GList of OBJECTs.

When a set of selected items is "copied":

1. Any existing items in the buffer are freed (the GList and OBJECTS destroyed).
2. The selection is recursively copied to the buffer.

When a set of selected items is "cut":

1. The copying procedure is followed.
2. All of the selected objects are deleted.

When a set of selected items is "pasted":

1. All the items in the buffer are copied into the schematic or symbol's GList, with an appropriate translation applied.

### Clipboard data types

#### Schematic/symbol data

Implemented in 1.5.2+.

On "copy to clipboard", gschem copies the selected objects to `GSCHEM_TOPLEVEL->clipboard_buffer`, gets control of the CLIPBOARD selection, and advertises `application/x-geda-schematic` data. On receiving a request, gschem uses `o_save_buffer()` to convert the selected objects to gEDA's on-disk schematic format for transmission.

On "paste from clipboard", gschem looks to see if the current owner of the CLIPBOARD selection is advertising `application/x-geda-schematic` data. If so, gschem requests the data, and uses `o_read_buffer()` to convert it to an object list, which it then enters the paste mode for.

To simplify the implementation, the first schematic data buffer is currently used as an intermediate store for clipboard data.

For the time being, it is assumed destination gschem instance has its library set up correctly -- i.e. no changes made to the embedding status of the data being sent before serialisation.