NAME
    gtk_button - GTK+ push button widget

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);

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 <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;
            }

  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
    <amundson@gtk.org>. For the authors of GTK+, see the AUTHORS
    file in the GTK+ distribution.