A Clipboard is created using the constructor:

  clipboard = gtk.Clipboard(display, selection)

where display is the gtk.gdk.Display associated with the Clipboard named by selection. The following convenience function creates a Clipboard using the default gtk.gdk.Display:

  clipboard = gtk.clipboard_get(selection)

Finally, a Clipboard can also be created using the Widget method:

  clipboard = widget.get_clipboard(selection)

The widget must be realized and be part of a toplevel window hierarchy.

Entry, SpinButton and TextView widgets have popup menus that provide the ability to cut and copy the selected text to and paste from the "CLIPBOARD" clipboard. In addition key bindings are set to allow keyboard accelerators to cut, copy and paste. Cut is activated by Control+X; copy, by Control+C; and, paste, by Control+V.

The widgets (Entry and SpinButton) implement the Editable interface that has the following methods to cut, copy and paste to and from the "CLIPBOARD" clipboard:

  editable.cut_clipboard()
  editable.copy_clipboard()
  editable.paste_clipboard()

A Label that is selectable (the "selectable" property is TRUE) also supports copying the selected text to the "CLIPBOARD" clipboard using a popup menu or the Control+C keyboard accelerator.

TextBuffers have similar methods though they also allow specifying the clipboard to use:

  textbuffer.copy_clipboard(clipboard)

The selection text will be copied to the Clipboard specified by clipboard.

  textbuffer.cut_clipboard(clipboard, default_editable)

The selected text will be copied to clipboard. If default_editable is TRUE the selected text will also be deleted from the TextBuffer. Otherwise, cut_clipboard() will act like the copy_clipboard() method.

  textbuffer.paste_clipboard(clipboard, override_location, default_editable)

If default_editable is TRUE, the contents of clipboard will be inserted into the TextBuffer at the location specified by the TextIter override_location. If default_editable is FALSE, paste_clipboard() will not insert the contents of clipboard. If override_location is None the contents of clipboard will be inserted at the cursor location.

TextBuffers also have two methods to manage a set of Clipboards that are automatically set with the contents of the current selection:

  textbuffer.add_selection_clipboard(clipboard)
  textbuffer.remove_selection_clipboard(clipboard)

When a TextBuffer is added to a TextView the "PRIMARY" clipboard is automatically added to the selection clipboards. Your application can add other clipboards (for example, the "CLIPBOARD" clipboard).

You can set the Clipboard data programmatically using either of:

  clipboard.set_with_data(targets, get_func, clear_func, user_data)

  clipboard.set_text(text, len=-1)

The set_with_data() method indicates which selection data targets are supported and provides functions (get_func and clear_func) that are called when the data is asked for or the clipboard data is changed. user_data is passed to get_func or clear_func when called. targets is a list of 3-tuples containing:

The signatures of get_func and clear_func are:

  def get_func(clipboard, selectiondata, info, data):

  def clear_func(clipboard, data):

where clipboard is the Clipboard, selectiondata is a SelectionData object to set the data in, info is the application assigned integer associated with a target, and data is user_data.

set_text() is a convenience method that uses the set_with_data() method to set text data on a Clipboard with the targets: "STRING", "TEXT", "COMPOUND_TEXT", and "UTF8_STRING". It uses internal get and clear functions to manage the data. set_text() is equivalent to the following:

  def my_set_text(self, text, len=-1):
      targets = [ ("STRING", 0, 0),
                  ("TEXT", 0, 1),
                  ("COMPOUND_TEXT", 0, 2),
                  ("UTF8_STRING", 0, 3) ]
      def text_get_func(clipboard, selectiondata, info, data):
          selectiondata.set_text(data)
          return
      def text_clear_func(clipboard, data):
          del data
          return
      self.set_with_data(targets, text_get_func, text_clear_func, text)
      return

Once data is set on a clipboard, it will be available until the application is finished or the clipboard data is changed.

To provide the behavior typical of cut to a clipboard, your application will have to delete the selected text or object after copying it to the clipboard.

The contents of a Clipboard can be retrieved using the following method:

  clipboard.request_contents(target, callback, user_data=None)

The contents specified by target are retrieved asynchronously in the function specified by callback which is called with user_data. The signature of callback is:

  def callback(clipboard, selectiondata, data):

where selectiondata is a SelectionData object containing the contents of clipboard. data is user_data. The request_contents() method is the most general way of retrieving the contents of a Clipboard. The following convenience method retrieves the text contents of a Clipboard:

  clipboard.request_text(callback, user_data=None)

The text string is returned to the callback function instead of a Selectiondata object. You can check which targets are available on the Clipboard by using the method:

  clipboard.request_targets(callback, user_data=None)

The targets are returned as a tuple of gtk.gdk.Atom objects to the callback function.

Two convenience methods are provided to return the Clipboard contents synchronously:

  selectiondata = clipboard.wait_for_contents(target)

  text = clipboard.wait_for_text()

To illustrate the use of a Clipboard the clipboard.py example program tracks the text items that are cut or copied to the "CLIPBOARD" clipboard and saves the last ten clipboard entries. There are ten buttons that provide access to the text of the saved entries. The button label display the first sixteen characters of the saved text and the tooltips display the targets that the entry originally had. When an entry button is clicked the text window is loaded with the associated saved text which is editable. The button below the text window saves the current text window contents to the clipboard.

Figure 15.1, “Clipboard Example Program” illustrates the clipboard.py example program in operation:

Figure 15.1. Clipboard Example Program

The example program polls the clipboard every 1.5 seconds to see if the contents have changed. The program could be changed to duplicate the complete set of target contents and then take ownership of the clipboard using the set_with_data() method. Later, when another program sets the contents of the clipboard, the clear_func will be called and it can be used to reload the clipboard contents and retake the clipboard ownership.