Beginning PHP-GTK: Signals

[Jordan]

• Part 1 - Beginning PHP-GTK: Creating a Simple Interface
• Part 2 - Beginning PHP-GTK: Signals
• Part 3 - Coming soon

Before you begin...
You should know that this tutorial builds off the first tutorial here. You should understand everything in that tutorial before continuing with this tutorial.

Introduction to "Beginning PHP-GTK Part 2"
In the last part of this series tutorial you created a basic GUI interface using PHP-GTK. At the end of the tutorial, the application we made looked like this:



If you don't have the code, go back and fetch it. We will be using that code during this tutorial.

Signals
Signals are notifications fired by the user or internal coding. The PHP-GTK manual puts it best:

Signals are notifications emitted by widgets.

When programming Graphical User Interfaces (GUI), it is often necessary to respond to actions performed by the user or initiated within the program itself. GNOME and GTK+ do this via the use of signals. Signals are used to let the program know that something happened. This might be, for example, a user clicking on a GtkButton, or a change being made to a GtkAdjustment value.

We use signals to respond to the user. An event driven GUI such as the one we are building would be useless without them.

Signal Callback Functions
In order to react to a signal, it must be connected to a callback function. A callback function is any PHP function or class method. You connect a signal to a function using connect().

Constructor:

int connect(string signal, string function, [mixed custom_data ]);

Signal: Textual name of the signal (IE: Clicked)
function: Name of the function (callback) to be called
custom_data: optional, used to pass extra data to the callback function (such as params)

Connecting a signal is easy. First, lets create a stop and start button method. In the CodeCallGtk class, add these methods:

    /**
     * This is the method that is executed when 
     * the stop "button" on the GtkWindow is clicked.
     * 
     */
    public function stopButtonClick() {
            /*
             * Create a messagebox
             */
            $dialog = new GtkMessageDialog($this, Gtk::DIALOG_MODAL, Gtk::MESSAGE_QUESTION, Gtk::BUTTONS_YES_NO, "");
            $dialog->set_markup(
                "<span foreground='red'>Do you really want to stop?</span>"
            );
            
            /*
             * Display the message
             */
            $response = $dialog->run();
            $dialog->destroy();
    }

    /**
     * This is the method that is executed when 
     * the start "button" on the GtkWindow is clicked.
     * 
     */
    public function startButtonClick() {
        // Place holder for now
    } 

The first method (stopButtonClick()) creates a messagebox with two buttons, yes and no. The second method does nothing during this tutorial.

Connecting the Signal
As mentioned earlier, connecting the signal is done with connect(). There is also connect_after(), connect_object() and connect_object_after but they are beyond the scope of this tutorial.

In the __construct() of CodeCallGtk (before show_all()), connect the buttons "clicked" signal with the functions we added earlier:

        /*
         * Connect our buttons
         */
         $btnStart->connect('clicked', array($this,'startButtonClick'));
         $btnStop->connect('clicked', array($this,'stopButtonClick')); 

You should end up with this code:

<?php

class CodeCallGtk extends GtkWindow {
    
    /**
     * FirstGTK constructor. Actually creates the
     * window
     *
     * @return FirstGtk
     */
    public function __construct() {
        /*
         * Call the parent constructor
         */
        parent::__construct();
        
        /*
         * Set the size of the new GTK Window
         * Set the Title
         * Connect the destroy/exit event to a function
         */
        $this->set_default_size(400,100);
        $this->set_title('CodeCall.net PHP-GTK GUI Tutorial');
        $this->connect_simple('destroy', array('gtk', 'main_quit'));
        
        /*
         * Create a virticle and horizontal box
         * container to hold our widgets
         */
        $table = new GtkTable(4,2);
        
        /*
         * Create Label
         */
        $lblHost   = new GtkLabel("Host:");
        
        /*
         * Create an entry for entering 
         * host to access
         */
        $txtEntry = new GtkEntry(); 
        
        /*
         * Create two buttons, one for starting
         * and another for stopping
         */
        $btnStart = new GtkButton('Start');
        $btnStop  = new GtkButton('Stop');
        
        /*
         * Connect our buttons
         */
         $btnStart->connect('clicked', array($this,'startButtonClick'));
         $btnStop->connect('clicked', array($this,'stopButtonClick'));
         
        
        
        /*
         * Attach widgets to the table
         */
        $table->attach($lblHost, 0, 1, 0, 1); // Column 1, Row 1
        $table->attach($txtEntry, 1, 4, 0, 1); // Comumn 2-4, Row 1
        $table->attach($btnStop, 2, 3, 1, 2); // Column 3, Row 2
        $table->attach($btnStart, 3, 4, 1, 2); // Column 4, Row 2
        
        /*
          * Add the table to the GTK Window
          */
        $this->add($table);



         /*
         * This will realize and show
         * all windows from child to parent.
         */
        $this->show_all();
    }
    
    /**
     * This is the method that is executed when 
     * the stop "button" on the GtkWindow is clicked.
     * 
     */
    public function stopButtonClick() {
            /*
             * Create a messagebox
             */
            $dialog = new GtkMessageDialog($this, Gtk::DIALOG_MODAL, Gtk::MESSAGE_QUESTION, Gtk::BUTTONS_YES_NO, "");
            $dialog->set_markup(
                "<span foreground='red'>Do you really want to stop?</span>"
            );
            
            /*
             * Display the message
             */
            $response = $dialog->run();
            echo $response;
            $dialog->destroy();
    }
    
    /**
     * This is the method that is executed when 
     * the start "button" on the GtkWindow is clicked.
     * 
     */
    public function startButtonClick() {
        // Place holder for now
    }
}

if (!@$GLOBALS['framework']) {
    new CodeCallGtk();
    Gtk::main();
}

Execute the program and click the stop button. You should see this message dialog:



Clicking the Start button currently does nothing.

Part 2 Conclusion
This was a very simple tutorial covering only signals in PHP-GTK. Signals are important because they allow you, the PHP-GTK programmer, to react to user events. Without them, event based GUIs such as this one would be useless.

<< Previous Part 1 | Continue to Part 3 >>
------

[BlaineSch]

Your making these too fast! lol I have not even gotten to the first one yet

[Jordan]

Part 3 probably will not come out until later next week so you have some time.

[chili5]

/**
* This is the method that is executed when
* the stop "button" on the GtkWindow is clicked.
*
*/
public function startButtonClick() {
// Place holder for now
}

Shouldn't that say when the "start" button is clicked? Either way it is very nice once again!

[Jordan]

Whoops. Yup. Thanks. Fixed!