I wanted to implement a draggable save button in my GTK+ app. This lets the user save his file by dragging the document’s icon from the application onto the desktop or a file browser window.

Drag and drop (DND) is an intuitive approach to file management and XDS avoids the problem of novice users trying to use the file selector dialog as a file manager. However it’s not suitable for mouseless or limited-mouse users, so applications must also provide the conventional file selector.

The protocol used for drag to save is called Extensible Desktop Save (XDS) and is supported by ROX, Thunar, Konqueror, and Nautilus file managers.

This entry will describe what the programmer needs to do to implement saving with XDS in his own GTK+ app, with a small example. The example is in Python because the language is succinct and good for prototyping.

At some point, I recommend reading or skimming this good introduction to DND in GTK+, and the XDS spec. I referenced these, and the file-roller source to write the example.

How to save with XDS

In your UI you need a widget that the user will drag from (the source widget), and perhaps a text entry for the user to choose a filename.

The following steps correspond to the ones detailed in the spec, except they are translated to GTK+, and details about what the file manager needs to do are omitted.

Step 0 — Declare support for XDS

Create two GDK atoms called “XdndDirectSave0″ and “text/plain” and keep them in variables to be used later. The atoms will be used to refer to the XdndDirectSave (type text/plain) property of the source widget. This property is a communication channel between source and destination. It is used by the source widget to provide a filename to the file manager, and by the destination to specify a path to the application.

fixme: charset

XDS_ATOM = gtk.gdk.atom_intern("XdndDirectSave0")
TEXT_ATOM = gtk.gdk.atom_intern("text/plain")

Set up the widget as a drag source, with the single target name XdndDirectSave0. The 0 at the end represents the protocol version you’re implementing.

TARGET_TYPE_XDS = 42  # this can be any integer
 
def init_xds(self):
    # self.save is a button widget: the drag source
    targets = [("XdndDirectSave0", 0, self.TARGET_TYPE_XDS)]
    self.save.drag_source_set(gtk.gdk.BUTTON1_MASK,
                              targets,
                              gtk.gdk.ACTION_COPY)

Connect the widget’s drag-begin, drag-data-get, drag-end signals up to handlers.

    self.save.connect("drag-begin", self.on_save_drag_begin)
    self.save.connect("drag-data-get", self.on_save_drag_data_get)
    self.save.connect("drag-end", self.on_save_drag_end)

Step 1 — On drag-begin event

Once the user starts dragging the source widget, set the widget’s XdndDirectSave property to the filename (just the filename, no path) that was given by the user.

def on_save_drag_begin(self, widget, context):
    filename = self.filename.get_text()
    context.source_window.property_change(self.XDS_ATOM, self.TEXT_ATOM, 8,
                                          gtk.gdk.PROP_MODE_REPLACE,
                                          filename)

Step 2 — On drag-data-get event

This event is caused by the file manager, after the save widget has been dropped on a folder. The file manager puts the full path and filename into the source widget’s XdndDirectSave property. Get the value of this property and save the file.

def get_xds_filename(self, context):
    if self.XDS_ATOM in context.targets:
        typ, fmt, data = context.source_window.property_get(self.XDS_ATOM,
                                                            self.TEXT_ATOM)
        return data
 
    return None
 
def on_save_drag_data_get(self, widget, context, selection, info, time):
    if info == self.TARGET_TYPE_XDS:
        destination = self.get_xds_filename(context)
 
        if destination is not None:
            error = self.save_file(destination)

Your app must return a status code to the file manager, depending on the result of saving the file. It is put in the selection that is normally used for DND. There are three possible status codes, but only two are important for GTK+ apps: “S” and “E” — Success and Error.

The third, “F” for Failure, is used when the file manager gave a network URI that isn’t supported by the app. In that case the protocol supports sending the file through a selection. But all new GTK+ apps should be using GIO, and with GVFS, this supports saving pretty much anywhere except to Bruce Schneier’s brain. So it’s not necessary to send “F”.

            code = "S" if error is None else "E"
            selection.set(selection.target, 8, code)

If there was a need to present some dialog to the user, for example “Could not save file: Permission denied,” then do it after selection.set(). Otherwise the file manager will be waiting for a response until the user closes the dialog.

            if error is not None:
                self.show_error(error)

Step 3

If the file manager received “S” or “E”, it sends a drag finished event. In the case of Success, it might need to refresh its view so the user can see the new file.

