Added the text for the initial section, and descriptions for the signals

2003-10-23  Federico Mena Quintero  <federico@ximian.com>

	* gtk/tmpl/gtkfilechooser.sgml: Added the text for the initial
	section, and descriptions for the signals and enumerations.

	* gtk/tmpl/gtkfilechooserdialog.sgml: Added the text for the
	initial section, and a short example.

	* gtk/tmpl/gtkfilechooserwidget.sgml: Added the text for the
	initial section.

5 files changed, 135 insertions, 69 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index e4e570954..dc695474a 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,14 @@
+2003-10-23  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/tmpl/gtkfilechooser.sgml: Added the text for the initial
+	section, and descriptions for the signals and enumerations.
+
+	* gtk/tmpl/gtkfilechooserdialog.sgml: Added the text for the
+	initial section, and a short example.
+
+	* gtk/tmpl/gtkfilechooserwidget.sgml: Added the text for the
+	initial section.
+
 Fri Oct 24 00:25:07 2003  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/tmpl/gtkfilefilter.sgml: 
diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt
index 959742b58..96b7d83e8 100644
--- a/docs/reference/gtk/gtk-sections.txt
+++ b/docs/reference/gtk/gtk-sections.txt
@@ -1067,7 +1067,6 @@ GtkExpanderPrivate
 <SECTION>
 <FILE>gtkfilechooser</FILE>
 <TITLE>GtkFileChooser</TITLE>
-GtkFileChooser
 GtkFileChooserAction
 GTK_FILE_CHOOSER_ERROR
 GtkFileChooserError
@@ -1121,6 +1120,7 @@ GTK_FILE_CHOOSER
 GTK_IS_FILE_CHOOSER
 GTK_TYPE_FILE_CHOOSER
 <SUBSECTION Private>
+GtkFileChooser
 gtk_file_chooser_get_type
 </SECTION>
 
diff --git a/docs/reference/gtk/tmpl/gtkfilechooser.sgml b/docs/reference/gtk/tmpl/gtkfilechooser.sgml
index b93a65b88..f989347e6 100644
--- a/docs/reference/gtk/tmpl/gtkfilechooser.sgml
+++ b/docs/reference/gtk/tmpl/gtkfilechooser.sgml
@@ -2,74 +2,51 @@
 GtkFileChooser
 
 <!-- ##### SECTION Short_Description ##### -->
-an interface that represents a graphical file selector
+File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+    <para>
+      #GtkFileChooser is an interface that can be implemented by file
+      selection widgets.  In GTK+, the main objects that implement
+      this interface are #GtkFileChooserWidget and
+      #GtkFileChooserDialog.  You do not need to write an object that
+      implements the #GtkFileChooser interface unless you are trying
+      to adapt an existing file selector to expose a standard
+      programming interface.
+    </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### STRUCT GtkFileChooser ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
-<!-- ##### SIGNAL GtkFileChooser::file-activated ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
-<!-- ##### SIGNAL GtkFileChooser::selection-changed ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
-<!-- ##### SIGNAL GtkFileChooser::update-preview ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
+    <para>
+      #GtkFileChooserDialog, #GtkFileChooserWidget
+    </para>
 
 <!-- ##### ENUM GtkFileChooserAction ##### -->
-<para>
+    <para>
+      Describes whether a #GtkFileChooser is being used to open
+      existing files or to save to a possibly new file.
+    </para>
 
-</para>
-
-@GTK_FILE_CHOOSER_ACTION_OPEN: 
-@GTK_FILE_CHOOSER_ACTION_SAVE: 
+@GTK_FILE_CHOOSER_ACTION_OPEN: Indicates Open mode.  The file chooser
+    will only let the user pick an existing file.
+@GTK_FILE_CHOOSER_ACTION_SAVE: Indicates Save mode.  The file chooser
+    will let the user pick an existing file, or type in a new
+    filename.
 
 <!-- ##### MACRO GTK_FILE_CHOOSER_ERROR ##### -->
-<para>
-
-</para>
+    <para>
+      Used to get the #GError quark for #GtkFileChooser errors.
+    </para>
 
 
 
 <!-- ##### ENUM GtkFileChooserError ##### -->
