NAME gtk_button - GTK+ push button widget SYNOPSIS #include 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); 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. OBJECT HIERARCHY gtk_object gtk_widget gtk_container gtk_button 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); USAGE 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 the gtk_label(3) manpage 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 the gtk_container(3) manpage for more information on adding widgets to containers. 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 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; } 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)); 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"); } 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. 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. AUTHORS The author of this man page is Shawn T. Amundson . For the authors of GTK+, see the AUTHORS file in the GTK+ distribution.