Added a section explaining character encoding for filenames.

2004-04-15  Federico Mena Quintero  <federico@ximian.com>

	* gtk/tmpl/gtkfilechooser.sgml: Added a section explaining
	character encoding for filenames.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 8bbf232b5701d373a57f000019446e4d3e0156f8..90246a2f3e210a718dcd943b06c3a34c9219dc32 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2004-04-15  Federico Mena Quintero  <federico@ximian.com>
+
+       * gtk/tmpl/gtkfilechooser.sgml: Added a section explaining
+       character encoding for filenames.
+
 2004-04-13  Matthias Clasen  <mclasen@redhat.com>
 
        * gtk/tmpl/gtkuimanager.sgml: Some corrections.

diff --git a/docs/reference/gtk/tmpl/gtkfilechooser.sgml b/docs/reference/gtk/tmpl/gtkfilechooser.sgml
index 8d88ae53247c2cdf75d4571f01862d64a9308f08..f8a003f9c37934da25a92f4c70b982de76e63211 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkfilechooser.sgml
+++ b/docs/reference/gtk/tmpl/gtkfilechooser.sgml
@@ -15,6 +15,35 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
       programming interface.
     </para>
 
+    <refsect2 id="gtkfilechooser-encodings">
+      <title>File Names and Encodings</title>
+
+      <para>
+       When the user is finished selecting files in a
+       #GtkFileChooser, your program can get the selected names
+       either as filenames or as URIs.  For URIs, the normal escaping
+       rules are applied if the URI contains non-ASCII characters.
+       However, filenames are <emphasis>always</emphasis> returned in
+       the character set specified by the
+       <envar>G_FILENAME_ENCODING</envar> environment variable.
+       Please see the Glib documentation for more details about this
+       variable.
+      </para>
+
+      <important>
+       <para>
+         This means that while you can pass the result of
+         gtk_file_chooser_get_filename() to
+         <function>open(2)</function> or
+         <function>fopen(3)</function>, you may not be able to
+         directly set it as the text of a #GtkLabel widget unless you
+         convert it first to UTF-8, which all GTK+ widgets expect.
+         You should use g_filename_to_utf8() to convert filenames
+         into strings that can be passed to GTK+ widgets.
+       </para>
+      </important>
+    </refsect2>
+
     <refsect2 id="gtkfilechooser-preview">
       <title>Adding a Preview Widget</title>