Add a "save" example to the typical usage.

2005-07-15  Federico Mena Quintero  <federico@ximian.com>

	* gtk/tmpl/gtkfilechooserdialog.sgml: Add a "save" example to the
	typical usage.

	* gtk/gtk-sections.txt: Add GtkFileChooserConfirmation,
	gtk_file_chooser_set_do_overwrite_confirmation,
	gtk_file_chooser_get_do_overwrite_confirmation.

	* gtk/tmpl/gtkfilechooser.sgml: Document the confirmation signal
	and enumeration; provide an example.

docs/reference/ChangeLog

@@ -1,3 +1,15 @@
+2005-07-15  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/tmpl/gtkfilechooserdialog.sgml: Add a "save" example to the
+	typical usage.
+
+	* gtk/gtk-sections.txt: Add GtkFileChooserConfirmation,
+	gtk_file_chooser_set_do_overwrite_confirmation,
+	gtk_file_chooser_get_do_overwrite_confirmation.
+
+	* gtk/tmpl/gtkfilechooser.sgml: Document the confirmation signal
+	and enumeration; provide an example.
+
 2005-07-14  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/gtk-sections.txt: Add new api.

docs/reference/gdk/tmpl/x_interaction.sgml

@@ -439,6 +439,14 @@ Since: 2.2
 @timestamp: 
 
 
+<!-- ##### FUNCTION gdk_x11_window_move_to_current_desktop ##### -->
+<para>
+
+</para>
+
+@window: 
+
+
 <!-- ##### FUNCTION gdk_x11_display_get_user_time ##### -->
 <para>
 

docs/reference/gtk/gtk-sections.txt

@@ -1195,6 +1195,7 @@ GtkExpanderPrivate
 <TITLE>GtkFileChooser</TITLE>
 GtkFileChooser
 GtkFileChooserAction
+GtkFileChooserConfirmation
 GTK_FILE_CHOOSER_ERROR
 GtkFileChooserError
 gtk_file_chooser_error_quark
@@ -1206,6 +1207,8 @@ gtk_file_chooser_set_select_multiple
 gtk_file_chooser_get_select_multiple
 gtk_file_chooser_set_show_hidden
 gtk_file_chooser_get_show_hidden
+gtk_file_chooser_set_do_overwrite_confirmation
+gtk_file_chooser_get_do_overwrite_confirmation
 gtk_file_chooser_set_current_name
 gtk_file_chooser_get_filename
 gtk_file_chooser_set_filename

docs/reference/gtk/tmpl/gtkfilechooser.sgml

@@ -410,6 +410,79 @@ class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"
 </para>
 
 
+<!-- ##### SIGNAL GtkFileChooser::confirm-overwrite ##### -->
+    <para>
+      This signal gets emitted whenever it is appropriate to present a
+      confirmation dialog when the user has selected a file name that
+      already exists.  The signal only gets emitted when the file
+      chooser is in #GTK_FILE_CHOOSER_ACTION_SAVE mode.
+    </para>
+
+    <para>
+      Most applications just need to turn on the <link
+      linkend="GtkFileChooser--do-overwrite-confirmation">do-overwrite-confirmation</link>
+      property (or call the
+      gtk_file_chooser_set_do_overwrite_confirmation() function), and
+      they will automatically get a stock confirmation dialog.
+      Applications which need to customize this behavior should do
+      that, and also connect to the <symbol>confirm-overwrite</symbol>
+      signal.
+    </para>
+
+    <para>
+      A signal handler for this signal must return a
+      #GtkFileChooserConfirmation value, which indicates the action to
+      take.  If the handler determines that the user wants to select a
+      different filename, it should return
+      #GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN.  If it determines
+      that the user is satisfied with his choice of file name, it
+      should return #GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME.
+      On the other hand, if it determines that the stock confirmation
+      dialog should be used, it should return
+      #GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM.  The following example
+      illustrates this.
+    </para>
+
+    <example id="gtkfilechooser-confirmation">
+      <title>Custom confirmation</title>
+
+      <programlisting>
+static GtkFileChooserConfirmation
+confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)
+{
+  char *uri;
+
+  uri = gtk_file_chooser_get_uri (chooser);
+
+  if (is_uri_read_only (uri))
+    {
+      if (user_wants_to_replace_read_only_file (uri))
+        return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME;
+      else
+        return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN;
+    } else
+      return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; /* fall back to the default dialog */
+}
+
+...
+
+chooser = gtk_file_chooser_dialog_new (...);
+
+gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
+g_signal_connect (chooser, "confirm-overwrite",
+                  G_CALLBACK (confirm_overwrite_callback), NULL);
+
+if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT)
+        save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser));
+
+gtk_widget_destroy (chooser);
+      </programlisting>
+    </example>
+
+@filechooser: the object which received the signal.
+@Returns: #GtkFileChooserConfirmation value that indicates which
+    action to take after emitting the signal.
+
 <!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
 <para>
 
