Signals and Events

Signals are not events, and events are not signals. A signal is a message emitted by an instance of a GtkObject in response to some predetermined element in its environment, e.g. an action by the end user, or an instruction from a function or method. Signals are always programmed into the code, either internally within GTK or externally by the PHP-GTK programmer.

Events, on the other hand, are a continual stream of impulses communicating messages concerning environmental changes in the underlying windowing system. The GTK main loop is made up of this stream of events, among other things.

It is not possible to connect a callback function to a GdkEvent directly.

Any widget having its own GdkWindow may capture events that are relevant to it. Widgets lacking a GdkWindow - those created with the GTK_NO_WINDOW flag - cannot do so, unless they are housed within a GtkEventBox - a widget created for this specific purpose. There are occasions when it is useful to be able to capture events; one obvious example would be the creation of an instance of GtkToolTips which is triggered when its subject widget captures the GDK_ENTER_NOTIFY event and destroyed when the same widget captures the GDK_LEAVE_NOTIFY event.

Although it is not possible to use an event to trigger a callback in the same way as a signal, there are a series of signals derived from GtkWidget collectively known as 'event' signals. These are effectively ways of describing an event in terms of a signal, allowing callbacks to be indirectly triggered through a captured occurrence of most of the GdkEventTypes. The GtkTooltips object itself uses the connect_object method and the generic "event" signal in order to monitor its subject widget.

The concept of events is not an easy one to grasp. Please copy, paste and run the following script in order to see the flow of events over a widget in action.

Example 2.8. Demonstration of the flow of events across a GtkButton

<?php

dl("php_gtk." . (strstr(PHP_OS, "WIN") ? "dll" : 
"so")) ||
die("Can't load php_gtk module!\n");

function show_event_type($button, $event, $text) 
{
    $event_type = $event->type;
    $insert = $text->get_length();
    $text->freeze();
    switch($event_type) {
      case 2:
        $text->insert_text("GDK_EXPOSE\n", $insert);
      break;
      case 3:
        $text->insert_text("GDK_MOTION_NOTIFY\n", $insert);
      break;
      case 4:
        $text->insert_text("GDK_BUTTON_PRESS\n", $insert);
      break;
      case 5:
        $text->insert_text("GDK_2BUTTON_PRESS\n", $insert);
        $button->hide();
      break;
      case 7:
        $text->insert_text("GDK_BUTTON_RELEASE\n", $insert);
      break;
      case 8:
        $text->insert_text("GDK_KEY_PRESS\n", $insert);
      break;
      case 9:
        $text->insert_text("GDK_KEY_RELEASE\n", $insert);
      break;
      case 10:
        $text->insert_text("GDK_ENTER_NOTIFY\n", $insert);
      break;
      case 11:
        $text->insert_text("GDK_LEAVE_NOTIFY\n", $insert);
      break;
      case 12:
        $text->insert_text("GDK_FOCUS_CHANGE\n", $insert); 
      break;
      case 14:
        $text->insert_text("GDK_MAP\n", $insert);
      break;
      case 15:
        $text->insert_text("GDK_UNMAP\n", $insert);
        $button->destroy();
        $text->insert_text(
"\n* GDK EVENTS AND GTK SIGNALS - background stream vs foreground 
messaging *
\n
* Most GdkEventTypes have counterpart GTK signals, known as 'event'
  signals, implemented in GtkWidget.  The types on your screen are there
  because the GtkButton was programmed to emit the generic 'event' signal
  each time it captured one of the stream of GDK events that makes up the
  GTK main loop.  In each case, the captured GdkEvent was passed as a
  callback parameter so that its enumerated type value could be determined
  within the signal handler function.  Scroll down to see the series of event
  values captured during your recent interaction with the GtkButton widget. *
\n
* Please note that the majority of GTK signals do NOT correspond to GDK
  events in this or any other way!  For example, the signal connection
                      \$button->connect('pressed', 'whatever');
  has no relationship to the GDK_BUTTON_PRESS event it generates, which
  refers to mouse-button activity and not to the GtkButton 'pressed' signal. *
\n", 0);
      break;
    }
    $text->thaw();
    return false;
}

$window = &new GtkWindow();
$window->set_position(GTK_WIN_POS_CENTER);
$window->set_default_size((gdk::screen_width()/1.5), 
(gdk::screen_height()-20));
$window->connect_object("destroy", array("gtk", 
"main_quit"));
$window->realize();

$box = &new GtkVBox(false, 5);
$window->add($box);
$scrlwin = &new GtkScrolledWindow();
$box->pack_start($scrlwin, true, true, 0);
$text = &new GtkText();
$scrlwin->add($text);

$button = &new GtkButton("Double-click here for information..");
$button->add_events(GDK_ALL_EVENTS_MASK);
$button->connect("event", "show_event_type", $text);
$box->pack_end($button, false, false, 5);

$window->show_all();

gtk::main();

?>