GtkAda Reference Manual - Package Gtk.Selection

[Contents] [Back] [Prev] [Up] [Next] [Forward]

# Package Gtk.Selection

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://www.freedesktop.org/standards/clipboards.txt for more information on the way selection works on X-Window systems.

- Gtk.Selection Signals
- Gtk.Selection Types
- Gtk.Selection Subprograms

## Signals

- "selection_get" procedure Handler (Widget : access Gtk_Widget_Record'Class;
  Data : Selection_Data;
  Info : Guint;
  Time : Guint);
  This signal is sent to the owner of a selection whenever some other widget wants to get data from that selection. The type of the data is indicated in Info, and is the third field that was set in the Target_Entrys for that specific widget and selection. The handler should modify the Data in the selection.
- "selection_received" procedure Handler (Widget : access Gtk_Widget_Record'Class;
  Data : Selection_Data;
  Time : Guint);
  This signal is sent to the receiver end of a selection, when the data has been sent by the owner. The receiver should call Convert, which will emit the signal selection_get to ask for the contents of the selection, and then selection_received will be emitted to warn the receiver. Note: you can not connect this signal to a widget that does not have an associated Gdk_Window (i.e the flag Gtk.Widget.No_Window must not be set for this widget), since it needs to be able to receive Property_Notify events from the server. It will not work with a Gtk_Label for instance.

## Types

    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");
    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.
    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.
    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;
        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.
    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_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 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          : in     Selection_Data)
       return Gint;
| Return the length of the data.
    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
    function Make_Atom
      (Num                :        Gulong)
       return Gdk.Types.Gdk_Atom;

[Contents] [Back] [Prev] [Up] [Next] [Forward]