@@ -443,6 +516,11 @@ class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"
 
 </para>
 
+<!-- ##### ARG GtkFileChooser:do-overwrite-confirmation ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkFileChooser:extra-widget ##### -->
 <para>
 
@@ -506,6 +584,23 @@ class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"
     new folder.  The file chooser will let the user name an existing or
     new folder.
 
+<!-- ##### ENUM GtkFileChooserConfirmation ##### -->
+    <para>
+      Used as a return value of handlers for the <link
+      linkend="GtkFileChooser-confirm-overwrite">confirm-overwrite</link>
+      signal of a <classname>GtkFileChooser</classname>.  This value
+      determines whether the file chooser will present the stock
+      confirmation dialog, accept the user's choice of a filename, or
+      let the user choose another filename.
+    </para>
+
+@GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM: The file chooser will present
+    its stock dialog to confirm about overwriting an existing file.
+@GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME: The file chooser will
+    terminate and accept the user's choice of a file name.
+@GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN: The file chooser will
+    continue running, so as to let the user select another file name.
+
 <!-- ##### MACRO GTK_FILE_CHOOSER_ERROR ##### -->
     <para>
       Used to get the #GError quark for #GtkFileChooser errors.
@@ -604,6 +699,24 @@ class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"
 @Returns: 
 
 
+<!-- ##### FUNCTION gtk_file_chooser_set_do_overwrite_confirmation ##### -->
+<para>
+
+</para>
+
+@chooser: 
+@do_overwrite_confirmation: 
+
+
+<!-- ##### FUNCTION gtk_file_chooser_get_do_overwrite_confirmation ##### -->
+<para>
+
+</para>
+
+@chooser: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gtk_file_chooser_set_current_name ##### -->
 <para>
 

docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml

@@ -24,8 +24,8 @@ A file chooser dialog, suitable for "File/Open" or "File/Save" commands
       <title>Typical usage</title>
 
       <para>
-	In the simplest of cases, you can use #GtkFileChooserDialog
-	as in the following code:
+	In the simplest of cases, you can the following code to use
+	#GtkFileChooserDialog to select a file for opening:
       </para>
 
       <programlisting>
@@ -47,6 +47,33 @@ if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
     g_free (filename);
   }
 
+gtk_widget_destroy (dialog);
+      </programlisting>
+
+      <para>
+        To use a dialog for saving, you can use this:
+      </para>
+
+      <programlisting>
+GtkWidget *dialog;
+
+dialog = gtk_file_chooser_dialog_new ("Save File",
+				      parent_window,
+				      GTK_FILE_CHOOSER_ACTION_SAVE,
+				      GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
+				      GTK_STOCK_SAVE, GTK_RESPONSE_ACCEPT,
+				      NULL);
+gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
+
+if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
+  {
+    char *filename;
+
+    filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
+    save_to_file (filename);
+    g_free (filename);
+  }
+
 gtk_widget_destroy (dialog);
       </programlisting>
     </example>

docs/reference/gtk/tmpl/gtktreemodel.sgml

@@ -514,6 +514,15 @@ compatibility reasons.
 @Returns: 
 
 
+<!-- ##### FUNCTION gtk_tree_row_reference_get_model ##### -->
+<para>
+
+</para>
+
+@reference: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gtk_tree_row_reference_get_path ##### -->
 <para>
 

docs/reference/gtk/tmpl/gtktreeview.sgml

@@ -794,6 +794,17 @@ has some similarity to strcmp() returning 0 for equal strings.
 @visible_rect: 
 
 
+<!-- ##### FUNCTION gtk_tree_view_get_visible_range ##### -->
+<para>
+
+</para>
+
+@tree_view: 
+@start_path: 
+@end_path: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gtk_tree_view_get_bin_window ##### -->
 <para>
 

docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml

@@ -607,3 +607,11 @@ calling gtk_tree_view_column_set_cell_data_func()
 @cell: 
 
 
+<!-- ##### FUNCTION gtk_tree_view_column_queue_resize ##### -->
+<para>
+
+</para>
+
+@tree_column: 
+
+