-<para>
+    <para>
+      These identify the various errors that can occur while calling
+      #GtkFileChooser functions.
+    </para>
 
-</para>
-
-@GTK_FILE_CHOOSER_ERROR_NONEXISTENT: 
-@GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: 
+@GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
+@GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
 
 <!-- ##### FUNCTION gtk_file_chooser_error_quark ##### -->
 <para>
@@ -481,3 +458,12 @@ an interface that represents a graphical file selector
 @Returns: 
 
 
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
+End:
+-->
+
+
diff --git a/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml b/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml
index 1863aa1cf..1c82b9cb9 100644
--- a/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml
+++ b/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml
@@ -2,18 +2,59 @@
 GtkFileChooserDialog
 
 <!-- ##### SECTION Short_Description ##### -->
-implements GtkFileChooser as a dialog
-
+A file chooser dialog, suitable for "File/Open" or "File/Save" commands.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
+    <para>
+      #GtkFileChooserDialog is a dialog box suitable for use with
+      "File/Open" or "File/Save as" commands.  This widget works by
+      putting a #GtkFileChooserWidget inside a #GtkDialog.  It exposes
+      the #GtkFileChooserIface interface, so you can use all of the
+      #GtkFileChooser functions on the file chooser dialog as well as
+      those for #GtkDialog.
+    </para>
 
-</para>
+    <para>
+      Note that #GtkFileChooserDialog does not have any methods of its
+      own.  Instead, you should use the functions that work on a
+      #GtkFileChooser.
+    </para>
 
-<!-- ##### SECTION See_Also ##### -->
-<para>
+    <example>
+      <title>Typical usage</title>
 
-</para>
+      <para>
+	In the simplest of cases, you can use #GtkFileChooserDialog
+	as in the following code:
+      </para>
+
+      <programlisting>
+GtkWidget *dialog;
+
+dialog = gtk_file_chooser_dialog_new ("Open File",
+				      parent_window,
+				      GTK_FILE_CHOOSER_ACTION_OPEN,
+				      GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
+				      GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
+				      NULL);
+
+if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
+  {
+    char *filename;
+
+    filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
+    open_file (filename);
+    g_free (filename);
+  }
+
+gtk_widget_destroy (dialog);
+      </programlisting>
+    </example>
+
+<!-- ##### SECTION See_Also ##### -->
+    <para>
+      #GtkFileChooser, #GtkDialog
+    </para>
 
 <!-- ##### FUNCTION gtk_file_chooser_dialog_new ##### -->
 <para>
@@ -28,3 +69,11 @@ implements GtkFileChooser as a dialog
 @Returns: 
 
 
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
+End:
+-->
+
+
diff --git a/docs/reference/gtk/tmpl/gtkfilechooserwidget.sgml b/docs/reference/gtk/tmpl/gtkfilechooserwidget.sgml
index c61e5a527..9cd988088 100644
--- a/docs/reference/gtk/tmpl/gtkfilechooserwidget.sgml
+++ b/docs/reference/gtk/tmpl/gtkfilechooserwidget.sgml
@@ -2,17 +2,27 @@
 GtkFileChooserWidget
 
 <!-- ##### SECTION Short_Description ##### -->
-implements GtkFileChooser as an embeddable widget
+File chooser widget that can be embedded in other widgets.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+    <para>
+      #GtkFileChooserWidget is a widget suitable for selecting files.
+      It is the main building block of a #GtkFileChooserDialog.  Most
+      applications will only need to use the latter; you can use
+      #GtkFileChooserWidget as part of a larger window if you have
+      special needs.
+    </para>
+
+    <para>
+      Note that #GtkFileChooserWidget does not have any methods of its
+      own.  Instead, you should use the functions that work on a
+      #GtkFileChooser.
+    </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+    <para>
+      #GtkFileChooser, #GtkFileChooserDialog
+    </para>
 
 <!-- ##### FUNCTION gtk_file_chooser_widget_new ##### -->
 <para>
@@ -23,3 +33,13 @@ implements GtkFileChooser as an embeddable widget
 @Returns: 
 
 
+
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
+End:
+-->
+
+