## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

## Index

Package: Selection

- Goto spec source

# Description

    package Gtk.Selection is

The contents of a selection can be represented in a number of formats, called targets. Each target is identified by an atom. A list of all possible targets supported by the selection owner can be retrieved by requesting the special target TARGETS. When a selection is retrieved, the data is accompanied by a type (an atom), and a format (an integer, representing the number of bits per item). See also http://standards.freedesktop.org/clipboards-spec/ for more information on the way selection works on X-Window systems. </description>

Binding from C File version 2.8.17

<testgtk>create_selection.adb</testgtk>

# Types

### Selection_Data

- Goto declaration in source

    type Selection_Data is new Gdk.C_Proxy;

Contents of a selection or a drag-and-drop operation. This structure can only be created internally by GtkAda. However, you need to be able to access it to get the selection. - Selection and Target identify the request. - Type specifies the type of the return. - if Length is negative, the Data should be ignored. Otherwise, it contains the data itself. - Time gives the timestamp at which the data was sent.

### Gdk_Selection

- Goto declaration in source

    subtype Gdk_Selection is Gdk.Types.Gdk_Atom;

These are predefined atom values for several common selections. You are of course free to create new ones, but most of the time you should simply use Selection_Primary unless you foresee the need for multiple simultaneous selections. To access the clipboard on windows machines, you might need to create a new selection with Gdk.Property.Atom_Intern ("CLIPBOARD");

### Gdk_Selection_Type

- Goto declaration in source

    subtype Gdk_Selection_Type is Gdk.Types.Gdk_Atom;

Predefined atom values for selection types. Although the preferred way in GtkAda to indicate the type of a selection is to use mime types, these values are provided for compatibility with older X11 applications.

### Gdk_Target

- Goto declaration in source

    subtype Gdk_Target is Gdk.Types.Gdk_Atom;

Predefined atom values which are used to describe possible targets for a selection. Other atoms can be used, and the recommended practice for GtkAda is to to use mime types for this purpose. However, supporting these types may be useful for compatibility with older programs.

### Target_Flags

- Goto declaration in source

    type Target_Flags is new Integer;

Used to specify constraints on an entry

### Target_Entry

- Goto declaration in source

    type Target_Entry is record
          Target : Gtkada.Types.Chars_Ptr;
          Flags  : Target_Flags;
          Info   : Guint;
       end record;

