Xfce Foundation Classes
Main Page | Index | Namespace List | Alphabetical List | Class List | File List

# Xfc::Gtk::SelectionData Class Reference

A GtkSelectionData C++ wrapper class. More...

`#include <xfc/gtk/selection.hh>`

Inheritance diagram for Xfc::Gtk::SelectionData:

List of all members.

## Public Member Functions

Constructors

- SelectionData (GtkSelectionData *data)
    Construct a new SelectionData from an existing GtkSelectionData.
- SelectionData (GtkSelectionData *data, bool copy)
    Construct a new SelectionData from an existing GtkSelectionData.
- ~SelectionData ()
    Destructor.

Accessors

- GtkSelectionData * gtk_selection_data () const
    Get a pointer to the GtkSelectionData structure.
- bool is_valid () const
    Returns true if the length of the data is >= zero; false indicates the data should be ignored.
- Gdk::Atom selection () const
    Returns an atom that defines which selection this data belongs to.
- String get_selection () const
    Returns a string corresponding to the atom that defines which selection this data belongs to.
- Gdk::Atom target () const
    Returns an atom that defines which target has been requested.
- String get_target () const
    Returns a string corresponding to the atom that defines which target has been requested.
- Gdk::Atom type () const
    Returns an atom that defines what type the received data has been converted to.
- String get_type () const
    Returns a string corresponding to the atom that defines what type the received data has been converted to.
- int format () const
    Returns the number of bits that are required to store one element of the target type.
- unsigned char * data () const
    Returns a pointer to the data that has been provided.
- int length () const
    Returns the length in bytes of the data that has been provided.
- Gdk::Display * display () const
    Returns the Gdk::Display where the selection is set.
- String get_text () const
    Gets the contents of the selection data as a UTF-8 string.
- Pointer< Gdk::Pixbuf > get_pixbuf () const
    Gets the contents of the selection data as a Gdk::Pixbuf.
- std::vector< String > get_uris () const
    Gets the contents of the selection data as a vector of URI Strings.
- bool get_targets (std::vector< Gdk::Atom > &targets) const
    Gets the contents of the selection data as a vector of Gdk::Atom that defines the targets available.
- bool get_targets (std::vector< String > &targets) const
    Gets the contents of the selection data as a vector of String corresponding to the atoms that define the targets available.
- bool targets_include_text () const
    Returns true if any of the targets can be used to provide text.
- bool targets_include_image (bool writable) const
    Given a Gtk::SelectionData object holding a list of targets, determines if any of the targets in targets can be used to provide a Gdk::Pixbuf.

Methods

- void set (Gdk::Atom type, int format, const void *data, int length)
    Stores new data in this SelectionData object.
- bool set_text (const String &str)
    Sets the contents of the selection from a UTF-8 encoded string.
- bool set_pixbuf (Gdk::Pixbuf &pixbuf)
    Sets the contents of the selection from a Gdk::Pixbuf.
- bool set_uris (const std::vector< String > &uris)
    Sets the contents of the selection from a list of URIs.

Drag-and-Drop Methods

- bool get_row_drag_data (TreeModel **model, Pointer< TreePath > *path) const
    Obtains a model and path from selection data of target type GTK_TREE_MODEL_ROW.
- bool set_row_drag_data (TreeModel &tree_model, const TreePath &path)
    Sets selection data of target type GTK_TREE_MODEL_ROW.

## Detailed Description

A GtkSelectionData C++ wrapper class.

The selection mechanism provides the basis for different types of communication between processes. In particular, drag-and-drop and Clipboard work via selections. You will very seldom or never need to use most of the functions in this section directly; Clipboard provides a nicer interface to the same functionality. Some of the datatypes defined in this section are used in the Clipboard and drag-and-drop API's as well.

The SelectionData object is used to store a chunk of data along with the data type and other associated information.

See also: the Selection HOWTO and example.

## Constructor & Destructor Documentation

Xfc::Gtk::SelectionData::SelectionData | ( | GtkSelectionData * | data | ) | `[explicit]`

Construct a new SelectionData from an existing GtkSelectionData.

Parameters:

  | data | A pointer to a GtkSelectionData.

The data can be a newly created GtkSelectionData or an existing GtkSelectionData. The SelectionData object created is a temporary object. It doesn't take over the ownership of GtkSelectionData and GtkSelectionData is not freed by the destructor.

Xfc::Gtk::SelectionData::SelectionData | ( | GtkSelectionData * | data,
|  | bool | copy
| ) |

Construct a new SelectionData from an existing GtkSelectionData.

Parameters:

  | data | A pointer to a GtkSelectionData.
  | copy | Whether the SelectionData object should make a copy of GtkSelectionData or not.

The data can be a newly created GtkSelectionData or an existing GtkSelectionData. If copy is true SelectionData will make a copy of GtkSelectionData. If copy is false SelectionData wont make a copy but instead takes over the ownership of GtkSelectionData. Either way, the destructor will free GtkSelectionData when the SelectionData object is destroyed. This constructor is used by G::Boxed::wrap() to wrap GtkSelectionData objects in a C++ wrapper.

