Functions for handling inter-process communication via selections

Description

The selection mechanism provides the basis for different types of communication between processes. In particular, drag and drop and Gnome::Gtk3::Clipboard work via selections. You will very seldom or never need to use most of the functions in this section directly; Gnome::Gtk3::Clipboard provides a nicer interface to the same functionality.

If an application is expected to exchange image data and work on Windows, it is highly advised to support at least "image/bmp" target for the widest possible compatibility with third-party applications. Gnome::Gtk3::Clipboard already does that by using gtk-target-list-add-image-targets() and set-pixbuf() or get-pixbuf(), which is one of the reasons why it is advised to use Gnome::Gtk3::Clipboard.

Some of the datatypes defined this section are used in the Gnome::Gtk3::Clipboard and drag-and-drop API’s as well. The

Gnome::Gtk3::TargetList object represent lists of data types that are supported when sending or receiving data. The Gnome::Gtk3::SelectionData object is used to store a chunk of data along with the data type and other associated information.

See Also

Gnome::Gtk3::Widget - Much of the operation of selections happens via signals for Gnome::Gtk3::Widget. In particular, if you are using the functions in this section, you may need to pay attention to selection-get, selection-received and selection-clear-event signals.

Synopsis

Declaration

unit class Gnome::Gtk3::SelectionData;
also is Gnome::GObject::Boxed;

Methods

new

:native-object

Create a SelectionData object using a native object from elsewhere. This data is mostly provided to signal handlers

multi method new ( N-GObject :$native-object! )

add-target

Appends a specified target to the list of supported targets for a given widget and selection.

method add-target (
  N-GObject $widget, Gnome::Gdk3::Atom $selection,
  Gnome::Gdk3::Atom $target, UInt $info
)

• N-GObject $widget; a Gnome::Gtk3::Widget

• Gnome::Gdk3::Atom $selection; the selection

• Gnome::Gdk3::Atom $target; target to add.

• UInt $info; A unsigned integer which will be passed back to the application.

add-targets

Prepends a table of targets to the list of supported targets for a given widget and selection.

method add-targets (
  N-GObject $widget, Gnome::Gdk3::Atom $selection,
  Array[Gnome::Gtk3::TargetEntry] $targets
)

• N-GObject $widget; a Gnome::Gtk3::Widget

• Gnome::Gdk3::Atom $selection; the selection

• $targets; an array of Gnome::Gtk3::TargetEntry targets to add

clear-targets

Remove all targets registered for the given selection for the widget.

method clear-targets ( N-GObject $widget, Gnome::Gdk3::Atom $selection )

• N-GObject $widget; a Gnome::Gtk3::Widget

• Gnome::Gdk3::Atom $selection; an atom representing a selection

convert

Requests the contents of a selection. When received, a “selection-received” signal will be generated.

Returns: True if requested succeeded. False if we could not process request. (e.g., there was already a request in process for this widget).

method convert (
  N-GObject $widget, Gnome::Gdk3::Atom $selection,
  Gnome::Gdk3::Atom $target, UInt $time --> Bool
)

• N-GObject $widget; The widget which acts as requestor

• Gnome::Gdk3::Atom $selection; Which selection to get

• Gnome::Gdk3::Atom $target; Form of information desired (e.g., STRING)

• UInt $time; Time of request (usually of triggering event)

copy

Makes a copy of a Gnome::Gtk3::SelectionData-struct and its data.

Returns: a pointer to a copy of data.

method copy ( N-GObject $data --> N-GObject )

• N-GObject $data; a pointer to a Gnome::Gtk3::SelectionData-struct.

free

Frees a Gnome::Gtk3::SelectionData-struct returned from copy().

method free ( N-GObject $data )

• N-GObject $data; a pointer to a Gnome::Gtk3::SelectionData-struct.

get

Raku convenience routine to get data.

method get (
  :$data-type! where * ~~ any(Int,Num,Rat,Str,Buf) = Int
  --> Any
)

• $data-type; a raku data type which is used to retrieve the data from the selection data structure.

get-data

Retrieves the raw data of the selection.

Returns: the raw data of the selection.

method get-data ( --> Pointer )

get-data-type

Retrieves the data type of the selection.

Returns: the data type of the selection.

method get-data-type ( --> Gnome::Gdk3::Atom )

get-data-with-length

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

method get-data-with-length ( --> List )

Returns a List;

• Pointer to the raw data of the selection

• Int length of the data

get-display

Retrieves the display of the selection.

Returns: the display of the selection.

method get-display ( --> N-GObject )

get-format

Retrieves the format of the selection.

Returns: the format of the selection.

method get-format ( --> Int )

get-length

Retrieves the length of the raw data of the selection.

method get-length ( --> Int )

get-pixbuf

Gets the contents of the selection data as a Gnome::Gdk3::Pixbuf.

Returns: if the selection data contained a recognized image type and it could be converted to a Gnome::Gdk3::Pixbuf, a newly allocated pixbuf is returned, otherwise undefined. If the result is non-undefined it must be freed with g-object-unref().

