17. Clipboard

Gtk.Clipboard provides a storage area for a variety of data, including text and images. Using a clipboard allows this data to be shared between applications through actions such as copying, cutting, and pasting. These actions are usually done in three ways: using keyboard shortcuts, using a Gtk.MenuItem, and connecting the functions to Gtk.Button widgets.

There are multiple clipboard selections for different purposes. In most circumstances, the selection named CLIPBOARD is used for everyday copying and pasting. PRIMARY is another common selection which stores text selected by the user with the cursor.

17.1. Clipboard Objects

class Gtk.Clipboard

get(selection)

Obtains the Gtk.Clipboard for the given selection.

selection is a Gdk.Atom describing which clipboard to use. Predefined values include:

• Gdk.SELECTION_CLIPBOARD
• Gdk.SELECTION_PRIMARY

set_text(text, length)

Sets the contents of the clipboard to the given text.

text is the string to put in the clipboard.

length is the number of characters to store. It may be omitted to store the entire string.

set_image(image)

Sets the contents of the clipboard to the given image.

image must be a Gdk.Pixbuf. To retrieve one from a Gdk.Image, use image.get_pixbuf().

wait_for_text()

Returns the clipboard’s content as a string, or returns None if the clipboard is empty or not currently holding text.

wait_for_image()

Returns the clipboard’s content as a Gtk.Pixbuf, or returns None if the clipboard is empty or not currently holding an image.

store()

Stores the clipboard’s data outside the application. Otherwise, data copied to the clipboard may be lost when the application exits.

clear()

Clears the contents of the clipboard. Use with caution; this may clear data from another application.

17.2. Example

from gi.repository import Gtk, Gdk

class ClipboardWindow(Gtk.Window):

    def __init__(self):
        Gtk.Window.__init__(self, title="Clipboard Example")

        table = Gtk.Table(3, 2)

        self.clipboard = Gtk.Clipboard.get(Gdk.SELECTION_CLIPBOARD)
        self.entry = Gtk.Entry()
        self.image = Gtk.Image.new_from_stock(Gtk.STOCK_STOP, Gtk.IconSize.MENU)

        button_copy_text = Gtk.Button("Copy Text")
        button_paste_text = Gtk.Button("Paste Text")
        button_copy_image = Gtk.Button("Copy Image")
        button_paste_image = Gtk.Button("Paste Image")

        table.attach(self.entry, 0, 1, 0, 1)
        table.attach(self.image, 0, 1, 1, 2)
        table.attach(button_copy_text, 1, 2, 0, 1)
        table.attach(button_paste_text, 2, 3, 0, 1)
        table.attach(button_copy_image, 1, 2, 1, 2)
        table.attach(button_paste_image, 2, 3, 1, 2)

        button_copy_text.connect("clicked", self.copy_text)
        button_paste_text.connect("clicked", self.paste_text)
        button_copy_image.connect("clicked", self.copy_image)
        button_paste_image.connect("clicked", self.paste_image)

        self.add(table)

    def copy_text(self, widget):
        self.clipboard.set_text(self.entry.get_text(), -1)

    def paste_text(self, widget):
        text = self.clipboard.wait_for_text()
        if text != None:
            self.entry.set_text(text)
        else:
            print "No text on the clipboard."

    def copy_image(self, widget):
        if self.image.get_storage_type() == Gtk.ImageType.PIXBUF:
            self.clipboard.set_image(self.image.get_pixbuf())
        else:
            print "No image has been pasted yet."

    def paste_image(self, widget):
        image = self.clipboard.wait_for_image()
        if image != None:
            self.image.set_from_pixbuf(image)


win = ClipboardWindow()
win.connect("delete-event", Gtk.main_quit)
win.show_all()
Gtk.main()