gtk.Clipboard

gtk.Clipboard
Prev	The gtk Class Reference	Next

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