gtk.Clipboard
Prev | The gtk Class Reference | Next

## gtk.Clipboard

gtk.Clipboard — an object to store data to and retrieve data from (new in PyGTK 2.2)

## Synopsis

    class gtk.Clipboard(gobject.GObject):
        gtk.Clipboard(display=gtk.gdk.display_get_default(), selection="CLIPBOARD")
        def get_display()
        def set_with_data(targets, get_func, clear_func, user_data)
        def get_owner()
        def clear()
        def set_text(text, len=-1)
        def request_contents(target, callback, user_data=None)
        def request_text(callback, user_data=None)
        def request_targets(callback, user_data=None)
        def wait_for_contents(target)
        def wait_for_text()
        def wait_is_text_available()
        def wait_for_targets()
        def wait_is_target_available(target)
        def set_can_store(targets)
        def store()
        def request_image(callback, user_data=None)
        def wait_for_image()
        def set_image(pixbuf)
        def wait_is_image_available()
        def request_rich_text(buffer, callback, user_data=None)
        def wait_for_rich_text(buffer)
        def wait_is_rich_text_available(buffer)

    Functions

        def gtk.clipboard_get(selection="CLIPBOARD")

## Ancestry

    +-- gobject.GObject
      +-- gtk.Clipboard

## gtk.Clipboard Signal Prototypes

gobject.GObject Signal Prototypes

"owner-change | `def callback(`clipboard`, `event`, `user_param1`, `...`)`

## Description

### Note

This object is available in PyGTK 2.2 and above.

The `gtk.Clipboard` object represents a clipboard of data shared between different processes or between different widgets in the same process. Each clipboard is identified by a name encoded as a `gtk.gdk.Atom`. The `gtk.Clipboard` is basically a higher-level interface to the lower-level `gtk.SelectionData` and selection interface. The built-in atoms are:

- "PRIMARY"
- "SECONDARY"
- "CLIPBOARD"
- "BITMAP"
- "COLORMAP"
- "DRAWABLE"
- "PIXMAP"
- "STRING"
- "WINDOW"

Creating a `gtk.gdk.Atom` from strings can be done with the gtk.gdk.atom_intern() constructor function though `PyGTK` will usually do the conversion under the covers as needed. The name of a `gtk.gdk.Atom` can be retrieved using the Python `str`() function:

      name = str(atom)

The default clipboard corresponds to the "CLIPBOARD" atom; another commonly used clipboard is the "PRIMARY" clipboard, which, in X, traditionally contains the currently selected text.

To simultaneously support different formats on the clipboard, the clipboard mechanism allows you to provide callbacks instead of the actual data. When you set the contents of the clipboard, you can either supply the data directly (via a method like `set_text`()), or you can supply a callback to be called when the data is needed (via the `set_with_data`() method.) Providing a callback also avoids making unnecessary copies of the data.

Along with the methods to get the clipboard contents as an arbitrary data chunk, there is a method to retrieve it as text, the `wait_for_text`() method. This method takes care of determining which formats are advertised by the clipboard provider, asking for the clipboard in the best available format and converting the results into the UTF-8 encoding. (The standard form for representing strings in `GTK`+.)

## Constructor

        gtk.Clipboard(display=gtk.gdk.display_get_default(), selection="CLIPBOARD")

`display` : | the `gtk.gdk.Display` for which the clipboard is to be retrieved or created.
`selection` : | a string that identifies the clipboard to use.
Returns : | the appropriate clipboard object or if no clipboard already exists, a new one will be created. Once a clipboard object has been created, it is persistent for all time and cannot be freed.

### Note

This constructor is available in PyGTK 2.2 and above.

Returns the clipboard object for the `gtk.gdk.Display` specified by `display` and the selection specified by the string in `selection`. Cut/copy/paste menu items and keyboard shortcuts should use the default clipboard, returned by passing `"CLIPBOARD"` for `selection`. The currently-selected object or text should be provided on the clipboard identified by `"PRIMARY"`. Cut/copy/paste menu items conceptually copy the contents of the `"PRIMARY"` clipboard to the default clipboard, i.e. they copy the selection to what the user sees as the clipboard.

See http://www.freedesktop.org/standards/clipboards-spec/clipboards.txt for a detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections under the X window system. On Win32 the `"PRIMARY"` clipboard is essentially ignored.

It's possible to have arbitrarily named clipboards. If you do invent new clipboards, you should prefix the selection name with an underscore (because the ICCCM requires that nonstandard atoms are underscore-prefixed), and namespace it as well. For example, if your application called "Foo" has a special-purpose clipboard, you might call it "_FOO_SPECIAL_CLIPBOARD".

