Update the docs with the policies for Save dialogs

Basically, don't ever set the current folder, and only use
gtk_file_chooser_set_filename() for 'File/Save As'.  This is so
that the file chooser will be able to present its recently-used
lists as appropriate, giving the user good suggestions by default.

Signed-off-by: Federico Mena Quintero <federico@gnome.org>

1 files changed, 48 insertions, 45 deletions

diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index f7676ff5af..edad536877 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -1070,31 +1070,26 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
  * @chooser: a #GtkFileChooser
  * @filename: (type filename): the filename to set as current
  * 
- * Sets @filename as the current filename for the file chooser, by changing
- * to the file's parent folder and actually selecting the file in list.  If
- * the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name
- * will also appear in the dialog's file name entry.
- *
- * If the file name isn't in the current folder of @chooser, then the current
- * folder of @chooser will be changed to the folder containing @filename. This
- * is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by
- * gtk_file_chooser_select_filename().
+ * Sets @filename as the current filename for the file chooser, by changing to
+ * the file's parent folder and actually selecting the file in list; all other
+ * files will be unselected.  If the @chooser is in
+ * %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name will also appear in
+ * the dialog's file name entry.
  *
  * Note that the file must exist, or nothing will be done except
  * for the directory change.
  *
- * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
- * you should use this function if you already have a file name to which the 
- * user may save; for example, when the user opens an existing file and then 
- * does <guimenuitem>File/Save As...</guimenuitem> on it.  If you don't have 
- * a file name already &mdash; for example, if the user just created a new 
- * file and is saving it for the first time, do not call this function.  
- * Instead, use something similar to this:
+ * You should use this function only when implementing a <guimenuitem>File/Save
+ * As...</guimenuitem> dialog for which you already have a file name to which
+ * the user may save.  For example, when the user opens an existing file and
+ * then does <guimenuitem>File/Save As...</guimenuitem> on it to save a copy or
+ * a modified version.  If you don't have a file name already &mdash; for
+ * example, if the user just created a new file and is saving it for the first
+ * time, do not call this function.  Instead, use something similar to this:
  * |[
  * if (document_is_new)
  *   {
  *     /&ast; the user just created a new document &ast;/
- *     gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
  *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
  *   }
  * else
@@ -1103,9 +1098,12 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
  *     gtk_file_chooser_set_filename (chooser, existing_filename);
  *   }
  * ]|
+ *
+ * In the first case, the file chooser will present the user with useful suggestions
+ * as to where to save his new file.  In the second case, the file's existing location
+ * is already known, so the file chooser will use it.
  * 
- * Return value: %TRUE if both the folder could be changed and the file was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
  *
  * Since: 2.4
  **/
