diff --git a/docs/reference/gtk/tmpl/gtkfilechooser.sgml b/docs/reference/gtk/tmpl/gtkfilechooser.sgml deleted file mode 100644 index c88131e4e..000000000 --- a/docs/reference/gtk/tmpl/gtkfilechooser.sgml +++ /dev/null @@ -1,1341 +0,0 @@ - -GtkFileChooser - - -File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog - - - - #GtkFileChooser is an interface that can be implemented by file - selection widgets. In GTK+, the main objects that implement this - interface are #GtkFileChooserWidget, #GtkFileChooserDialog, and - #GtkFileChooserButton. You do not need to write an object that - implements the #GtkFileChooser interface unless you are trying to - adapt an existing file selector to expose a standard programming - interface. - - - - #GtkFileChooser allows for shortcuts to various places in the filesystem. - In the default implementation these are displayed in the left pane. It - may be a bit confusing at first taht these shortcuts come from various - sources and in various flavours, so lets explain the terminology here: - - - - Bookmarks - - are created by the user, by dragging folders from the - right pane to the left pane, or by using the "Add". Bookmarks - can be renamed and deleted by the user. - - - - Shortcuts - - can be provided by the application or by the underlying filesystem - abstraction (e.g. both the gnome-vfs and the Windows filesystems - provide "Desktop" shortcuts). Shortcuts cannot be modified by the - user. - - - - Volumes - - are provided by the underlying filesystem abstraction. They are - the "roots" of the filesystem. - - - - - - File Names and Encodings - - - When the user is finished selecting files in a - #GtkFileChooser, your program can get the selected names - either as filenames or as URIs. For URIs, the normal escaping - rules are applied if the URI contains non-ASCII characters. - 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 - variable. - - - - - This means that while you can pass the result of - gtk_file_chooser_get_filename() to - open(2) or - fopen(3), you may not be able to - directly set it as the text of a #GtkLabel widget unless you - convert it first to UTF-8, which all GTK+ widgets expect. - You should use g_filename_to_utf8() to convert filenames - into strings that can be passed to GTK+ widgets. - - - - - - Adding a Preview Widget - - - You can add a custom preview widget to a file chooser and then - get notification about when the preview needs to be updated. - To install a preview widget, use - gtk_file_chooser_set_preview_widget(). Then, connect to the - #GtkFileChooser::update-preview signal to get notified when - you need to update the contents of the preview. - - - - Your callback should use - gtk_file_chooser_get_preview_filename() to see what needs - previewing. Once you have generated the preview for the - corresponding file, you must call - gtk_file_chooser_set_preview_widget_active() with a boolean - flag that indicates whether your callback could successfully - generate a preview. - - - - Sample Usage - - -{ - GtkImage *preview; - - ... - - preview = gtk_image_new (); - - gtk_file_chooser_set_preview_widget (my_file_chooser, preview); - g_signal_connect (my_file_chooser, "update-preview", - G_CALLBACK (update_preview_cb), preview); -} - -static void -update_preview_cb (GtkFileChooser *file_chooser, gpointer data) -{ - GtkWidget *preview; - char *filename; - GdkPixbuf *pixbuf; - gboolean have_preview; - - preview = GTK_WIDGET (data); - filename = gtk_file_chooser_get_preview_filename (file_chooser); - - pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL); - have_preview = (pixbuf != NULL); - g_free (filename); - - gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf); - if (pixbuf) - g_object_unref (pixbuf); - - gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview); -} - - - - - - Adding Extra Widgets - - - You can add extra widgets to a file chooser to provide options - that are not present in the default design. For example, you - can add a toggle button to give the user the option to open a - file in read-only mode. You can use - gtk_file_chooser_set_extra_widget() to insert additional - widgets in a file chooser. - - - - Sample Usage - - -{ - GtkWidget *toggle; - - ... - - toggle = gtk_check_button_new_with_label ("Open file read-only"); - gtk_widget_show (toggle); - gtk_file_chooser_set_extra_widget (my_file_chooser, toggle); -} - - - - - - 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 - and include your widgets in it. Then, set the container as - the whole extra widget. - - - - - - Key Bindings - - - Internally, GTK+ implements a file chooser's graphical user - interface with the private - GtkFileChooserDefaultClass. This - widget has several key - bindings and their associated signals. This section - describes the available key binding signals. - - - - GtkFileChooser key binding example - - - The default keys that activate the key-binding signals in - GtkFileChooserDefaultClass are as - follows: - - - - - - - Signal name - Default key combinations - - - location-popup - - ControlL (empty path); - / (path of "/") - - Both the individual / key and the - numeric keypad's "divide" key are supported. - - ; - ~ (path of "~") - - - - up-folder - - AltUp - - Both the individual Up key and the numeric - keypad's Up key are supported. - - - ; - Backspace - - - - down-folder - AltDown - - - home-folder - AltHome - - - desktop-folder - AltD - - - quick-bookmark - Alt1 through Alt0 - - - - - - - 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-2.0 file: - - - -binding "my-own-gtkfilechooser-bindings" { - 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" - - - - - The "GtkFileChooserDefault::location-popup" signal - - - void user_function (GtkFileChooserDefault *chooser, - const char *path, - gpointer user_data); - - - - This is used to make the file chooser show a "Location" - dialog which the user can use to manually type the name of - the file he wishes to select. The - path argument is a string that gets - put in the text entry for the file name. By default this is bound to - ControlL - with a path string of "" (the empty - string). It is also bound to / with a - path string of "/" - (a slash): this lets you type / and - immediately type a path name. On Unix systems, this is bound to - ~ (tilde) with a path string - of "~" itself for access to home directories. - - - - - chooser : - - - the object which received the signal. - - - - - path : - - - default contents for the text entry for the file name - - - - - user_data : - - - user data set when the signal handler was connected. - - - - - - - - You can create your own bindings for the - location-popup signal with custom - path strings, and have a crude form - of easily-to-type bookmarks. For example, say you access - the path /home/username/misc very - frequently. You could then create an - Alt M - shortcut by including the following in your - .gtkrc-2.0: - - - -binding "misc-shortcut" { - bind "<Alt>M" { - "location-popup" ("/home/username/misc") - } -} - -class "GtkFileChooserDefault" binding "misc-shortcut" - - - - - - The "GtkFileChooserDefault::up-folder" signal - - - void user_function (GtkFileChooserDefault *chooser, - gpointer user_data); - - - - This is used to make the file chooser go to the parent of - the current folder in the file hierarchy. By default this - is bound to Backspace and - AltUp - (the Up key in the numeric keypad also works). - - - - - chooser : - - - the object which received the signal. - - - - - user_data : - - - user data set when the signal handler was connected. - - - - - - - - The "GtkFileChooserDefault::down-folder" signal - - - void user_function (GtkFileChooserDefault *chooser, - gpointer user_data); - - - - This is used to make the file chooser go to a child of the - current folder in the file hierarchy. The subfolder that - will be used is displayed in the path bar widget of the file - chooser. For example, if the path bar is showing - "/foo/bar/baz", then this will cause - the file chooser to switch to the "baz" subfolder. By - default this is bound to - AltDown - (the Down key in the numeric keypad also works). - - - - - chooser : - - - the object which received the signal. - - - - - user_data : - - - user data set when the signal handler was connected. - - - - - - - - The "GtkFileChooserDefault::home-folder" signal - - - void user_function (GtkFileChooserDefault *chooser, - gpointer user_data); - - - - This is used to make the file chooser show the user's home - folder in the file list. By default this is bound to - AltHome - (the Home key in the numeric keypad also works). - - - - - chooser : - - - the object which received the signal. - - - - - user_data : - - - user data set when the signal handler was connected. - - - - - - - - The "GtkFileChooserDefault::desktop-folder" signal - - - void user_function (GtkFileChooserDefault *chooser, - gpointer user_data); - - - - This is used to make the file chooser show the user's Desktop - folder in the file list. By default this is bound to - AltD. - - - - - chooser : - - - the object which received the signal. - - - - - user_data : - - - user data set when the signal handler was connected. - - - - - - - - The "GtkFileChooserDefault::quick-bookmark" signal - - - void user_function (GtkFileChooserDefault *chooser, - gint bookmark_index, - gpointer user_data); - - - - This is used to make the file chooser switch to the bookmark - specified in the bookmark_index parameter. - For example, if you have three bookmarks, you can pass 0, 1, 2 to - this signal to switch to each of them, respectively. By default this is bound to - Alt1, - Alt2, - etc. until - Alt0. Note - that in the default binding, - that Alt1 is - actually defined to switch to the bookmark at index 0, and so on - successively; - Alt0 is - defined to switch to the bookmark at index 10. - - - - - chooser : - - - the object which received the signal. - - - - - bookmark_indes : - - - index of the bookmark to switch to; the indices start at 0. - - - - - user_data : - - - user data set when the signal handler was connected. - - - - - - - - - - #GtkFileChooserDialog, #GtkFileChooserWidget, #GtkFileChooserButton - - - - - - - - - - - - - - This signal gets emitted whenever it is appropriate to present a - confirmation dialog when the user has selected a file name that - already exists. The signal only gets emitted when the file - chooser is in #GTK_FILE_CHOOSER_ACTION_SAVE mode. - - - - Most applications just need to turn on the do-overwrite-confirmation - property (or call the - gtk_file_chooser_set_do_overwrite_confirmation() function), and - they will automatically get a stock confirmation dialog. - Applications which need to customize this behavior should do - that, and also connect to the confirm-overwrite - signal. - - - - A signal handler for this signal must return a - #GtkFileChooserConfirmation value, which indicates the action to - take. If the handler determines that the user wants to select a - different filename, it should return - #GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN. If it determines - that the user is satisfied with his choice of file name, it - should return #GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME. - On the other hand, if it determines that the stock confirmation - dialog should be used, it should return - #GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example - illustrates this. - - - - Custom confirmation - - -static GtkFileChooserConfirmation -confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data) -{ - char *uri; - - uri = gtk_file_chooser_get_uri (chooser); - - if (is_uri_read_only (uri)) - { - if (user_wants_to_replace_read_only_file (uri)) - return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME; - else - return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN; - } else - return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; /* fall back to the default dialog */ -} - -... - -chooser = gtk_file_chooser_dialog_new (...); - -gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE); -g_signal_connect (chooser, "confirm-overwrite", - G_CALLBACK (confirm_overwrite_callback), NULL); - -if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT) - save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser)); - -gtk_widget_destroy (chooser); - - - -@filechooser: the object which received the signal. -@Returns: #GtkFileChooserConfirmation value that indicates which - action to take after emitting the signal. - - - Since 2.8 - - - - - - - -@filechooser: the object which received the signal. - - - - - - -@filechooser: the object which received the signal. - - - - - - -@filechooser: the object which received the signal. - - - - - - -@filechooser: the object which received the signal. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Describes whether a #GtkFileChooser is being used to open - existing files or to save to a possibly new file. - - -@GTK_FILE_CHOOSER_ACTION_OPEN: Indicates open mode. The file chooser - will only let the user pick an existing file. -@GTK_FILE_CHOOSER_ACTION_SAVE: Indicates save mode. The file chooser - will let the user pick an existing file, or type in a new - filename. -@GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER: Indicates an Open mode for - selecting folders. The file chooser will let the user pick an - existing folder. -@GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER: Indicates a mode for creating a - new folder. The file chooser will let the user name an existing or - new folder. - - - - Used as a return value of handlers for the confirm-overwrite - signal of a GtkFileChooser. This value - determines whether the file chooser will present the stock - confirmation dialog, accept the user's choice of a filename, or - let the user choose another filename. - - -@GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM: The file chooser will present - its stock dialog to confirm about overwriting an existing file. -@GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME: The file chooser will - terminate and accept the user's choice of a file name. -@GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN: The file chooser will - continue running, so as to let the user select another file name. - - - Since 2.8 - - - - - Used to get the #GError quark for #GtkFileChooser errors. - - - - - - - These identify the various errors that can occur while calling - #GtkFileChooser functions. - - -@GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist. -@GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename. -@GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS: Indicates a duplicate path (e.g. when - adding a bookmark). -@GTK_FILE_CHOOSER_ERROR_INCOMPLETE_HOSTNAME: - - - - - - -@chooser: -@action: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@local_only: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@select_multiple: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@show_hidden: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@do_overwrite_confirmation: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@create_folders: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@name: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@filename: -@Returns: - - - - - - - -@chooser: -@filename: -@Returns: - - - - - - - -@chooser: -@filename: - - - - - - - -@chooser: - - - - - - - -@chooser: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@filename: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@uri: -@Returns: - - - - - - - -@chooser: -@uri: -@Returns: - - - - - - - -@chooser: -@uri: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@uri: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@preview_widget: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@active: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@use_label: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@extra_widget: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@filter: - - - - - - - -@chooser: -@filter: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@filter: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@folder: -@error: -@Returns: - - - - - - - -@chooser: -@folder: -@error: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@uri: -@error: -@Returns: - - - - - - - -@chooser: -@uri: -@error: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@Returns: - - - - - - - -@chooser: -@file: -@error: -@Returns: - - - - - - - -@chooser: -@file: -@error: -@Returns: - - - - - - - -@chooser: -@file: -@error: -@Returns: - - - - - - - -@chooser: -@file: - - diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c index 760c24ce7..705a845dc 100644 --- a/gtk/gtkfilechooser.c +++ b/gtk/gtkfilechooser.c @@ -27,6 +27,503 @@ #include "gtkmarshalers.h" #include "gtkalias.h" + +/** + * SECTION:gtkfilechooser + * @Short_description: File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog + * @Title: GtkFileChooser + * @See_also: #GtkFileChooserDialog, #GtkFileChooserWidget, #GtkFileChooserButton + * + * #GtkFileChooser is an interface that can be implemented by file + * selection widgets. In GTK+, the main objects that implement this + * interface are #GtkFileChooserWidget, #GtkFileChooserDialog, and + * #GtkFileChooserButton. You do not need to write an object that + * implements the #GtkFileChooser interface unless you are trying to + * adapt an existing file selector to expose a standard programming + * interface. + * + * #GtkFileChooser allows for shortcuts to various places in the filesystem. + * In the default implementation these are displayed in the left pane. It + * may be a bit confusing at first taht these shortcuts come from various + * sources and in various flavours, so lets explain the terminology here: + * + * + * Bookmarks + * + * are created by the user, by dragging folders from the + * right pane to the left pane, or by using the "Add". Bookmarks + * can be renamed and deleted by the user. + * + * + * + * Shortcuts + * + * can be provided by the application or by the underlying filesystem + * abstraction (e.g. both the gnome-vfs and the Windows filesystems + * provide "Desktop" shortcuts). Shortcuts cannot be modified by the + * user. + * + * + * + * Volumes + * + * are provided by the underlying filesystem abstraction. They are + * the "roots" of the filesystem. + * + * + * + * + * File Names and Encodings + * When the user is finished selecting files in a + * #GtkFileChooser, your program can get the selected names + * either as filenames or as URIs. For URIs, the normal escaping + * rules are applied if the URI contains non-ASCII characters. + * 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 + * variable. + * + * This means that while you can pass the result of + * gtk_file_chooser_get_filename() to + * open(2) or + * fopen(3), you may not be able to + * directly set it as the text of a #GtkLabel widget unless you + * convert it first to UTF-8, which all GTK+ widgets expect. + * You should use g_filename_to_utf8() to convert filenames + * into strings that can be passed to GTK+ widgets. + * + * + * + * Adding a Preview Widget + * + * You can add a custom preview widget to a file chooser and then + * get notification about when the preview needs to be updated. + * To install a preview widget, use + * gtk_file_chooser_set_preview_widget(). Then, connect to the + * #GtkFileChooser::update-preview signal to get notified when + * you need to update the contents of the preview. + * + * + * Your callback should use + * gtk_file_chooser_get_preview_filename() to see what needs + * previewing. Once you have generated the preview for the + * corresponding file, you must call + * gtk_file_chooser_set_preview_widget_active() with a boolean + * flag that indicates whether your callback could successfully + * generate a preview. + * + * + * Sample Usage + * + * { + * GtkImage *preview; + * + * ... + * + * preview = gtk_image_new (); + * + * gtk_file_chooser_set_preview_widget (my_file_chooser, preview); + * g_signal_connect (my_file_chooser, "update-preview", + * G_CALLBACK (update_preview_cb), preview); + * } + * + * static void + * update_preview_cb (GtkFileChooser *file_chooser, gpointer data) + * { + * GtkWidget *preview; + * char *filename; + * GdkPixbuf *pixbuf; + * gboolean have_preview; + * + * preview = GTK_WIDGET (data); + * filename = gtk_file_chooser_get_preview_filename (file_chooser); + * + * pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL); + * have_preview = (pixbuf != NULL); + * g_free (filename); + * + * gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf); + * if (pixbuf) + * g_object_unref (pixbuf); + * + * gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview); + * } + * + * + * + * + * Adding Extra Widgets + * + * You can add extra widgets to a file chooser to provide options + * that are not present in the default design. For example, you + * can add a toggle button to give the user the option to open a + * file in read-only mode. You can use + * gtk_file_chooser_set_extra_widget() to insert additional + * widgets in a file chooser. + * + * + * Sample Usage + * + * + * GtkWidget *toggle; + * + * ... + * + * toggle = gtk_check_button_new_with_label ("Open file read-only"); + * gtk_widget_show (toggle); + * gtk_file_chooser_set_extra_widget (my_file_chooser, toggle); + * } + * + * + * + * 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 + * and include your widgets in it. Then, set the container as + * the whole extra widget. + * + * + * + * Key Bindings + * + * Internally, GTK+ implements a file chooser's graphical user + * interface with the private + * GtkFileChooserDefaultClass. This + * widget has several key + * bindings and their associated signals. This section + * describes the available key binding signals. + * + * + * GtkFileChooser key binding example + * + * The default keys that activate the key-binding signals in + * GtkFileChooserDefaultClass are as + * follows: + * + * + * + * + * + * Signal name + * Default key combinations + * + * + * location-popup + * + * ControlL (empty path); + * / (path of "/") + * + * Both the individual / key and the + * numeric keypad's "divide" key are supported. + * ; + * ~ (path of "~") + * + * + * + * up-folder + * + * AltUp + * + * Both the individual Up key and the numeric + * keypad's Up key are supported. + * + * ; + * Backspace + * + * + * + * down-folder + * AltDown + * + * + * home-folder + * AltHome + * + * + * desktop-folder + * AltD + * + * + * quick-bookmark + * Alt1 through Alt0 + * + * + * + * + * + * 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-2.0 file: + * + * + * binding "my-own-gtkfilechooser-bindings" { + * 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" + * + * + * + * The "GtkFileChooserDefault::location-popup" signal + * + * void user_function (GtkFileChooserDefault *chooser, + * const char *path, + * gpointer user_data); + * + * + * This is used to make the file chooser show a "Location" + * dialog which the user can use to manually type the name of + * the file he wishes to select. The + * path argument is a string that gets + * put in the text entry for the file name. By default this is bound to + * ControlL + * with a path string of "" (the empty + * string). It is also bound to / with a + * path string of "/" + * (a slash): this lets you type / and + * immediately type a path name. On Unix systems, this is bound to + * ~ (tilde) with a path string + * of "~" itself for access to home directories. + * + * + * + * chooser : + * + * + * the object which received the signal. + * + * + * + * + * path : + * + * + * default contents for the text entry for the file name + * + * + * + * + * user_data : + * + * + * user data set when the signal handler was connected. + * + * + * + * + * + * You can create your own bindings for the + * GtkFileChooserDefault::location-popup signal with custom + * path strings, and have a crude form + * of easily-to-type bookmarks. For example, say you access + * the path /home/username/misc very + * frequently. You could then create an + * Alt M + * shortcut by including the following in your + * .gtkrc-2.0: + * + * binding "misc-shortcut" { + * bind "<Alt>M" { + * "location-popup" ("/home/username/misc") + * } + * } + * + * class "GtkFileChooserDefault" binding "misc-shortcut" + * + * + * + * + * The "GtkFileChooserDefault::up-folder" signal + * + * void user_function (GtkFileChooserDefault *chooser, + * gpointer user_data); + * + * + * This is used to make the file chooser go to the parent of + * the current folder in the file hierarchy. By default this + * is bound to Backspace and + * AltUp + * (the Up key in the numeric keypad also works). + * + * + * + * chooser : + * + * + * the object which received the signal. + * + * + * + * + * user_data : + * + * + * user data set when the signal handler was connected. + * + * + * + * + * + * + * The "GtkFileChooserDefault::down-folder" signal + * + * void user_function (GtkFileChooserDefault *chooser, + * gpointer user_data); + * + * + * This is used to make the file chooser go to a child of the + * current folder in the file hierarchy. The subfolder that + * will be used is displayed in the path bar widget of the file + * chooser. For example, if the path bar is showing + * "/foo/bar/baz", then this will cause + * the file chooser to switch to the "baz" subfolder. By + * default this is bound to + * AltDown + * (the Down key in the numeric keypad also works). + * + * + * + * chooser : + * + * + * the object which received the signal. + * + * + * + * + * user_data : + * + * + * user data set when the signal handler was connected. + * + * + * + * + * + * + * The "GtkFileChooserDefault::home-folder" signal + * + * void user_function (GtkFileChooserDefault *chooser, + * gpointer user_data); + * + * + * This is used to make the file chooser show the user's home + * folder in the file list. By default this is bound to + * AltHome + * (the Home key in the numeric keypad also works). + * + * + * + * chooser : + * + * + * the object which received the signal. + * + * + * + * + * user_data : + * + * + * user data set when the signal handler was connected. + * + * + * + * + * + * + * The "GtkFileChooserDefault::desktop-folder" signal + * + * void user_function (GtkFileChooserDefault *chooser, + * gpointer user_data); + * + * + * This is used to make the file chooser show the user's Desktop + * folder in the file list. By default this is bound to + * AltD. + * + * + * + * chooser : + * + * + * the object which received the signal. + * + * + * + * + * user_data : + * + * + * user data set when the signal handler was connected. + * + * + * + * + * + * + * The "GtkFileChooserDefault::quick-bookmark" signal + * + * void user_function (GtkFileChooserDefault *chooser, + * gint bookmark_index, + * gpointer user_data); + * + * + * This is used to make the file chooser switch to the bookmark + * specified in the bookmark_index parameter. + * For example, if you have three bookmarks, you can pass 0, 1, 2 to + * this signal to switch to each of them, respectively. By default this is bound to + * Alt1, + * Alt2, + * etc. until + * Alt0. Note + * that in the default binding, + * that Alt1 is + * actually defined to switch to the bookmark at index 0, and so on + * successively; + * Alt0 is + * defined to switch to the bookmark at index 10. + * + * + * + * chooser : + * + * + * the object which received the signal. + * + * + * + * + * bookmark_indes : + * + * + * index of the bookmark to switch to; the indices start at 0. + * + * + * + * + * user_data : + * + * + * user data set when the signal handler was connected. + * + * + * + * + * + * + */ + + static void gtk_file_chooser_class_init (gpointer g_iface); GType @@ -180,7 +677,74 @@ gtk_file_chooser_class_init (gpointer g_iface) g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); - /* Documented in the docbook files */ + /** + * GtkFileChooser::confirm-overwrite: + * @chooser: the object which received the signal. + * + * This signal gets emitted whenever it is appropriate to present a + * confirmation dialog when the user has selected a file name that + * already exists. The signal only gets emitted when the file + * chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode. + * + * Most applications just need to turn on the + * #GtkFileChooser:do-overwrite-confirmation property (or call the + * gtk_file_chooser_set_do_overwrite_confirmation() function), and + * they will automatically get a stock confirmation dialog. + * Applications which need to customize this behavior should do + * that, and also connect to the #GtkFileChooser::confirm-overwrite + * signal. + * + * A signal handler for this signal must return a + * #GtkFileChooserConfirmation value, which indicates the action to + * take. If the handler determines that the user wants to select a + * different filename, it should return + * %GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN. If it determines + * that the user is satisfied with his choice of file name, it + * should return %GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME. + * On the other hand, if it determines that the stock confirmation + * dialog should be used, it should return + * %GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example + * illustrates this. + * + * Custom confirmation + * + * static GtkFileChooserConfirmation + * confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data) + * { + * char *uri; + * + * uri = gtk_file_chooser_get_uri (chooser); + * + * if (is_uri_read_only (uri)) + * { + * if (user_wants_to_replace_read_only_file (uri)) + * return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME; + * else + * return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN; + * } else + * return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; // fall back to the default dialog + * } + * + * ... + * + * chooser = gtk_file_chooser_dialog_new (...); + * + * gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE); + * g_signal_connect (chooser, "confirm-overwrite", + * G_CALLBACK (confirm_overwrite_callback), NULL); + * + * if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT) + * save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser)); + * + * gtk_widget_destroy (chooser); + * + * + * + * Returns: a #GtkFileChooserConfirmation value that indicates which + * action to take after emitting the signal. + * + * Since: 2.8 + */ g_signal_new (I_("confirm-overwrite"), iface_type, G_SIGNAL_RUN_LAST, @@ -402,8 +966,8 @@ gtk_file_chooser_get_local_only (GtkFileChooser *chooser) * @select_multiple: %TRUE if multiple files can be selected. * * Sets whether multiple files can be selected in the file selector. This is - * only relevant if the action is set to be GTK_FILE_CHOOSER_ACTION_OPEN or - * GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. + * only relevant if the action is set to be %GTK_FILE_CHOOSER_ACTION_OPEN or + * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. * * Since: 2.4 **/ @@ -446,7 +1010,7 @@ gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser) * * Sets whether file choser will offer to create new folders. * This is only relevant if the action is not set to be - * GTK_FILE_CHOOSER_ACTION_OPEN. + * %GTK_FILE_CHOOSER_ACTION_OPEN. * * Since: 2.18 **/ @@ -525,7 +1089,7 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser) * * 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 + * 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 @@ -724,7 +1288,7 @@ gtk_file_chooser_set_current_folder (GtkFileChooser *chooser, * Note that this is the folder that the file chooser is currently displaying * (e.g. "/home/username/Documents"), which is not the same * as the currently-selected folder if the chooser is in - * #GTK_FILE_CHOOSER_SELECT_FOLDER mode + * %GTK_FILE_CHOOSER_SELECT_FOLDER mode * (e.g. "/home/username/Documents/selected-folder/". To get the * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the * usual way to get the selection. @@ -823,7 +1387,7 @@ gtk_file_chooser_get_uri (GtkFileChooser *chooser) * * Sets the file referred to by @uri as the current file for the file chooser, * by changing to the URI's parent folder and actually selecting the URI in the - * 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. * * If the URI isn't in the current folder of @chooser, then the current folder @@ -1028,7 +1592,7 @@ gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser, * Note that this is the folder that the file chooser is currently displaying * (e.g. "file:///home/username/Documents"), which is not the same * as the currently-selected folder if the chooser is in - * #GTK_FILE_CHOOSER_SELECT_FOLDER mode + * %GTK_FILE_CHOOSER_SELECT_FOLDER mode * (e.g. "file:///home/username/Documents/selected-folder/". To get the * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the * usual way to get the selection. @@ -1178,7 +1742,7 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser) * * Sets @file 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 + * 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 @@ -1294,7 +1858,7 @@ _gtk_file_chooser_get_file_system (GtkFileChooser *chooser) * * Sets an application-supplied widget to use to display a custom preview * of the currently selected file. To implement a preview, after setting the - * preview widget, you connect to the ::update-preview + * preview widget, you connect to the #GtkFileChooser::update-preview * signal, and call gtk_file_chooser_get_preview_filename() or * gtk_file_chooser_get_preview_uri() on each change. If you can * display a preview of the new file, update your widget and @@ -1981,17 +2545,17 @@ gtk_file_chooser_get_show_hidden (GtkFileChooser *chooser) * @chooser: a #GtkFileChooser * @do_overwrite_confirmation: whether to confirm overwriting in save mode * - * Sets whether a file chooser in GTK_FILE_CHOOSER_ACTION_SAVE mode will present + * Sets whether a file chooser in %GTK_FILE_CHOOSER_ACTION_SAVE mode will present * a confirmation dialog if the user types a file name that already exists. This * is %FALSE by default. * - * Regardless of this setting, the @chooser will emit the "confirm-overwrite" - * signal when appropriate. + * Regardless of this setting, the @chooser will emit the + * #GtkFileChooser::confirm-overwrite signal when appropriate. * * If all you need is the stock confirmation dialog, set this property to %TRUE. * You can override the way confirmation is done by actually handling the - * "confirm-overwrite" signal; please refer to its documentation for the - * details. + * #GtkFileChooser::confirm-overwrite signal; please refer to its documentation + * for the details. * * Since: 2.8 **/ diff --git a/gtk/gtkfilechooser.h b/gtk/gtkfilechooser.h index 0772690bd..21ba7ee5f 100644 --- a/gtk/gtkfilechooser.h +++ b/gtk/gtkfilechooser.h @@ -36,6 +36,23 @@ G_BEGIN_DECLS typedef struct _GtkFileChooser GtkFileChooser; +/** + * GtkFileChooserAction: + * @GTK_FILE_CHOOSER_ACTION_OPEN: Indicates open mode. The file chooser + * will only let the user pick an existing file. + * @GTK_FILE_CHOOSER_ACTION_SAVE: Indicates save mode. The file chooser + * will let the user pick an existing file, or type in a new + * filename. + * @GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER: Indicates an Open mode for + * selecting folders. The file chooser will let the user pick an + * existing folder. + * @GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER: Indicates a mode for creating a + * new folder. The file chooser will let the user name an existing or + * new folder. + * + * Describes whether a #GtkFileChooser is being used to open existing files + * or to save to a possibly new file. + */ typedef enum { GTK_FILE_CHOOSER_ACTION_OPEN, @@ -44,6 +61,23 @@ typedef enum GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER } GtkFileChooserAction; +/** + * GtkFileChooserConfirmation: + * @GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM: The file chooser will present + * its stock dialog to confirm about overwriting an existing file. + * @GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME: The file chooser will + * terminate and accept the user's choice of a file name. + * @GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN: The file chooser will + * continue running, so as to let the user select another file name. + * + * Used as a return value of handlers for the + * #GtkFileChooser::confirm-overwrite signal of a #GtkFileChooser. This + * value determines whether the file chooser will present the stock + * confirmation dialog, accept the user's choice of a filename, or + * let the user choose another filename. + * + * Since: 2.8 + */ typedef enum { GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM, @@ -54,9 +88,24 @@ typedef enum GType gtk_file_chooser_get_type (void) G_GNUC_CONST; /* GError enumeration for GtkFileChooser */ - +/** + * GTK_FILE_CHOOSER_ERROR: + * + * Used to get the #GError quark for #GtkFileChooser errors. + */ #define GTK_FILE_CHOOSER_ERROR (gtk_file_chooser_error_quark ()) +/** + * GtkFileChooserError: + * @GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist. + * @GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename. + * @GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS: Indicates a duplicate path (e.g. when + * adding a bookmark). + * @GTK_FILE_CHOOSER_ERROR_INCOMPLETE_HOSTNAME: + * + * These identify the various errors that can occur while calling + * #GtkFileChooser functions. + */ typedef enum { GTK_FILE_CHOOSER_ERROR_NONEXISTENT, GTK_FILE_CHOOSER_ERROR_BAD_FILENAME,