Chapter 15. New Widgets in PyGTK 2.2
Prev |  | Next

## Chapter 15. New Widgets in PyGTK 2.2

The `Clipboard` object was added in PyGTK 2.2. The `GtkClipboard` was available in GTK+ 2.0 but was not wrapped by PyGTK 2.0 because it was not a complete `GObject`. Some new objects were added to the gtk.gdk module in PyGTK 2.2 but they will not be described in this tutorial. See the PyGTK 2 Reference Manual for more information on the `gtk.gdk.Display`, `gtk.gdk.DisplayManager` and `gtk.gdk.Screen` objects.

## 15.1. Clipboards

A `Clipboard` provides a storage area for sharing data between processes or between different widgets in the same process. Each `Clipboard` is identified by a string name encoded as a `gdk.Atom`. You can use any name you want to identify a `Clipboard` and a new one will be created if it doesn't exist. If you want to share a `Clipboard` with other processes each process will need to know the `Clipboard`'s name.

`Clipboard`s are built on the `SelectionData` and selection interfaces. The default `Clipboard` used by the `TextView`, `Label` and `Entry` widgets is "CLIPBOARD". Other common clipboards are "PRIMARY" and "SECONDARY" that correspond to the primary and secondary selections (Win32 ignores these). These can also be specified using the `gtk.gdk.Atom` objects: `gtk.gdk.SELECTION_CLIPBOARD`, `gtk.gdk.SELECTION_PRIMARY` and `gtk.gdk.SELECTION_SECONDARY`. See the gtk.gdk.Atom reference documentation for more information.

### 15.1.1. Creating A Clipboard

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.

### 15.1.2. Using Clipboards with Entry, Spinbutton and TextView

`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.

`TextBuffer`s 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.

`TextBuffer`s also have two methods to manage a set of `Clipboard`s 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).

### 15.1.3. Setting Data on a 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:

- a string representing a target supported by the clipboard.
- a flags value used for drag and drop - use 0.
- an application assigned integer that is passed as a parameter to a signal handler to help identify the target type.

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.

### 15.1.4. Retrieving the Clipboard Contents

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()

### 15.1.5. A Clipboard Example

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.

Prev | Up | Next
14.12. The Generic CellRenderer | Home | Chapter 16. New Widgets in PyGTK 2.4