Xfce Foundation Classes
 « Main Page | Index

EventBox


Some widgets don't have an associated X window, so they just draw on their parents. Because of this, they cannot receive events and if they are incorrectly sized, they don't clip so you can get messy overwriting. 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.

The following widgets do not have an associated X window:

Gtk::Alignment
Gtk::Arrow
Gtk::AspectFrame
Gtk::Bin
Gtk::Box
Gtk::Button
Gtk::CheckButton
Gtk::Fixed
Gtk::Frame
Gtk::Image
Gtk::Label
Gtk::MenuItem
Gtk::Notebook
Gtk::Paned
Gtk::RadioButton
Gtk::Range
Gtk::ScrolledWindow
Gtk::Separator
Gtk::Table
Gtk::Toolbar
Gtk::VBox
Gtk::HBox
Gtk::VSeparator
Gtk::HSeparator
Widgets with no GDK 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 its contents. Although the name EventBox emphasizes the event-handling function, the widget can also be used for clipping. (and more, see the example below).

To create a new EventBox widget use the following constructor:

EventBox();

A child widget can then be added to this EventBox:

eventbox->add(*child_widget);

You will need to call the following Gtk::Widget method to set which events the EventBox should receive:

void set_events(Gdk::EventMaskField events);

The 'events' argument is a mask that determines which events the EventBox will receive. It can be one or more values from the Gdk::EventMask enum:
  • EXPOSURE_MASK - maps to the expose-event.
  • POINTER_MOTION_MASK - maps to the motion-notify-event.
  • POINTER_MOTION_HINT_MASK - decreases the number of motion-notify events.
  • BUTTON_MOTION_MASK - maps to the motion-notify-event.
  • BUTTON1_MOTION_MASK - maps to the motion-notify-event.
  • BUTTON2_MOTION_MASK - maps to the motion-notify-event.
  • BUTTON3_MOTION_MASK - maps to the motion-notify-event.
  • BUTTON_PRESS_MASK - maps to the button-press-event.
  • BUTTON_RELEASE_MASK - maps to the button-press-event.
  • KEY_PRESS_MASK - maps to the key-press-event.
  • KEY_RELEASE_MASK - maps to the key-release-event.
  • ENTER_NOTIFY_MASK - maps to the enter-notify-event.
  • LEAVE_NOTIFY_MASK - maps to the leave-notify-event.
  • FOCUS_CHANGE_MASK - maps to the focus-change-event.
  • STRUCTURE_MASK- Allows map, unmap, destroy and configure events to be captured.
  • PROPERTY_CHANGE_MASK - maps to the property-notify-event.
  • VISIBILITY_NOTIFY_MASK - maps to the visibilty-notify-event.
  • PROXIMITY_IN_MASK - maps to the proximity-in-event.
  • PROXIMITY_OUT_MASK - maps to the proximity-out-event.
  • SUBSTRUCTURE_MASK - allows a window to receive STRUCTURE_MASK events on any child windows.
  • SCROLL_MASK - Maps to the scroll-event
  • ALL_EVENTS_MASK - Maps to the all events.

EventBox Example

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

The header file for the Event Box example is <eventbox.hh>:

#include <xfc/main.hh>
#include <xfc/gtk/window.hh>
#include <xfc/gdk/cursor.hh>

using namespace Inti;

class EventBoxWindow : public Gtk::Window
{
    Pointer<Gdk::Cursor> hand_cursor;

protected:
    bool on_button_press_event(const Gdk::EventButton&);

public:
    EventBoxWindow();
    virtual ~EventBoxWindow();
};

and the source file is <eventbox.cc>:

#include "eventbox.hh"
#include <xfc/gtk/eventbox.hh>
#include <xfc/gtk/label.hh>
#include <xfc/gdk/window.hh>

EventBoxWindow::EventBoxWindow()
{
    set_title("Event Box");
    set_border_width(10);

    // Create an EventBox and add it to our toplevel window
    Gtk::EventBox *event_box = new Gtk::EventBox;
    add(*event_box);
    event_box->show();

    // Create a long label
    Gtk::Label *label = new Gtk::Label("Click here to quit, quit, quit, quit, quit");
    event_box->add(*label);
    label->show();

    // Clip it short
    label->set_size_request(110, 20);

    // And bind an action to it
    event_box->set_events(Gdk::BUTTON_PRESS_MASK);
    event_box->signal_button_press_event().connect(sigc::mem_fun(this, &EventBoxWindow::on_button_press_event));

    // Yet one more thing you need an X window for ...
    event_box->realize();
    hand_cursor = new Gdk::Cursor(GDK_HAND1);
    event_box->get_window()->set_cursor(*hand_cursor);
    show();
}

EventBoxWindow::~EventBoxWindow()
{
}

bool
EventBoxWindow::on_button_press_event(const Gdk::EventButton&)
{
    dispose();
    return true;
}

int main (int argc, char *argv[])
{
    using namespace Main;

    init(&argc, &argv);

    EventBoxWindow window;
    window.signal_destroy().connect(sigc::ptr_fun(&Xfc::Main::quit));

    run();
    return 0;
}

Compiling EventBox

If you compiled and installed XFC yourself, you will find the source code for EventBox in the <examples/howto/eventbox> source directory along with a Makefile. If XFC came pre-installed, or you installed it from an RPM package, you will find the source code in the </usr/share/doc/xfcui-X.X/examples/howto/eventbox> subdirectory. In this case you will have to create the Makefile yourself (replace X.X with the version number of the libXFCui library you have installed).

To create a Makefile for EventBox, add the following lines to a new text file and save it using the name "Makefile":

CC = g++

CFLAGS = -Wall -O2

eventbox: eventbox.cc eventbox.hh
    $(CC) eventbox.cc -o eventbox $(CFLAGS) `pkg-config xfcui-X.X --cflags --libs`

clean:
    rm -f *.o eventbox


If you cut and paste these lines make sure the whitespace before $(CC) and rm is a tab character. When you compile and run this program you will see the following window appear:



If you click on the label the window will be destroyed.


Copyright © 2004-2005 The XFC Development Team Top
XFC 4.4