diff options
Diffstat (limited to 'docs/man/gtk_button.pod')
| -rw-r--r-- | docs/man/gtk_button.pod | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/docs/man/gtk_button.pod b/docs/man/gtk_button.pod new file mode 100644 index 0000000000..065ef83605 --- /dev/null +++ b/docs/man/gtk_button.pod @@ -0,0 +1,242 @@ + +=head1 NAME + +gtk_button - GTK+ push button widget + +=head1 SYNOPSIS + + #include <gtk/gtkbutton.h> + + GtkType gtk_button_get_type (void); + GtkWidget* gtk_button_new (void); + GtkWidget* gtk_button_new_with_label (const gchar *label); + void gtk_button_pressed (GtkButton *button); + void gtk_button_released (GtkButton *button); + void gtk_button_clicked (GtkButton *button); + void gtk_button_enter (GtkButton *button); + void gtk_button_leave (GtkButton *button); + void gtk_button_set_relief (GtkButton *button, + GtkReliefStyle style); + GtkReliefStyle gtk_button_get_relief (GtkButton *button); + +=head1 DESCRIPTION + +This widget is a standard push button widget. Push button widgets +are generally used for allowing the user to click on them to initiate +a command. + +This widget is a container widget which contains one child. + +=head1 OBJECT HIERARCHY + + gtk_object + gtk_widget + gtk_container + gtk_button + +=head1 SIGNAL PROTOTYPES + + "clicked" void user_function (GtkWidget *widget, gpointer data); + "pressed" void user_function (GtkWidget *widget, gpointer data); + "released" void user_function (GtkWidget *widget, gpointer data); + "enter" void user_function (GtkWidget *widget, gpointer data); + "leave" void user_function (GtkWidget *widget, gpointer data); + +=head1 USAGE + +=head2 Creation + +The most common way to create a button is with a label in it, which +contains text for the user to read. The child of the button will then +be a L<gtk_label(3)> widget with the text you passwd in. You can +do this in one command: + + GtkWidget *button; + button = gtk_button_new_with_label ("This is a button"); + +To create a gtk_button widget which does not already have a child, +use gtk_button_new(): + + GtkWidget *button; + button = gtk_button_new (); + +After you have created a button you can then add a widget to the +button (such as a label or pixmap) using gtk_container_add(). See +L<gtk_container(3)> for more information on adding widgets to +containers. + +=head2 Creating a pixmap in a button in a window + +After we have an empty gtk_button, such as above, and we have a gtk_pixmap, +we can simply add the gtk_pixmap to the gtk_button with gtk_container_add(). + +The following code will open the file "gimp.xpm" and place it in a +button. + + #include <gtk/gtk.h> + + int main (int argc, char *argv[]) + { + GtkWidget *window; + GtkWidget *button; + GtkWidget *pixmap; + GtkStyle *style; + GdkPixmap *gdkpixmap; + GdkBitmap *mask; + char *filename = "gimp.xpm"; + + gtk_init (&argc, &argv); + + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + + button = gtk_button_new (); + gtk_container_add (GTK_CONTAINER (window), button); + + /* The button is realized now, which creates button->window + used below to create the pixmap. */ + gtk_widget_realize (button); + + style = gtk_widget_get_style (button); + gdkpixmap = gdk_pixmap_create_from_xpm (button->window, &mask, + &style->bg[GTK_STATE_NORMAL], + filename); + pixmap = gtk_pixmap_new (gdkpixmap, mask); + + gtk_container_add (GTK_CONTAINER (button), pixmap); + + gtk_widget_show (pixmap); + gtk_widget_show (button); + gtk_widget_show (window); + + gtk_main (); + return 0; + } + +=head2 Different reliefs + +Reliefs affect how the shadowing of the button is drawn. The different +types of relief styles are: + + GTK_RELIEF_NORMAL + GTK_RELIEF_HALF + GTK_RELIEF_NONE + +When set to a normal relief, the widget looks and acts like a normal +button. When half or none relief is used, shadowing is only drawn when the +mouse cursor is over the widget. + +To set the relief, use gtk_button_set_relief(), like: + + gtk_button_set_relief (button, GTK_RELIEF_HALF); + +To get the current relief of a button, use gtk_button_get_relief(): + + GtkReliefStyle relief; + relief = gtk_button_get_relief (GTK_BUTTON (button)); + +=head2 Executing a command when the button is pressed + +To execute a function when a button is pressed, use +gtk_signal_connect() to connect to the "clicked" signal. + + gtk_signal_connect (GTK_OBJECT (button), "clicked", + GTK_SIGNAL_FUNC (user_function), + NULL); + +user_function is a user defined function, like the following: + + void user_function (GtkWidget *button, gpointer data) + { + printf("clicked\n"); + } + +=head1 FUNCTIONS + +GtkType gtk_button_get_type (void); + + This function returns the GtkType which is assigned to the + object class for gtk_button. + +GtkWidget* gtk_button_new (void); + + This functions returns a new button widget which can then be + used as a container for another widget. + +GtkWidget* gtk_button_new_with_label (const gchar *label); + + This function returns a new button widget with a label widget + as a child. The label widget will have the text passed into + the commant. + +void gtk_button_pressed (GtkButton *button); + + This function sends a "pressed" signal to the button. + +void gtk_button_released (GtkButton *button); + + This function sends a "released" signal to the button. + +void gtk_button_clicked (GtkButton *button); + + This function sends a "clicked" signal to the button. + +void gtk_button_enter (GtkButton *button); + + This function sends a "enter" signal to the button. + +void gtk_button_leave (GtkButton *button); + + This function sends a "leave" signal to the button. + +void gtk_button_set_relief (GtkButton *button, GtkReliefStyle style); + + This function is sets the GtkReliefStyle of the button. The + relief style is one of: GTK_RELIEF_NORMAL, GTK_RELIEF_HALF, + or GTK_RELIEF_NONE. The relief determines when the shadow of + the button is drawn. + +GtkReliefStyle gtk_button_get_relief (GtkButton *button); + + This function returns the current relief of the button. + +=head1 SIGNALS + +"clicked" + + void user_function (GtkWidget *widget, gpointer data); + + Gets emitted when the button is clicked. A click is + a press and release of the button when the cursor is + inside the button on release. + +"pressed" + + void user_function (GtkWidget *widget, gpointer data); + + Gets emitted when the left mouse button is pressed. + +"released" + + void user_function (GtkWidget *widget, gpointer data); + + Gets emitted when the left mouse button is released and + the widget was previously pressed. + +"enter" + + void user_function (GtkWidget *widget, gpointer data); + + Emitted when the mouse cursor enters the button. + +"leave" + + void user_function (GtkWidget *widget, gpointer data); + + Emitted when the mouse cursor leaves the button. + +=head1 AUTHORS + +The author of this man page is Shawn T. Amundson E<lt>amundson@gtk.orgE<gt>. +For the authors of GTK+, see the AUTHORS file in the GTK+ distribution. + + |