docs: Move documentation to inline comments: GtkSettings

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 65a1e4d1ac8aec6f72fdae599a8c3d8f8dda83aa..227f7d33ded1497f09ff572f74118fbff28b1c74 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -46,6 +46,7 @@ gtkscrolledwindow.sgml
 gtkseparator.sgml
 gtkseparatormenuitem.sgml
 gtkseparatortoolitem.sgml
+gtksettings.sgml
 gtkstatusbar.sgml
 gtkstyle.sgml
 gtktesting.sgml

diff --git a/docs/reference/gtk/tmpl/gtksettings.sgml b/docs/reference/gtk/tmpl/gtksettings.sgml
deleted file mode 100644 (file)
index bcabd31..0000000
--- a/docs/reference/gtk/tmpl/gtksettings.sgml
+++ /dev/null
@@ -1,532 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-Settings
-
-<!-- ##### SECTION Short_Description ##### -->
-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 ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkSettings ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkSettings:color-hash ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-alternative-button-order ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-alternative-sort-arrows ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-application-prefer-dark-theme ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-auto-mnemonics ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-button-images ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-can-change-accels ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-color-palette ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-color-scheme ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-cursor-blink ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-cursor-blink-time ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-cursor-blink-timeout ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-cursor-theme-name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-cursor-theme-size ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-dnd-drag-threshold ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-double-click-distance ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-double-click-time ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-enable-accels ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-enable-animations ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-enable-event-sounds ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-enable-input-feedback-sounds ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-enable-mnemonics ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-enable-tooltips ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-entry-password-hint-timeout ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-entry-select-on-focus ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-error-bell ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-fallback-icon-theme ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-file-chooser-backend ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-font-name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-fontconfig-timestamp ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-icon-sizes ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-icon-theme-name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-im-module ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-key-theme-name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-keynav-cursor-only ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-keynav-wrap-around ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-label-select-on-focus ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-menu-bar-accel ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-menu-bar-popup-delay ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-menu-images ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-menu-popdown-delay ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-menu-popup-delay ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-modules ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-print-backends ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-print-preview-command ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-recent-files-limit ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-recent-files-max-age ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-scrolled-window-placement ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-show-input-method-menu ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-show-unicode-menu ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-sound-theme-name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-split-cursor ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-theme-name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-timeout-expand ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-timeout-initial ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-timeout-repeat ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-toolbar-icon-size ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-toolbar-style ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-tooltip-browse-mode-timeout ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-tooltip-browse-timeout ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-tooltip-timeout ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-touchscreen-mode ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-xft-antialias ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-xft-dpi ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-xft-hinting ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-xft-hintstyle ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSettings:gtk-xft-rgba ##### -->
-<para>
-
-</para>
-
-<!-- ##### STRUCT GtkSettingsValue ##### -->
-<para>
-
-</para>
-
-@origin: 
-@value: 
-
-<!-- ##### FUNCTION gtk_settings_get_default ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_settings_get_for_screen ##### -->
-<para>
-
-</para>
-
-@screen: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_settings_install_property ##### -->
-<para>
-
-</para>
-
-@pspec: 
-
-
-<!-- ##### FUNCTION gtk_settings_install_property_parser ##### -->
-<para>
-
-</para>
-
-@pspec: 
-@parser: 
-
-
-<!-- ##### FUNCTION gtk_rc_property_parse_color ##### -->
-<para>
-
-</para>
-
-@pspec: 
-@gstring: 
-@property_value: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_rc_property_parse_enum ##### -->
-<para>
-
-</para>
-
-@pspec: 
-@gstring: 
-@property_value: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_rc_property_parse_flags ##### -->
-<para>
-
-</para>
-
-@pspec: 
-@gstring: 
-@property_value: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_rc_property_parse_requisition ##### -->
-<para>
-
-</para>
-
-@pspec: 
-@gstring: 
-@property_value: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_rc_property_parse_border ##### -->
-<para>
-
-</para>
-
-@pspec: 
-@gstring: 
-@property_value: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_settings_set_property_value ##### -->
-<para>
-
-</para>
-
-@settings: 
-@name: 
-@svalue: 
-
-
-<!-- ##### FUNCTION gtk_settings_set_string_property ##### -->
-<para>
-
-</para>
-
-@settings: 
-@name: 
-@v_string: 
-@origin: 
-
-
-<!-- ##### FUNCTION gtk_settings_set_long_property ##### -->
-<para>
-
-</para>
-
-@settings: 
-@name: 
-@v_long: 
-@origin: 
-
-
-<!-- ##### FUNCTION gtk_settings_set_double_property ##### -->
-<para>
-
-</para>
-
-@settings: 
-@name: 
-@v_double: 
-@origin: 
-
-

diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index 4ea8685bd68fb4e4f166e44a2a447685330fa07c..9b622254c25639e90a923bb56728248ecc407595 100644 (file)
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -16,6 +16,7 @@
  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
+
 #define PANGO_ENABLE_BACKEND /* for pango_fc_font_map_cache_clear() */
 
 #include "config.h"
@@ -35,6 +36,41 @@
 #include <pango/pangofc-fontmap.h>
 #endif
 
+
+/**
+ * SECTION:gtksettings
+ * @Short_description: Sharing settings between applications
+ * @Title: Settings
+ *
+ * GtkSettings provide a mechanism to share global settings between applications.
+ * On the X window system, this sharing is realized by an
+ * <ulink url="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.
+ *
+ * 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 (&argc, &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>
+ *
+ * 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.
+ */
+
+
 #ifdef GDK_WINDOWING_QUARTZ
 #define DEFAULT_KEY_THEME "Mac"
 #else