Toc Gallery Index Tree Gtk.Selection

Description

This package implements support for the selection mechanism (ie a way to get a currently active selection anywhere on your Xserver or on your Windows machine).

This also acts as the low-level support for drag-and-drop, as described in Gtk.Dnd.

A lot of subprograms in this package work on Gdk_Atom types, instead of strings. Converting from one to the other can easily be done through calls to the subprograms in Gdk.Property (Atom_Intern and Atom_Name). The reason we use Gdk_Atom is for efficiency, since comparing two integers is of course faster than comparing two strings.

The selection mechanism is the primary mechanism by which applications can transfer data to each other on a given system. Even though both applications must be visible on the same screen, this does not mean that they can access the same files or ressources, since they might in fact be running on different machines. You should always keep this in mind when setting the data to be transfered. A selection is a essentially a named clipboard, identified by a string interned as a Gdk_Atom. By claiming ownership of a selection, an application indicates that it will be responsible for supplying its contents. 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.

Types

  • type 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");
  • type 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.
  • type 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.
  • 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.
  • type Target_Entry is record Target : Gtkada.Types.Chars_Ptr;
  • type Target_Entry_Array is array (Natural range <>) of Target_Entry;
  • type Target_Flags is new Integer;
    Used to specify constraints on an entry
  • type Target_List is new Gdk.C_Proxy;
    A list of targets. You can only manipulate this list through the functions below.

Subprograms

    Target_List

  • function Target_List_New (Targets : Target_Entry_Array) return Target_List;
    Create a new list of target, starting from an array.
  • 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.
  • 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.
  • 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.
  • procedure Target_List_Add_Table (List : Target_List; Targets : Target_Entry_Array);
    Add a new set of targets to the list.
  • 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.
  • 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.
  • 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.
  • procedure Target_List_Remove (List : Target_List; Target : Gdk.Types.Gdk_Atom);
    Remove a specific target from the list.
  • 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_Data

  • function Selection_Get_Type return Glib.GType;
    Return the internal type used for a selection
  • function Get_Selection (Selection : Selection_Data) return Gdk_Selection;
    Return the selection used (primary, clipboard, ...)
  • 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).
  • 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.
  • 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.
  • 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.
  • 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.
  • function Get_Length (Selection : Selection_Data) return Gint;
    Return the length of the data.
  • Setting and getting contents

  • 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.
  • 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.
  • 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
  • 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).
  • 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.
  • 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.
  • 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.
  • 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.
  • 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".
  • 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.
  • 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.
  • function Selection_Data_Copy (Selection : Selection_Data) return Selection_Data;
    Make a copy of a selection data.
  • procedure Selection_Data_Free (Selection : Selection_Data);
    Free a Selection_Data structure returned from Selection_Data_Copy.
  • Manipulating the selection

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

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

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

Signals

Testgtk source code

This code is part of testgtk, a demo application packaged with GtkAda. Testgtk demonstrates the various widgets of GtkAda
----------------------------------------------------------------------- -- GtkAda - Ada95 binding for the Gimp Toolkit -- -- -- -- Copyright (C) 2000 -- -- Emmanuel Briot, Joel Brobecker and Arnaud Charlet -- -- Copyright (C) 2001-2006 AdaCore -- -- -- -- This library is free software; you can redistribute it and/or -- -- modify it under the terms of the GNU General Public -- -- License as published by the Free Software Foundation; either -- -- version 2 of the License, or (at your option) any later version. -- -- -- -- This library is distributed in the hope that it will be useful, -- -- but WITHOUT ANY WARRANTY; without even the implied warranty of -- -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -- -- General Public License for more details. -- -- -- -- You should have received a copy of the GNU General Public -- -- License along with this library; if not, write to the -- -- Free Software Foundation, Inc., 59 Temple Place - Suite 330, -- -- Boston, MA 02111-1307, USA. -- -- -- -- -- -- -- -- -- -- ----------------------------------------------------------------------- with Gtk.Frame; use Gtk.Frame; with Gtk.Button; use Gtk.Button; with Gtk.Clipboard; use Gtk.Clipboard; with Gtk.Text_Iter; use Gtk.Text_Iter; with Gtk.Text_View; use Gtk.Text_View; with Gtk.Text_Buffer; use Gtk.Text_Buffer; with Gtk.Box; use Gtk.Box; with Gtk.Handlers; use Gtk.Handlers; with Gtk.Label; use Gtk.Label; with Gtk.Scrolled_Window; use Gtk.Scrolled_Window; package body Create_Selection is type My_Button_Record is new Gtk_Button_Record with record Text : Gtk_Text_Buffer; Text_View : Gtk_Text_View; Label : Gtk_Label; end record; type My_Button is access all My_Button_Record'Class; package My_Button_Handler is new Gtk.Handlers.Callback (My_Button_Record); ---------- -- Help -- ---------- function Help return String is begin return "This package demonstrates how to interact with the clipboard to" & " retrieve text copied from other applications" & ASCII.LF & "Try selecting some other text outside of this demo, and press" & " once again the button at the top."; end Help; --------------------- -- On_Button_Click -- --------------------- procedure On_Button_Click (Button : access My_Button_Record'Class) is Text : constant String := Wait_For_Text (Gtk.Clipboard.Get); Iter : Gtk_Text_Iter; begin -- For the text buffer, we query directly the clipboard Get_End_Iter (Button.Text, Iter); Insert (Button.Text, Iter, Text); end On_Button_Click; --------- -- Run -- --------- procedure Run (Frame : access Gtk.Frame.Gtk_Frame_Record'Class) is Box : Gtk_Box; Button : My_Button; Scrolled : Gtk_Scrolled_Window; begin Set_Label (Frame, "Selection"); Gtk_New_Vbox (Box, Homogeneous => False); Add (Frame, Box); Button := new My_Button_Record; Initialize (Button, "Paste the selection/clipboard"); Pack_Start (Box, Button, Fill => False, Expand => False); My_Button_Handler.Connect (Button, "clicked", My_Button_Handler.To_Marshaller (On_Button_Click'Access)); -- The text Gtk_New (Scrolled); Pack_Start (Box, Scrolled, Fill => True, Expand => True); Gtk_New (Button.Text); Gtk_New (Button.Text_View, Button.Text); Add (Scrolled, Button.Text_View); Show_All (Frame); end Run; end Create_Selection;

Alphabetical Index