new directory new file, initial gtk_button man page

Tue Jul 28 20:32:03 CDT 1998 Shawn T. Amundson <amundson@gtk.org>

        * gtk/docs/man: new directory
        * gtk/docs/man/gtk_button.pod: new file, initial gtk_button man page

ChangeLog

+Tue Jul 28 20:32:03 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* gtk/docs/man: new directory
+	* gtk/docs/man/gtk_button.pod: new file, initial gtk_button man page
+
 Tue Jul 28 00:03:20 1998  Lars Hamann  <lars@gtk.org>
 
 	* gtk/gtknotebook.c (gtk_notebook_paint): small fix for border drawing

ChangeLog.pre-2-0

+Tue Jul 28 20:32:03 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* gtk/docs/man: new directory
+	* gtk/docs/man/gtk_button.pod: new file, initial gtk_button man page
+
 Tue Jul 28 00:03:20 1998  Lars Hamann  <lars@gtk.org>
 
 	* gtk/gtknotebook.c (gtk_notebook_paint): small fix for border drawing

ChangeLog.pre-2-10

+Tue Jul 28 20:32:03 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* gtk/docs/man: new directory
+	* gtk/docs/man/gtk_button.pod: new file, initial gtk_button man page
+
 Tue Jul 28 00:03:20 1998  Lars Hamann  <lars@gtk.org>
 
 	* gtk/gtknotebook.c (gtk_notebook_paint): small fix for border drawing

ChangeLog.pre-2-2

+Tue Jul 28 20:32:03 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* gtk/docs/man: new directory
+	* gtk/docs/man/gtk_button.pod: new file, initial gtk_button man page
+
 Tue Jul 28 00:03:20 1998  Lars Hamann  <lars@gtk.org>
 
 	* gtk/gtknotebook.c (gtk_notebook_paint): small fix for border drawing

ChangeLog.pre-2-4

+Tue Jul 28 20:32:03 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* gtk/docs/man: new directory
+	* gtk/docs/man/gtk_button.pod: new file, initial gtk_button man page
+
 Tue Jul 28 00:03:20 1998  Lars Hamann  <lars@gtk.org>
 
 	* gtk/gtknotebook.c (gtk_notebook_paint): small fix for border drawing

ChangeLog.pre-2-6

+Tue Jul 28 20:32:03 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* gtk/docs/man: new directory
+	* gtk/docs/man/gtk_button.pod: new file, initial gtk_button man page
+
 Tue Jul 28 00:03:20 1998  Lars Hamann  <lars@gtk.org>
 
 	* gtk/gtknotebook.c (gtk_notebook_paint): small fix for border drawing

ChangeLog.pre-2-8

+Tue Jul 28 20:32:03 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* gtk/docs/man: new directory
+	* gtk/docs/man/gtk_button.pod: new file, initial gtk_button man page
+
 Tue Jul 28 00:03:20 1998  Lars Hamann  <lars@gtk.org>
 
 	* gtk/gtknotebook.c (gtk_notebook_paint): small fix for border drawing

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