gtk.SelectionData
Prev | The gtk Class Reference | Next

## gtk.SelectionData

gtk.SelectionData — an object that stores information about a selection

## Synopsis

    class gtk.SelectionData(gobject.GBoxed):
        def set(type, format, data)
        def set_text(str, len)
        def get_text()
        def get_targets()
        def targets_include_text()
        def tree_set_row_drag_data(tree_model, path)
        def tree_get_row_drag_data()
        def set_pixbuf(pixbuf)
        def get_pixbuf()
        def set_uris(uris)
        def get_uris()
        def targets_include_image(writable)
        def targets_include_rich_text(buffer)
        def targets_include_uri()
        def get_data_type()
        def get_display()
        def get_format()
        def get_length()
        def get_target()

    Functions

        def gtk.selection_owner_set_for_display(display, widget, selection, time=0)
        def gtk.target_list_add_image_targets(list=None, info=0, writable=False)
        def gtk.target_list_add_text_targets(list=None, info=0)
        def gtk.target_list_add_uri_targets(list=None, info=0)
        def gtk.target_list_add_rich_text_targets(list, info, deserializable, buffer)
        def gtk.targets_include_image(targets, writable)
        def gtk.targets_include_rich_text(targets, buffer)
        def gtk.targets_include_text(targets)
        def gtk.targets_include_uri(targets)

## Attributes

"selection" | Read | A `gtk.gdk.Atom` indicating the selection type (e.g. "PRIMARY").
"target" | Read | A `gtk.gdk.Atom` indicating the selection target type (e.g. "TARGETS").
"type" | Read | A `gtk.gdk.Atom` indicating the selection data type (e.g. "STRING").
"format" | Read | The unit length of the data in bits (e.g. 8 for a string or 32 of an integer).
"data" | Read | The data as a string.

## Description

A `gtk.SelectionData` object is used to store information about a chunk of data associated with a selection. In PyGTK the selection data is always a string so the application will have to provide functions to convert the data to and from a string to support data types other than strings and targets. The string and targets types are directly supported using the `set_text`(), `get_text`() and `get_targets`() methods.

## Methods

### gtk.SelectionData.set

        def set(type, format, data)

`type` : | a `gtk.gdk.Atom` or string that specifies a `gtk.gdk.Atom`
`format` : | the number of bits in a unit
`data` : | a string containing the data

The `set`() method sets the data for a selection in the `gtk.SelectionData` object. `data` is a string containing the data to be set; `format` is the number of bits in a unit of the data (e.g. integer data has a format of 32 on most systems; string data format is 8); and, `type` is a `gtk.gdk.Atom` or a string that specifies a `gtk.gdk.Atom`.

### gtk.SelectionData.set_text

        def set_text(str, len)

`str` : | a string
`len` : | the length of `str`, or -1 if `str` for the full length.
Returns : | `True`, if the selection was successfully set; otherwise, `False`.

The `set_text`() method sets the contents of the selection from the string specified by `str`. The string is converted to the form specified by the `selection_data.target` attribute. This method returns True if the selection data was successfully set.

### gtk.SelectionData.get_text

        def get_text()

Returns : | a string containing the converted text, or `None`.

The `get_text`() method returns the contents of the selection data as a string.

### gtk.SelectionData.get_targets

        def get_targets()

Returns : | a tuple containing a list of targets (`gtk.gdk.Atom`s) or `None` if no valid targets are available.

The `get_targets`() method returns a tuple containing a list of valid targets for the selection as a list of `gtk.gdk.Atom`s or None if there are no valid targets.

### gtk.SelectionData.targets_include_text

        def targets_include_text()

Returns : | `True` if the selection data holds a list of targets, and a suitable target for text is included.

The `targets_include_text`() method returns `True` if any of the selection data targets can be used to provide text.

### gtk.SelectionData.tree_set_row_drag_data

        def tree_set_row_drag_data(tree_model, path)

`tree_model` : | a `gtk.TreeModel`
`path` : | a row in `tree_model`
Returns : | `True` if the `gtk.SelectionData` had the proper target type to allow us to set a tree row

The `tree_set_row_drag_data`() method sets the selection data of target type `GTK_TREE_MODEL_ROW` for the row (specified by `path`) in the `gtk.TreeModel` (specified by tree_model). Normally used in a "drag-data-get" signal handler.