In PyGTK 2.4 and above, the `display` argument is optional and defaults to the default display returned from the `gtk.gdk.display_get_default`() function.

In PyGTK 2.4 and above, the `selection` argument is optional and defaults to "CLIPBOARD".

## Methods

### gtk.Clipboard.get_display

        def get_display()

Returns : | the `gtk.gdk.Display` associated with the clipboard

### Note

This method is available in PyGTK 2.2 and above.

The `get_display`() method returns the `gtk.gdk.Display` associated with the clipboard.

### gtk.Clipboard.set_with_data

        def set_with_data(targets, get_func, clear_func, user_data)

`targets` : | a list of 3-tuples containing information about the available forms for the clipboard data
`get_func` : | a function to call to get the actual clipboard data
`clear_func` : | when the clipboard contents are set again, this function will be called, and `get_func` will not be subsequently called.
`user_data` : | the user data to pass to `get_func` and `clear_func`.
Returns : | `True` if setting the clipboard data succeeded. If setting the clipboard data failed the provided callback functions will be ignored.

### Note

This method is available in PyGTK 2.2 and above.

The `set_with_data`() method virtually sets the contents of the specified clipboard by providing a list of supported formats (specified by `targets`) for the clipboard data and a function (specified by `get_func`) to call to get the actual data when it is requested. `clear_func` is a function that is called when the contents of the clipboard are being changed to provide cleanup operations on `user_data`. `user_data` is passed to `get_func` and `clear_func` when they are invoked. The 3-tuples listed in `targets` contain the following items:

- a string representing a target supported by the clipboard
- a flags value used for drag and drop - a combination of: `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET`
- an application assigned integer that is passed as a signal parameter to help identify the target type

The signature of `get_func` is:

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

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

The signature of `clear_func` is:

      def clear_func(clipboard, data):

where `clipboard` is the `gtk.Clipboard` and `data` is the `user_data` argument.

### gtk.Clipboard.get_owner

        def get_owner()

Returns : | the owner of the clipboard, if any; otherwise `None`.

### Note

This method is available in PyGTK 2.2 and above.

The `get_owner`() method returns the owner set by the `set_with_owner`() method if neither the `set_with_data()` method nor the `clear()` method have been subsequently called. This method returns `None` otherwise.

### gtk.Clipboard.clear

        def clear()

### Note

This method is available in PyGTK 2.2 and above.

The `clear`() method clears the contents of the clipboard. Generally this should only be called between the time you call the `set_with_data()`, and when the `clear_func` you supplied is called. Otherwise, the clipboard may be owned by someone else.

### gtk.Clipboard.set_text

        def set_text(text, len=-1)

`text` : | a string.
`len` : | the length of `text`, in bytes, or -1, to calculate the length.

### Note

This method is available in PyGTK 2.2 and above.

The `set_text`() method sets the contents of the clipboard to the string specified by `text`. If `len` is given it determines the length of `text` to be copied. If `len` is not specified it defaults to -1 and the method calculates the text length.

### gtk.Clipboard.request_contents

        def request_contents(target, callback, user_data=None)

`target` : | a `gtk.gdk.Atom` or string representing the form that the clipboard owner should convert the selection to.
`callback` : | a function to call when the results are received (or the retrieval fails).
`user_data` : | user data to pass to `callback`

### Note

This method is available in PyGTK 2.4 and above.

The `request_contents`() method requests the contents of clipboard in the form specified by `target`. When the results of the request are later received the function specified by `callback` will be invoked and passed the data specified by `user_data`. The signature of `callback` is:

      def callback(clipboard, selection_data, data):

where `clipboard` is the `gtk.Clipboard` that invoked callback and `selection_data` is the `gtk.SelectionData` containing the target data and `data` is `user_data`.

### gtk.Clipboard.request_text

        def request_text(callback, user_data=None)

`callback` : | a function to call when the text is received, or the retrieval fails. (It will always be called one way or the other.)
`user_data` : | user data to pass to `callback`.

### Note

This method is available in PyGTK 2.4 and above.

The `request_text`() method requests the contents of the clipboard as text. When the text is later received, it will be converted to UTF-8 if necessary, and `callback` will be called with the data specified by `user_data`. The signature of `callback` is:

      def callback(clipboard, text, data):

