Re: Proposal for making the GtkFileChooser code asynchronous

[Matthias Clasen <mclasen redhat com>]

On Tue, 2005-11-08 at 15:08 +0100, Kristian Rietveld wrote:
> Hi,
> 
> The last few weeks I have been working on making the GtkFileChooser code
> asynchronous.  I've been making quite a bit of progress and hope to get the
> changes in on time for GTK+ 2.10.  However, one of the most important
> changes is making the GtkFileSystem API suitable for asynchronous operation,
> which should not be a problem since GtkFileSystem is not supported API for
> general use (see gtkfilesystem.h).
> 
> In this mail I will propose a set of changes to the GtkFileSystem API.  If
> people are ok with these changes, I can go ahead and adapt all components
> -- GtkFileChooser*, GtkFileSystemUnix, GtkFileSystemGnomeVFS -- to the new
> GtkFileSystem API.
> 
> 
> 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 which would be defined the same way as GtkFileFolder --
>    each backend can provide it's own handle object.  Of course we add a
>    call which we can use to actually cancel an operation:
> 
>    gboolean gtk_file_system_cancel_operation (GtkFileSystem        *file_system,
>                                               GtkFileSystemHandle  *handle,
>                                               GError              **error);
> 
>    The gboolean return value will indicate success or failure, in the latter
>    case the error will be provided via GError.

I don't see why we need any error indication here. If canceling can
fail, failing silently should be fine, I think.

> 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) (GtkFileSystem       *file_system,
>                                                   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,
>                                                   GError                       **error);
> 
> 
>    If the return value of gtk_file_system_get_info() is NULL, and the error
>    argument is non-NULL a description of the error will be provided in there.
>    Only errors which occurred before the asynchronous information acquisition
>    process started will be reported this way.  All other errors will be
>    reported via the callback.
> 
> 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) (GtkFileSystem       *file_system,
>                                                     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,
>                                                     GError                        **error);
> 
> 
>    If the return value of gtk_file_system_get_folder() is NULL, and the error
>    argument is non NULL a description of the error will be provided in there.
>    As with the other functions, only errors which occurred before the actual
>    asynchronous operation started will be reported this way.
> 
>    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.
> 
> 4. gtk_file_system_create_folder() needs to be changed in order to be able
>    to operate asynchronously.  The new prototypes:
> 
>    typedef void (* GtkFileSystemCreateFolderCallback) (GtkFileSystem     *file_system,
>                                                        const GtkFilePath *path
>                                                        GError            *error,
>                                                        gpointer           data);

Any reason why the GtkFileSystemGetFolderCallback gets a handle passed
in, while the others don't ?

Matthias