Like all modern GUI toolkits, GtkAda has a full support for drag-and-drop operations. This is a mechanism for interactively transferring data between two widgets, either in the same application or in two different applications. The user clicks on a widget (called a "drag source"), and, while keeping the mouse button pressed, moves it to another widget, where the mouse button is released (this other widget is called a "drop site"). As a result, and if both widgets can handle the same type of data, some data is either copied or moved to this new widget.
This is a very intuitive way, in some cases, to enhance the usability of your application, although you should carefully consider whether this should be used or not.
GtkAda supports several drag-and-drop protocols, so as to be able to communicate with the maximum number of applications. These protocols are Xdnd and Motif.
Below is a summary of what is needed to add drag-and-drop capabilities to your application. We highly recommend that you look at, and understand, the example in testgtk (create_dnd.adb), before using these features in your own application.
See also the package Gtk.Selection, that contains some lower subprograms and data types that are used when implementing drag-and-drop.
You need to call Source_Set, specifying which mouse buttons can activate the drag, which types of data will be given, and which kind of action will be performed. You then need to connect to the signal "drag_data_get", that will be emitted when the user has dropped the item and GtkAda needs to find the data. You must call Selection_Data_Set in the handler to set the actual data. You can also connect the widget to "drag_data_delete", which will be called whenever the data set for the selection is no longer required and should be deleted. The signal will be emitted only if the drop site requests it, or if the selected action for the drag-and-drop operation was Action_Move. It will not be called automatically for an Action_Copy. Note that the callback might be called several times, if for instance this was an Action_Move, and the drop site requires explicitly to delete the data in its call to Finish.
You need to call Dest_Set, specifying which types of Data are accepted by the widget, which actions are recognized, and whether you accept drops from external applications. You also need to connect to "drag_data_received", that will be emitted when the user has dropped some data on the widget. The handler should call Finish, to warn the source widget that the drag and drop operation is finished, and whether it was successful or not.
Signals |
---|
Types |
---|
type Dest_Defaults is new Integer; | |
Specify the various types of action that will be taken on behalf of the
user for a drag destination site.
|
Subprograms |
---|
Setting up a widget as a destination | ||
procedure Dest_Set (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Flags : Dest_Defaults := Dest_No_Default; Targets : Target_Entry_Array := Any_Target_Entry; Actions : Drag_Action := Action_Any); | ||
Set a widget as a potential drop destination. Flags specifies what action GtkAda should take on behalf of a widget for drops onto that widget. The Targets and Actions fields are used only if Dest_Default_Motion or Dest_Default_Drop are given. Targets indicates the drop types that Widget accepts. If no item from Targets matches the list of targets emitted by the source (as set in Source_Set), then the drop will be considered illegal and refused.
Actions is a bitmask of possible actions for a drop onto Widget. At
least of the actions must be in common with what was set for the source
in Source_Set, or the drop is considered illegal.
| ||
procedure Dest_Set_Proxy (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Proxy_Window : Gdk.Window.Gdk_Window; Protocol : Drag_Protocol; Use_Coordinates : Boolean); | ||
Set this widget as a proxy for drops to another window. | ||
procedure Dest_Unset (Widget : access Gtk.Widget.Gtk_Widget_Record'Class); | ||
Clear information about a drop destination set with Dest_Set. The | ||
function Dest_Find_Target (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Context : Drag_Context; Target_List : Gtk.Selection.Target_List) return Gdk.Types.Gdk_Atom; | ||
| ||
function Dest_Get_Target_List (Widget : access Gtk.Widget.Gtk_Widget_Record'Class) return Target_List; | ||
| ||
procedure Dest_Set_Target_List (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Target_List : Gtk.Selection.Target_List); | ||
| ||
Setting up a widget as a source | ||
procedure Source_Set (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Start_Button_Mask : Gdk.Types.Gdk_Modifier_Type; Targets : Target_Entry_Array; Actions : Drag_Action); | ||
Set up a widget so that GtkAda will start a drag operation when the Targets is the list of targets that the drag can provide. The first possible target accepted by the drop site will be used. For instance, it Targets contains "text/plain" and "text/url", and the drop site only accepts "text/url", this will be the one used. However, if the drop site also accepts "text/plain", the latter will be prefered. Widget needs to be able to convert the data to any of the types in Target, as any of them might be requested by the drop site.
Actions is a list of possible actions for drags from Widget. At least
one of the actions must be in common with the drop site for the
drag-and-drop operation to succeed.
| ||
procedure Source_Unset (Widget : access Gtk.Widget.Gtk_Widget_Record'Class); | ||
Undo the effects of Source_Set.
| ||
The drag-and-drop operation | ||
procedure Finish (Context : Drag_Context; Success : Boolean; Del : Boolean; Time : Guint32 := 0); | ||
Inform the drag source that the drop is finished, and that the data of | ||
procedure Get_Data (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Context : Drag_Context; Target : Gdk.Types.Gdk_Atom; Time : Guint32 := 0); | ||
Get the data associated with a drag. When the data is received or the
Target is the target (form of the data) to retrieve.
Time is a timestamp to retrive the data, and will be given to
"drag_data_motion" or "drag_data_drop" signals.
| ||
function Get_Source_Widget (Context : Drag_Context) return Gtk.Widget.Gtk_Widget; | ||
Determine the source widget for a drag. | ||
procedure Highlight (Widget : access Gtk.Widget.Gtk_Widget_Record'Class); | ||
Draw a highlight around a widget.
| ||
procedure Unhighlight (Widget : access Gtk.Widget.Gtk_Widget_Record'Class); | ||
Remove a highlight set by Highlight.
| ||
function Drag_Begin (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Targets : Target_List; Actions : Drag_Action; Button : Gint; Event : Gdk.Event.Gdk_Event) return Drag_Context; | ||
Initiate a drag on the source side. The function only needs to be used | ||
function Check_Threshold (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Start_X : Gint; Start_Y : Gint; Current_X : Gint; Current_Y : Gint) return Boolean; | ||
Checks to see if a mouse drag starting at (Start_X, Start_Y) and ending | ||
Icons | ||
procedure Set_Icon_Widget (Context : Drag_Context; Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Hot_X : Gint; Hot_Y : Gint); | ||
Change the icon for a drag. | ||
procedure Set_Icon_Pixmap (Context : Drag_Context; Colormap : Gdk.Color.Gdk_Colormap; Pixmap : Gdk.Pixmap.Gdk_Pixmap; Mask : Gdk.Bitmap.Gdk_Bitmap; Hot_X : Gint; Hot_Y : Gint); | ||
Sets a given pixmap as the icon for a given drag. GtkAda retains a | ||
procedure Set_Icon_Default (Context : Drag_Context); | ||
Set the icon for a particular drag to the default icon. | ||
procedure Set_Default_Icon (Colormap : Gdk.Color.Gdk_Colormap; Pixmap : Gdk.Pixmap.Gdk_Pixmap; Mask : Gdk.Bitmap.Gdk_Bitmap; Hot_X : Gint; Hot_Y : Gint); | ||
Change the default drag icon. GtkAda retains a reference count for the | ||
procedure Set_Icon_Pixbuf (Context : Drag_Context; Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf; Hot_X : Gint; Hot_Y : Gint); | ||
Sets Pixbuf as the icon for a given drag. | ||
procedure Set_Icon_Stock (Context : Drag_Context; Stock_Id : String; Hot_X : Gint; Hot_Y : Gint); | ||
Sets the icon for a given drag from a stock ID | ||
procedure Source_Set_Icon (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Colormap : Gdk.Color.Gdk_Colormap; Pixmap : Gdk.Pixmap.Gdk_Pixmap; Mask : Gdk.Bitmap.Gdk_Bitmap); | ||
Set the icon that will be used for drags from a particular widget. | ||
procedure Source_Set_Icon_Pixbuf (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf); | ||
| ||
procedure Source_Set_Icon_Stock (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Stock_Id : String); | ||
|