### gtk.SelectionData.tree_get_row_drag_data

        def tree_get_row_drag_data()

Returns : | a tuple containing a `gtk.TreeModel` and one of its rows.

The `tree_get_row_drag_data`() method returns a tuple containing a `gtk.TreeModel` and a row from that `gtk.TreeModel` from selection data of target type `GTK_TREE_MODEL_ROW`. Normally called from a "drag-data-received" signal handler. This method can only be used if the selection data originates from the same process that's calling this method, because a pointer to the tree model is being passed around. In the "drag-data-received" signal handler, you can assume that selection data of type `"GTK_TREE_MODEL_ROW"` is from the current process.

### gtk.SelectionData.set_pixbuf

        def set_pixbuf(pixbuf)

`pixbuf` : | a `gtk.gdk.Pixbuf`
Returns : | `True`, if the selection was successfully set; otherwise, `False`.

### Note

This method is available in PyGTK 2.6 and above.

The `set_pixbuf`() method sets the contents of the selection from the `gtk.gdk.Pixbuf` specified by `pixbuf`. This method returns `True` if the selection data was successfully set.

### gtk.SelectionData.get_pixbuf

        def get_pixbuf()

Returns : | if the selection data contained a recognized image type and it could be converted to a `gtk.gdk.Pixbuf`, a newly allocated pixbuf is returned, or `None`.

### Note

This method is available in PyGTK 2.6 and above.

The `get_pixbuf`() method returns the contents of the selection data as a `gtk.gdk.Pixbuf` if possible.

### gtk.SelectionData.set_uris

        def set_uris(uris)

`uris` : | a list of strings holding URIs
Returns : | `True`, if the selection was successfully set; otherwise, `False`.

### Note

This method is available in PyGTK 2.6 and above.

The `set_uris`() method sets the contents of the selection from the list of URIs specified by `uris`. This method returns `True` if the selection data was successfully set.

### gtk.SelectionData.get_uris

        def get_uris()

Returns : | a list of URIs, or `None`.

### Note

This method is available in PyGTK 2.6 and above.

The `get_uris`() method returns the contents of the selection data as a list of URIs.

### gtk.SelectionData.targets_include_image

        def targets_include_image(writable)

`writable` : | If `True` only accept targets that GTK+ can convert a `gtk.gdk.Pixbuf` to.
Returns : | `True`, if the selection has a list of targets that includes an image target.

### Note

This method is available in PyGTK 2.6 and above.

The `targets_include_image`() method returns `True` if the selection targets include an image target.

### gtk.SelectionData.targets_include_rich_text

        def targets_include_rich_text(buffer)

`buffer` : | a `gtk.TextBuffer`
Returns : | `True` if a suitable target for rich text is included in the selectiondata targets.

### Note

This method is available in PyGTK 2.10 and above.

Determines if any of the selectiondata targets can be used to provide rich text.

### gtk.SelectionData.targets_include_uri

        def targets_include_uri()

Returns : | `True` if a suitable target for uris is included in the selectiondata targets.

### Note

This method is available in PyGTK 2.10 and above.

Determines if any of the selectiondata targets can be used to provide a list of URIs.

### gtk.SelectionData.get_data_type

        def get_data_type()

Returns : | the data type of the selection.

### Note

This method is available in PyGTK 2.14 and above.

Retrieves the data type of the selection.

### gtk.SelectionData.get_display

        def get_display()

Returns : | the display of the selection.

### Note

This method is available in PyGTK 2.14 and above.

Retrieves the display of the selection.

### gtk.SelectionData.get_format

        def get_format()

Returns : | the format of the selection.

### Note

This method is available in PyGTK 2.14 and above.

Retrieves the format of the selection.

### gtk.SelectionData.get_length

        def get_length()

Returns : | the length of the data of the selection.

### Note

This method is available in PyGTK 2.14 and above.

Retrieves the length of the data of the selection.

### gtk.SelectionData.get_targets

        def get_target()

Returns : | the target of the selection.

### Note

This method is available in PyGTK 2.14 and above.

Retrieves the target of the selection.

## Functions

### gtk.selection_owner_set_for_display

        def gtk.selection_owner_set_for_display(display, widget, selection, time=0)

