gtkmm: Gtk::SelectionData Class Reference

gtkmm 3.93.0

Public Member Functions | Static Public Member Functions | Protected Attributes | Related Functions | List of all members
Gtk::SelectionData Class Reference

Functions for handling inter-process communication via selections. More...

`#include <gtkmm/selectiondata.h>`

## Public Member Functions
| SelectionData ()
| SelectionData (GtkSelectionData* gobject, bool make_a_copy=true)
| SelectionData (const SelectionData& other)
SelectionData& | operator= (const SelectionData& other)
| SelectionData (SelectionData&& other) noexcept
SelectionData& | operator= (SelectionData&& other) noexcept
| ~SelectionData () noexcept
void | swap (SelectionData& other) noexcept
GtkSelectionData* | gobj ()
| Provides access to the underlying C instance. More...
const GtkSelectionData* | gobj () const
| Provides access to the underlying C instance. More...
GtkSelectionData* | gobj_copy () const
| Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs. More...
void | set (int format, const guint8* data, int length)
| Assign a memory block of raw data. More...
void | set (const std::string& type, int format, const guint8* data, int length)
| Assign a memory block of raw data. More...
void | set (const std::string& type, const std::string& data)
| Assign a string of raw data. More...
bool | set_text (const Glib::ustring& data)
| Assign UTF-8 encoded text. More...
Glib::ustring | get_text () const
| Gets the contents of the selection data as a UTF-8 string. More...
bool | set_pixbuf (const Glib::RefPtr< const Gdk::Pixbuf >& pixbuf)
| Sets the contents of the selection from a Gdk::Pixbuf The pixbuf is converted to the form determined by selection_data->target. More...
Glib::RefPtr< Gdk::Pixbuf > | get_pixbuf () const
| Gets the contents of the selection data as a Gdk::Pixbuf. More...
bool | set_surface (const Cairo::RefPtr< const Cairo::Surface >& surface)
| Sets the contents of the selection from a cairo image surface. More...
Cairo::RefPtr< Cairo::Surface > | get_surface () const
| Gets the contents of the selection data as a cairo surface. More...
bool | set_texture (const Glib::RefPtr< const Gdk::Texture >& texture)
| Sets the contents of the selection from a Gdk::Texture. More...
Glib::RefPtr< Gdk::Texture > | get_texture () const
| Gets the contents of the selection data as a Gdk::Pixbuf. More...
bool | set_uris (const std::vector< Glib::ustring >& uris)
| Sets the contents of the selection from a list of URIs. More...
std::vector< Glib::ustring > | get_uris () const
| Gets the contents of the selection data as a container of URIs. More...
const guchar* | get_data () const
| Retrieves the raw data of the selection. More...
int | get_length () const
| Retrieves the length of the raw data of the selection. More...
const guchar* | get_data (int& length) const
| Retrieves the raw data of the selection along with its length. More...
std::string | get_data_as_string () const
| Retrieves the raw data of the selection as a std::string. More...
std::string | get_target () const
| Retrieves the target of the selection. More...
std::vector< std::string > | get_targets () const
| See also Gtk::Clipboard::request_targets() More...
std::string | get_data_type () const
| Returns the type of the data as set by SelectionData::set(). More...
int | get_format () const
| Retrieves the format of the selection. More...
Glib::RefPtr< Gdk::Display > | get_display ()
| Retrieves the display of the selection. More...
Glib::RefPtr< const Gdk::Display > | get_display () const
| Retrieves the display of the selection. More...
bool | targets_include_uri () 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 list or URIs. More...
bool | targets_include_text () const
| Given a Gtk::SelectionData object holding a list of targets, determines if any of the targets in targets can be used to provide text. More...
bool | targets_include_image (bool writable=true) 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. More...

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...

## Protected Attributes
GtkSelectionData* | gobject_

