PHP-GTK
Thursday, July 24, 2014 
download | documentation | applications | faq | changelog | resources 


search for in the  


previousCallbacks and Signal Handlers
Eventsnext

Last updated: Sun, 12 May 2013
view this page in English

It should be clear by now that if you want to react to an action, you must connect its signal to a signal handler that you have written, so that PHP-GTK 2 can call that function whenever the signal is triggered. Let's look into how you can connect signals to signal handlers.

There are 4 main functions that you can use to connect signals to callbacks:

The *_after methods are used if you want your signal handlers to be invoked after the ones connected using connect and connect_simple. We will be discussing only the connect_simple and connect methods. The respective *_after methods behave in the same way except for the fact that the signal handler is guaranteed to be invoked only after those connected via connect or connect_simple have.

First we'll look into how to connect a signal to a signal handler in the most simplest way. We'll be using, you guessed it, the connect_simple method.

Of course, it is vital that you know the names of the signals that you would want to connect to. The PHP-GTK 2 documentation contains a list of all signals that are relevant for a particular widget. Once you know that, and once you have written a function that contains the code you want to be executed when the signal is generated all you have to do is:

${widget}->connect_simple('{signal-name}', '{callback-name}');
where, {widget} is the object whose signal you want to connect, {signal-name} is the signal name, which of course must be relevant to {widget}, and {callback-name} is the name of the callback function.

Signal handlers are invoked whenever a signal is generated, by whatever means. Remember that it is possible to generate signals through functions, and hence a signal generation does not guarantee that the user has performed an action.

To make things a little clearer, let's take a full fledged example. Here, we add a button to a window. When a user clicks the button, the application quits:

Example 9.1. A simple connection

<?php
 
$win = new GtkWindow();
$but = new GtkButton('Click to Quit!');
 
$win->add($but);
$win->show_all();
 
$but->connect_simple('clicked', 'quit');
 
function quit()
{
    echo "You have quit!\n";
    Gtk::main_quit();
}
 
Gtk::main();
 
?>

It's quite a simple program. We create a button and a window, add the button to the window and show them. The line we are concerned with is:

$but->connect_simple('clicked', 'quit');
As you can see, we have connected the "
clicked" signal of a GtkButton widget to the signal handler named quit. Simple, eh? The function quit will be called whenever the clicked signal is emitted from our button, or, whenever the user clicks on our button.

You can see in the quit function definition that we display a message and then call the Gtk::main_quit() function to exit the program.

What if I connect the same signal twice to two different callbacks?, I hear you ask. Well, the signal handlers will simply be called in the order in which they were connected.

An example to make things crystal clear:

Example 9.2. Multiple signal connections

<?php
 
$win = new GtkWindow();
$but = new GtkButton('Click to Quit!');
 
$win->add($but);
$win->show_all();
 
$but->connect_simple('clicked', 'first');
$but->connect_simple('clicked', 'second');
$but->connect_simple('clicked', 'third');
 
function first()
{
    echo "I am the first function!\n";
}
 
function second()
{
    echo "I am the second function!\n";
}
 
function third()
{
    echo "And I'm the function that's going to stop this program!\n";
    Gtk::main_quit();
}
 
Gtk::main();
 
?>
Run the program and you will see that signal handlers are indeed invoked in the order in which they were connected.

OK, but what if I connect the signal to the same callback a hundred times? The callback will be invoked a hundred times. But there's no reason anyone would want to do this.

Can I connect multiple signals to the same callback? Yes, and in fact this is actually very useful. Many applications will have multiple ways of quitting the program: the regular "cross" button, a "quit" button on the file menu etc. You can connect signals for each one of them to a single quit function. You don't have to worry about where the signal came from, you just know that the user wants to quit the application.

Sometimes, its useful to know which widget had triggered a particular signal. If your application has more than one button, and you've connected all their clicked signals to a single callback, you'd definitely want to know which button the signal came from. It is in fact efficient to write a single signal handler for multiple signals.

Here is where the connect method comes into the picture. This method passes the object of the widget that generated the signal as the first parameter to the signal handler.

$button1 = new GtkButton('First');
$button2 = new GtkButton('Second');
 
$button1->connect('clicked', 'show');
$button2->connect('clicked', 'show');
 
function show($whichbutton)
{
    echo $whichbutton->get_label();
}
In the above example, you will get an output of "First" or "Second" depending on which button was clicked.

It is also useful at times if you could pass custom parameters to your signal handlers. PHP-GTK 2 provides this functionality in both the connect and connect_after methods. You simply pass your parameters after the second argument to both these methods separated by commas like this:

Example 9.3. Passing custom parameters

<?php
 
$win = new GtkWindow();
$but = new GtkButton('Move over me!');
 
$win->add($but);
$win->show_all();
 
$win->connect_simple('destroy', array('gtk', 'main_quit'));
$but->connect_simple('enter-notify-event', 'showMessage', true, 'You moved the mouse');
$but->connect_simple('leave-notify-event', 'showMessage', false, 'You moved the mouse');
 
function showMessage($enter, $message)
{
    if ($enter) {
        echo $message." over the button!\n";
    } else {
        echo $message." away from the button!\n";
    }
}
 
Gtk::main();
 
?>
In this example, we pass two custom parameters to our signal handler that helps us from differentiating whether the mouse entered the button or left it. Note that your custom parameters can be of any type: string, boolean, integer, an array or even an object, as long as its a valid type in PHP. In fact, it is a very common necessity to pass widget objects as parameters to signal handlers, because a callback connected to a signal triggered by some widget may need to modify some other widget. You may pass as many custom parameters as you want. Just ensure that your signal handler is designed to receive the same number of parameters, or you may raise warnings.


User Contributed Notes
tutorials.signals.connecting.php
add a note about notes
There are no user contributed notes for this page.


previousCallbacks and Signal Handlers
Eventsnext

Last updated: Sun, 12 May 2013
view this page in English


credits 

PHP  Copyright © 2001-2014 The PHP Group
 All rights reserved.
Last updated: Sun May 12 20:51:01 2013 CEST