method get-pixbuf ( --> Gnome::Gdk3::Pixbuf )

get-selection

Retrieves the selection Gnome::Gtk3::Atom of the selection data.

method get-selection ( --> Gnome::Gdk3::Atom )

get-target

Retrieves the target of the selection.

method get-target ( --> Gnome::Gdk3::Atom )

get-targets

Gets the contents of selection-data as an array of targets. This can be used to interpret the results of getting the standard TARGETS target that is always supplied for any selection.

Returns: True if selection-data contains a valid array of targets, otherwise False.

method get-targets (, Gnome::Gdk3::Atom $targets --> Bool )

• Gnome::Gdk3::Atom $targets; (array length=n-atoms) (transfer container): location to store an array of targets. The result stored here must be freed with g-free().

• Int $n_atoms; location to store number of items in targets.

get-text

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 newly allocated string containing the converted text, otherwise undefined.

method get-text ( --> Str )

get-uris

Gets the contents of the selection data as array of URIs.

Returns: an Array if the selection data contains a list of URIs, otherwise empty.

method get-uris ( --> Array )

set

Stores new data into a Gnome::Gtk3::SelectionData object. Should only be called from a selection handler callback.

method set (
  N-GObject $type, $data, Int :$format where * ~~ any(8,16,32) = 32
)

• N-GObject $type; the type of selection data. A Gnome::Gdk3::Atom

• $data; data which can be of type Int, Num, Rat, Array[ Int, Num or Rat], Str or Buf.

• Int() $format; format (number of bits per value). Default set to 32 for numbers and 8 for strings. Only usefull to set to 8 or 16 when integers are small. Num and Rat are always set to 32.

Example

# the method to handle a drag-data-get signal on the source widget
method get (
  N-GObject $context, N-GObject $selection-data, UInt $info, UInt $time,
  :_widget($widget)
) {
  my Gnome::Gtk3::SelectionData $sd .= new(:native-object($selection-data));

  # check for target name to decide what to provide
  my Gnome::Gdk3::Atom $atom .= new(:native-object($sd.get-target));
  if $atom.name eq 'number' {
    # we provide a 16 bit integer
    $sd.set( $!targets<number>, $number, :format(16));
  }
  …
}


# the method to handle a drag-data-received signal on the
# destination widget
method received (
  N-GObject $context, Int $x, Int $y,
  N-GObject $data, UInt $info, UInt $time, :_widget($widget)
) {
  my Gnome::Gtk3::SelectionData $sd .= new(:native-object($data));
  my Gnome::Gdk3::Atom $atom .= new(:native-object($sd.get-target));
  if $atom.name eq 'number' and (my $num = $sd.get).defined {
      …
  }
  …
}

set-pixbuf

Sets the contents of the selection from a Gnome::Gtk3::Pixbuf The pixbuf is converted to the form determined by selection data target.

Returns: True if the selection was successfully set, otherwise False.

method set-pixbuf ( N-GObject $pixbuf --> Bool )

• N-GObject $pixbuf; a Gnome::Gtk3::Pixbuf

set-text

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

Returns: True if the selection was successfully set, otherwise False.

method set-text ( Str $str --> Bool )

• Str $str; a UTF-8 string

• Int() $len; the length of str, or -1 if str is nul-terminated.

set-uris

Sets the contents of the selection from a list of URIs. The string is converted to the form determined by selection-data->target.

Returns: True if the selection was successfully set, otherwise False.

method set-uris (, CArray[Str] $uris --> Bool )

• CArray[Str] $uris; a undefined-terminated array of strings holding URIs

owner-set

Claims ownership of a given selection for a particular widget, or, if widget is undefined, release ownership of the selection.

Returns: True if the operation succeeded

method owner-set (
  N-GObject $widget, Gnome::Gdk3::Atom $selection, UInt $time
  --> Bool
)

• N-GObject $widget; a Gnome::Gtk3::Widget, or undefined.

• Gnome::Gdk3::Atom $selection; an interned atom representing the selection to claim

• UInt $time; timestamp with which to claim the selection

owner-set-for-display

Claim ownership of a given selection for a particular widget, or, if widget is undefined, release ownership of the selection.

Returns: TRUE if the operation succeeded

method owner-set-for-display ( N-GObject $display, N-GObject $widget, Gnome::Gdk3::Atom $selection, UInt $time --> Bool )

• N-GObject $display; the Gnome::Gtk3::Display where the selection is set

• N-GObject $widget; new selection owner (a Gnome::Gtk3::Widget), or undefined.

• Gnome::Gdk3::Atom $selection; an interned atom representing the selection to claim.

• UInt $time; timestamp with which to claim the selection

remove-all

Removes all handlers and unsets ownership of all selections for a widget. Called when widget is being destroyed. This function will not generally be called by applications.

method remove-all ( N-GObject $widget )

• N-GObject $widget; a Gnome::Gtk3::Widget