`display` : | the `gtk.gdk.Display` where the selection is set
`widget` : | the new selection owner (a `gtk.Widget`), or `None`.
`selection` : | a `gtk.gdk.Atom` or string representing a selection target
`time` : | the timestamp used to claim the selection
Returns : | `True` if the operation succeeded

The `gtk.selection_owner_set_for_display`() function claims ownership of the selection specified by `selection` for the widget specified by `widget` on the `gtk.gdk.Display` specified by `display`. If `widget` is `None`, the ownership of the selection is released.

### gtk.target_list_add_image_targets

        def gtk.target_list_add_image_targets(list=None, info=0, writable=False)

`list` : | A sequence of target entry tuples or `None`
`info` : | an application specified ID that will be passed back to the application
`writable` : | If `True`, only add targets for image formats that a pixbuf can be converted to.
Returns : | a new list concatenating `list` and the built-in image targets supported by `gtk.SelectionData`.

### Note

This function is available in PyGTK 2.6 and above.

The `gtk.target_list_add_image_targets`() function adds the image target tuples supported by `gtk.SelectionData` to the list of target entry tuples specified by `list`. `info` is used as the info field of the target entry tuples.

### gtk.target_list_add_text_targets

        def gtk.target_list_add_text_targets(list=None, info=0)

`list` : | A sequence of target entry tuples or `None`
`info` : | an application specified ID that will be passed back to the application
Returns : | a new list concatenating `list` and the built-in text targets supported by `gtk.SelectionData`.

### Note

This function is available in PyGTK 2.6 and above.

The `gtk.target_list_add_text_targets`() function adds the text target tuples supported by `gtk.SelectionData` to the list of target entry tuples specified by `list`. `info` is used as the info field of the target entry tuples.

### gtk.target_list_add_uri_targets

        def gtk.target_list_add_uri_targets(list=None, info=0)

`list` : | A sequence of target entry tuples or `None`
`info` : | an application specified ID that will be passed back to the application
Returns : | a new list concatenating `list` and the built-in URI targets supported by `gtk.SelectionData`.

### Note

This function is available in PyGTK 2.6 and above.

The `gtk.target_list_add_uri_targets`() function adds the URI target tuples supported by `gtk.SelectionData` to the list of target entry tuple specified by `list`. `info` is used as the info field of the target entry tuples.

### gtk.targets_include_uri

        def gtk.targets_include_uri(targets)

`targets` : | a list of target strings
Returns : | `True` if targets includes a uri target.

### Note

This function is available in PyGTK 2.10 and above.

Determines if any of the targets in `targets` can be used to provide an uri list.

### gtk.targets_include_text

        def gtk.targets_include_text(targets)

`targets` : | a list of target strings
Returns : | `True` if targets includes a text target.

### Note

This function is available in PyGTK 2.10 and above.

Determines if any of the targets in `targets` can be used to provide text.

### gtk.targets_include_rich_text

        def gtk.targets_include_rich_text(targets, buffer)

`targets` : | a list of target strings
`buffer` : | a `gtk.TextBuffer`
Returns : |

### Note

This function is available in PyGTK 2.10 and above.

Determines if any of the targets in `targets` can be used to provide rich text.

### gtk.targets_include_image

        def gtk.targets_include_image(targets, writable)

`targets` : | a list of target strings
`writable` : | if `True` accept only targets for which GTK+ knows how to convert a pixbuf into the format
Returns : | `True` if `targets` include a suitable target for images

### Note

This function is available in PyGTK 2.10 and above.

Determines if any of the targets in targets can be used to provide a `gtk.gdk.Pixbuf`.

### gtk.target_list_add_rich_text_targets

        def gtk.target_list_add_rich_text_targets(list, info, deserializable, buffer)

`list` : | a list of targets
`info` : | an ID that will be passed back to the application
`deserializable` : | if `True`, deserializable rich text formats will be added, otherwise, serializable formats will be added.
`buffer` : | a `gtk.TextBuffer`
Returns : | a target list with the rich text targets registered with `buffer` appended to `list`.

### Note

This function is available in PyGTK 2.10 and above.

Appends the rich text targets registered with the `register_serialize_format`() or `register_deserialize_format`() methods to the target list. All targets are added with the same `info`. list

Prev | Up | Next
gtk.ScrolledWindow | Home | gtk.Separator