docs/wiki/geda-wip-clipboard.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <h1 class="sectionedit1" id="clipboard_support">Clipboard Support</h1>
  14 <div class="level1">
  15
  16 <p>
  17 Targetted for release in gEDA 1.8.0.
  18 </p>
  19
  20 </div>
  21 <!-- EDIT1 SECTION "Clipboard Support" [1-71] -->
  22 <h3 class="sectionedit2" id="introduction">Introduction</h3>
  23 <div class="level3">
  24
  25 <p>
  26 Currently, if you &#039;copy&#039; in gschem and &#039;paste&#039; 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.
  27 </p>
  28
  29 <p>
  30 It would be nice to be able to:
  31 </p>
  32 <ol>
  33 <li class="level1"><div class="li"> Copy in gschem, paste in text editor. Should it paste schematic file source code equivalent to copied elements?</div>
  34 </li>
  35 <li class="level1"><div class="li"> Copy in gschem, paste in another instance of gschem. How should it handle differences in component library settings between programs?</div>
  36 </li>
  37 <li class="level1"><div class="li"> Copy in gschem, paste in &lt;program that understands images&gt;. Should paste an image representation of the copied elements.</div>
  38 </li>
  39 </ol>
  40
  41 <p>
  42 Consider the use case of “I want this circuit in my OpenOffice presentation, let&#039;s try the obvious thing to get it there.”
  43 </p>
  44
  45 </div>
  46 <!-- EDIT2 SECTION "Introduction" [72-930] -->
  47 <h3 class="sectionedit3" id="the_x_clipboard">The X clipboard</h3>
  48 <div class="level3">
  49
  50 <p>
  51 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:
  52 </p>
  53 <ol>
  54 <li class="level1"><div class="li"> 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.</div>
  55 </li>
  56 <li class="level1"><div class="li"> The CLIPBOARD selection is customarily used with an application&#039;s “Copy”, “Cut” and “Paste” actions.</div>
  57 </li>
  58 </ol>
  59
  60 <p>
  61 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.
  62 </p>
  63
  64 <p>
  65 Due to the primarily non-textual nature of schematic or symbol data, gschem should use the CLIPBOARD on copy/paste, and ignore the SELECTION.
  66 </p>
  67
  68 </div>
  69 <!-- EDIT3 SECTION "The X clipboard" [931-1845] -->
  70 <h3 class="sectionedit4" id="the_windows_clipboard">The Windows clipboard</h3>
  71 <div class="level3">
  72
  73 <p>
  74 Research needed.
  75 </p>
  76
  77 </div>
  78 <!-- EDIT4 SECTION "The Windows clipboard" [1846-1896] -->
  79 <h3 class="sectionedit5" id="gtk_clipboard_api">GTK clipboard API</h3>
  80 <div class="level3">
  81
  82 <p>
  83 The Gimp Toolkit used by gschem&#039;s <abbr title="Graphical User Interface">GUI</abbr> provides APIs for manipulating the X selection (see <a href="https://developer.gnome.org/gtk2/2.24/gtk2-Clipboards.html" class="urlextern" title="https://developer.gnome.org/gtk2/2.24/gtk2-Clipboards.html" rel="nofollow">the GTK manual</a>). Since gschem already links against GTK, and the GTK clipboard <abbr title="Application Programming Interface">API</abbr> is considerably simpler than using low-level X library calls (as well as being more portable), gschem should make use of it.
  84 </p>
  85
  86 </div>
  87 <!-- EDIT5 SECTION "GTK clipboard API" [1897-2287] -->
  88 <h3 class="sectionedit6" id="buffers_in_gschem">Buffers in gschem</h3>
  89 <div class="level3">
  90
  91 <p>
  92 gschem currently uses “buffers” to store cut or copied objects for pasting. A buffer is simply a GList of OBJECTs.
  93 </p>
  94
  95 <p>
  96 When a set of selected items is “copied”:
  97 </p>
  98 <ol>
  99 <li class="level1"><div class="li"> Any existing items in the buffer are freed (the GList and OBJECTS destroyed).</div>
 100 </li>
 101 <li class="level1"><div class="li"> The selection is recursively copied to the buffer.</div>
 102 </li>
 103 </ol>
 104
 105 <p>
 106 When a set of selected items is “cut”:
 107 </p>
 108 <ol>
 109 <li class="level1"><div class="li"> The copying procedure is followed.</div>
 110 </li>
 111 <li class="level1"><div class="li"> All of the selected objects are deleted.</div>
 112 </li>
 113 </ol>
 114
 115 <p>
 116 When a set of selected items is “pasted”:
 117 </p>
 118 <ol>
 119 <li class="level1"><div class="li"> All the items in the buffer are copied into the schematic or symbol&#039;s GList, with an appropriate translation applied.</div>
 120 </li>
 121 </ol>
 122
 123 </div>
 124 <!-- EDIT6 SECTION "Buffers in gschem" [2288-2907] -->
 125 <h3 class="sectionedit7" id="clipboard_data_types">Clipboard data types</h3>
 126 <div class="level3">
 127
 128 </div>
 129
 130 <h4 id="schematic_symbol_data">Schematic/symbol data</h4>
 131 <div class="level4">
 132
 133 <p>
 134 <a href="http://git.geda-project.org/geda-gaf/commit/?id=6a07d737a32a816f43e1f061409a10e616d7aa2a" class="urlextern" title="http://git.geda-project.org/geda-gaf/commit/?id=6a07d737a32a816f43e1f061409a10e616d7aa2a" rel="nofollow"> Implemented in 1.5.2+</a>.
 135 </p>
 136
 137 <p>
 138 On “copy to clipboard”, gschem copies the selected objects to <code>GSCHEM_TOPLEVEL→clipboard_buffer</code>, gets control of the CLIPBOARD selection, and advertises <code>application/x-geda-schematic</code> data. On receiving a request, gschem uses <code>o_save_buffer()</code> to convert the selected objects to gEDA&#039;s on-disk schematic format for transmission.
 139 </p>
 140
 141 <p>
 142 On “paste from clipboard”, gschem looks to see if the current owner of the CLIPBOARD selection is advertising <code>application/x-geda-schematic</code> data. If so, gschem requests the data, and uses <code>o_read_buffer()</code> to convert it to an object list, which it then enters the paste mode for.
 143 </p>
 144
 145 <p>
 146 To simplify the implementation, the first schematic data buffer is currently used as an intermediate store for clipboard data.
 147 </p>
 148
 149 <p>
 150 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.
 151 </p>
 152
 153 </div>
 154 <!-- EDIT7 SECTION "Clipboard data types" [2908-] --></body>
 155 </html>