A single type of data that can be supplied or received during a drag-and-drop or a selection. Target is a string that represents the drag type. This can be any string if you want to implement drag-and-drop inside your application. However, if you want to communicate with other external application, you should use MIME types, ie "text/plain", "text/uri-list", ... See the RFCs 2045, 2046, 2047, 2048, 2049 for more information on MIME types. For more information, see ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/ Another set of supported names are the ones associated with the X Inter-Client Communications Conventions Manual (ICCCM). Here some of the default names and their meaning. See the ICCCM manual online for a complete list (for instance at http://www.tronche.com/gui/x/icccm/). - "TIMESTAMP" (type Integer) Timestamp used to acquire the selection - "TEXT" (type Text) Text in owner's encoding - "STRING" (type String) Iso Latin1 text - "PIXMAP" (type Drawable) Pixmap Id - "BITMAP" (type Bitmap) Bitmap Id - "FOREGROUND" (type Pixel) Pixel Value - "BACKGROUND" (type Pixel) Pixel Value Info is an application-assigned integer (i.e. that you choose), that will be passed as a signal parameter for all the dnd-related signals, like "selection_get". This saves a lot of expensive string compares, and in fact replaced Target everywhere in your application expect in Source_Set and Dest_Set.

### Target_Entry_Array

- Goto declaration in source

    type Target_Entry_Array is array (Natural range <>) of Target_Entry;

### Target_List

- Goto declaration in source

    type Target_List is new Gdk.C_Proxy;

A list of targets. You can only manipulate this list through the functions below.

# Constants & Global variables

### Selection_Primary

- Goto declaration in source

(Gdk_Selection)

    Selection_Primary   : constant Gdk_Selection;

### Selection_Secondary

- Goto declaration in source

(Gdk_Selection)

    Selection_Secondary : constant Gdk_Selection;

### Selection_Type_Atom

- Goto declaration in source

(Gdk_Selection_Type)

    Selection_Type_Atom     : constant Gdk_Selection_Type;

A Gdk_Atom (format=32 bits)

### Selection_Type_Bitmap

- Goto declaration in source

(Gdk_Selection_Type)

    Selection_Type_Bitmap   : constant Gdk_Selection_Type;

A Gdk_Bitmap Id (format=32 bits)

### Selection_Type_Colormap

- Goto declaration in source

(Gdk_Selection_Type)

    Selection_Type_Colormap : constant Gdk_Selection_Type;

A colormap Id (format=32 bits)

### Selection_Type_Drawable

- Goto declaration in source

(Gdk_Selection_Type)

    Selection_Type_Drawable : constant Gdk_Selection_Type;

A drawable Id (format=32 bits), ie the result of Gdk.Window.Get_Window.

### Selection_Type_Integer

- Goto declaration in source

(Gdk_Selection_Type)

    Selection_Type_Integer  : constant Gdk_Selection_Type;

An integer (format=32 bits)

### Selection_Type_Pixmap

- Goto declaration in source

(Gdk_Selection_Type)

    Selection_Type_Pixmap   : constant Gdk_Selection_Type;

A Gdk_Pixmap ID (format=32 bits)

### Selection_Type_Window

- Goto declaration in source

(Gdk_Selection_Type)

    Selection_Type_Window   : constant Gdk_Selection_Type;

A Gdk_Window ID (format=32 bits)

### Selection_Type_String

- Goto declaration in source

(Gdk_Selection_Type)

    Selection_Type_String   : constant Gdk_Selection_Type;

A string encoded in Iso-latin1 format (format=8 bits per character)

### Target_Bitmap

- Goto declaration in source

(Gdk_Target)

    Target_Bitmap   : constant Gdk_Target;

### Target_Colormap

- Goto declaration in source

(Gdk_Target)

    Target_Colormap : constant Gdk_Target;

### Target_Drawable

- Goto declaration in source

(Gdk_Target)

    Target_Drawable : constant Gdk_Target;

### Target_Pixmap

- Goto declaration in source

(Gdk_Target)

    Target_Pixmap   : constant Gdk_Target;

### Target_String

- Goto declaration in source

(Gdk_Target)

    Target_String   : constant Gdk_Target;

### Target_No_Constraint

- Goto declaration in source

(Target_Flags)

    Target_No_Constraint : constant Target_Flags;

No constraint is specified.

### Target_Same_App

- Goto declaration in source

(Target_Flags)

    Target_Same_App      : constant Target_Flags;

If this is set, the target will only be selected for drags within a single application.

### Target_Same_Widget

- Goto declaration in source

(Target_Flags)

    Target_Same_Widget   : constant Target_Flags;

If this is set, the target will only be selected for drags within a single widget.

### Any_Target_Entry

- Goto declaration in source

(Target_Entry_Array)

    Any_Target_Entry : Target_Entry_Array (1 .. 0);

To be used for drop sites that accept any kind of data.

# Subprograms & Entries

### Target_List_New

- Goto spec in source

    function Target_List_New (Targets: Target_Entry_Array) return Target_List;

Create a new list of target, starting from an array.

### Target_List_Ref

- Goto spec in source
- Goto body in source

    procedure Target_List_Ref (List: Target_List);

Increment the reference count for the list. You should almost never have to use this function, this is done transparently by GtkAda.

### Target_List_Unref

- Goto spec in source
- Goto body in source

    procedure Target_List_Unref (List: Target_List);

Decrement the reference count for the list. You should almost never have to use this function, since everything is done transparently by GtkAda. As usual, the list is freed when the reference count reaches 0.

### Target_List_Add

- Goto spec in source
- Goto body in source

    procedure Target_List_Add (List: Target_List;Target: Gdk.Types.Gdk_Atom;Flags: Guint;Info: Guint);

Add a new target to the list. You can for instance use the result of Get_Targets (Drag_Context) for the value of Target.

### Target_List_Add_Table

- Goto spec in source

    procedure Target_List_Add_Table (List: Target_List;Targets: Target_Entry_Array);

Add a new set of targets to the list.

### Target_List_Add_Text_Targets

- Goto spec in source
- Goto body in source

    procedure Target_List_Add_Text_Targets (List: Target_List;Info: Guint);

Appends the text targets supported internally by gtk+ to List. All targets are added with the same info. Info will be passed back to the application.

### Target_List_Add_URI_Targets

- Goto spec in source
- Goto body in source

    procedure Target_List_Add_URI_Targets (List: Target_List;Info: Guint);

Appends the URI targets supported internally by gtk+ to List. All targets are added with the same info.

### Target_List_Add_Image_Targets

- Goto spec in source

    procedure Target_List_Add_Image_Targets (List: Target_List;Info: Guint;Writable: Boolean);

Appends the image targets supported internally by gtk+ to List. All targets are added with the same info. If Writable is True, then only those targets for which gtk+ knows how to convert a Gdk_Pixbuf into the format are added.

### Target_List_Remove

- Goto spec in source
- Goto body in source

    procedure Target_List_Remove (List: Target_List;Target: Gdk.Types.Gdk_Atom);

Remove a specific target from the list.

### Target_List_Find

- Goto spec in source

    procedure Target_List_Find (List: Target_List;Target: Gdk.Types.Gdk_Atom;Info: out Guint;Found: out Boolean);

Search for a specific target in the list. If the target was found, Found is set to True and Info contains the integer that was associated with the target when it was created.

### Selection_Get_Type

- Goto spec in source
- Goto body in source

    function Selection_Get_Type return Glib.GType;

Return the internal type used for a selection

### Get_Selection

- Goto spec in source
- Goto body in source

    function Get_Selection (Selection: Selection_Data) return Gdk_Selection;

Return the selection used (primary, clipboard, ...)

### Get_Target

- Goto spec in source
- Goto body in source

    function Get_Target (Selection: Selection_Data) return Gdk.Types.Gdk_Atom;

Return the target of the selection (ie a MIME string that identifies the selection).

### Get_Type

- Goto spec in source
- Goto body in source

    function Get_Type (Selection: Selection_Data) return Gdk.Types.Gdk_Atom;

Return the type of the selection, as defined in Gdk_Selection_Type, ie for compatibility with older X11 applications.

### Get_Format

- Goto spec in source
- Goto body in source

    function Get_Format (Selection: Selection_Data) return Gint;

Return the format of the data. The semantics depends on the type of data. For instance, for strings this is the number of bits per character.

### Get_Data

- Goto spec in source
- Goto body in source

    function Get_Data (Selection: Selection_Data) return System.Address;

Return the data of the selection. This should be ignored if Get_Length returns a value < 0.

### Get_Data_As_String

- Goto spec in source

    function Get_Data_As_String (Selection: Selection_Data) return String;

Return the data as a string. This is only a convenience function, since it simply creates a string from the return of Get_Data.

### Get_Length

- Goto spec in source
- Goto body in source

    function Get_Length (Selection: Selection_Data) return Gint;

Return the length of the data.

### Set_Pixbuf

- Goto spec in source

    function Set_Pixbuf (Selection: Selection_Data;Pixbuf: Gdk.Pixbuf.Gdk_Pixbuf) return Boolean;

Sets the contents of the selection from a pixbuf The pixbuf is converted to the form determined by Get_Target (Selection_Data). Returns True if the selection was successfully set.

### Get_Pixbuf

- Goto spec in source

    function Get_Pixbuf (Selection: Selection_Data) return Gdk.Pixbuf.Gdk_Pixbuf;

Gets the contents of the selection data as a pixbuf. Return value: if the selection data contained a recognized image type and it could be converted to a pixbuf, a newly allocated pixbuf is returned, otherwise null. If the result is non-null it must be freed with Unref.

### Targets_Include_Image

- Goto spec in source

    function Targets_Include_Image (Selection: Selection_Data;Writable: Boolean := True) return Boolean;

Given a Selection object holding a list of targets, determines if any of the targets in these targets can be used to provide a Gdk.Pixbuf. Writable: whether to accept only targets for which gtk+ knows how to convert a pixbuf into the format. Returns True if Selection holds a list of targets and a suitable target for images is included

### Set_Text

- Goto spec in source

    function Set_Text (Selection: Selection_Data;Str: UTF8_String) return Boolean;

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

### Get_Text

- Goto spec in source

    function Get_Text (Selection: Selection_Data) return UTF8_String;

Gets the contents of the selection data as a UTF-8 string. Return value: if the selection data contained a recognized text type and it could be converted to UTF-8, the string is returned.

### Targets_Include_Text

- Goto spec in source

    function Targets_Include_Text (Selection: Selection_Data) return Boolean;

Given a Selection object holding a list of targets, determines if any of the targets can be used to provide text.

### Set_Uris

- Goto spec in source

    function Set_Uris (Selection: Selection_Data;URIs: GNAT.Strings.String_List) return Boolean;

Sets the contents of the selection from a list of URIs. The string is converted to the form determined by Get_Target (Selection). Return True if the selection was successfully set.

### Get_Uris

- Goto spec in source

    function Get_Uris (Selection: Selection_Data) return GNAT.Strings.String_List;

Gets the contents of the selection data as array of URIs. The returned value must be freed by the caller.

### Get_Targets

- Goto spec in source

    function Get_Targets (Selection: Selection_Data) return Gdk.Types.Gdk_Atom_Array;

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. This is different from Get_Target, which indicate the current format that the selection contains. Get_Targets only applies when Get_Target is "TARGETS".

### Selection_Data_Set

- Goto spec in source
- Goto body in source

    procedure Selection_Data_Set (Selection: Selection_Data;The_Type: Gdk.Types.Gdk_Atom;Format: Gint;Data: System.Address;Length: Gint);

General form of Selection_Data_Set. Any data can be transmitted. Length is the number of bytes in Data.

### Selection_Data_Set

- Goto spec in source

    procedure Selection_Data_Set (Selection: Selection_Data;The_Type: Gdk.Types.Gdk_Atom;Format: Gint;Data: String);

Set the data for a selection (special case for strings) This function is generally called when a drag-and-drop operation ask the source widget for the data to be transmitted. In that case, a Selection_Data was already transmitted and is given as a handler parameter for the signal "drag_data_get". The_Type can simply be extracted from the Selection_Data.

### Selection_Data_Copy

- Goto spec in source
- Goto body in source

    function Selection_Data_Copy (Selection: Selection_Data) return Selection_Data;

Make a copy of a selection data.

### Selection_Data_Free

- Goto spec in source
- Goto body in source

    procedure Selection_Data_Free (Selection: Selection_Data);

Free a Selection_Data structure returned from Selection_Data_Copy.

### Owner_Set

- Goto spec in source

    function Owner_Set (Widget: Gtk.Widget.Gtk_Widget;Selection: Gdk_Selection := Selection_Primary;Time: Guint32 := 0) return Boolean;

Claim ownership of a given selection for a particular widget, or, if widget is null, release ownership of the selection. Once a Widget has claimed selection, it is responsible for delivering the data whenever it is needed. Time is the timestamp for claiming the selection (default is the current time). This function returns True if the operation succeeded.

### Add_Target

- Goto spec in source

    procedure Add_Target (Widget: access Gtk.Widget.Gtk_Widget_Record'Class;Selection: Gdk_Selection;Target: Gdk.Types.Gdk_Atom;Info: Guint);

Add specified target to the list of supported targets for a given widget and selection. Info is an integer which will be passed back to the application instead of a string when the target is used.

### Add_Targets

- Goto spec in source

    procedure Add_Targets (Widget: access Gtk.Widget.Gtk_Widget_Record'Class;Selection: Gdk_Selection;Targets: Target_Entry_Array);

Add a set of targets to the list of supported targets for a given widget and selection.

### Clear_Targets

- Goto spec in source

    procedure Clear_Targets (Widget: access Gtk.Widget.Gtk_Widget_Record'Class;Selection: Gdk_Selection);

Clear the list of supported targets for a given widget and selection.

### Convert

- Goto spec in source

    function Convert (Widget: access Gtk.Widget.Gtk_Widget_Record'Class;Selection: Gdk_Selection := Selection_Primary;Target: Gdk.Types.Gdk_Atom;Time: Guint32 := 0) return Boolean;

Request the contents of a selection. When received, a "selection_received" signal will be generated, and the widget needs to have a handler for it. Target is the form of information desired, for instance an intern Gdk_Atom whose name is "text/plain", or one of the Gdk_Target values. This function returns True if the request succeeded, False if the request could not be processed, for instance if there was already a request in process for this widget or this target is not known by the owner of the selection. Widget is the widget which acts as a requestor.

### Remove_All

- Goto spec in source

    procedure Remove_All (Widget: access Gtk.Widget.Gtk_Widget_Record'Class);

Remove 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.