X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=gtk%2Fgtkfilechooser.c;h=8e2d64da4c87e8e2d37b5a97f921d028a3c0cf1d;hb=6767541ead7cc150d1dd066d3b84d85559500c28;hp=da9d7c5e942b6474db2d48db321faf11b5474375;hpb=a1c297a310751892d7540c0b281bb93ec6750549;p=~andy%2Fgtk diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c index da9d7c5e9..8e2d64da4 100644 --- a/gtk/gtkfilechooser.c +++ b/gtk/gtkfilechooser.c @@ -13,9 +13,7 @@ * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * License along with this library. If not, see . */ #include "config.h" @@ -81,7 +79,7 @@ * However, filenames are always returned in * the character set specified by the * G_FILENAME_ENCODING environment variable. - * Please see the Glib documentation for more details about this + * Please see the GLib documentation for more details about this * variable. * * This means that while you can pass the result of @@ -178,7 +176,7 @@ * * * If you want to set more than one extra widget in the file - * chooser, you can a container such as a #GtkVBox or a #GtkTable + * chooser, you can a container such as a #GtkBox or a #GtkGrid * and include your widgets in it. Then, set the container as * the whole extra widget. * @@ -222,18 +220,25 @@ * * up-folder * - * AltUp + * AltUp; + * AltShiftUp * * Both the individual Up key and the numeric * keypad's Up key are supported. - * - * ; + * ; * Backspace * * * * down-folder - * AltDown + * + * AltDown; + * AltShiftDown + * + * Both the individual Down key and the numeric + * keypad's Down key are supported. + * + * * * * home-folder @@ -254,22 +259,20 @@ * You can change these defaults to something else. For * example, to add a Shift modifier to a few * of the default bindings, you can include the following - * fragment in your .gtkrc-3.0 file: + * fragment in your .config/gtk-3.0/gtk.css file: * * - * binding "my-own-gtkfilechooser-bindings" { - * bind "<Alt><Shift>Up" { - * "up-folder" () - * } - * bind "<Alt><Shift>Down" { - * "down-folder" () - * } - * bind "<Alt><Shift>Home" { - * "home-folder" () - * } + * @binding-set MyOwnFilechooserBindings + * { + * bind "<Alt><Shift>Up" { "up-folder" () } + * bind "<Alt><Shift>Down" { "down-folder" () } + * bind "<Alt><Shift>Home" { "home-folder" () } * } * - * class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings" + * GtkFileChooserDefault + * { + * gtk-key-bindings: MyOwnFilechooserBindings + * } * * * @@ -329,15 +332,17 @@ * frequently. You could then create an * Alt M * shortcut by including the following in your - * .gtkrc-3.0: + * .config/gtk-3.0/gtk.css: * - * binding "misc-shortcut" { - * bind "<Alt>M" { - * "location-popup" ("/home/username/misc") - * } + * @binding-set MiscShortcut + * { + * bind "<Alt>M" { "location-popup" ("/home/username/misc") } * } * - * class "GtkFileChooserDefault" binding "misc-shortcut" + * GtkFileChooserDefault + * { + * gtk-key-bindings: MiscShortcut + * } * * * @@ -549,7 +554,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface) GType iface_type = G_TYPE_FROM_INTERFACE (iface); /** - * GtkFileChooser::current-folder-changed + * GtkFileChooser::current-folder-changed: * @chooser: the object which received the signal. * * This signal is emitted when the current folder in a #GtkFileChooser @@ -575,7 +580,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface) G_TYPE_NONE, 0); /** - * GtkFileChooser::selection-changed + * GtkFileChooser::selection-changed: * @chooser: the object which received the signal. * * This signal is emitted when there is a change in the set of selected files @@ -602,7 +607,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface) G_TYPE_NONE, 0); /** - * GtkFileChooser::update-preview + * GtkFileChooser::update-preview: * @chooser: the object which received the signal. * * This signal is emitted when the preview in a file chooser should be @@ -636,7 +641,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface) G_TYPE_NONE, 0); /** - * GtkFileChooser::file-activated + * GtkFileChooser::file-activated: * @chooser: the object which received the signal. * * This signal is emitted when the user "activates" a file in the file @@ -1027,8 +1032,9 @@ gtk_file_chooser_get_create_folders (GtkFileChooser *chooser) * @chooser: a #GtkFileChooser * * Gets the filename for the currently selected file in - * the file selector. If multiple files are selected, - * one of the filenames will be returned at random. + * the file selector. The filename is returned as an absolute path. If + * multiple files are selected, one of the filenames will be returned at + * random. * * If the file chooser is in folder mode, this function returns the selected * folder. @@ -1063,31 +1069,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 @@ -1096,9 +1097,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 **/ @@ -1121,8 +1125,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 **/ @@ -1233,8 +1238,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 **/ @@ -1305,7 +1313,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. @@ -1368,25 +1377,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 @@ -1396,8 +1400,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 **/ @@ -1420,8 +1428,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 **/ @@ -1538,6 +1545,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. * @@ -1654,8 +1665,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 **/ @@ -1698,9 +1708,10 @@ gtk_file_chooser_unselect_file (GtkFileChooser *chooser, * Lists all the selected files and subfolders in the current folder of @chooser * as #GFile. An internal function, see gtk_file_chooser_get_uris(). * - * Return value: (element-type utf8) (transfer full): a #GSList containing a #GFile for each selected - * file and subfolder in the current folder. Free the returned list - * with g_slist_free(), and the files with g_object_unref(). + * Return value: (element-type GFile) (transfer full): a #GSList + * containing a #GFile for each selected file and subfolder in the + * current folder. Free the returned list with g_slist_free(), and + * the files with g_object_unref(). * * Since: 2.14 **/ @@ -1752,8 +1763,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 **/ @@ -1988,7 +1998,7 @@ gtk_file_chooser_get_use_preview_label (GtkFileChooser *chooser) * Gets the #GFile that should be previewed in a custom preview * Internal function, see gtk_file_chooser_get_preview_uri(). * - * Return value: (transfer none): the #GFile for the file to preview, + * Return value: (transfer full): the #GFile for the file to preview, * or %NULL if no file is selected. Free with g_object_unref(). * * Since: 2.14 @@ -2208,10 +2218,10 @@ gtk_file_chooser_remove_filter (GtkFileChooser *chooser, * Lists the current set of user-selectable filters; see * gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter(). * - * Return value: (element-type utf8) (transfer container): a #GSList containing the current set of - * user selectable filters. The contents of the list are - * owned by GTK+, but you must free the list itself with - * g_slist_free() when you are done with it. + * Return value: (element-type GtkFileFilter) (transfer container): a + * #GSList containing the current set of user selectable filters. The + * contents of the list are owned by GTK+, but you must free the list + * itself with g_slist_free() when you are done with it. * * Since: 2.4 **/