21.1.1. A Checklist for functional Drag and Drop

• Each item which will be dragged needs to declare itself as a drag source.

  This is accomplished with the 'drag_source_set' method of the Gtk2::Widget class.

• Each item which will receive dragged items needs to declare itself as a drag destination.

  This is accomplished with the 'drag_dest_set' method of the Gtk2::Widget class.

  An item can be a drag source and destination at the same time.

• If you want to change the drag icon, connect a callback to the 'drag-begin' signal of the drag source. This callback is then used to set up the drag icon. You use the 'drag_source_set_icon_pixbuf' method of the Gtk2::Widget class for this.

• When a drag source is dropped onto a valid drag destination, data must flow between them. Two signals and their callbacks are used to accomplish this. First the 'drag-data-get' signal will trigger on the drag source.

  After this signal, the 'drag-data-received' signal will trigger on the drag destination.

  Callbacks need to be connected to both these signals in order for data to flow between the source and destination widgets. The one callback will set up the data, and the other will extract the data.

The above four (or five if you like cosmetics) checks is all you ever need to remember for the typical drag and drop operations.

21.1.2. Two data types explained

There are two data types used in drag and drop operations which can be strange and obscure on first encounter. We discuss them here so you may recognize them in the sample program later on.

21.1.2.1. Gtk2::TargetEntry

The 'drag_source_set' and 'drag_dest_set' methods are used to enable a widget to be a drag source and a drag destination respectively.

$widget->drag_source_set ($start_button_mask, $actions, ...) 
    * $start_button_mask (Gtk2::Gdk::ModifierType)
    * $actions (Gtk2::Gdk::DragAction)
    * ... (list) of Gtk2::TargetEntry's

Gtk2::Gdk::ModifierType and Gtk2::Gdk::DragAction are explained on the POD of Gtk2::Widget and we do not want to duplicate documentation here.

The Gtk2::TargetEntry data structure represents a single type of data which can be supplied or received during drag-and-drop.

# as a HASH
$target_entry = {
    target => 'text/plain', # some string representing the drag type
    flags => [], # Gtk2::TargetFlags
    info => 42,  # some app-defined integer identifier
};               

It is used as an argument to the 'drag_source_set' and 'drag_dest_set' methods.

The 'drag_source_set' usually contains only one Gtk2::TargetEntry, but the 'drag_dest_set' can contain an array of them, each representing a source it is willing to accept drag data from.

#Create a target table to receive drops
my @target_table = (
 
    {'target' => 'STRING',       'flags' => [], 'info' => ID_ICONVIEW   },
    {'target' => "text/uri-list",'flags' => [], 'info' => ID_URI        },
    {'target' => "text/plain",  'flags' => [], 'info' => ID_LABEL       },
);
 
#make this the drag destination (drop) for various drag sources
$slist->drag_dest_set('all', ['copy'], @target_table);

If you want to receive dropped data from the file browser (eg Nautilus), you need to specify a target as "text/uri-list". When you drop data from Nautilus onto a drag destination, it receives a list of newline separated URIs each representing a dragged item.

Not going into to much detail, the usual values will be either 'text/plain' or 'STRING' to transfer text between a drag source and destination. The end results of both are the same. The one is a MIME type, the other is a Gtk2::Gdk::Atom. There are pre-defined Gtk2::Gdk::Atoms which can be used. 'STRING' is such one. If you want to transfer data other than plain text during drag and drop, you can specify another type of Gtk2::Gdk::Atom. To find out more about the pre-defined Gtk2::Gdk::Atoms, you can visit this URL.

The flags value is empty most of the time.

The 'info' is an integer value that will represent the source of the data which is send or received. This value will be passed on to the 'drag-data-get' and 'drag-data-received' callbacks. This will enable you to differentiate between the sources of the drag and drop action.

It makes your program more readable if you assign constants to the integer values.

21.1.2.2. Gtk2::SelectionData

When a drag source is dropped onto a drag destination you need to first set up the data of the drag source, and then extract that data on the drag destination.

A typical signal handler for the drag source's 'drag-data-get' signal will look like this:

sub source_drag_data_get {
#---------------------------------------------------
#This sets up the data of the drag source. It is ---
#required before the 'drag-data-received' event ----
#fires which can be used to extract this data ------
#---------------------------------------------------
    
    my ($widget, $context, $data, $info, $time,$string) = @_;
    
    $data->set_text($string,-1);
}

