[gtk+] Add a long description for GtkSettings

[Matthias Clasen <matthiasc src gnome org>]

commit cf0ab196fe1edcd7a82dc3071db74d4ba436deaa
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Jun 11 01:28:39 2009 -0400

    Add a long description for GtkSettings
    
    Among other things, the description mentions the problem in
    bug 585024, that some settings may not be available before the
    widget class has been realized.
---
 docs/reference/gtk/tmpl/gtksettings.sgml |   28 ++++++++++++++++++++++++++++
 1 files changed, 28 insertions(+), 0 deletions(-)

diff --git a/docs/reference/gtk/tmpl/gtksettings.sgml b/docs/reference/gtk/tmpl/gtksettings.sgml
index 2a5988d..5219c1a 100644
--- a/docs/reference/gtk/tmpl/gtksettings.sgml
+++ b/docs/reference/gtk/tmpl/gtksettings.sgml
@@ -6,7 +6,35 @@ Sharing settings between applications
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+GtkSettings provide a mechanism to share global settings between applications.
+On the X window system, this sharing is realized by an <ulink href="http://www.freedesktop.org/wiki/Specifications/xsettings-spec";>XSettings</ulink>
+manager that is usually part of the desktop environment, along with utilities
+that let the user change these settings. In the absence of an Xsettings manager,
+settings can also be specified in RC files.
+</para>
+
+<para>
+Applications can override system-wide settings with gtk_settings_set_string_property(),
+gtk_settings_set_long_property(), etc. This should be restricted to special
+cases though; GtkSettings are not meant as an application configuration
+facility. When doing so, you need to be aware that settings that are specific
+to individual widgets may not be available before the widget type has been
+realized at least once. The following example demonstrates a way to do this:
+<informalexample><programlisting>
+  gtk_init (&amp;argc, &amp;argv);
+
+  /&ast; make sure the type is realized &ast/
+  g_type_class_unref (g_type_class_ref (GTK_TYPE_IMAGE_MENU_ITEM));
 
+  g_object_set (gtk_settings_get_default (), "gtk-menu-images", FALSE, NULL);
+</programlisting></informalexample>
+</para>
+
+<para>
+There is one GtkSettings instance per screen. It can be obtained with
+gtk_settings_get_for_screen(), but in many cases, it is more convenient
+to use gtk_widget_get_settings(). gtk_settings_get_default() returns the
+GtkSettings instance for the default screen.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->