gtk2/docs/man/gtk_button.pod

243 lines
6.6 KiB
Plaintext
Raw Normal View History

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