9. The EventBox Widget

This is only available in gtk+970916.tar.gz and later distributions.

Some gtk widgets don't have associated X windows, so they just draw on thier parents. Because of this, they cannot recieve events and if they are incorrectly sized, they don't clip so you can get messy overwritting etc. If you require more from these widgets, the EventBox is for you.

At first glance, the EventBox widget might appear to be totally useless. It draws nothing on the screen and responds to no events. However, it does serve a function - it provides an X window for its child widget. This is important as many GTK widgets do not have an associated X window. Not having an X window saves memory and improves performance, but also has some drawbacks. A widget without an X window cannot receive events, and does not perform any clipping on it's contents. Although the name ``EventBox'' emphasizes the event-handling function, the widget also can be used for clipping. (And more ... see the example below.)

To create a new EventBox widget, use:

GtkWidget* gtk_event_box_new (void);

A child widget can then be added to this EventBox:

gtk_container_add (GTK_CONTAINER(event_box), widget);

The following example demonstrates both uses of an EventBox - a label is created that clipped to a small box, and set up so that a mouse-click on the label causes the program to exit.

#include <gtk/gtk.h>

int 
main (int argc, char *argv[])
{
    GtkWidget *window;
    GtkWidget *event_box;
    GtkWidget *label;
    
    gtk_init (&argc, &argv);
    
    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
    
    gtk_window_set_title (GTK_WINDOW (window), "Event Box");
    
    gtk_signal_connect (GTK_OBJECT (window), "destroy",
                        GTK_SIGNAL_FUNC (gtk_exit), NULL);
    
    gtk_container_border_width (GTK_CONTAINER (window), 10);
    
    /* Create an EventBox and add it to our toplevel window */
    
    event_box = gtk_event_box_new ();
    gtk_container_add (GTK_CONTAINER(window), event_box);
    gtk_widget_show (event_box);
    
    /* Create a long label */
    
    label = gtk_label_new ("Click here to quit, quit, quit, quit, quit");
    gtk_container_add (GTK_CONTAINER (event_box), label);
    gtk_widget_show (label);
    
    /* Clip it short. */
    gtk_widget_set_usize (label, 110, 20);
    
    /* And bind an action to it */
    gtk_widget_set_events (event_box, GDK_BUTTON_PRESS_MASK);
    gtk_signal_connect (GTK_OBJECT(event_box), "button_press_event",
                        GTK_SIGNAL_FUNC (gtk_exit), NULL);
    
    /* Yet one more thing you need an X window for ... */
    
    gtk_widget_realize (event_box);
    gdk_window_set_cursor (event_box->window, gdk_cursor_new (GDK_HAND1));
    
    gtk_widget_show (window);
    
    gtk_main ();
    
    return 0;
}