forked from AuroraMiddleware/gtk
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>
This commit is contained in:
Federico Mena Quintero
parent
9eb324dbaf
commit
121f787136
@ -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 — 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 — 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 <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 — 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 — 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 <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
|
||||
**/
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user