GtkFileChooser API changes

[Federico Mena Quintero <federico ximian com>]

Hi,

I've been doing public API changes to the code in the gtkfilechooser
module, and it would be great if people could take some time to review
them.  There are three important areas for new APIs.

Application-side shortcuts
--------------------------

Say you have a drawing program, foodraw.  When you install it, it
creates a /usr/share/foodraw/Clipart directory.  It would be good if
foodraw gave you an easy way to access the clipart directory any time
you want to open a file.

I added these functions:

/* Takes a list of GtkFilePath */
void gtk_file_chooser_set_shortcut_folders (
	GtkFileChooser *chooser,
	GSList         *shortcut_directories);

/* Returns a list of GtkFilePath */
GSList *gtk_file_chooser_list_shortcut_folders (
	GtkFileChooser *chooser);

There are also the corresponding virtual methods in
GtkFileChooserIface.  The implementation is supposed to just list the
specified folders somewhere in the GUI.  The default implementation
shows them in the combined shortcuts/bookmarks list.

User-configurable bookmarks
---------------------------

These are similar to the bookmarks you can set in the file selection
dialog of Mac OS X Panther:

	http://www.atommic.com/images/panther/OpenBox.jpg

The is that you drag commonly-used directories into the list on the left
part of the dialog, and it will keep them for you.  This lets you access
your "working set" of directories easily.  When you stop using a
directory in your current projects, you just drag it away from the list
to remove it.

There is no public API for this, as it is the job of the internal
GtkFileSystem implementation to store the bookmarks.  Currently
GtkFileSystemUnix says "I don't support bookmarks", and
GtkFileSystemGnomeVFS stores the bookmarks using GConf.

The internal API in GtkFileSystem is this:

gboolean gtk_file_system_get_supports_bookmarks (
	GtkFileSystem *file_system);

/* Takes a list of GtkFilePath */
void gtk_file_system_set_bookmarks (
	GtkFileSystem *file_system,
	GSList        *bookmarks,
	GError       **error);

/* Returns a list of GtkFilePath */
GSList *gtk_file_system_list_bookmarks (
	GtkFileSystem *file_system);

Of course, there are the corresponding virtual methods in
GtkFileSystemIface.

Activating a file
-----------------

What happens when the user double-clicks on a file, or when he hits
Enter?  I added a signal as GtkFileChooserIface::file_activated().

The implementation of GtkFileChooserDialog catches this signal and
activates the default button in the dialog, which would normally be the
"Open" or "Save" button.

However, since you can also take a non-dialog GtkFileChooserWidget and
embed it somewhere else, you can also connect to the "file-activated"
signal by yourself and do whatever is appropriate for your application.

The signal is simply

struct _GtkFileChooserIface {
	...
	void (*file_activated) (GtkFileChooser *chooser);
};

>From your signal handler you can use gtk_file_chooser_get_uris() or any
of the similar functions to get the list of selected files.


So, what do people think?  It would be great if someone could do a
review of the public API for GtkFileChooser --- gtkfilechooser.h,
gtkfilechooserprivate.h (just for the signals, not for the
underscore-prefixed functions), gtkfilechooserwidget.h,
gtkfilechooserdialog.h, gtkfilefilter.h.

  Federico