where `clipboard` is the `gtk.Clipboard` that `text` is retrieved from and `data` is `user_data`. `text` will contain the resulting text if the request succeeded, or the empty string if it failed. This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into text form.

### gtk.Clipboard.request_targets

        def request_targets(callback, user_data=None)

`callback` : | a function to call when the targets are received, or the retrieval fails. (It will always be called one way or the other.)
`user_data` : | user data to pass to `callback`.

### Note

This method is available in PyGTK 2.4 and above.

The `request_targets`() method requests the contents of the clipboard as list of supported targets. When the list is later received, `callback` will be called with the data specified by `user_data`. The signature of `callback` is:

      def callback(clipboard, targets, data):

where `clipboard` is the `gtk.Clipboard` that `targets` is retrieved from. `targets` is a tuple containing the `gtk.gdk.Atom` objects corresponding to the targets of clipboard. `targets` will contain the resulting targets if the request succeeded, or an empty tuple if it failed.

### gtk.Clipboard.wait_for_contents

        def wait_for_contents(target)

`target` : | an atom or string representing the form into which the clipboard owner should convert the selection.
Returns : | a newly-allocated `gtk.SelectionData` object or `None` if retrieving the given target failed.

### Note

This method is available in PyGTK 2.2 and above.

The `wait_for_contents`() method requests the contents of the clipboard using the target specified by `target`. This method waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait.

### gtk.Clipboard.wait_for_text

        def wait_for_text()

Returns : | a string, or `None` if retrieving the selection data failed. (This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into text form.)

### Note

This method is available in PyGTK 2.2 and above.

The `wait_for_text`() method requests the contents of the clipboard as text and converts the result to UTF-8 if necessary. This method waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait.

### gtk.Clipboard.wait_is_text_available

        def wait_is_text_available()

Returns : | `True` is there is text available.

### Note

This method is available in PyGTK 2.2 and above.

The `wait_is_text_available`() method tests to see if there is text available to be copied from the clipboard. This is done by requesting the "TARGETS" atom and checking if it contains any of the names: "STRING", "TEXT", "COMPOUND_TEXT", "UTF8_STRING". This method waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait.

This method is a little faster than calling the `wait_for_text()` since it doesn't need to retrieve the actual text.

### gtk.Clipboard.wait_for_targets

        def wait_for_targets()

Returns : | returns a tuple containing any targets that are present on the clipboard or `None`.

### Note

This method is available in PyGTK 2.4 and above.

The `wait_for_targets`() method returns a tuple containing the targets (as `gtk.gdk.Atom` objects) that are present on the clipboard, or `None` if there aren't any targets available. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait.

### gtk.Clipboard.wait_is_target_available

        def wait_is_target_available(target)

`target` : | an atom or string representing the target of interest.
Returns : | `True` if the target is available.

### Note

This method is available in PyGTK 2.6 and above.

The `wait_is_target_available`() method tests to see if the target specified by `target` is available to be copied from the clipboard. This method can be used to determine if a Paste menu item should be insensitive or not.

If you want to see if there's text available on the clipboard, use the `wait_is_text_available`() method instead.

### gtk.Clipboard.set_can_store

        def set_can_store()

`targets` : | a list of 3-tuples containing information about the available forms that should be stored or `None` to indicate that all forms should be stored.

### Note

This method is available in PyGTK 2.6 and above.

The `set_can_store`() method sets a hint that the `gtk.Clipboard` can store the list of targets specified by `targets` can be stored somewhere when the application exits or when the `store`() method is called. This value is reset when the clipboard owner changes. Where the clipboard data is stored is platform dependent, see the `gtk.gdk.Display.store_clipboard`() method for more information. If `targets` is `None` all target forms currently available on the clipboard should be stored.

The 3-tuples listed in `targets` contain the following items:

- a string representing a target supported by the clipboard
- a flags value used for drag and drop - a combination of: `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET`
- an application assigned integer that is passed as a signal parameter to help identify the target type

### gtk.Clipboard.store

        def store()

### Note

This method is available in PyGTK 2.6 and above.

The `store`() method stores the current clipboard data (as specified by the `set_can_store`() method) somewhere so that it will stay around after the application has quit.

### gtk.Clipboard.request_image

        def request_image(callback, user_data=None)

`callback` : | a function to call when the image is received, or the retrieval fails. (It will always be called one way or the other.)
`user_data` : | user data to pass to `callback`.

### Note

This method is available in PyGTK 2.10 and above.

