[glib/gdbus-merge] Add a migration chapter for dbus bits
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib/gdbus-merge] Add a migration chapter for dbus bits
- Date: Thu, 6 May 2010 22:01:42 +0000 (UTC)
commit 133f66538dbf266be3c99b34f1eeee0a5e6068ac
Author: Matthias Clasen <mclasen redhat com>
Date: Thu May 6 17:52:54 2010 -0400
Add a migration chapter for dbus bits
Also split migration.xml into separate files per chapter, it was
getting unwieldy.
docs/reference/gio/Makefile.am | 10 +-
docs/reference/gio/gio-docs.xml | 8 +-
docs/reference/gio/migrating-dbus-glib.xml | 7 +
.../gio/{migrating.xml => migrating-gconf.xml} | 163 --------------------
docs/reference/gio/migrating-gnome-vfs.xml | 133 ++++++++++++++++
.../gio/{migrating.xml => migrating-posix.xml} | 0
6 files changed, 155 insertions(+), 166 deletions(-)
---
diff --git a/docs/reference/gio/Makefile.am b/docs/reference/gio/Makefile.am
index 3d667e1..4e77a25 100644
--- a/docs/reference/gio/Makefile.am
+++ b/docs/reference/gio/Makefile.am
@@ -114,7 +114,10 @@ HTML_IMAGES = \
content_files = \
version.xml \
overview.xml \
- migrating.xml \
+ migrating-posix.xml \
+ migrating-gnome-vfs.xml \
+ migrating-gconf.xml \
+ migrating-dbus-glib.xml \
gio-querymodules.xml \
glib-compile-schemas.xml\
gsettings.xml \
@@ -122,7 +125,10 @@ content_files = \
expand_content_files = \
overview.xml \
- migrating.xml
+ migrating-posix.xml \
+ migrating-gnome-vfs.xml \
+ migrating-gconf.xml \
+ migrating-dbus-glib.xml
extra_files = \
version.xml.in \
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index 748955b..7a0e4ae 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -169,7 +169,13 @@
</chapter>
</part>
- <xi:include href="xml/migrating.xml"/>
+ <part id="migrating">
+ <title>Migrating to GIO</title>
+ <xi:include href="xml/migrating-posix.xml"/>
+ <xi:include href="xml/migrating-gnome-vfs.xml"/>
+ <xi:include href="xml/migrating-gconf.xml"/>
+ <xi:include href="xml/migrating-dbus-glib.xml"/>
+ </part>
<chapter id="gio-hierarchy">
<title>Object Hierarchy</title>
diff --git a/docs/reference/gio/migrating-dbus-glib.xml b/docs/reference/gio/migrating-dbus-glib.xml
new file mode 100644
index 0000000..2dda37e
--- /dev/null
+++ b/docs/reference/gio/migrating-dbus-glib.xml
@@ -0,0 +1,7 @@
+<chapter>
+ <title>Migrating from dbus-glib to GDBus</title>
+
+ <para>
+ Hints for migrating from dbus-glib to GDBus will appear here shortly...
+ </para>
+</chapter>
diff --git a/docs/reference/gio/migrating.xml b/docs/reference/gio/migrating-gconf.xml
similarity index 75%
copy from docs/reference/gio/migrating.xml
copy to docs/reference/gio/migrating-gconf.xml
index df711af..23c2ddb 100644
--- a/docs/reference/gio/migrating.xml
+++ b/docs/reference/gio/migrating-gconf.xml
@@ -1,164 +1,3 @@
-<part id="migrating">
- <title>Migrating to GIO</title>
-
- <chapter>
- <title>Migrating from POSIX to GIO</title>
-
- <table id="posix-vs-gio">
- <title>Comparison of POSIX and GIO concepts</title>
- <tgroup cols="2">
- <thead>
- <row><entry>POSIX</entry><entry>GIO</entry></row>
- </thead>
- <tbody>
- <row><entry>char *path</entry><entry>GFile *file</entry></row>
- <row><entry>struct stat *buf</entry><entry>GFileInfo *info</entry></row>
- <row><entry>struct statvfs *buf</entry><entry>GFileInfo *info</entry></row>
- <row><entry morerows="1">int fd</entry><entry>GInputStream *in</entry></row>
- <row><entry>GOutputStream *out</entry></row>
- <row><entry>DIR *</entry><entry>GFileEnumerator *enum</entry></row>
- <row><entry>fstab entry</entry><entry>GUnixMountPoint *mount_point</entry></row>
- <row><entry>mtab entry</entry><entry>GUnixMountEntry *mount_entry</entry></row>
- </tbody>
- </tgroup>
- </table>
-
- </chapter>
-
- <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 & 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="http://bugzilla.gnome.org";>bugzilla.gnome.org</ulink>.
- </para>
- </section>
- </chapter>
-
<chapter>
<title>Migrating from GConf to GSettings</title>
@@ -577,5 +416,3 @@ some-odd-key1 = /apps/myapp/some_ODD-key1
</para>
</section>
</chapter>
-
-</part>
diff --git a/docs/reference/gio/migrating-gnome-vfs.xml b/docs/reference/gio/migrating-gnome-vfs.xml
new file mode 100644
index 0000000..ba3987c
--- /dev/null
+++ b/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 & 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="http://bugzilla.gnome.org";>bugzilla.gnome.org</ulink>.
+ </para>
+ </section>
+ </chapter>
diff --git a/docs/reference/gio/migrating.xml b/docs/reference/gio/migrating-posix.xml
similarity index 100%
rename from docs/reference/gio/migrating.xml
rename to docs/reference/gio/migrating-posix.xml
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