You may want to pass an extra string to define $data's value. $info is used to determine which source called this callback. It is the 'info' value of the Gtk2::TargetEntry data type. This allows you to utilize the same callback by various drag sources. $data is what this section is discussing, and will follow after a snippet of the typical 'drag-data-received' signal callback.

sub target_drag_data_received {
    #---------------------------------------------------
    #Extract the data which was set up during the  -----
    #'drag-data-get' event which fired just before -----
    #the 'drag-data-received' event. Also checks which--
    #source supplied the data, and handle accordingly----
    #---------------------------------------------------
    
    my ($widget, $context, $x, $y, $data, $info, $time) = @_;
    
    if  ($info eq ID_URI){
    
        print "Mmmm feels like Nautilus...\n";
        foreach ($data->get_uris){
            print "Got file ".$_."\n";
        }
    }
}

$info and $data are used most often. The rest can be used during more advanced implementations.

The Gtk2::SelectionData object is used to store a chunk of data along with the data type and other associated information. It has various convenient methods to insert and extract data to and from it. You can check out its POD for more info.

In the sample program we will use its 'get_uris', 'data' and 'set_text' methods. They are sufficient to transfer text between the drag source and destination.

Although Gtk2::SelectionData can be used to carry all sorts of data types Perl removes complex type castings :)!

21.1.3. Quit dragging and start dropping!

This is the fun part. Enough theory, lets look at a sample. In the sample we make use of the two Gtk2::Paned classes, Gtk2::VPaned and Gtk2::HPaned. We have a Gtk2::IconView widget that contains a list of all the Gtk2::Stock icons. These can be dragged onto a Gtk2::SimpleList. This Gtk2::SimpleList can also accept dragged items from the Nautilus file browser and the forbidden 'Now Stanley, DO NOT drag this item' event box. (come on, try it out :)). As a last bonus, we introduce Gtk2::ToolTips to the reader.

21.1.4. A Screenshot

21.1.5. The Code.

