From: Federico Mena Quintero Date: Tue, 13 Apr 2004 01:11:34 +0000 (+0000) Subject: Added documentation to all the signals. X-Git-Url: http://pileus.org/git/?p=~andy%2Fgtk;a=commitdiff_plain;h=fc586da5a8576436d4e859ecb7802b635b533df6 Added documentation to all the signals. 2004-04-12 Federico Mena Quintero * gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added documentation to all the signals. --- diff --git a/ChangeLog b/ChangeLog index d0a63f180..1401e17fb 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2004-04-12 Federico Mena Quintero + + * gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added + documentation to all the signals. + 2004-04-12 Matthias Clasen * gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index d0a63f180..1401e17fb 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,8 @@ +2004-04-12 Federico Mena Quintero + + * gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added + documentation to all the signals. + 2004-04-12 Matthias Clasen * gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index d0a63f180..1401e17fb 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,8 @@ +2004-04-12 Federico Mena Quintero + + * gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added + documentation to all the signals. + 2004-04-12 Matthias Clasen * gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index d0a63f180..1401e17fb 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,8 @@ +2004-04-12 Federico Mena Quintero + + * gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added + documentation to all the signals. + 2004-04-12 Matthias Clasen * gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index d0a63f180..1401e17fb 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,8 @@ +2004-04-12 Federico Mena Quintero + + * gtk/gtkfilechooser.c (gtk_file_chooser_class_init): Added + documentation to all the signals. + 2004-04-12 Matthias Clasen * gtk/gtkcombobox.c (gtk_combo_box_unset_model): Don't unref diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 99e0ff857..04357bdc7 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +2004-04-12 Federico Mena Quintero + + * gtk/tmpl/gtkfilechooser.sgml: Added documentation about + GtkFileChooserDefault's key binding signals. + 2004-03-26 Federico Mena Quintero * gtk/tmpl/gtkfilechooserdialog.sgml: Added a section about using diff --git a/docs/reference/gtk/tmpl/gtkfilechooser.sgml b/docs/reference/gtk/tmpl/gtkfilechooser.sgml index 6e7d41916..1d1decca4 100644 --- a/docs/reference/gtk/tmpl/gtkfilechooser.sgml +++ b/docs/reference/gtk/tmpl/gtkfilechooser.sgml @@ -116,6 +116,162 @@ update_preview_cb (GtkFileChooser *file_chooser, gpointer data) + + 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. + + + + The "GtkFileChooserDefault::location-popup" signal + + + void user_function (GtkFileChooserDefault *chooser, + 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. By default this is bound to + ControlL. + + + + + chooser : + + + the object which received the signal. + + + + + user_data : + + + user data set when the signal handler was connected. + + + + + + + + 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 + AltUp. + + + + + 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. + + + + + 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. + + + + + chooser : + + + the object which received the signal. + + + + + user_data : + + + user data set when the signal handler was connected. + + + + + + + #GtkFileChooserDialog, #GtkFileChooserWidget diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c index 4f4c4e27c..12bc6b1c3 100644 --- a/gtk/gtkfilechooser.c +++ b/gtk/gtkfilechooser.c @@ -59,6 +59,24 @@ gtk_file_chooser_class_init (gpointer g_iface) { GType iface_type = G_TYPE_FROM_INTERFACE (g_iface); + /** + * GtkFileChooser::current-folder-changed + * @chooser: the object which received the signal. + * + * This signal is emitted when the current folder in a #GtkFileChooser + * changes. This can happen due to the user performing some action that + * changes folders, such as selecting a bookmark or visiting a folder on the + * file list. It can also happen as a result of calling a function to + * explicitly change the current folder in a file chooser. + * + * Normally you do not need to connect to this signal, unless you need to keep + * track of which folder a file chooser is showing. + * + * See also: gtk_file_chooser_set_current_folder(), + * gtk_file_chooser_get_current_folder(), + * gtk_file_chooser_set_current_folder_uri(), + * gtk_file_chooser_get_current_folder_uri(). + */ g_signal_new ("current-folder-changed", iface_type, G_SIGNAL_RUN_LAST, @@ -66,6 +84,26 @@ gtk_file_chooser_class_init (gpointer g_iface) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * 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 + * in a #GtkFileChooser. This can happen when the user modifies the selection + * with the mouse or the keyboard, or when explicitly calling functions to + * change the selection. + * + * Normally you do not need to connect to this signal, as it is easier to wait + * for the file chooser to finish running, and then to get the list of + * selected files using the functions mentioned below. + * + * See also: gtk_file_chooser_select_filename(), + * gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(), + * gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(), + * gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(), + * gtk_file_chooser_get_uris(). + */ g_signal_new ("selection-changed", iface_type, G_SIGNAL_RUN_LAST, @@ -73,6 +111,33 @@ gtk_file_chooser_class_init (gpointer g_iface) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkFileChooser::update-preview + * @chooser: the object which received the signal. + * + * This signal is emitted when the preview in a file chooser should be + * regenerated. For example, this can happen when the currently selected file + * changes. You should use this signal if you want your file chooser to have + * a preview widget. + * + * Once you have installed a preview widget with + * gtk_file_chooser_set_preview_widget(), you should update it when this + * signal is emitted. You can use the functions + * gtk_file_chooser_get_preview_filename() or + * gtk_file_chooser_get_preview_uri() to get the name of the file to preview. + * Your widget may not be able to preview all kinds of files; your callback + * must call gtk_file_chooser_set_preview_wiget_active() to inform the file + * chooser about whether the preview was generated successfully or not. + * + * Please see the example code in . + * + * See also: gtk_file_chooser_set_preview_widget(), + * gtk_file_chooser_set_preview_widget_active(), + * gtk_file_chooser_set_use_preview_label(), + * gtk_file_chooser_get_preview_filename(), + * gtk_file_chooser_get_preview_uri(). + */ g_signal_new ("update-preview", iface_type, G_SIGNAL_RUN_LAST, @@ -80,6 +145,23 @@ gtk_file_chooser_class_init (gpointer g_iface) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkFileChooser::file-activated + * @chooser: the object which received the signal. + * + * This signal is emitted when the user "activates" a file in the file + * chooser. This can happen by double-clicking on a file in the file list, or + * by pressing Enter. + * + * Normally you do not need to connect to this signal. It is used internally + * by #GtkFileChooserDialog to know when to activate the default button in the + * dialog. + * + * See also: gtk_file_chooser_get_filename(), + * gtk_file_chooser_get_filenames(), gtk_file_chooser_get_uri(), + * gtk_file_chooser_get_uris(). + */ g_signal_new ("file-activated", iface_type, G_SIGNAL_RUN_LAST,