Step 4 — On drag-end event

After the drag operation has finished, your app can delete the source widget’s XdndDirectSave property.

def on_save_drag_end(self, widget, context):
    context.source_window.property_delete(self.XDS_ATOM)

Summary

As you can see, it’s fairly straightforward to implement drag to save in an application. It should be enough to copy and paste this code and translate it to the language you’re using.

An app could also support DND of URIs, depending on what you’re trying to achieve. The example application allows dragging a file onto the window to load it. It also illustrates a simple use of GIO.

Full example source can be downloaded here:

• xds.py
• xds.ui

Here is an easy way to setup GDB to step through the GTK+ source code if you’re using the Debian (or Ubuntu) -dbg packages.

First thing to do, if you haven’t already done it, is to install the relevant debug packages. gnome-dbg is a metapackage which depends on a few other GNOME debug packages. Install it if you have enough disk space. If you’re like me and can’t spare the GBs then install only the necessary dependencies. In my case: gnome-panel-dbg libglib2.0-0-dbg libgtk2.0-0-dbg.

The -dbg packages put a tree of unstripped shared libraries in /usr/lib/debug. Unstripped objects contain symbol definitions (e.g. function names and their addresses) and debugging information (i.e. a mapping from instruction addresses to source code line numbers).

At this point you already have some useful information. When you debug your app in GDB you will notice that GDB reads symbols from the objects in /usr/lib/debug corresponding to the ones in /usr/lib. So when you look at the backtrace, function names will appear instead of something like this: #3 0x0f09ad50 in ?? () from /usr/lib/libgobject-2.0.so.0. However it would be nice to be able to trace through the source code.

The source code corresponding to a library is easy enough to get if you’re using Debian. You just need somewhere to put it. I have mine in ~/dev/pkg. So:


$ cd ~/dev/pkg
$ apt-get source gnome-panel-dbg libglib2.0-0-dbg libgtk2.0-0-dbg


If you try going up your backtrace in GDB and stepping through the GTK+ code you will see no code and a message like this:

gtk_widget_event_internal (widget=0x100ca420, event=0x10190ee8) at /build/buildd/gtk+2.0-2.12.3/gtk/gtkwidget.c:4677
4677	/build/buildd/gtk+2.0-2.12.3/gtk/gtkwidget.c: No such file or directory.
	in /build/buildd/gtk+2.0-2.12.3/gtk/gtkwidget.c

The directory /build/buildd is the directory from which your GTK+ was built, when it was built on some other unknown machine. This will vary depending on the distribution (Debian or Ubuntu), the architecture, the package, and whoever happens to be the package maintainer. If you built the GTK+ package yourself it would be different. Sometimes the filename referred to is not absolute, e.g. this is the case for libpanel-applet.

Obviously, GDB must be told where to find the code. The GDB manual describes the possibilities available to you.

Absolute filenames like /build/buildd or /scratch/build-area

In this case, the easiest way is to create a source path substitution rule like this:


set substitute-path /build/buildd /home/rodney/dev/pkg


Change /build/buildd to whatever directory the debug symbols point to.

Change the underlined path to the place where you ran the apt-get source command.

No path in filename

If the message looks like this:

#5  0x00007f0521248624 in panel_applet_factory_main_closure (
    iid=0x404b74 "OAFIID:PanelVisApplet_Factory",
    applet_type=, closure=)
    at panel-applet.c:1754
1754	panel-applet.c: No such file or directory.
	in panel-applet.c

i.e. gdb is looking for a file in the current directory, then find where the sources are.


$ find ~/dev/pkg -name panel-applet.c -printf '%h\n'
/home/rodney/dev/pkg/gnome-panel-2.24.2/libpanel-applet


And then use the dir command in gdb.


dir /home/rodney/dev/pkg/gnome-panel-2.24.2/libpanel-applet


Permanence

Put these commands in your ~/.gdbinit and you will never have to think about it again… until someone upgrades the library.

Library upgrades

When the library packages are upgraded, the paths with become invalid, because they have the version in them. In this case, you will need to re-run the apt-get source command to retrieve the source code which matches your library version, then update your ~/.gdbinit. Alternatively, you could keep the old source code and add extra substitution rules to point GDB to the old code. However I don’t recommend this practice because the debugger will appear to act strange if the source code is too different and the line numbers don’t match up. A nasty surprise like that is the last thing you need when you’re up at 2AM debugging something.