The program can be found here: 'gtk2_iconview.pl'

    
 #! /usr/bin/perl -w
 
 use strict;
 use Gtk2 '-init';
 use Glib qw/TRUE FALSE/;
 use Gtk2::SimpleList;
 
 #Declare our columns
 use constant C_MARKUP               => 0;
 use constant C_PIXBUF               => 1;
 
 #Declare our IDENDTIFIER ID's
 use constant ID_ICONVIEW            => 48;
 use constant ID_LABEL               => 49;
 use constant ID_URI                 => 50;
 
 #Add a tooltip object
 my $tooltips = Gtk2::Tooltips->new();
 
 #standard window creation, placement, and signal connecting
 my $window = Gtk2::Window->new('toplevel');
 $window->signal_connect('delete_event' => sub { Gtk2->main_quit; });
 $window->set_border_width(5);
 $window->set_position('center_always');
 
 #add and show the vbox
 $window->add(&ret_vbox);
 $window->show();
 
 #our main event-loop
 Gtk2->main();
 
 sub ret_vbox {
 
     my $vbox = Gtk2::VBox->new(FALSE,5);
     my $h_paned = Gtk2::HPaned->new();
 
         my $v_paned = Gtk2::VPaned->new();
         #get the iconview
         $v_paned->pack1(create_iconview(),TRUE,FALSE);
         #get the simple list where everything will be dropped into
         $v_paned->pack2(create_simple_list(),TRUE,FALSE);
 
     $h_paned->pack1($v_paned,TRUE,FALSE);
 
         #create an eventbox to accept drag actions
         my $event_box = Gtk2::EventBox->new();
             my $label_drag_me = Gtk2::Label->new("Now Stanley,\nDO NOT drag this item");
         $event_box->add($label_drag_me);
 
         #Try and convince the user otherwise
         $tooltips->set_tip ($event_box,
             'No way! You have to drag it at least once!'.
             'Drag it, and drop it into the bottom list'
             );
 
         #Setting up the Gtk2::Event Box instead of the Gtk2::Label, enabling it as 
         #a drag source
         $event_box->drag_source_set (
                                     ['button1_mask', 'button3_mask'],
                                     ['copy'],
                                     {
                                     'target' => 'text/plain',
                                     'flags' => [],
                                     'info' => ID_LABEL,
                                     },
         );
 
             my $text_to_drag = '<span foreground="red" size="x-large">"Well there\'s another nice mess you\'ve gotten me into."</span>';
 
         #set up the data which needs to be fed to the drag destination (drop)
         $event_box->signal_connect ('drag-data-get' => \&source_drag_data_get,$text_to_drag );
 
     $h_paned->pack2($event_box,TRUE,FALSE);
 
 $vbox->add($h_paned);
 $vbox->show_all();
 return $vbox;
 }
 
 sub create_iconview {
 #---------------------------------------------------
 #Creates an Iconview in a ScrolledWindow. This -----
 #Iconview has the ability to drag items off it  -----
 #---------------------------------------------------
 
     my $icon_string= undef;
     my $tree_model = create_iconview_model();
 
     my $icon_view = Gtk2::IconView->new_with_model($tree_model);
     $icon_view->set_markup_column(C_MARKUP);
     $icon_view->set_pixbuf_column(C_PIXBUF);
 
     #Enable the Gtk2::IconView as a drag source
     $icon_view->drag_source_set (
                                 ['button1_mask', 'button3_mask'],
                                 ['copy'],
                                 {
                                     'target' => 'STRING',
                                     'flags' => [],
                                     'info' => ID_ICONVIEW,
                                 },
                         );
 
     #This is a nice to have. It changes the drag icon to that of the
     #icon which are now selected and dragged (single selection mode)
     $icon_view->signal_connect('drag-begin' => sub { 
         $icon_view->selected_foreach ( sub{
 
                 my $iter =$tree_model->get_iter($_[1]);
                 #set the text and pixbuf
                 my $icon_pixbuf = $tree_model->get_value($iter,C_PIXBUF);
                 $icon_string = $tree_model->get_value($iter,C_MARKUP);
                 $icon_view->drag_source_set_icon_pixbuf ($icon_pixbuf);
         } );
     });
 
     #set up the data which needs to be fed to the drag destination (drop)
     $icon_view->signal_connect ('drag-data-get' => sub { source_drag_data_get(@_,$icon_string) } );
     
     #Standard scrolledwindow to allow growth
     my $sw = Gtk2::ScrolledWindow->new(undef,undef);
     $sw->set_policy('never','automatic');
     $sw->add($icon_view);
     $sw->set_border_width(6);
     $sw->set_size_request(600,150);
     return $sw;
 }
 
 sub create_iconview_model {
 #----------------------------------------------------
 #The Iconview needs a Gtk2::Treemodel implementation-
 #containing at least a Glib::String and -------------
 #Gtk2::Gdk::Pixbuf type. The first is used for the --
 #text of the icon, and the last for the icon self----
 #Gtk2::ListStore is ideal for this ------------------
 #----------------------------------------------------
 
     my $list_store = Gtk2::ListStore->new(qw/Glib::String Gtk2::Gdk::Pixbuf/);
 
     #******************************************************
     #we populate the Gtk2::ListStore with Gtk2::Stock icons
     #******************************************************
 
     my $icon_factory = Gtk2::IconFactory->new();
 
     foreach my $val(sort Gtk2::Stock->list_ids){
         #get the iconset from the icon_factory
         my $iconset = $icon_factory->lookup_default($val);
         #try and extract the icon from it
         my $pixbuf = $iconset->render_icon(Gtk2::Style->new(),'none','normal','dnd',undef);
 
         #if there was a valid icon in the iconset, add it
         if( defined $pixbuf ){
 
             my $iter = $list_store->append;
             $list_store->set (
                         $iter,
                         C_MARKUP, "<b>$val</b>",
                         C_PIXBUF, $pixbuf,
              );
 
         }
     }
 
     return $list_store;
 }
 
 sub create_simple_list {
 #---------------------------------------------------
 #Creates a simple list with pixbuf and markup  -----
 #columns make this list the drop target for various-
 #drag sources --------------------------------------
 #---------------------------------------------------
 
     my $slist = Gtk2::SimpleList->new ('' => 'pixbuf', ''  => 'markup');
     $slist->set_rules_hint(TRUE);
     $slist->set_headers_visible(FALSE);
 
      #Also suggest to try Nautilus
      $tooltips->set_tip ($slist,
             'Drag a few files from Nautilus '.
             'and drop it here'
             );
 
     #Create a target table to receive drops
     my @target_table = (
 
         {'target' => 'STRING',       'flags' => [], 'info' => ID_ICONVIEW   },
         {'target' => "text/uri-list",'flags' => [], 'info' => ID_URI        },
         {'target' => "text/plain",  'flags' => [], 'info' => ID_LABEL       },
     );
 
     #make this the drag destination (drop) for various drag sources
     $slist->drag_dest_set('all', ['copy'], @target_table);
 
     #do a callback as soon as drag data is received
     $slist->signal_connect ('drag-data-received' => \&target_drag_data_received,$slist );
 
     #Standard scrolledwindow to allow growth
     my $sw = Gtk2::ScrolledWindow->new(undef,undef);
     $sw->set_policy('never','automatic');
     $sw->add($slist);
     $sw->set_border_width(6);
     $sw->set_size_request(600,150);
     return $sw;
 }
 
 sub target_drag_data_received {
 #---------------------------------------------------
 #Extract the data which was set up during the  -----
 #'drag-data-get' event which fired just before -----
 #the 'drag-data-received' event. Also checks which--
 #source supplied the data, and handle accordingly----
 #---------------------------------------------------
 
     my ($widget, $context, $x, $y, $data, $info, $time,$slist) = @_;
 
     my $icon_factory = Gtk2::IconFactory->new();
 
     if ($info eq ID_LABEL){
         my $iconset = $icon_factory->lookup_default('gtk-no');
         my $pixbuf = $iconset->render_icon(Gtk2::Style->new(),'none','normal','menu',undef);
         push @{$slist->{data}}, [ $pixbuf, $data->data ];
     }
 
     if ($info eq ID_URI){
         my $iconset = $icon_factory->lookup_default('gtk-yes');
         my $pixbuf = $iconset->render_icon(Gtk2::Style->new(),'none','normal','menu',undef);
 
         foreach ($data->get_uris){
             push @{$slist->{data}}, 
                     [ $pixbuf, '<span foreground="forest green" size="x-small">'.$_.'</span>' ];
         }
     }
 
     if ($info eq ID_ICONVIEW){
 
         my $no_markup = $data->data;
         $no_markup =~ s/<[^>]*>//g;
         my $iconset = $icon_factory->lookup_default($no_markup);
         my $pixbuf = $iconset->render_icon(Gtk2::Style->new(),'none','normal','menu',undef);
         push @{$slist->{data}}, [ $pixbuf, $data->data ];
     }
 
     $context->finish (0, 0, $time);
 }
 
 sub source_drag_data_get {
 #---------------------------------------------------
 #This sets up the data of the drag source. It is ---
 #required before the 'drag-data-received' event ----
 #fires which can be used to extract this data ------
 #---------------------------------------------------
 
     my ($widget, $context, $data, $info, $time,$string) = @_;
 
     $data->set_text($string,-1);
 }

