When connecting signals, it is possible to add an extra custom parameter to the callback. This is useful for passing the object you want to perform an action on, to your callback function.

For example, when a button is pressed we might want to destroy the parent instance of GtkWindow that that instance of GtkButton has been added to.

You can do this by including an optional third parameter to the connect() call. This will then be passed to your signal handler function as the final callback parameter.

<?php

function button_clicked($button, $window) 
{
    $window->destroy();
    gtk::main_quit();
}

$window = &new GtkWindow();

$button = &new GtkButton("exit");
$button->connect("clicked","button_clicked", $window);

$window->add($button);
$window->show_all();

gtk::main();

?>

By passing the $button variable as our calling object parameter and the $window variable as our custom parameter, we could use this same callback for more than one GtkButton on more than one GtkWindow. Note that the names given to the parameters within the callback are irrelevant outside the callback function; PHP-GTK picks up on the positions of the parameters in the connect* method calls and passes these to the variables listed in the callback declaration as an array, so that any instance of a connection using the same parameter structure can use that same callback. This is demonstrated in the code below using a single custom parameter, but is equally true for more than one.

<?php

function button_clicked($button, $window)
{
    $window->set_title("titled");
}

$window1 = &new GtkWindow();
$window1->connect_object("destroy", array("gtk", 
"main_quit"));
$window2 = &new GtkWindow();
$window2->connect_object("destroy", array("gtk", 
"main_quit"));

$button1 = &new GtkButton("click me");
$button2 = &new GtkButton("or me");

$button1->connect("clicked", "button_clicked", 
$window1);
$button2->connect("clicked", "button_clicked", 
$window2);

$window1->add($button1);
$window2->add($button2);

$window1->show_all();
$window2->show_all();

gtk::main();

?>

Both connect_object() and connect_object_after() allow you to pass an object other than the calling object as the first parameter to your callback function. This is mainly used for calling static PHP-GTK functions, as in (for example) the gtk::main_quit() function:

<?php

$window = &new GtkWindow();
$window->connect_object("destroy", array("gtk", 
"main_quit"));
$window->show();

gtk::main();

?>

It also means you can have a single callback for multiple signals. For example; you might create a window containing (within the necessary container widgets) a GtkMenuBar, a GtkToolbar and a GtkButton. When Exit is chosen by the user through any of these widgets, a shutdown function could be invoked by passing the instance of GtkWindow as its first parameter, allowing the window to be destroyed from any of those connections. The callback function and the connections in this instance would look like this:

<?php

function destroy_window($window)
{
    $window->destroy();
    gtk::main_quit();
}

$exit_button->connect_object("clicked", 
"destroy_window", $window);

?>

The connect_after* methods allow callbacks to be "run after" the default signal handler for that signal. This can be useful in some situations; for example, where you want to destroy only one of several windows in a given circumstance. However, connect_after* methods will only work when a signal has been created in the GTK source with a GTK_RUN_LAST flag. The "destroy" signal and all the 'event' signals have this flag; beyond that, the only way to check is to either test the signal within PHP-GTK or read the GTK source.

<?php

function quit_routine($window) 
{
    print("Shutting down...\n");
    gtk::main_quit();
}

$window1 = &new GtkWindow();
$window1->set_title("Quit the main loop");
$window1->connect("destroy", "quit_routine");

$window2 = &new GtkWindow();
$window2->set_title("Destroy this window");
$window2->connect_after("destroy", "quit_routine");

$window1->show();
$window2->show();

gtk::main();

?>

See also: GtkObject, connect_after() connect_object() and connect_object_after() .