Index

Package: Selection

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 

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 

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 

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 

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 

type Target_Flags is new Integer;
Used to specify constraints on an entry

Target_Entry 

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 

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

Target_List 

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 (Gdk_Selection) 

Selection_Primary   : constant Gdk_Selection;

Selection_Secondary (Gdk_Selection) 

Selection_Secondary : constant Gdk_Selection;

Selection_Type_Atom (Gdk_Selection_Type) 

Selection_Type_Atom     : constant Gdk_Selection_Type;
A Gdk_Atom (format=32 bits)

Selection_Type_Bitmap (Gdk_Selection_Type) 

Selection_Type_Bitmap   : constant Gdk_Selection_Type;
A Gdk_Bitmap Id (format=32 bits)

Selection_Type_Colormap (Gdk_Selection_Type) 

Selection_Type_Colormap : constant Gdk_Selection_Type;
A colormap Id (format=32 bits)

Selection_Type_Drawable (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 (Gdk_Selection_Type) 

Selection_Type_Integer  : constant Gdk_Selection_Type;
An integer (format=32 bits)

Selection_Type_Pixmap (Gdk_Selection_Type) 

Selection_Type_Pixmap   : constant Gdk_Selection_Type;
A Gdk_Pixmap ID (format=32 bits)

Selection_Type_Window (Gdk_Selection_Type) 

Selection_Type_Window   : constant Gdk_Selection_Type;
A Gdk_Window ID (format=32 bits)

Selection_Type_String (Gdk_Selection_Type) 

Selection_Type_String   : constant Gdk_Selection_Type;
A string encoded in Iso-latin1 format (format=8 bits per character)

Target_Bitmap (Gdk_Target) 

Target_Bitmap   : constant Gdk_Target;

Target_Colormap (Gdk_Target) 

Target_Colormap : constant Gdk_Target;

Target_Drawable (Gdk_Target) 

Target_Drawable : constant Gdk_Target;

Target_Pixmap (Gdk_Target) 

Target_Pixmap   : constant Gdk_Target;

Target_String (Gdk_Target) 

Target_String   : constant Gdk_Target;

Target_No_Constraint (Target_Flags) 

Target_No_Constraint : constant Target_Flags;
No constraint is specified.

Target_Same_App (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 (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 (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 

function Target_List_New 
(Targets: Target_Entry_Array) return Target_List;
Create a new list of target, starting from an array.

Target_List_Ref 

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 

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 

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 

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 

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 

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 

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 

procedure Target_List_Remove 
(List: Target_List;
Target: Gdk.Types.Gdk_Atom);
Remove a specific target from the list.

Target_List_Find 

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 

function Selection_Get_Type return Glib.GType;
Return the internal type used for a selection

Get_Selection 

function Get_Selection 
(Selection: Selection_Data) return Gdk_Selection;
Return the selection used (primary, clipboard, ...)

Get_Target 

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 

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 

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 

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 

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 

function Get_Length 
(Selection: Selection_Data) return Gint;
Return the length of the data.

Set_Pixbuf 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

function Selection_Data_Copy 
(Selection: Selection_Data) return Selection_Data;
Make a copy of a selection data.

Selection_Data_Free 

procedure Selection_Data_Free 
(Selection: Selection_Data);
Free a Selection_Data structure returned from Selection_Data_Copy.

Owner_Set 

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 

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 

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 

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 

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 

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.