From 2ed1bab6bfffd22ea2fcdaaa696d25d299f02370 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Tadej=20Borov=C5=A1ak?= Date: Sat, 1 May 2010 19:17:51 +0200 Subject: [PATCH] [docs] GtkButton: Move documentation to inline comments MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Fixes https://bugzilla.gnome.org/show_bug.cgi?id=617386 Signed-off-by: Javier Jardón --- docs/reference/gtk/tmpl/.gitignore | 1 + docs/reference/gtk/tmpl/gtkbutton.sgml | 398 ------------------------- gtk/gtkbutton.c | 116 ++++++- 3 files changed, 103 insertions(+), 412 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkbutton.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 9e683a037..996aa553b 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -1,6 +1,7 @@ gtkbbox.sgml gtkbox.sgml gtkbuilder.sgml +gtkbutton.sgml gtkhbox.sgml gtkiconview.sgml gtkmessagedialog.sgml diff --git a/docs/reference/gtk/tmpl/gtkbutton.sgml b/docs/reference/gtk/tmpl/gtkbutton.sgml deleted file mode 100644 index 9cab72a40..000000000 --- a/docs/reference/gtk/tmpl/gtkbutton.sgml +++ /dev/null @@ -1,398 +0,0 @@ - -GtkButton - - -A widget that creates a signal when clicked on - - - -The #GtkButton widget is generally used to attach a function to that -is called when the button is pressed. The various signals and how to use -them are outlined below. - - -The #GtkButton widget can hold any valid child widget. That is it can -hold most any other standard #GtkWidget. The most commonly used child is -the #GtkLabel. - - - - - - - - - - - - - - - -This should not be accessed directly. Use the accessor functions below. - - - - - - - - -@button: the object which received the signal. - - - - - - -@button: - - - - - - -@button: - - - - - - -@button: - - - - - - -@button: - - - - - - -@button: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Creates a new #GtkButton widget. To add a child widget to the button, -use gtk_container_add(). - - -@void: -@Returns: The newly created #GtkButton widget. - - - - -Creates a #GtkButton widget with a #GtkLabel child containing the given -text. - - -@label: The text you want the #GtkLabel to hold. -@Returns: The newly created #GtkButton widget. - - - - - - - -@label: -@Returns: - - - - - - - -@stock_id: -@Returns: - - - - -Emits a #GtkButton::pressed signal to the given #GtkButton. - - -@button: The #GtkButton you want to send the signal to. -@Deprecated: 2.20: Use the #GtkWidget::button-press-event signal. - - - - -Emits a #GtkButton::released signal to the given #GtkButton. - - -@button: The #GtkButton you want to send the signal to. -@Deprecated: 2.20: Use the #GtkWidget::button-release-event signal. - - - - -Emits a #GtkButton::clicked signal to the given #GtkButton. - - -@button: The #GtkButton you want to send the signal to. - - - - -Emits a #GtkButton::enter signal to the given #GtkButton. - - -@button: The #GtkButton you want to send the signal to. -@Deprecated: 2.20: Use the #GtkWidget::enter-notify-event signal. - - - - -Emits a #GtkButton::leave signal to the given #GtkButton. - - -@button: The #GtkButton you want to send the signal to. -@Deprecated: 2.20: Use the #GtkWidget::leave-notify-event signal. - - - - -Sets the relief style of the edges of the given #GtkButton widget. -Three styles exist, GTK_RELIEF_NORMAL, GTK_RELIEF_HALF, GTK_RELIEF_NONE. -The default style is, as one can guess, GTK_RELIEF_NORMAL. - - - - -@button: The #GtkButton you want to set relief styles of. -@newstyle: The GtkReliefStyle as described above. - - - - -Returns the current relief style of the given #GtkButton. - - -@button: The #GtkButton you want the #GtkReliefStyle from. -@Returns: The current #GtkReliefStyle - - - - - - - -@button: -@Returns: - - - - - - - -@button: -@label: - - - - - - - -@button: -@Returns: - - - - - - - -@button: -@use_stock: - - - - - - - -@button: -@Returns: - - - - - - - -@button: -@use_underline: - - - - - - - -@button: -@focus_on_click: - - - - - - - -@button: -@Returns: - - - - - - - -@button: -@xalign: -@yalign: - - - - - - - -@button: -@xalign: -@yalign: - - - - - - - -@button: -@image: - - - - - - - -@button: -@Returns: - - - - - - - -@button: -@position: - - - - - - - -@button: -@Returns: - - - - - - - -@button: -@Returns: - - diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c index b0f41d55f..a684c265d 100644 --- a/gtk/gtkbutton.c +++ b/gtk/gtkbutton.c @@ -24,6 +24,20 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/** + * SECTION:gtkbutton + * @Short_description: A widget that creates a signal when clicked on + * @Title: GtkButton + * + * The #GtkButton widget is generally used to attach a function to that is + * called when the button is pressed. The various signals and how to use them + * are outlined below. + * + * The #GtkButton widget can hold any valid child widget. That is it can hold + * most any other standard #GtkWidget. The most commonly used child is the + * #GtkLabel. + */ + #include "config.h" #include #include "gtkalignment.h" @@ -268,7 +282,7 @@ gtk_button_class_init (GtkButtonClass *klass) * If the child of the button is a #GtkMisc or #GtkAlignment, this property * can be used to control it's horizontal alignment. 0.0 is left aligned, * 1.0 is right aligned. - * + * * Since: 2.4 */ g_object_class_install_property (gobject_class, @@ -287,7 +301,7 @@ gtk_button_class_init (GtkButtonClass *klass) * If the child of the button is a #GtkMisc or #GtkAlignment, this property * can be used to control it's vertical alignment. 0.0 is top aligned, * 1.0 is bottom aligned. - * + * * Since: 2.4 */ g_object_class_install_property (gobject_class, @@ -302,9 +316,9 @@ gtk_button_class_init (GtkButtonClass *klass) /** * GtkButton::image: - * + * * The child widget to appear next to the button text. - * + * * Since: 2.6 */ g_object_class_install_property (gobject_class, @@ -319,7 +333,7 @@ gtk_button_class_init (GtkButtonClass *klass) * GtkButton:image-position: * * The position of the image relative to the text inside the button. - * + * * Since: 2.10 */ g_object_class_install_property (gobject_class, @@ -339,7 +353,7 @@ gtk_button_class_init (GtkButtonClass *klass) * @button: the object that received the signal * * Emitted when the button is pressed. - * + * * Deprecated: 2.8: Use the #GtkWidget::button-press-event signal. */ button_signals[PRESSED] = @@ -356,7 +370,7 @@ gtk_button_class_init (GtkButtonClass *klass) * @button: the object that received the signal * * Emitted when the button is released. - * + * * Deprecated: 2.8: Use the #GtkWidget::button-release-event signal. */ button_signals[RELEASED] = @@ -388,7 +402,7 @@ gtk_button_class_init (GtkButtonClass *klass) * @button: the object that received the signal * * Emitted when the pointer enters the button. - * + * * Deprecated: 2.8: Use the #GtkWidget::enter-notify-event signal. */ button_signals[ENTER] = @@ -405,7 +419,7 @@ gtk_button_class_init (GtkButtonClass *klass) * @button: the object that received the signal * * Emitted when the pointer leaves the button. - * + * * Deprecated: 2.8: Use the #GtkWidget::leave-notify-event signal. */ button_signals[LEAVE] = @@ -513,9 +527,9 @@ gtk_button_class_init (GtkButtonClass *klass) /** * GtkButton::image-spacing: - * + * * Spacing in pixels between the image and label. - * + * * Since: 2.10 */ gtk_widget_class_install_style_property (widget_class, @@ -924,6 +938,14 @@ gtk_button_set_use_action_appearance (GtkButton *button, } } +/** + * gtk_button_new: + * + * Creates a new #GtkButton widget. To add a child widget to the button, + * use gtk_container_add(). + * + * Returns: The newly created #GtkButton widget. + */ GtkWidget* gtk_button_new (void) { @@ -1063,6 +1085,15 @@ gtk_button_construct_child (GtkButton *button) } +/** + * gtk_button_new_with_label: + * @label: The text you want the #GtkLabel to hold. + * + * Creates a #GtkButton widget with a #GtkLabel child containing the given + * text. + * + * Returns: The newly created #GtkButton widget. + */ GtkWidget* gtk_button_new_with_label (const gchar *label) { @@ -1111,6 +1142,14 @@ gtk_button_new_with_mnemonic (const gchar *label) return g_object_new (GTK_TYPE_BUTTON, "label", label, "use-underline", TRUE, NULL); } +/** + * gtk_button_pressed: + * @button: The #GtkButton you want to send the signal to. + * + * Emits a #GtkButton::pressed signal to the given #GtkButton. + * + * Deprecated: 2.20: Use the #GtkWidget::button-press-event signal. + */ void gtk_button_pressed (GtkButton *button) { @@ -1120,6 +1159,14 @@ gtk_button_pressed (GtkButton *button) g_signal_emit (button, button_signals[PRESSED], 0); } +/** + * gtk_button_released: + * @button: The #GtkButton you want to send the signal to. + * + * Emits a #GtkButton::released signal to the given #GtkButton. + * + * Deprecated: 2.20: Use the #GtkWidget::button-release-event signal. + */ void gtk_button_released (GtkButton *button) { @@ -1128,6 +1175,12 @@ gtk_button_released (GtkButton *button) g_signal_emit (button, button_signals[RELEASED], 0); } +/** + * gtk_button_clicked: + * @button: The #GtkButton you want to send the signal to. + * + * Emits a #GtkButton::clicked signal to the given #GtkButton. + */ void gtk_button_clicked (GtkButton *button) { @@ -1136,6 +1189,14 @@ gtk_button_clicked (GtkButton *button) g_signal_emit (button, button_signals[CLICKED], 0); } +/** + * gtk_button_enter: + * @button: The #GtkButton you want to send the signal to. + * + * Emits a #GtkButton::enter signal to the given #GtkButton. + * + * Deprecated: 2.20: Use the #GtkWidget::enter-notify-event signal. + */ void gtk_button_enter (GtkButton *button) { @@ -1144,6 +1205,14 @@ gtk_button_enter (GtkButton *button) g_signal_emit (button, button_signals[ENTER], 0); } +/** + * gtk_button_leave: + * @button: The #GtkButton you want to send the signal to. + * + * Emits a #GtkButton::leave signal to the given #GtkButton. + * + * Deprecated: 2.20: Use the #GtkWidget::leave-notify-event signal. + */ void gtk_button_leave (GtkButton *button) { @@ -1152,6 +1221,17 @@ gtk_button_leave (GtkButton *button) g_signal_emit (button, button_signals[LEAVE], 0); } +/** + * gtk_button_set_relief: + * @button: The #GtkButton you want to set relief styles of. + * @newstyle: The GtkReliefStyle as described above. + * + * Sets the relief style of the edges of the given #GtkButton widget. + * Three styles exist, GTK_RELIEF_NORMAL, GTK_RELIEF_HALF, GTK_RELIEF_NONE. + * The default style is, as one can guess, GTK_RELIEF_NORMAL. + * + * + */ void gtk_button_set_relief (GtkButton *button, GtkReliefStyle newrelief) @@ -1166,6 +1246,14 @@ gtk_button_set_relief (GtkButton *button, } } +/** + * gtk_button_get_relief: + * @button: The #GtkButton you want the #GtkReliefStyle from. + * + * Returns the current relief style of the given #GtkButton. + * + * Returns: The current #GtkReliefStyle + */ GtkReliefStyle gtk_button_get_relief (GtkButton *button) { @@ -2004,7 +2092,7 @@ gtk_button_get_use_stock (GtkButton *button) * gtk_button_set_focus_on_click: * @button: a #GtkButton * @focus_on_click: whether the button grabs focus when clicked with the mouse - * + * * Sets whether the button will grab focus when it is clicked with the mouse. * Making mouse clicks not grab focus is useful in places like toolbars where * you don't want the keyboard focus removed from the main area of the @@ -2031,7 +2119,7 @@ gtk_button_set_focus_on_click (GtkButton *button, /** * gtk_button_get_focus_on_click: * @button: a #GtkButton - * + * * Returns whether the button grabs focus when it is clicked with the mouse. * See gtk_button_set_focus_on_click(). * @@ -2116,7 +2204,7 @@ gtk_button_get_alignment (GtkButton *button, * _gtk_button_set_depressed: * @button: a #GtkButton * @depressed: %TRUE if the button should be drawn with a recessed shadow. - * + * * Sets whether the button is currently drawn as down or not. This is * purely a visual setting, and is meant only for use by derived widgets * such as #GtkToggleButton. -- 2.43.2