Updated proposal for making the GtkFileChooser code asynchronous

[Kristian Rietveld <kris imendio com>]

Here is an updated proposal based on the received comments.  Feedback is of
course still welcome ;)


1. Let's start out with a somewhat more general change.  We need to be able
   to cancel currently running asynchronous operations.  For this we need
   to have a handle on an operation, so we need to introduce a
   GtkFileSystemHandle.  The GtkFileSystemHandle will be a GObject:

   struct _GtkFileSystemHandle
   {
     GObject parent_instance;

     GtkFileSystem *file_system;

     guint cancelled : 1;		/* indicates whether the operation
					   has been cancelled or not */
   };

   struct _GtkFileSystemHandleClass
   {
     GObjectClass parent_class;
   };

   File system backends can of course subclass GtkFileSystemHandle and
   add their own fields as required.  We will add a call which we can use to
   actually cancel an operation:

   void gtk_file_system_cancel_operation (GtkFileSystemHandle  *handle);

2. Addition of gtk_file_system_get_info(), so we are able to retrieve
   information about a file without having to create a folder.  This is
   useful in for example GtkPathBar.  Prototypes:

   typedef void (* GtkFileSystemGetInfoCallback) (GtkFileSystemHandle *handle,
                                                  GtkFileInfo         *file_info,
                                                  GError              *error,
                                                  gpointer             data);

   GtkFileSystemHandle *gtk_file_system_get_info (GtkFileSystem                 *file_system,
                                                  const GtkFilePath             *path,
                                                  GtkFileInfoType                types,
                                                  GtkFileSystemGetInfoCallback   callback,
                                                  gpointer
 data);


   The function gtk_file_system_get_info() itself does not take an
   GError argument.  All errors will be reported via the callback, this means
   that error handling will only have to be implemented at a single place.
   The error argument of the callback will be NULL when no error occurred.

3. Change gtk_file_system_get_folder().  We cannot directly return a folder
   here, because we need to access the file system to figure out if the
   given path is really a folder.  Let's use the following as a new call:

   typedef void (* GtkFileSystemGetFolderCallback) (GtkFileSystemHandle *handle,
                                                    GtkFileFolder       *folder,
                                                    GError              *error,
                                                    gpointer             data);

   GtkFileSystemHandle *gtk_file_system_get_folder (GtkFileSystem                  *file_system,
                                                    const GtkFilePath              *path,
                                                    GtkFileInfoType                 types,
                                                    GtkFileSystemGetFolderCallback  callback,
                                                    gpointer                        data);


   Likewise with gtk_file_system_get_info(), all errors will be reported
   via the callback.

   Using this new call would work as follows:
      I.   Call gtk_file_system_get_folder().
      II.  The callback provided will be called to tell whether the folder
           exists or not.  If it exists, you will be provided with a pointer
           to a valid GtkFileFolder, if not the process ends here.
      III. A directory load will immediately start, children will be added via
           the "files-added" signal until you receive a "finished-loading"
           signal.

   The functions gtk_file_folder_list_children() and gtk_file_folder_get_info()
   will not be changed.  However, there still is some discussion going on
   whether to remove gtk_file_folder_get_info() from the API, consensus on
   this point has not yet been reached.

4. gtk_file_system_create_folder() needs to be changed in order to be able
   to operate asynchronously.  The new prototypes:

   typedef void (* GtkFileSystemCreateFolderCallback) (GtkFileSystemHandle
*handle,
                                                       const GtkFilePath        *path
                                                       GError                   *error,
                                                       gpointer                  data);

   GtkFileSystemHandle *gtk_file_system_create_folder (GtkFileSystem                      *file_system,
                                                       const GtkFilePath                  *path,
                                                       GtkFileSystemCreateFolderCallback   callback,
                                                       gpointer                            data);

   The error reporting works on the same way as the other functions.

5. We will also change gtk_file_system_volume_mount() to report the result
   of the operation via a callback as follows:

   typedef void (* GtkFileSystemVolumeMountCallback) (GtkFileSystemHandle *handle,
                                                      GtkFileSystemVolume *volume,
                                                      GError              *error,
                                                      gpointer             data);

   GtkFileSystemHandle *gtk_file_system_volume_mount (GtkFileSystem                     *file_system,
                                                      GtkFileSystemVolume               *volume,
                                                      GtkFileSystemVolumeMountCallback   callback,
                                                      gpointer                           data);

   The error reporting works on the same way as the other functions.

6. Right now gtk_file_system_render_icon() is synchronous, because it needs
   some information about the file in order to be able to render a suitable
   icon.  We plan to add appropriate fields to GtkFileInfo, GTK_FILE_INFO_ICON
   and the following function:

   GdkPixbuf *gtk_file_info_render_icon (GtkFileInfo *file_info,
                                         GtkWidget   *widget,
                                         gint         pixel_size,
                                         GError     **error);

   When loading a folder or getting info with GTK_FILE_INFO_ICON set,
   all information needed to render the icon will be loaded.  The function
   gtk_file_info_render_icon() will then be able to render the icon without
   having to do any asynchronous or possibly blocking synchronous calls.

   We will remove the function gtk_file_system_render_icon() from the API,
   and leave gtk_file_system_volume_render_icon() the way it is.

7. Additional file system backends (like the gnome-vfs backend) are (already)
   installed in versioned directories.  This will prevent older versions of
   GTK+ from using file system backends using the new API and vice versa.



thanks,

-kris.