AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Update the docs with the policies for Save dialogs

Browse Source 
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>
This commit is contained in:
Federico Mena Quintero 2011-07-01 18:04:25 -05:00
parent 9eb324dbaf
commit 121f787136
2 changed files with 102 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
gtk/gtkfilechooser.c
View File

@ -1070,31 +1070,26 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
* @chooser: a #GtkFileChooser * @chooser: a #GtkFileChooser
* @filename: (type filename): the filename to set as current * @filename: (type filename): the filename to set as current
* *
* Sets @filename as the current filename for the file chooser, by changing * Sets @filename as the current filename for the file chooser, by changing to
* to the file's parent folder and actually selecting the file in list. If * the file's parent folder and actually selecting the file in list; all other
* the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name * files will be unselected. If the @chooser is in
* will also appear in the dialog's file name entry. * %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().
* *
* Note that the file must exist, or nothing will be done except * Note that the file must exist, or nothing will be done except
* for the directory change. * for the directory change.
* *
* If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog, * You should use this function only when implementing a <guimenuitem>File/Save
* you should use this function if you already have a file name to which the * As...</guimenuitem> dialog for which you already have a file name to which
* user may save; for example, when the user opens an existing file and then * the user may save. For example, when the user opens an existing file and
* does <guimenuitem>File/Save As...</guimenuitem> on it. If you don't have * then does <guimenuitem>File/Save As...</guimenuitem> on it to save a copy or
* a file name already &mdash; for example, if the user just created a new * a modified version. If you don't have a file name already &mdash; for
* file and is saving it for the first time, do not call this function. * example, if the user just created a new file and is saving it for the first
* Instead, use something similar to this: * time, do not call this function. Instead, use something similar to this:
* |[ * |[
* if (document_is_new) * if (document_is_new)
* { * {
* /&ast; the user just created a new document &ast;/ * /&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"); * gtk_file_chooser_set_current_name (chooser, "Untitled document");
* } * }
* else * else
@ -1103,9 +1098,12 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
* gtk_file_chooser_set_filename (chooser, existing_filename); * 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 * Return value: Not useful.
* selected successfully, %FALSE otherwise.
* *
* Since: 2.4 * Since: 2.4
**/ **/
@ -1128,8 +1126,9 @@ gtk_file_chooser_set_filename (GtkFileChooser *chooser,
* folder of @chooser, then the current folder of @chooser will * folder of @chooser, then the current folder of @chooser will
* be changed to the folder containing @filename. * be changed to the folder containing @filename.
* *
* Return value: %TRUE if both the folder could be changed and the file was * Return value: Not useful.
* selected successfully, %FALSE otherwise. *
* See also: gtk_file_chooser_set_filename()
* *
* Since: 2.4 * 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, * The user will be shown the full contents of the current folder,
* plus user interface elements for navigating to other folders. * plus user interface elements for navigating to other folders.
* *
* Return value: %TRUE if the folder could be changed successfully, %FALSE * In general, you should not use this function. See the <link
* otherwise. * 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 * 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 * 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 * by the user. Note that the name passed in here is a UTF-8
* string rather than a filename. This function is meant for * 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 * If you want to preselect a particular existing file, you should use
* gtk_file_chooser_set_filename() or gtk_file_chooser_set_uri() instead. * 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 * 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. * 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 * Note that the URI must exist, or nothing will be done except for the
* directory change. * 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 * You should use this function only when implementing a <guimenuitem>File/Save
* user may save; for example, when the user opens an existing file and then * As...</guimenuitem> dialog for which you already have a file name to which
* does <guimenuitem>File/Save As...</guimenuitem> on it. If you don't have * the user may save. For example, whenthe user opens an existing file and then
* a file name already &mdash; for example, if the user just created a new * does <guimenuitem>File/Save As...</guimenuitem> on it to save a copy or a
* file and is saving it for the first time, do not call this function. * modified version. If you don't have a file name already &mdash; for example,
* Instead, use something similar to this: * 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) * if (document_is_new)
* { * {
* /&ast; the user just created a new document &ast;/ * /&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"); * gtk_file_chooser_set_current_name (chooser, "Untitled document");
* } * }
* else * 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 * 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 * file in the current folder of @chooser, then the current folder of
* @chooser will be changed to the folder containing @filename. * @chooser will be changed to the folder containing @filename.
* *
* Return value: %TRUE if both the folder could be changed and the URI was * Return value: Not useful.
* selected successfully, %FALSE otherwise.
* *
* Since: 2.4 * 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, * The user will be shown the full contents of the current folder,
* plus user interface elements for navigating to other folders. * 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 * Return value: %TRUE if the folder could be changed successfully, %FALSE
* otherwise. * 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 * Selects the file referred to by @file. An internal function. See
* _gtk_file_chooser_select_uri(). * _gtk_file_chooser_select_uri().
* *
* Return value: %TRUE if both the folder could be changed and the path was * Return value: Not useful.
* selected successfully, %FALSE otherwise.
* *
* Since: 2.14 * 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 * Return value: Not useful.
* selected successfully, %FALSE otherwise.
* *
* Since: 2.14 * Since: 2.14
**/ **/

58
gtk/gtkfilechooserdialog.c
View File

@ -93,10 +93,7 @@
* gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE); * gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
* *
* if (user_edited_a_new_document) * if (user_edited_a_new_document)
* { * gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled 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");
* }
* else * else
* gtk_file_chooser_set_filename (GTK_FILE_CHOOSER (dialog), filename_for_existing_document); * gtk_file_chooser_set_filename (GTK_FILE_CHOOSER (dialog), filename_for_existing_document);
* *
@ -113,6 +110,59 @@
* </programlisting></informalexample> * </programlisting></informalexample>
* </para> * </para>
* </example> * </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"> * <section id="gtkfilechooserdialog-response-codes">
* <title>Response Codes</title> * <title>Response Codes</title>
* #GtkFileChooserDialog inherits from #GtkDialog, so buttons that * #GtkFileChooserDialog inherits from #GtkDialog, so buttons that