@@ -1128,8 +1126,9 @@ gtk_file_chooser_set_filename (GtkFileChooser *chooser,
  * folder of @chooser, then the current folder of @chooser will
  * be changed to the folder containing @filename.
  *
- * Return value: %TRUE if both the folder could be changed and the file was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
+ *
+ * See also: gtk_file_chooser_set_filename()
  *
  * Since: 2.4
  **/
@@ -1240,8 +1239,11 @@ gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
  * The user will be shown the full contents of the current folder,
  * plus user interface elements for navigating to other folders.
  *
- * Return value: %TRUE if the folder could be changed successfully, %FALSE
- * otherwise.
+ * In general, you should not use this function.  See the <link
+ * linkend="gtkfilechooserdialog-setting-up">section on setting up a file
+ * chooser dialog</link> for the rationale behind this.
+ *
+ * Return value: Not useful.
  *
  * Since: 2.4
  **/
@@ -1312,7 +1314,8 @@ gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
  * Sets the current name in the file selector, as if entered
  * by the user. Note that the name passed in here is a UTF-8
  * string rather than a filename. This function is meant for
- * such uses as a suggested name in a "Save As..." dialog.
+ * such uses as a suggested name in a "Save As..." dialog.  You can
+ * pass "Untitled.doc" or a similarly suitable suggestion for the @name.
  *
  * If you want to preselect a particular existing file, you should use
  * gtk_file_chooser_set_filename() or gtk_file_chooser_set_uri() instead.
@@ -1375,25 +1378,20 @@ gtk_file_chooser_get_uri (GtkFileChooser *chooser)
  * list.  If the @chooser is %GTK_FILE_CHOOSER_ACTION_SAVE mode, the URI's base
  * name will also appear in the dialog's file name entry.
  *
- * If the URI isn't in the current folder of @chooser, then the current folder
- * of @chooser will be changed to the folder containing @uri. This is equivalent
- * to a sequence of gtk_file_chooser_unselect_all() followed by
- * gtk_file_chooser_select_uri().
- *
  * Note that the URI must exist, or nothing will be done except for the 
  * directory change.
- * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog,
- * you should use this function if you already have a file name to which the 
- * user may save; for example, when the user opens an existing file and then 
- * does <guimenuitem>File/Save As...</guimenuitem> on it.  If you don't have 
- * a file name already &mdash; for example, if the user just created a new 
- * file and is saving it for the first time, do not call this function.  
- * Instead, use something similar to this:
+ *
+ * You should use this function only when implementing a <guimenuitem>File/Save
+ * As...</guimenuitem> dialog for which you already have a file name to which
+ * the user may save.  For example, whenthe user opens an existing file and then
+ * does <guimenuitem>File/Save As...</guimenuitem> on it to save a copy or a
+ * modified version.  If you don't have a file name already &mdash; for example,
+ * if the user just created a new file and is saving it for the first time, do
+ * not call this function.  Instead, use something similar to this:
  * |[
  * if (document_is_new)
  *   {
  *     /&ast; the user just created a new document &ast;/
- *     gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
  *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
  *   }
  * else
@@ -1403,8 +1401,12 @@ gtk_file_chooser_get_uri (GtkFileChooser *chooser)
  *   }
  * ]|
  *
- * Return value: %TRUE if both the folder could be changed and the URI was
- * selected successfully, %FALSE otherwise.
+ *
+ * In the first case, the file chooser will present the user with useful suggestions
+ * as to where to save his new file.  In the second case, the file's existing location
+ * is already known, so the file chooser will use it.
+ * 
+ * Return value: Not useful.
  *
  * Since: 2.4
  **/
@@ -1427,8 +1429,7 @@ gtk_file_chooser_set_uri (GtkFileChooser *chooser,
  * file in the current folder of @chooser, then the current folder of
  * @chooser will be changed to the folder containing @filename.
  *
- * Return value: %TRUE if both the folder could be changed and the URI was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
  *
  * Since: 2.4
  **/
@@ -1545,6 +1546,10 @@ gtk_file_chooser_get_uris (GtkFileChooser *chooser)
  * The user will be shown the full contents of the current folder,
  * plus user interface elements for navigating to other folders.
  *
+ * In general, you should not use this function.  See the <link
+ * linkend="gtkfilechooserdialog-setting-up">section on setting up a file
+ * chooser dialog</link> for the rationale behind this.
+ *
  * Return value: %TRUE if the folder could be changed successfully, %FALSE
  * otherwise.
  *
@@ -1661,8 +1666,7 @@ gtk_file_chooser_get_current_folder_file (GtkFileChooser *chooser)
  * Selects the file referred to by @file. An internal function. See
  * _gtk_file_chooser_select_uri().
  *
- * Return value: %TRUE if both the folder could be changed and the path was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
  *
  * Since: 2.14
  **/
@@ -1760,8 +1764,7 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser)
  *   }
  * ]|
  *
- * Return value: %TRUE if both the folder could be changed and the file was
- * selected successfully, %FALSE otherwise.
+ * Return value: Not useful.
  *
  * Since: 2.14
  **/