## Related Functions
(Note that these are not member functions.)
void | swap (SelectionData& lhs, SelectionData& rhs) noexcept
Gtk::SelectionData | wrap (GtkSelectionData* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Detailed Description

Functions for handling inter-process communication via selections.

The selection mechanism provides the basis for different types of communication between processes. In particular, drag and drop works via selections. You will very seldom or never need to use most of the functions in this section directly.

Some of the datatypes defined in this section are used in the drag-and-drop API as well. The Gdk::ContentFormats object represents lists of data types that are supported when sending or receiving data. The Gtk::SelectionData object is used to store a chunk of data along with the data type and other associated information.

## Constructor & Destructor Documentation

## ◆ SelectionData() [1/4]

Gtk::SelectionData::SelectionData | ( |  | ) |

## ◆ SelectionData() [2/4]

Gtk::SelectionData::SelectionData | ( | GtkSelectionData * | gobject,
|  | bool | make_a_copy = `true`
| ) |  |
| explicit

## ◆ SelectionData() [3/4]

Gtk::SelectionData::SelectionData | ( | const SelectionData& | other | ) |

## ◆ SelectionData() [4/4]

Gtk::SelectionData::SelectionData | ( | SelectionData&& | other | ) |
| noexcept

## ◆ ~SelectionData()

Gtk::SelectionData::~SelectionData | ( |  | ) |
| noexcept

## Member Function Documentation

## ◆ get_data() [1/2]

const guchar* Gtk::SelectionData::get_data | ( |  | ) | const

Retrieves the raw data of the selection.

Returns
  The raw data of the selection.

## ◆ get_data() [2/2]

const guchar* Gtk::SelectionData::get_data | ( | int & | length | ) | const

Retrieves the raw data of the selection along with its length.

Parameters

  length | Return location for length of the data segment.

Returns
  The raw data of the selection.

## ◆ get_data_as_string()

std::string Gtk::SelectionData::get_data_as_string | ( |  | ) | const

Retrieves the raw data of the selection as a std::string.

Returns
  The raw data of the selection. Contains 0-bytes, if the selection data does.

## ◆ get_data_type()

std::string Gtk::SelectionData::get_data_type | ( |  | ) | const

Returns the type of the data as set by SelectionData::set().

## ◆ get_display() [1/2]

Glib::RefPtr<Gdk::Display> Gtk::SelectionData::get_display | ( |  | ) |

Retrieves the display of the selection.

Returns
  The display of the selection.

## ◆ get_display() [2/2]

Glib::RefPtr<const Gdk::Display> Gtk::SelectionData::get_display | ( |  | ) | const

Retrieves the display of the selection.

Returns
  The display of the selection.

## ◆ get_format()

int Gtk::SelectionData::get_format | ( |  | ) | const

Retrieves the format of the selection.

Returns
  The format of the selection.

## ◆ get_length()

int Gtk::SelectionData::get_length | ( |  | ) | const

Retrieves the length of the raw data of the selection.

Returns
  The length of the data of the selection.

## ◆ get_pixbuf()

Glib::RefPtr<Gdk::Pixbuf> Gtk::SelectionData::get_pixbuf | ( |  | ) | const

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

Returns
  If the selection data contained a recognized image type and it could be converted to a Gdk::Pixbuf, a newly allocated pixbuf is returned, otherwise `nullptr`. If the result is non-`nullptr` it must be freed with Glib::object_unref().

## ◆ get_surface()

Cairo::RefPtr<Cairo::Surface> Gtk::SelectionData::get_surface | ( |  | ) | const

Gets the contents of the selection data as a cairo surface.

Returns
  If the selection data contained a recognized image type and it could be converted to a cairo surface, a newly allocated surface is returned, otherwise `nullptr`. If the result is non-`nullptr` it must be freed with Glib::object_unref().

## ◆ get_target()

std::string Gtk::SelectionData::get_target | ( |  | ) | const

Retrieves the target of the selection.

Since gtkmm 2.14:

## ◆ get_targets()

std::vector<std::string> Gtk::SelectionData::get_targets | ( |  | ) | const

See also Gtk::Clipboard::request_targets()

## ◆ get_text()

Glib::ustring 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 an empty string.

## ◆ get_texture()

Glib::RefPtr<Gdk::Texture> Gtk::SelectionData::get_texture | ( |  | ) | const

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

Returns
  If the selection data contained a recognized image type and it could be converted to a Gdk::Texture, a newly allocated texture is returned, otherwise `nullptr`. If the result is non-`nullptr` it must be freed with Glib::object_unref().

## ◆ get_type()

static GType Gtk::SelectionData::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ get_uris()

std::vector<Glib::ustring> Gtk::SelectionData::get_uris | ( |  | ) | const

Gets the contents of the selection data as a container of URIs.

Since gtkmm 2.6:

Returns
  If the selection data contains a list of URIs, a container containing the URIs, otherwise an empty container.

## ◆ gobj() [1/2]

GtkSelectionData* Gtk::SelectionData::gobj | ( |  | ) |
| inline

Provides access to the underlying C instance.

## ◆ gobj() [2/2]

const GtkSelectionData* Gtk::SelectionData::gobj | ( |  | ) | const
| inline

Provides access to the underlying C instance.

## ◆ gobj_copy()

GtkSelectionData* Gtk::SelectionData::gobj_copy | ( |  | ) | const

Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.

## ◆ operator=() [1/2]

SelectionData& Gtk::SelectionData::operator= | ( | const SelectionData& | other | ) |

## ◆ operator=() [2/2]

SelectionData& Gtk::SelectionData::operator= | ( | SelectionData&& | other | ) |
| noexcept

## ◆ set() [1/3]

void Gtk::SelectionData::set | ( | int | format,
|  | const guint8 * | data,
|  | int | length
| ) |  |

Assign a memory block of raw data.

Store new data into the Gtk::SelectionData object. Should only be called from a selection handler callback. A 0-byte terminates the stored data. The type of data is determined by get_target().

Parameters

  format | The data format, i.e. the number of bits in a unit.
  data | Pointer to the data (will be copied).
  length | The length of the data block in bytes.

## ◆ set() [2/3]

void Gtk::SelectionData::set | ( | const std::string & | type,
|  | int | format,
|  | const guint8 * | data,
|  | int | length
| ) |  |

Assign a memory block of raw data.

Store new data into the Gtk::SelectionData object. Should only be called from a selection handler callback. A 0-byte terminates the stored data.

Parameters

  type | The type of the selection data.
  format | The data format, i.e. the number of bits in a unit.
  data | Pointer to the data (will be copied).
  length | The length of the data block in bytes.

## ◆ set() [3/3]

void Gtk::SelectionData::set | ( | const std::string & | type,
|  | const std::string & | data
| ) |  |

Assign a string of raw data.

Store new data into the Gtk::SelectionData object. Should only be called from a selection handler callback.

Parameters

  type | The type of the selection data.
  data | A string that contains the data (does not have to be text).

## ◆ set_pixbuf()

bool Gtk::SelectionData::set_pixbuf | ( | const Glib::RefPtr< const Gdk::Pixbuf >& | pixbuf | ) |

Sets the contents of the selection from a Gdk::Pixbuf The pixbuf is converted to the form determined by selection_data->target.

Parameters

  pixbuf | A Gdk::Pixbuf.

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

## ◆ set_surface()

bool Gtk::SelectionData::set_surface | ( | const Cairo::RefPtr< const Cairo::Surface > & | surface | ) |

Sets the contents of the selection from a cairo image surface.

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

Parameters

  surface | A cairo image surface.

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

## ◆ set_text()

bool Gtk::SelectionData::set_text | ( | const Glib::ustring & | data | ) |

Assign UTF-8 encoded text.

Sets the contents of the selection from a UTF-8 encoded string. The string is converted to the form determined by get_target().

Parameters

  data | A UTF-8 encoded string.

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

## ◆ set_texture()

bool Gtk::SelectionData::set_texture | ( | const Glib::RefPtr< const Gdk::Texture >& | texture | ) |

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

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

Parameters

  texture | A Gdk::Texture.

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

## ◆ set_uris()

bool Gtk::SelectionData::set_uris | ( | const std::vector< Glib::ustring > & | uris | ) |

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

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

Parameters

  uris | A `nullptr`-terminated array of strings holding URIs.

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

## ◆ swap()

void Gtk::SelectionData::swap | ( | SelectionData& | other | ) |
| noexcept

## ◆ targets_include_image()

bool Gtk::SelectionData::targets_include_image | ( | bool | writable = `true` | ) | 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 selection_data holds a list of targets, and a suitable target for images is included, otherwise `false`.

## ◆ targets_include_text()

bool Gtk::SelectionData::targets_include_text | ( |  | ) | const

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

Returns
  `true` if selection_data holds a list of targets, and a suitable target for text is included, otherwise `false`.

## ◆ targets_include_uri()

bool Gtk::SelectionData::targets_include_uri | ( |  | ) | 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 list or URIs.

Returns
  `true` if selection_data holds a list of targets, and a suitable target for URI lists is included, otherwise `false`.

## Friends And Related Function Documentation

## ◆ swap()

void swap | ( | SelectionData& | lhs,
|  | SelectionData& | rhs
| ) |  |
| related

Parameters

  lhs | The left-hand side
  rhs | The right-hand side

## ◆ wrap()

Gtk::SelectionData wrap | ( | GtkSelectionData * | object,
|  | bool | take_copy = `false`
| ) |  |
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.

## Member Data Documentation

## ◆ gobject_

GtkSelectionData* Gtk::SelectionData::gobject_
| protected