279. How to set up wizards using GtkAssistant - Part 2 - respond to forward button?

Problem

Suppose you have set up a wizard with GtkAssistant as outlined in Part 1.

For a wizard to be useful, we will usually need to perform some actions when the user moves from one page to another.

So fundamental to a GtkAssistant is to know when the user clicks the Forward button. In this example, when the user clicks the Forward button, we should get the contents of the two text entry fields and perform some actions as shown below.

How to set up wizards using GtkAssistant - Part 2 - respond to forward button?


Solution

  • The signal 'apply' allows you to know when the user clicks the 'Forward' button.
  • The method set_forward_page_func() also allows you to decide which page to jump to when the user clicks the Forward button. For example, if the user chooses the "Express" setup, you can jump from Step 2 direct to Step 6. If you do not specify this method, the default action is to move to the next page when the user clicks the Forward button.

Important Note: This only works for PHP-GTK2 compliled with gtk+ v2.10 and above. If you are using an older version, for linux, you may follow the step-by-step instructions to recompile php-gtk2 with gtk+ v2.10. For windows, please refer to How to install php gtk2 on windows? You may also want to take a look here to see some of the new exciting PHP-GTK2 Functionalities.


Sample Code

1   
2   
3   
4   
5   
6   
7   
8   
9   
10   
11   
12   
13   
14   
15   
16   
17   
18   
19   
20   
21   
22   
23   
24   
25   
26   
27   
28   
29   
30   
31   
32   
33   
34   
35   
36   
37   
38   
39   
40   
41   
42   
43   
44   
45   
46   
47   
49   
50   
53   
54   
55   
56   
57   
58   
59   
60   
61   
66   
67   
68   
69   
70   
71   
72   
73   
74   
75   
76   
77   
78   
79   
80   
81   
82   
83   
84   
85   
86   
87   
88   
89   
90   
<?php
// setup button
$assistant = new GtkAssistant();
$assistant->set_title($argv[0]);
$assistant->set_size_request(400,300);
$assistant->connect_simple('delete_event', array('Gtk', 'main_quit'));

//intro
$vbox = new GtkVBox();
$assistant->append_page($vbox);
$assistant->set_page_title($vbox, 'Create New Account');
$assistant->set_page_type($vbox, Gtk::ASSISTANT_PAGE_INTRO);
$vbox->pack_start(new GtkLabel(
"This wizard will help you create a new account.\n\n".
"Creating a new account is just a two-step process.\n\n".
"Click the Forward button to start getting a free email account."));
$assistant->set_page_complete($assistant->get_nth_page(0), true);
$vbox->show_all();

//Step 1
$vbox = new GtkVBox();
$assistant->append_page($vbox);
$assistant->set_page_title($vbox, 'Step 1 of 2');
$assistant->set_page_type($vbox, Gtk::ASSISTANT_PAGE_PROGRESS);
$vbox->pack_start(new GtkLabel('Please enter your name and email, \n".
"and click Forward'), 0);
$vbox->pack_start(setup_textentry('Name: '), 0);
$vbox->pack_start(setup_textentry('Email: '), 0);
$assistant->set_page_complete($assistant->get_nth_page(1), true);
$vbox->show_all();

//Step 2
$vbox = new GtkVBox();
$assistant->append_page($vbox);
$assistant->set_page_title($vbox, 'Step 2 of 2');
$assistant->set_page_type($vbox, Gtk::ASSISTANT_PAGE_PROGRESS);
$vbox->pack_start(new GtkLabel("This is Step 2."));
$assistant->set_page_complete($assistant->get_nth_page(2), true);
$vbox->show_all();

//Done
$vbox = new GtkVBox();
$vbox->pack_start(new GtkLabel(
'Congratulations! Your new account has been successfully created.'));
$assistant->append_page($vbox);
$assistant->set_page_title($vbox, 'Done');
$assistant->set_page_type($vbox, Gtk::ASSISTANT_PAGE_SUMMARY);
$vbox->show_all();

$assistant->connect('apply', 'on_apply'); // note 1
//$assistant->set_forward_page_func('page_func'); // note 3


$assistant->connect('close', 'on_close');

$assistant->show_all();
Gtk::main();

function on_close() {
    echo "You have clicked the close button\n";
    Gtk::main_quit();
}

function apply($assistant) {
    $current_page = $assistant->get_current_page(); // note 2
    echo "You are now on page $current_page!\n";
}

function page_func($assistant) {
    $current_page = $assistant->get_current_page();
    return $current_page+1;
}

function setup_textentry($label) {
    $hbox = new GtkHBox();
    $hbox->pack_start(new GtkLabel($label), 0);
    $entry = new GtkEntry();
    $hbox->pack_start($entry, 0);
    return $hbox;
}

?>

Output

As shown above.
 

Explanation

  1. Register the 'apply' signal.
  2. The signal handler for the 'apply' signal. Here you can perform the actions based on which page the user is on now.
  3. Set up your user-defined forward function.

Note

If you've tried the sample code above, you will find that the signal 'apply' doesn't work yet in the beta release of php-gtk2. Have tried it on both windows and linux. Both just do not respond to the Forward button.

Fundamental to a GtkAssistant is to be able to know when the user clicks the Forward button. In the example above, when the user clicks the Forward button, we should get the contents of the two text entry fields and perform some action. Without the 'apply' signal, there's no way you can get hold of the contents of the two GtkEntry!

Another important method that is missing from this beta release of php-gtk2 is the set_forward_page_func(). This method allows you to set your own self-defined handler that will be called when the usr clicks the Forward button. For example, if your wizard allows users to choose between Express, Complete and Custom setup. If the user chooses Express setup, you can jump from Page 2 direct to Page 6. Currently, this method is missing in the beta release of php-gtk2 - both windows and linux.

Without the 'apply' signal and the method set_forward_page_func(), it's really difficult to come out with anything useful using GtkAssistant.

Hopefully the PHP-GTK2 development team will add these soon.

In the meantime, you could still achieve the same functionalities provided by GtkAssistant using plain old GtkDialog as outlined in How to set up wizards using GtkDialog - Part 1?.

Related Links

Add comment


Security code
Refresh