mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-02-04 10:16:17 +01:00
Matthias Clasen
Philip Withnall
parent
221ba4e211
commit
c09f48bb28
@ -270,7 +270,6 @@
|
||||
<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-gdbus.xml"/>
|
||||
</part>
|
||||
|
||||
|
||||
@ -41,6 +41,7 @@ urlmap_file = "urlmap.js"
|
||||
# The same order will be used when generating the index
|
||||
content_files = [
|
||||
"migrating-gconf.md",
|
||||
"migrating-gnome-vfs.md",
|
||||
]
|
||||
content_images = [
|
||||
"menu-example.png",
|
||||
|
||||
@ -163,7 +163,6 @@ if get_option('gtk_doc')
|
||||
content_files = [
|
||||
'overview.xml',
|
||||
'migrating-posix.xml',
|
||||
'migrating-gnome-vfs.xml',
|
||||
'migrating-gdbus.xml',
|
||||
'gio-querymodules.xml',
|
||||
'glib-compile-schemas.xml',
|
||||
@ -199,7 +198,6 @@ if get_option('gtk_doc')
|
||||
expand_content_files : [
|
||||
'overview.xml',
|
||||
'migrating-posix.xml',
|
||||
'migrating-gnome-vfs.xml',
|
||||
'migrating-gdbus.xml',
|
||||
'gdbus-codegen.xml',
|
||||
],
|
||||
@ -236,6 +234,7 @@ endif
|
||||
# gi-docgen version
|
||||
expand_content_files = [
|
||||
'migrating-gconf.md',
|
||||
'migrating-gnome-vfs.md',
|
||||
]
|
||||
|
||||
gio_gir = meson.current_source_dir() / 'Gio-2.0.gir'
|
||||
|
||||
109
docs/reference/gio/migrating-gnome-vfs.md
Normal file
109
docs/reference/gio/migrating-gnome-vfs.md
Normal file
@ -0,0 +1,109 @@
|
||||
Title: Migrating from GnomeVFS to GIO
|
||||
SPDX-License-Identifier: LGPL-2.1-or-later
|
||||
SPDX-FileCopyrightText: 2010 Matthias Clasen
|
||||
|
||||
# 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).
|
||||
@ -1,133 +0,0 @@
|
||||
<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="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
Loading…
Reference in New Issue
Block a user