Import Upstream version 2.72.4

docs/reference/gio/migrating-gnome-vfs.xml

@@ -0,0 +1,133 @@
+  <chapter>
+    <title>Migrating from GnomeVFS to GIO</title>
+
+    <table id="gnome-vfs-vs-gio">
+      <title>Comparison of GnomeVFS and GIO concepts</title>
+      <tgroup cols="2">
+        <thead>
+          <row><entry>GnomeVFS</entry><entry>GIO</entry></row>
+        </thead>
+        <tbody>
+          <row><entry>GnomeVFSURI</entry><entry>GFile</entry></row>
+          <row><entry>GnomeVFSFileInfo</entry><entry>GFileInfo</entry></row>
+          <row><entry>GnomeVFSResult</entry><entry>GError, with G_IO_ERROR values</entry></row>
+          <row><entry>GnomeVFSHandle &amp; GnomeVFSAsyncHandle</entry><entry>GInputStream or GOutputStream</entry></row>
+          <row><entry>GnomeVFSDirectoryHandle</entry><entry>GFileEnumerator</entry></row>
+          <row><entry>mime type</entry><entry>content type</entry></row>
+          <row><entry>GnomeVFSMonitor</entry><entry>GFileMonitor</entry></row>
+          <row><entry>GnomeVFSVolumeMonitor</entry><entry>GVolumeMonitor</entry></row>
+          <row><entry>GnomeVFSVolume</entry><entry>GMount</entry></row>
+          <row><entry>GnomeVFSDrive</entry><entry>GVolume</entry></row>
+          <row><entry>-</entry><entry>GDrive</entry></row>
+          <row><entry>GnomeVFSContext</entry><entry>GCancellable</entry></row>
+          <row><entry>gnome_vfs_async_cancel</entry><entry>g_cancellable_cancel</entry></row>
+        </tbody>
+      </tgroup>
+    </table>
+
+    <section>
+      <title>Trash handling</title>
+
+      <para>
+        The handling of trashed files has been changed in GIO, compared
+        to gnome-vfs. gnome-vfs has a home-grown trash implementation that 
+        predates the freedesktop.org <ulink url="http://www.freedesktop.org/wiki/Specifications/trash-spec">Desktop Trash Can</ulink> specification
+        that is implemented in GIO. The location for storing trashed files 
+        has changed from <filename>$HOME/.Trash</filename> to 
+        <filename>$HOME/.local/share/Trash</filename> (or more correctly
+        <filename>$XDG_DATA_HOME/Trash</filename>), which means that 
+        there is a need for migrating files that have been trashed by 
+        gnome-vfs to the new location.
+      </para>
+      <para>
+        In gnome-vfs, the <filename>trash://</filename> scheme offering a 
+        merged view of all trash directories was implemented in nautilus,
+        and trash-handling applications had to find and monitor all trash 
+        directories themselves. With GIO, the <filename>trash://</filename>
+        implementation has been moved to gvfs and applications can simply
+        monitor that location:
+      </para>
+<informalexample><programlisting>
+static void
+file_changed (GFileMonitor      *file_monitor,
+              GFile             *child,
+              GFile             *other_file,
+              GFileMonitorEvent  event_type,
+              gpointer           user_data)
+{
+  switch (event_type)
+  {
+  case G_FILE_MONITOR_EVENT_DELETED:
+    g_print ("'%s' removed from trash\n", g_file_get_basename (child));
+    break;
+  case G_FILE_MONITOR_EVENT_CREATED:
+    g_print ("'%s' added to trash\n", g_file_get_basename (child));
+    break;
+  default: ;
+  }
+}
+
+static void
+start_monitoring_trash (void)
+{
+  GFile *file;
+  GFileMonitor *monitor;
+
+  file = g_file_new_for_uri ("trash://");
+  monitor = g_file_monitor_directory (file, 0, NULL, NULL);
+  g_object_unref (file);
+
+  g_signal_connect (monitor, "changed", G_CALLBACK (file_changed), NULL);
+
+  /* ... */
+
+}       
+</programlisting></informalexample> 
+      <para>
+        GIO exposes some useful metadata about trashed files. There are
+        trash::orig-path and trash::deletion-date attributes. The 
+        standard::icon attribute of the <filename>trash://</filename> 
+        itself provides a suitable icon for displaying the trash can on 
+        the desktop. If you are using this icon, make sure to monitor
+        this attribute for changes, since the icon may be updated to
+        reflect that state of the trash can.
+      </para>
+      <para>
+        Moving a file to the trash is much simpler with GIO. Instead of
+        using gnome_vfs_find_directory() with %GNOME_VFS_DIRECTORY_KIND_TRASH 
+        to find out where to move the trashed file, just use the g_file_trash()
+        function.
+      </para>
+    </section>
+
+    <section>
+      <title>Operations on multiple files</title>
+
+      <para>
+        gnome-vfs has the dreaded gnome_vfs_xfer_uri_list() function which
+        has tons of options and offers the equivalent of cp, mv, ln, mkdir
+        and rm at the same time. 
+      </para>
+      <para>
+        GIO offers a much simpler I/O scheduler functionality instead, that
+        lets you schedule a function to be called in a separate thread, or
+        if threads are not available, as an idle in the mainloop.
+        See g_io_scheduler_push_job(). 
+      </para>
+
+    </section>
+
+    <section>
+      <title>Mime monitoring</title>
+
+      <para>
+        gnome-vfs offered a way to monitor the association between mime types
+        and default handlers for changes, with the #GnomeVFSMIMEMonitor object.
+        GIO does not offer a replacement for this functionality at this time,
+        since we have not found a compelling use case where
+        #GnomeVFSMIMEMonitor was used. If you think you have such a use
+        case, please report it at
+        <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
+      </para>
+    </section>
+  </chapter>