From 133f66538dbf266be3c99b34f1eeee0a5e6068ac Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 6 May 2010 17:52:54 -0400 Subject: [PATCH] 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 + docs/reference/gio/migrating-gconf.xml | 418 ++++++++++++++++++ docs/reference/gio/migrating-gnome-vfs.xml | 133 ++++++ .../{migrating.xml => migrating-posix.xml} | 0 6 files changed, 573 insertions(+), 3 deletions(-) create mode 100644 docs/reference/gio/migrating-dbus-glib.xml create mode 100644 docs/reference/gio/migrating-gconf.xml create mode 100644 docs/reference/gio/migrating-gnome-vfs.xml rename docs/reference/gio/{migrating.xml => migrating-posix.xml} (100%) diff --git a/docs/reference/gio/Makefile.am b/docs/reference/gio/Makefile.am index 3d667e122..4e77a2578 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 748955b0e..7a0e4ae2c 100644 --- a/docs/reference/gio/gio-docs.xml +++ b/docs/reference/gio/gio-docs.xml @@ -169,7 +169,13 @@ - + + Migrating to GIO + + + + + Object Hierarchy diff --git a/docs/reference/gio/migrating-dbus-glib.xml b/docs/reference/gio/migrating-dbus-glib.xml new file mode 100644 index 000000000..2dda37ec9 --- /dev/null +++ b/docs/reference/gio/migrating-dbus-glib.xml @@ -0,0 +1,7 @@ + + Migrating from dbus-glib to GDBus + + + Hints for migrating from dbus-glib to GDBus will appear here shortly... + + diff --git a/docs/reference/gio/migrating-gconf.xml b/docs/reference/gio/migrating-gconf.xml new file mode 100644 index 000000000..23c2ddb55 --- /dev/null +++ b/docs/reference/gio/migrating-gconf.xml @@ -0,0 +1,418 @@ + + Migrating from GConf to GSettings + +
+ Before you start + + + Converting individual applications and their settings from GConf to + GSettings can be done at will. But desktop-wide settings like font or + theme settings often have consumers in multiple modules. Therefore, + some consideration has to go into making sure that all users of a setting + are converted to GSettings at the same time or that the program + responsible for configuring that setting continues to update the value in + both places. + + + It is always a good idea to have a look at how others have handled + similar problems before. An examplaric conversion can be found e.g. + in the gsettings-tutorial branch of gnome-utils. + +
+ +
+ Conceptual differences + + + Conceptually, GConf and GSettings are fairly similar. Both + have a concept of pluggable backends. Both keep information + about keys and their types in schemas. Both have a concept of + mandatory values, which lets you implement lock-down. + + + There are some differences in the approach to schemas. GConf + installs the schemas into the database and has API to handle + schema information (gconf_client_get_default_from_schema(), + gconf_value_get_schema(), etc). GSettings on the other hand + assumes that an application knows its own schemas, and does + not provide API to handle schema information at runtime. + GSettings is also more strict about requiring a schema whenever + you want to read or write a key. To deal with more free-form + information that would appear in schema-less entries in GConf, + GSettings allows for schemas to be 'relocatable'. + + + One difference in the way applications interact with their + settings is that with GConf you interact with a tree of + settings (ie the keys you pass to functions when reading + or writing values are actually paths with the actual name + of the key as the last element. With GSettings, you create + a GSettings object which has an implicit prefix that determines + where the settings get stored in the global tree of settings, + but the keys you pass when reading or writing values are just + the key names, not the full path. + +
+ +
+ GConfClient (and GConfBridge) API conversion + + + Most people use GConf via the high-level #GConfClient API. + The corresponding API is the #GSettings object. While not + every GConfClient function has a direct GSettings equivalent, + many do: + + + + GConfClientGSettings + + + gconf_client_get_default()no direct equivalent, + instead you call g_settings_new() for the schemas you use + gconf_client_set()g_settings_set() + gconf_client_get()g_settings_get() + gconf_client_get_bool()g_settings_get_boolean() + gconf_client_set_bool()g_settings_set_boolean() + gconf_client_get_int()g_settings_get_int() + gconf_client_set_int()g_settings_set_int() + gconf_client_get_float()g_settings_get_double() + gconf_client_set_float()g_settings_set_double() + gconf_client_get_string()g_settings_get_string() + gconf_client_set_string()g_settings_set_string() + gconf_client_get_list()for string lists, see g_settings_get_strv(), else see g_settings_get_value() and #GVariant API + gconf_client_set_list()for string lists, see g_settings_set_strv(), else see g_settings_set_value() and #GVariant API + gconf_entry_get_is_writable()g_settings_is_writable() + gconf_client_notify_add()not required, the #GSettings::changed signal is emitted automatically + gconf_client_add_dir()not required, each GSettings instance automatically watches all keys in its path + #GConfChangeSetg_settings_delay(), g_settings_apply() + gconf_client_get_default_from_schema()no equivalent, applications are expected to know their schema + gconf_client_all_entries()no equivalent, applications are expected to know their schema, and GSettings does not allow schema-less entries + gconf_client_get_without_default()no equivalent + gconf_bridge_bind_property()g_settings_bind() + gconf_bridge_bind_property_full()g_settings_bind_with_mapping() + + +
+ + + GConfBridge was a third-party library that used GConf to bind an object property + to a particular configuration key. GSettings offers this service itself. + + + There is a pattern that is sometimes used for GConf, where a setting can have + explicit 'value A', explicit 'value B' or 'use the system default'. With GConf, + 'use the system default' is sometimes implemented by unsetting the user value. + + + This is not possible in GSettings, since it does not have API to determine if a value + is the default and does not let you unset values. The recommended way (and much + clearer) way in which this can be implemented in GSettings is to have a separate + 'use-system-default' boolean setting. + +
+ +
+ Change notification + + + GConf requires you to call gconf_client_add_dir() and + gconf_client_notify_add() to get change notification. With + GSettings, this is not necessary; signals get emitted automatically + for every change. + + + The #GSettings::changed signal is emitted for each changed key. + There is also a #GSettings::change-event signal that you can handle + if you need to see groups of keys that get changed at the same time. + + + GSettings also notifies you about changes in writability of keys, + with the #GSettings::writable-changed signal (and the + #GSettings::writable-change-event signal). + +
+ +
Change sets + + GConf has a a concept of a set of changes which can be applied or reverted + at once: #GConfChangeSet (GConf doesn't actually apply changes atomically, + which is one of its shortcomings). + + + Instead of a separate object to represent a change set, GSettings has a + 'delayed-apply' mode, which can be turned on for a GSettings object by + calling g_settings_delay(). In this mode, changes done to the GSettings + object are not applied - they are still visible when calling g_settings_get() + on the same object, but not to other GSettings instances + or even other processes. + + + To apply the pending changes all at once (GSettings does + atomicity here), call g_settings_apply(). To revert the pending changes, + call g_settings_revert() or just drop the reference to the #GSettings object. + +
+ +
+ Schema conversion + + + If you are porting your application from GConf, most likely you already + have a GConf schema. GIO comes with a commandline tool + gsettings-schema-convert + that can help with the task of converting a GConf schema into + an equivalent GSettings schema. The tool is not perfect and + may need assistence in some cases. + + An example for using gsettings-schema-convert + Running gsettings-schema-convert --gconf --xml --schema-id "org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml destop_gnome_font_rendering.schemas on the following desktop_gnome_font_rendering.schemas file: + + + + + + /schemas/desktop/gnome/font_rendering/dpi + /desktop/gnome/font_rendering/dpi + gnome + int + 96 + + DPI + The resolution used for converting font sizes to pixel sizes, in dots per inch. + + + + +]]> + +produces a org.gnome.font-rendering.gschema.xml file with the following content: + + + + + 96 + DPI + The resolution used for converting font sizes to pixel sizes, in dots per inch. + + + +]]> + + + + + + GSettings schemas are identified at runtime by their id (as specified + in the XML source file). It is recommended to use a dotted name as schema + id, similar in style to a DBus bus name, e.g. "org.gnome.font-rendering". + The filename used for the XML schema source is immaterial, but + schema compiler expects the files to have the extension + .gschema.xml. It is recommended to simply + use the schema id as the filename, followed by this extension, + e.g. org.gnome.font-rendering.gschema.xml. + + + + The XML source file for your GSettings schema needs to get installed + into $datadir/glib-2.0/schemas, and needs to be + compiled into a binary form. At runtime, GSettings looks for compiled + schemas in the glib-2.0/schemas subdirectories + of all XDG_DATA_DIRS directories, so if you install + your schema in a different location, you need to set the + XDG_DATA_DIRS environment variable appropriately. + + + Schemas are compiled into binary form by the + glib-compile-schemas utility. + GIO provides a gschema_compile + variable for the schema compiler, which can be used in + configure.in as follows: + +GLIB_GSETTINGS + + The corresponding Makefile.am fragment looks like + this: + +# gsettingsschemadir and gschema_compile are defined by the GLIB_GSETTINGS +# macro in configure.ac +gsettingsschema_DATA = my.app.gschema.xml +# This rule will check your schemas for validity before installation +@GSETTINGS_CHECK_RULE@ +if GSETTINGS_SCHEMAS_INSTALL +install-data-hook: + $(GLIB_COMPILE_SCHEMAS) $(DESTDIR)$(gsettingsschemadir) +endif + + + + + One possible pitfall in doing schema conversion is that the default + values in GSettings schemas are parsed by the #GVariant parser. + This means that strings need to include quotes in the XML. Also note + that the types are now specified as #GVariant type strings. + +string +rgb +]]> + + becomes + + + 'rgb' + +]]> + + + + Another possible complication is that GConf specifies full paths + for each key, while a GSettings schema has a 'path' attribute that + contains the prefix for all the keys in the schema, and individual + keys just have a simple name. So + +/schemas/desktop/gnome/font_rendering/antialiasing +]]> + + becomes + + + +]]> + + + + Default values can be localized in both GConf and GSettings schemas, + but GSettings uses gettext for the localization. You can specify + the gettext domain to use in the gettext-domain + attribute. Therefore, when converting localized defaults in GConf, + +/schemas/apps/my_app/font_size + + 18 + + + 24 + + +]]> + + becomes + + + ... + + 18 + +]]> + + Note how we used the context attribute to add msgctxt - "18" is not a + good string to look up in gettext by itself. Also note that the value + 24 is not present in the schema anymore. It has to be added to the + gettext catalog for "be" instead. + + + GSettings schemas have optional summary and + description elements for each key which + correspond to the short and + long elements in the GConf schema and + will be used in similar ways by a future gsettings-editor, so you + should use the same conventions for them: The summary is just a short + label with no punctuation, the description can be one or more complete + sentences. Translations for these strings will also be handled + via gettext, so you should arrange for these strings to be + extracted into your gettext catalog. + + + GSettings is a bit more restrictive about key names than GConf. Key + names in GSettings can be at most 32 characters long, and must only + consist of lowercase characters, numbers and dashes, with no + consecutive dashes. The first character must not be a number or dash, + and the last character cannot be '-'. + + + If you are using the GConf backend for GSettings during the + transition, you may want to keep your key names the same they + were in GConf, so that existing settings in the users GConf + database are preserved. You can achieve this by using the + with the + glib-compile-schemas schema + compiler. Note that this option is only meant + to ease the process of porting your application, allowing parts + of your application to continue to access GConf and parts to use + GSettings. By the time you have finished porting your application + you must ensure that all key names are valid. + +
+ +
Data conversion + + GConf comes with a GSettings backend that can be used to + facility the transition to the GSettings API until you are + ready to make the jump to a different backend (most likely + dconf). To use it, you need to set the GSETTINGS_BACKEND + to 'gconf', e.g. by using + + g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE); + + early on in your program. Note that this backend is meant purely + as a transition tool, and should not be used in production. + + + GConf also comes with a utility called + gsettings-data-convert, which is designed to help + with the task of migrating user settings from GConf into another + GSettings backend. It can be run manually, but it is designed to be + executed automatically, every time a user logs in. It keeps track of + the data migrations that it has already done, and it is harmless to + run it more than once. + + + To make use of this utility, you must install a keyfile in the + directory /usr/share/GConf/gsettings which + lists the GSettings keys and GConf paths to map to each other, for + each schema that you want to migrate user data for. + + + Here is an example: + + + + The last key demonstrates that it may be necessary to modify the key + name to comply with stricter GSettings key name rules. Of course, + that means your application must use the new key names when looking + up settings in GSettings. + + + The last group in the example also shows how to handle the case + of 'relocatable' schemas, which don't have a fixed path. You can + specify the path to use in the group name, separated by a colon. + + + There are some limitations: gsettings-data-convert + does not do any transformation of the values. And it does not handle + complex GConf types other than lists of strings or integers. + + + Don't forget to require GConf 2.31.1 or newer in your configure + script if you are making use of the GConf backend or the conversion + utility. + +
+ diff --git a/docs/reference/gio/migrating-gnome-vfs.xml b/docs/reference/gio/migrating-gnome-vfs.xml new file mode 100644 index 000000000..ba3987cad --- /dev/null +++ b/docs/reference/gio/migrating-gnome-vfs.xml @@ -0,0 +1,133 @@ + + Migrating from GnomeVFS to GIO + + + Comparison of GnomeVFS and GIO concepts + + + GnomeVFSGIO + + + GnomeVFSURIGFile + GnomeVFSFileInfoGFileInfo + GnomeVFSResultGError, with G_IO_ERROR values + GnomeVFSHandle & GnomeVFSAsyncHandleGInputStream or GOutputStream + GnomeVFSDirectoryHandleGFileEnumerator + mime typecontent type + GnomeVFSMonitorGFileMonitor + GnomeVFSVolumeMonitorGVolumeMonitor + GnomeVFSVolumeGMount + GnomeVFSDriveGVolume + -GDrive + GnomeVFSContextGCancellable + gnome_vfs_async_cancelg_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 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: + + +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 g_file_trash() + function. + +
+ +
+ 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 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(). + + +
+ +
+ 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 report it at + bugzilla.gnome.org. + +
+ 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