The `request_image`() method requests the contents of the clipboard as a `gtk.gdk.Pixbuf` image. When the image is later received, it will be converted to a `gtk.gdk.Pixbuf` and `callback` will be called with the data specified by `user_data`. The signature of `callback` is:

      def callback(clipboard, pixbuf, data):

where `clipboard` is the `gtk.Clipboard` that `pixbuf` is retrieved from and `data` is `user_data`. `pixbuf` will contain the resulting image data if the request succeeded, or `None` if it failed. This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into an image.

### gtk.Clipboard.wait_for_image

        def wait_for_image()

Returns : | a `gtk.gdk.Pixbuf`, or `None` if retrieving the selection data failed. (This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into an image.)

### Note

This method is available in PyGTK 2.10 and above.

The `wait_for_image`() method requests the contents of the clipboard as an image and converts the result to a `gtk.gdk.Pixbuf`. This method waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait.

### gtk.Clipboard.set_image

        def set_image(pixbuf)

`pixbuf` : | a `gtk.gdk.Pixbuf`.

### Note

This method is available in PyGTK 2.10 and above.

The `set_image`() method sets the contents of the clipboard to the `gtk.gdk.Pixbuf` specified by `pixbuf`. GTK+ will take responsibility for responding for requests for the image, and for converting the image into the requested format.

### gtk.Clipboard.wait_is_image_available

        def wait_is_image_available()

Returns : | `True` is there is an image available.

### Note

This method is available in PyGTK 2.10 and above.

The `wait_is_image_available`() method tests to see if there is an image available to be copied from the clipboard. This is done by requesting the "TARGETS" atom and checking if it contains any of the supported image targets. This method waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait.

This method is a little faster than calling the `wait_for_image()` since it doesn't need to retrieve the actual image data.

### gtk.Clipboard.request_rich_text

        def request_rich_text(buffer, callback, user_data=None)

`buffer` : | a `gtk.TextBuffer` to retrieve the deserialize formats from.
`callback` : | a function to call when the text is received, or the retrieval fails. (It will always be called one way or the other.)
`user_data` : | user data to pass to `callback`.

### Note

This method is available in PyGTK 2.10 and above.

The `request_rich_text`() method requests the contents of the clipboard as rich text. When the rich text is later received, the function specified by `callback` will be called with the argument specified by `user_data`.

The signature of the callback is:

            def callback(clipboard, format, text, length, data):

where `format` is the atom indicating the text format, `text` contains the resulting rich text if the request succeeded, or `None` if it failed, `length` contains the length of `text` and `data` is `user_data`. This function can fail for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into rich text form.

### gtk.Clipboard.wait_for_rich_text

        def wait_for_rich_text(buffer)

`buffer` : | a `gtk.TextBuffer` to retrieve the deserialize formats from.
Returns : | a 2-tuple containing the rich text as a string and the format string , or `None` if retrieving the selection data failed. (This could happen for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into text form.)

### Note

This method is available in PyGTK 2.10 and above.

The `wait_for_rich_text`() method requests the contents of the clipboard as rich text. This method waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait.

### gtk.Clipboard.wait_is_rich_text_available

        def wait_is_rich_text_available(buffer)

`buffer` : | a `gtk.TextBuffer` to retrieve the deserialize formats from.
Returns : | `True` if is there is rich text available, `False` otherwise.

### Note

This method is available in PyGTK 2.10 and above.

The `wait_is_rich_text_available`() method tests to see if there is rich text available to be pasted. This is done by requesting the `TARGETS` atom and checking if it contains any of the supported rich text targets. This method waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait.

This method is a little faster than calling `wait_for_rich_text()` since it doesn't need to retrieve the actual text.

## Functions

### gtk.clipboard_get

        def gtk.clipboard_get(selection="CLIPBOARD")

`selection` : | a string specifying a `gtk.Clipboard`. If not specified it defaults to "CLIPBOARD".
Returns : | the appropriate clipboard object or if no clipboard already exists, a new one will be created. Once a clipboard object has been created, it is persistent for all time and cannot be freed.

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.clipboard_get`() function returns the `gtk.Clipboard` specified by selection for the default `gtk.gdk.Display`. See the gtk.Clipboard constructor for more information.

## Signals

### The "owner-change" gtk.Clipboard Signal

        def callback(clipboard, event, user_param1, ...)

`clipboard` : | the object that received the signal.
`event` : | the event marking the ownership change.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.8 and above.

The "owner-changed" signal is emitted when the owner of the clipboard is changed.

Prev | Up | Next
gtk.CheckMenuItem | Home | gtk.ColorButton