[gtk+/bgo593793-filechooser-recent-folders-master: 20/20] Update the docs with the policies for Save dialogs

From: Federico Mena Quintero <federico src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk+/bgo593793-filechooser-recent-folders-master: 20/20] Update the docs with the policies for Save dialogs
Date: Fri, 1 Jul 2011 23:53:29 +0000 (UTC)
commit 121f78713681512db99db97c90f66b20f73c4659
Author: Federico Mena Quintero <federico gnome org>
Date:   Fri Jul 1 18:04:25 2011 -0500

    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>

 gtk/gtkfilechooser.c       |   93 ++++++++++++++++++++++---------------------
 gtk/gtkfilechooserdialog.c |   58 +++++++++++++++++++++++++--
 2 files changed, 102 insertions(+), 49 deletions(-)
---
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index f7676ff..edad536 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
  **/
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index ea19777..08dfc62 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -93,10 +93,7 @@
  * gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
  *
  * if (user_edited_a_new_document)
- *   {
- *     gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (dialog), default_folder_for_saving);
- *     gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled document");
- *   }
+ *   gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled document");
  * else
  *   gtk_file_chooser_set_filename (GTK_FILE_CHOOSER (dialog), filename_for_existing_document);
  *
@@ -113,6 +110,59 @@
  * </programlisting></informalexample>
  * </para>
  * </example>
+ * <section id="gtkfilechooserdialog-setting-up">
+ * <title>Setting up a file chooser dialog</title>
+ * There are various cases in which you may need to use a #GtkFileChooserDialog:
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>
+ *       To select a file for opening, as for a
+ *       <guimenuitem>File/Open</guimenuitem> command.  Use
+ *       #GTK_FILE_CHOOSER_ACTION_OPEN.
+ *     </para>
+ *   </listitem>
+ *
+ *   <listitem>
+ *     <para>
+ *       To save a file for the first time, as for a
+ *       <guimenuitem>File/Save</guimenuitem> command.  Use
+ *       #GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as
+ *       "Untitled" with gtk_file_chooser_set_current_name().
+ *     </para>
+ *   </listitem>
+ *
+ *   <listitem>
+ *     <para>
+ *       To save a file under a different name, as for a
+ *       <guimenuitem>File/Save As</guimenuitem> command.  Use
+ *       #GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing filename
+ *       with gtk_file_chooser_set_filename().
+ *     </para>
+ *   </listitem>
+ *
+ *   <listitem>
+ *     <para>
+ *        To choose a folder instead of a file.  Use
+ *        #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
+ *     </para>
+ *   </listitem>
+ * </itemizedlist>
+ * <note>
+ * <para>
+ * Old versions of the file chooser's documentation suggested
+ * using gtk_file_chooser_set_current_folder() in various
+ * situations, with the intention of letting the application
+ * suggest a reasonable default folder.  This is no longer
+ * considered to be a good policy, as now the file chooser is
+ * able to make good suggestions on its own.  In general, you
+ * should only cause the file chooser to show a specific folder
+ * when it is appropriate to use gtk_file_chooser_set_filename()
+ * - i.e. when you are doing a <guimenuitem>File/Save
+ * As</guimenuitem> command <emphasis>and</emphasis> you already
+ * have a file saved somewhere.
+ * </para>
+ * </note>
+ * </section>
  * <section id="gtkfilechooserdialog-response-codes">
  * <title>Response Codes</title>
  * #GtkFileChooserDialog inherits from #GtkDialog, so buttons that
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]