From 121f78713681512db99db97c90f66b20f73c4659 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Fri, 1 Jul 2011 18:04:25 -0500 Subject: [PATCH] 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 --- 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 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 File/Save As... 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 File/Save As... on it. If you don't have - * a file name already — 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 File/Save + * As... 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 File/Save As... on it to save a copy or + * a modified version. If you don't have a file name already — 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) * { * /* the user just created a new document */ - * 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 section on setting up a file + * chooser dialog 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 File/Save As... 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 File/Save As... on it. If you don't have - * a file name already — 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 File/Save + * As... 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 File/Save As... on it to save a copy or a + * modified version. If you don't have a file name already — 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) * { * /* the user just created a new document */ - * 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 section on setting up a file + * chooser dialog 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 ea19777c7b..08dfc62d3e 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 @@ * * * + *
+ * Setting up a file chooser dialog + * There are various cases in which you may need to use a #GtkFileChooserDialog: + * + * + * + * To select a file for opening, as for a + * File/Open command. Use + * #GTK_FILE_CHOOSER_ACTION_OPEN. + * + * + * + * + * + * To save a file for the first time, as for a + * File/Save command. Use + * #GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as + * "Untitled" with gtk_file_chooser_set_current_name(). + * + * + * + * + * + * To save a file under a different name, as for a + * File/Save As command. Use + * #GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing filename + * with gtk_file_chooser_set_filename(). + * + * + * + * + * + * To choose a folder instead of a file. Use + * #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. + * + * + * + * + * + * 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 File/Save + * As command and you already + * have a file saved somewhere. + * + * + *
*
* Response Codes * #GtkFileChooserDialog inherits from #GtkDialog, so buttons that