gtk/docs/man/gtk_button.pod

=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.