21.1.6. Code that needs further explanation.

#get the iconset from the icon_factory
my $iconset = $icon_factory->lookup_default('gtk-ok');

#try and extract the icon from it
my $pixbuf = $iconset->render_icon(Gtk2::Style->new(),'none','normal','dnd',undef);

21.1.6.2. The Gtk2::IconView.

This is a viewer for the typical MVC (Model-View-Controller) design pattern. It makes use of the Gtk2::ListStore as the implementation of the Gtk2::TreeModel interface. This model must contain at least a Gtk2::Gdk::Pixbuf column containing pixbufs of the icons to display.

We connect the Gtk2::Gdk::Pixbuf column in the Gtk2::ListStore to the Gtk2::IconView using its set_pixbuf_column method.

If you need to display text below the icons, you may specify a Glib::String type on the Gtk2::ListStore model. This gets connected to the Gtk2::IconView using its set_text_column. This text can be Gtk2::Pango markup, then you simply connect to the model using the Gtk2::IconView's set_markup_column method.

Again you can make life easier for yourself by using constants instead of integers to keep track of the columns.

21.1.6.3. Gtk2::Paned

A paned widget draws a separator between the two child widgets and a small handle that the user can drag to adjust the division. It does not draw any relief around the children or around the separator.

You can read more about Gtk2::Paned widgets on its POD.

To force a minimum size on a widget, you can use the set_size_request method from the Gtk2::Widget class. This helps in setting up the initial shape of widgets packed inside a Gtk2::Paned widget;

#Try and convince the user otherwise
$tooltips->set_tip (
    $event_box,
    'No way! You have to drag it at least once!'.
    'Drag it, and drop it into the bottom list'
);    

21.1.7. Conclusion.

This brings us to the end of the drag and drop section. I trust this may get you out of a nice mess some day.