Author: Mathieu H.

What is PHP/TK ?

PHP/TK is an native extension for the PHP programming language that implements language bindings for TCL/TK. It provides an object-oriented interface and greatly simplifies writing client-side cross-platform GUI applications.

The Tk extention functions currently only on Unix systems. To use it, you need to have Tk installed on your system.
Tk is very well documented, so we won't waste time here by delving too deeply into Tk itself, but instead concentrate on how to access Tk features from PHP. The binding we use is closest to the Perl binding, so you can use the documentation of PERL/TK to help you.
- Let us see some examples of use now.

Simple Tk Application

A simple Tk application in PHP could resemble this:

#!/usr/local/bin/php -q
<?php
dl('tk.so');

$root = new Tk();
$root->wmTitle('"Hello World"');

$label = new Label($root, '-text "Hello, world!"');
$label->pack('-side left', '-padx 15', '-pady 15');

Tk_MainLoop();
?>

Let's look at the code a little more closely. After loading in the tk extension module, we create a new instance of Tk class, this one created the principal frame.
Then we use the wmtitle() function of this class to allot a name to the window. This being made, we make a label widget as a child of the root frame, with the option -text which has as a value "Hello World".
To note that, it is imperative to delimit the character strings allotted to the options, by { } or " ".
In short, to finish, we use the pack() function on the widget "label", in order to place it in the window. The tk_mainloop() function generate the main GUI event loop, it is essential.

Widgets

Creating widgets is easy. Take the name of the widget as given in the Tk documentation.
You create an instance of a widget using new, just as you would any other object. If you don't specify a parent for a given widget, it will default to the root-level frame.
We also need to be able to get information back from our widgets while our program is running by setting up callbacks and sharing data.

Setting widget option

If you look at a Tk reference manual, you'll notice that options for widgets are usually listed with a hyphen as a command-line option might be. That functions in the same way with PHP/TK.

$button = new Button($parent_widget, '-text {Hello, World!}');
# or
$button = new Button();
$button->configure('-text', '{Hello, World!}');

$button->pack();

Return values

To the creation of a widget or the execution of a function on this one, a value is turned over.

$label = new Label('-text "hello"'); // return instance.
$label = new Label('-bad_option "hello"'); // return false, generate error and quit program.

$label->configure('-text', 'Goodbye'); // return an empty string.
$label->configure('-bad_option', 'goodbye'); // return false and generate error.

$text = $label->cget('-text'); // return "Goodbye"

As we can see it in this example:
- An error is returned when the creation of a widget failed. The program is then stopped.
- An error is returned when a function of the widget failed. The program continues its execution.
- An string is returned when the function succeeded. This string is empty if the function does not turn over anything.

Binding events

Our hands can produce events that we can capture. To react to these events, functions of callback are used.

$button = new Button($root, '-text "Click here!"');
$button->configure('-command '. Tk_Callback('function_name', '$button'));

Tk_MainLoop();

function function_name($param1) {
Tk_MessageBox('-message "'.$param1.' pressed"');
}

In this first example, we allot a function of callback to event of type "KeyPressed". We associate the tk_callback function to the option '-command' of the widget.
The second parameter of the function tk_callback is equivalent to the first parameter of the call procedure.

$button = new Button($root, '-text "..."');
$button->bind('<Enter>', Tk_Callback('function_name'));

Objects by parameter

The objects can be passed in parameter, several solutions are offered to you:

$gfx = new Image('-file gfx.gif');

$button = new Button($root, '-image '. $gfx->id);
# or
$button = new Button($root, '-image', $gfx);

In both cases, you will have a superb image in the button (:

Character strings

The character strings passed to the functions tk must be treated with greatest severity.
On the one hand, they must be delimited by the characters ", or { }. And also that the special characters are preceded by a backslash.

$text = new Text();
...

$string = "Test example";
$text->insert('end '. $string); // not valid

$string = '"Test example"';
$text->insert('end '. $string); // valid

$text->insert('end {Test example}'); // valid

$text->insert('end "Test [ ] $ { example"'); // not valid

$string = Tk_Addslashes("Test [ ] $ { example");
$text->insert('end '. $string); // valid
# --> $string = "\"Test \[ \] \$ \{ example\""

Conclusion

To help you, I advise you to juggle between the Tk manual ( http://www.tcl.tk/man/tcl8.5/TkCmd/contents.htm) and the list of the prototypes contained in the documentation page.