[gtk/docs-gtk-org] glib: Port the "Migrating from GNOME VFS" guide

[Emmanuele Bassi <ebassi src gnome org>]

commit 64613b25e0ad00cc0e4b7f71422caa36580b8a63
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Nov 25 12:06:20 2021 +0000

    glib: Port the "Migrating from GNOME VFS" guide

 glib/gio/gio.toml.in            |   4 +-
 glib/gio/meson.build            |   1 +
 glib/gio/migrating-gnome-vfs.md | 107 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 111 insertions(+), 1 deletion(-)
---
diff --git a/glib/gio/gio.toml.in b/glib/gio/gio.toml.in
index 874a70979f..665e277e44 100644
--- a/glib/gio/gio.toml.in
+++ b/glib/gio/gio.toml.in
@@ -35,7 +35,9 @@ show_class_hierarchy = true
 [extra]
 urlmap_file = "urlmap.js"
 # The same order will be used when generating the index
-content_files = []
+content_files = [
+  "migrating-gnome-vfs.md",
+]
 content_images = [
   "gvfs-overview.png",
   "menu-example.png",
diff --git a/glib/gio/meson.build b/glib/gio/meson.build
index 053276628d..2985d14da1 100644
--- a/glib/gio/meson.build
+++ b/glib/gio/meson.build
@@ -1,4 +1,5 @@
 expand_content_files = [
+  'migrating-gnome-vfs.md',
 ]
 
 gio_gir = meson.current_source_dir() / 'Gio-2.0.gir'
diff --git a/glib/gio/migrating-gnome-vfs.md b/glib/gio/migrating-gnome-vfs.md
new file mode 100644
index 0000000000..dd92cb78ae
--- /dev/null
+++ b/glib/gio/migrating-gnome-vfs.md
@@ -0,0 +1,107 @@
+Title: Migrating from GnomeVFS to GIO
+
+# Migrating from GnomeVFS to GIO
+
+## Comparison of GnomeVFS and GIO concepts
+
+| GnomeVFS | GIO |
+|----------|-----|
+| `GnomeVFSURI` | [iface Gio File] |
+| `GnomeVFSFileInfo` | [class@Gio.FileInfo] |
+| `GnomeVFSResult` | [struct@GLib.Error], with `G_IO_ERROR` values |
+| `GnomeVFSHandle` & `GnomeVFSAsyncHandle` | [class@Gio.InputStream] or [class@Gio.OutputStream] |
+| `GnomeVFSDirectoryHandle` | [class@Gio.FileEnumerator] |
+| MIME type | content type |
+| `GnomeVFSMonitor` | [class@Gio.FileMonitor] |
+| `GnomeVFSVolumeMonitor` | [class@Gio.VolumeMonitor] |
+| `GnomeVFSVolume` | [iface@Gio.Mount] |
+| `GnomeVFSDrive` | [iface@Gio.Volume] |
+| - | [iface@Gio.Drive] |
+| `GnomeVFSContext` | [class@Gio.Cancellable] |
+| `gnome_vfs_async_cancel()` | [method@Gio.Cancellable.cancel] |
+
+## Trash handling
+
+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 [Desktop Trash
+Can](http://www.freedesktop.org/wiki/Specifications/trash-spec)
+specification that is implemented in GIO.  The location for storing trashed
+files has changed from `$HOME/.Trash` to `$HOME/.local/share/Trash` (or more
+correctly `$XDG_DATA_HOME/Trash`), which means that there is a need for
+migrating files that have been trashed by gnome-vfs to the new location.
+
+In gnome-vfs, the `trash://` 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
+`trash://` implementation has been moved to gvfs and applications can simply
+monitor that location:
+
+```c
+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);
+
+  /* ... */
+
+}
+```
+
+GIO exposes some useful metadata about trashed files. There are
+`trash::orig-path` and `trash::deletion-date` attributes. The
+`standard::icon` attribute of the `trash://` 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.
+
+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 [`method Gio File.trash`]
+method.
+
+## Operations on multiple files
+
+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.
+
+GIO offers a much simpler asynchronous task functionality instead, that lets
+you schedule a function to be called in a separate thread, making sure that
+updates are scheduled within the main context that created the task, so you
+can update your user interface. See: [`class Gio Task`].
+
+## Mime monitoring
+
+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 [open an issue on the GLib
+issue tracker](https://gitlab.gnome.org/GNOME/glib/issues/new).