[gtk+/gtk-2-24] filechooser: Document the settings keys

[Federico Mena Quintero <federico src gnome org>]

commit a0a005def7d2c37e350ad494cd020107548cd248
Author: Federico Mena Quintero <federico gnome org>
Date:   Mon Jan 6 15:05:44 2014 -0600

    filechooser: Document the settings keys
    
    This is so people can modify gnome-tweak-tool or whatever without directly diving into
    the source.

 gtk/gtkfilechooser.c |   91 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 91 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index a4214d3..be078b4 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -529,6 +529,97 @@
  *     </variablelist>
  * </refsect3>
  * </refsect2>
+ * <refsect2 id="gtkfilechooser-configuration-options">
+ * <title>Configuration Options</title>
+ * <para>
+ * In GTK+ 2.x, the file chooser saves its state and configuration options in a
+ * <filename>gtk-2.0/gtkfilechooser.ini</filename> file under the directory that
+ * g_get_user_config_dir() returns.  (On Unix, this usually resolves to
+ * <filename>$HOME/username/.config/gtk-2.0/gtkfilechooser.ini.)  While some of
+ * the available options can be changed directly through the file chooser's user
+ * interface, a couple are only editable by hand or by third-party tools (such
+ * as <ulink
+ * url="https://wiki.gnome.org/action/show/Apps/GnomeTweakTool";>gnome-tweak-tool</ulink>).
+ * This section describes the available options.
+ * </para>
+ * <para>
+ * This is a sample of the contents of a <filename>gtkfilechooser.ini</filename>
+ * file.  Note that all the following options go under a
+ * <literal>[Filechooser Settings]</literal> heading.
+ * </para>
+ * <programlisting>
+ * [Filechooser Settings]
+ * LocationMode=filename-entry
+ * ShowHidden=false
+ * ExpandFolders=true
+ * GeometryX=570
+ * GeometryY=273
+ * GeometryWidth=780
+ * GeometryHeight=585
+ * ShowSizeColumn=true
+ * SortColumn=name
+ * SortOrder=ascending
+ * StartupMode=recent
+ * </programlisting>
+ * <refsect3 id="gtkfilechooser-settings-location-mode">
+ * <title>LocationMode key</title>
+ * <para>
+ * The <literal>LocationMode</literal> key controls whether the file chooser
+ * shows just a path bar, or a visible entry for the filename as well, for the
+ * benefit of typing-oriented users.  The possible string values for these modes
+ * are <literal>path-bar<literal> and <literal>filename-entry</literal>,
+ * respectively.
+ * </para>
+ * </refsect3>
+ * <refsect3 id="gtkfilechooser-settings-show-hidden">
+ * <title>ShowHidden key</title>
+ * <para>
+ * The <literal>ShowHidden</literal> key controls whether the file chooser shows
+ * hidden files or not.  The value can be be <literal>true</literal> or
+ * <literal>false</literal>.
+ * </para>
+ * </refsect3>
+ * <refsect3 id="gtkfilechooser-settings-show-size-column">
+ * <title>ShowSizeColumn key</title>
+ * <para>
+ * The <literal>ShowSize</literal> key controls whether the file chooser shows
+ * a column with file sizes.  The value can be be <literal>true</literal> or
+ * <literal>false</literal>.
+ * </para>
+ * </refsect3>
+ * <refsect3 id="gtkfilechooser-settings-geometry-keys">
+ * <title>Geometry keys</title>
+ * <para>
+ * The four keys <literal>GeometryX</literal>, <literal>GeometryY</literal>,
+ * <literal>GeometryWidth</literal>, <literal>GeometryHeight</literal> save the
+ * position and dimensions of the #GtkFileChooserDialog's window.
+ * </para>
+ * <refsect3 id="gtkfilechooser-settings-sort-column">
+ * <title>SortColumn key</title>
+ * <para>
+ * The <literal>SortColumn</literal> key can be one of the strings
+ * <literal>name</literal>, <literal>modified</literal>, or
+ * <literal>size</literal>.  It controls which of the columns in the file
+ * chooser is used for sorting the list of files.
+ * </para>
+ * </refsect3>
+ * <refsect3 id="gtkfilechooser-settings-sort-order">
+ * <title>SortOrder key</title>
+ * <para>
+ * The <literal>SortOrder<literal> key can be one of the strings
+ * <literal>ascending</literal> or <literal>descending</literal>.
+ * </para>
+ * </refsect3>
+ * <refsect3 id="gtkfilechooser-settings-startup-mode">
+ * <title>StartupMode key</title>
+ * <para>
+ * The <literal>StartupMode</literal> key controls whether the file chooser
+ * starts up showing the list of recently-used files, or the contents of the
+ * current working directory.  Respectively, the values can be
+ * <literal>recent</literal> or <literal>cwd</literal>.
+ * </para>
+ * </refsect3>
+ * </refsect2>
  */