Added documentation to all the signals.

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

	* gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added
	documentation to all the signals.

8 files changed, 268 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index d0a63f180a..1401e17fb6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2004-04-12  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added
+	documentation to all the signals.
+
 2004-04-12  Matthias Clasen  <mclasen@dhcp64-228.boston.redhat.com>
 
 	* gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index d0a63f180a..1401e17fb6 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,8 @@
+2004-04-12  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added
+	documentation to all the signals.
+
 2004-04-12  Matthias Clasen  <mclasen@dhcp64-228.boston.redhat.com>
 
 	* gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref
diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index d0a63f180a..1401e17fb6 100644
--- a/ChangeLog.pre-2-4
+++ b/ChangeLog.pre-2-4
@@ -1,3 +1,8 @@
+2004-04-12  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added
+	documentation to all the signals.
+
 2004-04-12  Matthias Clasen  <mclasen@dhcp64-228.boston.redhat.com>
 
 	* gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref
diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index d0a63f180a..1401e17fb6 100644
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,3 +1,8 @@
+2004-04-12  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added
+	documentation to all the signals.
+
 2004-04-12  Matthias Clasen  <mclasen@dhcp64-228.boston.redhat.com>
 
 	* gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref
diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index d0a63f180a..1401e17fb6 100644
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,3 +1,8 @@
+2004-04-12  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added
+	documentation to all the signals.
+
 2004-04-12  Matthias Clasen  <mclasen@dhcp64-228.boston.redhat.com>
 
 	* gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 99e0ff8575..04357bdc71 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2004-04-12  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/tmpl/gtkfilechooser.sgml: Added documentation about
+	GtkFileChooserDefault's key binding signals.
+
 2004-03-26  Federico Mena Quintero  <federico@ximian.com>
 
 	* gtk/tmpl/gtkfilechooserdialog.sgml: Added a section about using
diff --git a/docs/reference/gtk/tmpl/gtkfilechooser.sgml b/docs/reference/gtk/tmpl/gtkfilechooser.sgml
index 6e7d419162..1d1decca47 100644
--- a/docs/reference/gtk/tmpl/gtkfilechooser.sgml
+++ b/docs/reference/gtk/tmpl/gtkfilechooser.sgml
@@ -116,6 +116,162 @@ update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
       </note>
     </refsect2>
 