## Member Function Documentation

Pointer<Gdk::Pixbuf> Xfc::Gtk::SelectionData::get_pixbuf | ( |  | ) | const

Gets the contents of the selection data as a Gdk::Pixbuf.

Returns:
  A smart pointer to a Gdk::Pixbuf.

If the selection data contained a recognized image type and it could be converted to a Gdk::Pixbuf, a pixbuf is returned, otherwise a null pointer is returned.

bool Xfc::Gtk::SelectionData::get_row_drag_data | ( | TreeModel ** | model,
|  | Pointer< TreePath > * | path
| ) | const

Obtains a model and path from selection data of target type GTK_TREE_MODEL_ROW.

Parameters:

  | model | A pointer to a TreeModel pointer.
  | path | A pointer to a smart TreePath pointer to hold the path to a row in tree_model.

Returns:
  true if SelectionData had target type GTK_TREE_MODEL_ROW and is otherwise valid.

Normally called from a drag_data_received handler. This method can only be used if SelectionData originates from the same process that's calling this method, because a pointer to the tree model is being passed around. If you aren't in the same process, then you'll get memory corruption. In the TreeDragDest drag_data_received handler, you can assume that SelectionData of type GTK_TREE_MODEL_ROW is from the current process. If the target type is wrong this method returns false.

bool Xfc::Gtk::SelectionData::get_targets | ( | std::vector< String > & | targets | ) | const

Gets the contents of the selection data as a vector of String corresponding to the atoms that define the targets available.

Parameters:

  | targets | A reference to a vector of String to store the names of targets.

Returns:
  true if selection data contains a valid targets, otherwise false.

This can be used to interpret the results of getting the standard TARGETS target that is always supplied for any selection.

bool Xfc::Gtk::SelectionData::get_targets | ( | std::vector< Gdk::Atom > & | targets | ) | const

Gets the contents of the selection data as a vector of Gdk::Atom that defines the targets available.

Parameters:

  | targets | A reference to a vector of Gdk::Atom to store the list of targets.

Returns:
  true if selection data contains a valid targets, otherwise false.

This can be used to interpret the results of getting the standard TARGETS target that is always supplied for any selection.

String Xfc::Gtk::SelectionData::get_text | ( |  | ) | const

Gets the contents of the selection data as a UTF-8 string.

Returns:
  If the selection data contained a recognized text type and it could be converted to UTF-8, a String containing the converted text, otherwise a null String.

std::vector<String> Xfc::Gtk::SelectionData::get_uris | ( |  | ) | const

Gets the contents of the selection data as a vector of URI Strings.

Returns:
  A vector of String that holds the URIs.

If the selection data contained no URIs the returned vector of String will be empty.

void Xfc::Gtk::SelectionData::set | ( | Gdk::Atom | type,
|  | int | format,
|  | const void * | data,
|  | int | length
| ) |

Stores new data in this SelectionData object.

Parameters:

  | type | The type of selection data.
  | format | The format (number of bits in a unit).
  | data | The pointer to the data (will be copied).
  | length | The length of the data.

Should only be called from a selection handler callback. Zero-terminates the stored data.

bool Xfc::Gtk::SelectionData::set_pixbuf | ( | Gdk::Pixbuf & | pixbuf | ) |

Sets the contents of the selection from a Gdk::Pixbuf.

Parameters:

  | pixbuf | A Gdk::Pixbuf

Returns:
  true if the selection was successfully set, otherwise false.

The pixbuf is converted to the form determined by selection_data->target.

bool Xfc::Gtk::SelectionData::set_row_drag_data | ( | TreeModel & | tree_model,
|  | const TreePath & | path
| ) |

Sets selection data of target type GTK_TREE_MODEL_ROW.

Parameters:

  | tree_model | A reference to a TreeModel.
  | path | A row in tree_model.

Returns:
  true if the SelectionData had the proper target type to allow us to set a tree row.

Normally used in a drag_data_get handler. If the target type is wrong this method returns false.

bool Xfc::Gtk::SelectionData::set_text | ( | const String & | str | ) |

Sets the contents of the selection from a UTF-8 encoded string.

The string is converted to the form determined by target().

Parameters:

  | str | A UTF-8 string.

Returns:
  true if the selection was successfully set, otherwise false.

bool Xfc::Gtk::SelectionData::set_uris | ( | const std::vector< String > & | uris | ) |

Sets the contents of the selection from a list of URIs.

Parameters:

  | uris | A vector of String holding the URIs.

Returns:
  true if the selection was successfully set, otherwise false.

The strings are converted to the form determined by selection_data->target.

bool Xfc::Gtk::SelectionData::targets_include_image | ( | bool | writable | ) | const

Given a Gtk::SelectionData object holding a list of targets, determines if any of the targets in targets can be used to provide a Gdk::Pixbuf.

Parameters:

  | writable | Whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format

Returns:
  true if the selection data holds a list of targets, and a suitable target for images is included, otherwise false.

The documentation for this class was generated from the following file:

- gtk/selection.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3