glib r6362 - in trunk/docs/reference: . gio

[matthiasc svn gnome org]

Author: matthiasc
Date: Thu Jan 24 05:35:33 2008
New Revision: 6362
URL: http://svn.gnome.org/viewvc/glib?rev=6362&view=rev

Log:
Updates


Modified:
   trunk/docs/reference/ChangeLog
   trunk/docs/reference/gio/migrating.xml

Modified: trunk/docs/reference/gio/migrating.xml
==============================================================================
--- trunk/docs/reference/gio/migrating.xml	(original)
+++ trunk/docs/reference/gio/migrating.xml	Thu Jan 24 05:35:33 2008
@@ -52,6 +52,56 @@
       </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.
+      </para>
+      <para>
+        Both systems support a the <filename>trash://</filename> scheme to
+        access a merged view of all trashed files, but 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>
+        GIO exposes some useful metadata about trashed files. There are
+        trash::orig-path and tash::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. 
+        See g_io_scheduler_push_job(). 
+      </para>
+
+    </section>
   </chapter>
 
 </part>