mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-05-14 18:03:11 +02:00
Matthias Clasen
Philip Withnall
parent
221ba4e211
commit
c09f48bb28
@ -270,7 +270,6 @@
|
|||||||
<part id="migrating">
|
<part id="migrating">
|
||||||
<title>Migrating to GIO</title>
|
<title>Migrating to GIO</title>
|
||||||
<xi:include href="xml/migrating-posix.xml"/>
|
<xi:include href="xml/migrating-posix.xml"/>
|
||||||
<xi:include href="xml/migrating-gnome-vfs.xml"/>
|
|
||||||
<xi:include href="xml/migrating-gdbus.xml"/>
|
<xi:include href="xml/migrating-gdbus.xml"/>
|
||||||
</part>
|
</part>
|
||||||
|
|
||||||
|
|||||||
@ -41,6 +41,7 @@ urlmap_file = "urlmap.js"
|
|||||||
# The same order will be used when generating the index
|
# The same order will be used when generating the index
|
||||||
content_files = [
|
content_files = [
|
||||||
"migrating-gconf.md",
|
"migrating-gconf.md",
|
||||||
|
"migrating-gnome-vfs.md",
|
||||||
]
|
]
|
||||||
content_images = [
|
content_images = [
|
||||||
"menu-example.png",
|
"menu-example.png",
|
||||||
|
|||||||
@ -163,7 +163,6 @@ if get_option('gtk_doc')
|
|||||||
content_files = [
|
content_files = [
|
||||||
'overview.xml',
|
'overview.xml',
|
||||||
'migrating-posix.xml',
|
'migrating-posix.xml',
|
||||||
'migrating-gnome-vfs.xml',
|
|
||||||
'migrating-gdbus.xml',
|
'migrating-gdbus.xml',
|
||||||
'gio-querymodules.xml',
|
'gio-querymodules.xml',
|
||||||
'glib-compile-schemas.xml',
|
'glib-compile-schemas.xml',
|
||||||
@ -199,7 +198,6 @@ if get_option('gtk_doc')
|
|||||||
expand_content_files : [
|
expand_content_files : [
|
||||||
'overview.xml',
|
'overview.xml',
|
||||||
'migrating-posix.xml',
|
'migrating-posix.xml',
|
||||||
'migrating-gnome-vfs.xml',
|
|
||||||
'migrating-gdbus.xml',
|
'migrating-gdbus.xml',
|
||||||
'gdbus-codegen.xml',
|
'gdbus-codegen.xml',
|
||||||
],
|
],
|
||||||
@ -236,6 +234,7 @@ endif
|
|||||||
# gi-docgen version
|
# gi-docgen version
|
||||||
expand_content_files = [
|
expand_content_files = [
|
||||||
'migrating-gconf.md',
|
'migrating-gconf.md',
|
||||||
|
'migrating-gnome-vfs.md',
|
||||||
]
|
]
|
||||||
|
|
||||||
gio_gir = meson.current_source_dir() / 'Gio-2.0.gir'
|
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…
x
Reference in New Issue
Block a user