+    <refsect2 id="gtkfilechooser-key-bindings">
+      <title>Key Bindings</title>
+
+      <para>
+	Internally, GTK+ implements a file chooser's graphical user
+	interface with the private
+	<classname>GtkFileChooserDefaultClass</classname>.  This
+	widget has several <link linkend="gtk-Bindings"">key
+	bindings</link> and their associated signals.  This section
+	describes the available key binding signals.
+      </para>
+
+      <refsect3 id="GtkFileChooserDefault-location-popup">
+	<title>The &quot;GtkFileChooserDefault::location-popup&quot; signal</title>
+
+	<programlisting>
+          void user_function (GtkFileChooserDefault *chooser,
+                              <link linkend="gpointer">gpointer</link> user_data);
+	</programlisting>
+
+	<para>
+	  This is used to make the file chooser show a "Location"
+	  dialog which the user can use to manually type the name of
+	  the file he wishes to select.  By default this is bound to
+	  <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>.
+	</para>
+
+	<variablelist role="params">
+	  <varlistentry>
+	    <term><parameter>chooser</parameter>&nbsp;:</term>
+	    <listitem>
+	      <simpara>
+		the object which received the signal.
+	      </simpara>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>user_data</parameter>&nbsp;:</term>
+	    <listitem>
+	      <simpara>
+		user data set when the signal handler was connected.
+	      </simpara>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect3>
+
+      <refsect3 id="GtkFileChooserDefault-up-folder">
+	<title>The &quot;GtkFileChooserDefault::up-folder&quot; signal</title>
+
+	<programlisting>
+          void user_function (GtkFileChooserDefault *chooser,
+                              <link linkend="gpointer">gpointer</link> user_data);
+	</programlisting>
+
+	<para>
+	  This is used to make the file chooser go to the parent of
+	  the current folder in the file hierarchy.  By default this
+	  is bound to
+	  <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>.
+	</para>
+
+	<variablelist role="params">
+	  <varlistentry>
+	    <term><parameter>chooser</parameter>&nbsp;:</term>
+	    <listitem>
+	      <simpara>
+		the object which received the signal.
+	      </simpara>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>user_data</parameter>&nbsp;:</term>
+	    <listitem>
+	      <simpara>
+		user data set when the signal handler was connected.
+	      </simpara>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect3>
+
+      <refsect3 id="GtkFileChooserDefault-down-folder">
+	<title>The &quot;GtkFileChooserDefault::down-folder&quot; signal</title>
+
+	<programlisting>
+          void user_function (GtkFileChooserDefault *chooser,
+                              <link linkend="gpointer">gpointer</link> user_data);
+	</programlisting>
+
+	<para>
+	  This is used to make the file chooser go to a child of the
+	  current folder in the file hierarchy.  The subfolder that
+	  will be used is displayed in the path bar widget of the file
+	  chooser.  For example, if the path bar is showing
+	  "/foo/<emphasis>bar/</emphasis>baz", then this will cause
+	  the file chooser to switch to the "baz" subfolder.  By
+	  default this is bound to
+	  <keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>.
+	</para>
+
+	<variablelist role="params">
+	  <varlistentry>
+	    <term><parameter>chooser</parameter>&nbsp;:</term>
+	    <listitem>
+	      <simpara>
+		the object which received the signal.
+	      </simpara>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>user_data</parameter>&nbsp;:</term>
+	    <listitem>
+	      <simpara>
+		user data set when the signal handler was connected.
+	      </simpara>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect3>
+
+      <refsect3 id="GtkFileChooserDefault-home-folder">
+	<title>The &quot;GtkFileChooserDefault::home-folder&quot; signal</title>
+
+	<programlisting>
+          void user_function (GtkFileChooserDefault *chooser,
+                              <link linkend="gpointer">gpointer</link> user_data);
+	</programlisting>
+
+	<para>
+	  This is used to make the file chooser show the user's home
+	  folder in the file list.  By default this is bound to
+	  <keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo>.
+	</para>
+
+	<variablelist role="params">
+	  <varlistentry>
+	    <term><parameter>chooser</parameter>&nbsp;:</term>
+	    <listitem>
+	      <simpara>
+		the object which received the signal.
+	      </simpara>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>user_data</parameter>&nbsp;:</term>
+	    <listitem>
+	      <simpara>
+		user data set when the signal handler was connected.
+	      </simpara>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect3>
+    </refsect2>
+
 <!-- ##### SECTION See_Also ##### -->
     <para>
       #GtkFileChooserDialog, #GtkFileChooserWidget
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 4f4c4e27cf..12bc6b1c3b 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -59,6 +59,24 @@ gtk_file_chooser_class_init (gpointer g_iface)
 {
   GType iface_type = G_TYPE_FROM_INTERFACE (g_iface);
 
+  /**
+   * GtkFileChooser::current-folder-changed
+   * @chooser: the object which received the signal.
+   *
+   * This signal is emitted when the current folder in a #GtkFileChooser
+   * changes.  This can happen due to the user performing some action that
+   * changes folders, such as selecting a bookmark or visiting a folder on the
+   * file list.  It can also happen as a result of calling a function to
+   * explicitly change the current folder in a file chooser.
+   *
+   * Normally you do not need to connect to this signal, unless you need to keep
+   * track of which folder a file chooser is showing.
+   *
+   * See also:  gtk_file_chooser_set_current_folder(),
+   * gtk_file_chooser_get_current_folder(),
+   * gtk_file_chooser_set_current_folder_uri(),
+   * gtk_file_chooser_get_current_folder_uri().
+   */
   g_signal_new ("current-folder-changed",
 		iface_type,
 		G_SIGNAL_RUN_LAST,
@@ -66,6 +84,26 @@ gtk_file_chooser_class_init (gpointer g_iface)
 		NULL, NULL,
 		g_cclosure_marshal_VOID__VOID,
 		G_TYPE_NONE, 0);
+
+  /**
+   * GtkFileChooser::selection-changed
+   * @chooser: the object which received the signal.
+   *
+   * This signal is emitted when there is a change in the set of selected files
+   * in a #GtkFileChooser.  This can happen when the user modifies the selection
+   * with the mouse or the keyboard, or when explicitly calling functions to
+   * change the selection.
+   *
+   * Normally you do not need to connect to this signal, as it is easier to wait
+   * for the file chooser to finish running, and then to get the list of
+   * selected files using the functions mentioned below.
+   *
+   * See also: gtk_file_chooser_select_filename(),
+   * gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(),
+   * gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(),
+   * gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(),
+   * gtk_file_chooser_get_uris().
+   */
   g_signal_new ("selection-changed",
 		iface_type,
 		G_SIGNAL_RUN_LAST,
@@ -73,6 +111,33 @@ gtk_file_chooser_class_init (gpointer g_iface)
 		NULL, NULL,
 		g_cclosure_marshal_VOID__VOID,
 		G_TYPE_NONE, 0);
+
+  /**
+   * GtkFileChooser::update-preview
+   * @chooser: the object which received the signal.
+   *
+   * This signal is emitted when the preview in a file chooser should be
+   * regenerated.  For example, this can happen when the currently selected file
+   * changes.  You should use this signal if you want your file chooser to have
+   * a preview widget.
+   *
+   * Once you have installed a preview widget with
+   * gtk_file_chooser_set_preview_widget(), you should update it when this
+   * signal is emitted.  You can use the functions
+   * gtk_file_chooser_get_preview_filename() or
+   * gtk_file_chooser_get_preview_uri() to get the name of the file to preview.
+   * Your widget may not be able to preview all kinds of files; your callback
+   * must call gtk_file_chooser_set_preview_wiget_active() to inform the file
+   * chooser about whether the preview was generated successfully or not.
+   *
+   * Please see the example code in <xref linkend="gtkfilechooser-preview"/>.
+   *
+   * See also: gtk_file_chooser_set_preview_widget(),
+   * gtk_file_chooser_set_preview_widget_active(),
+   * gtk_file_chooser_set_use_preview_label(),
+   * gtk_file_chooser_get_preview_filename(),
+   * gtk_file_chooser_get_preview_uri().
+   */
   g_signal_new ("update-preview",
 		iface_type,
 		G_SIGNAL_RUN_LAST,
@@ -80,6 +145,23 @@ gtk_file_chooser_class_init (gpointer g_iface)
 		NULL, NULL,
 		g_cclosure_marshal_VOID__VOID,
 		G_TYPE_NONE, 0);
+
+  /**
+   * GtkFileChooser::file-activated
+   * @chooser: the object which received the signal.
+   *
+   * This signal is emitted when the user "activates" a file in the file
+   * chooser.  This can happen by double-clicking on a file in the file list, or
+   * by pressing <keycap>Enter</keycap>.
+   *
+   * Normally you do not need to connect to this signal.  It is used internally
+   * by #GtkFileChooserDialog to know when to activate the default button in the
+   * dialog.
+   *
+   * See also: gtk_file_chooser_get_filename(),
+   * gtk_file_chooser_get_filenames(), gtk_file_chooser_get_uri(),
+   * gtk_file_chooser_get_uris().
+   */
   g_signal_new ("file-activated",
 		iface_type,
 		G_SIGNAL_RUN_LAST,