GitLab repository storage has been migrated to hashed layout. Please contact Infrastructure team if you notice any issues with repositories or hooks.

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's avatarFederico Mena Quintero <federico@gnome.org>
parent a06f1b38
......@@ -66,14 +66,10 @@ dialog = gtk_file_chooser_dialog_new ("Save File",
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);
if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
{
char *filename;
......@@ -87,6 +83,66 @@ gtk_widget_destroy (dialog);
</programlisting>
</example>
<section id="gtkfilechooserdialog-setting-up">
<title>Setting up a file chooser dialog</title>
<para>
There are various cases in which you may need to use a
#GtkFileChooserDialog:
</para>
<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>
......
......@@ -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
**/
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment