Ancestry

gtk.Clipboard Signal Prototypes

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+.)

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.

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

Note

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.

gtk.Clipboard.set_can_store

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

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

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

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

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.

gtk.Clipboard.wait_is_uris_available

def wait_is_uris_available()

Returns :

True if is there is an URI list
available, False
otherwise.

Note

This method is available in PyGTK 2.14 and above.

The wait_is_uris_available()
method Test to see if there is a list of URIs available to be pasted This
is done by requesting the TARGETS atom and checking if it contains the URI targets.
This function waits for the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.

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.