Tkx - Yet another Tk interface
use Tkx; my $mw = Tkx::widget->new("."); $mw->new_button( -text => "Hello, world", -command => sub { $mw->g_destroy; }, )->g_pack; Tkx::MainLoop();
The Tkx
module provides yet another Tk interface for Perl. Tk is a
GUI toolkit tied to the Tcl language, and Tkx
provides a bridge to
Tcl that allows Tk based applications to be written in Perl.
The main idea behind Tkx is that it is a very thin wrapper on top of Tcl, i.e. that what you get is exactly the behaviour you read about in the Tcl/Tk documentation with no surprises added by the Perl layer.
This is the "reference manual" for Tkx. For a gentle introduction please read the the Tkx::Tutorial manpage. The tutorial at http://www.tkdocs.com/tutorial/ is also strongly recommened.
The following functions are provided:
This will enter the Tk mainloop and start processing events. The function returns when the main window has been destroyed. There is no return value.
This creates an object that if passed as the first argument to a callback will expand the corresponding Tcl template substitutions in the context of that callback. The description of Tkx::foo below explain how callback arguments are provided.
The $field should be a string like "%A" or "%x". The available
substitutions are described in the Tcl documentation for the bind
command.
This will split up a Tcl list into Perl list. The individual elements of the list are returned as separate elements:
@a = Tkx::SplitList(Tkx::set("a"));
This function will croak if the argument is not a well formed list or if called in scalar context.
Any other function will invoke the foo Tcl function with the given arguments. The name foo first undergo the following substitutions of embedded underlines:
foo_bar --> "foo", "bar" # break into words foo__bar --> "foo::bar" # access namespaces foo___bar --> "foo_bar" # when you actually need a '_'
This allow us conveniently to map the Tcl namespace to Perl.
If this mapping does not suit you, use Tkx::i::call($func, @args)
. This will invoke the function named by $func with no name
substitutions or magic.
Examples:
Tkx::expr("3 + 3"); Tkx::package_require("BWidget"); Tkx::DynamicHelp__add(".", -text => "Hi there"); if (Tkx::tk_windowingsystem() eq "x11") { ... } if (Tkx::tk___messageBox( ... ) eq "yes") { ... }
One part of the Tcl namespace that is not conveniently mapped to Perl in this way are commands that use "." as part of their name, mostly Tk widget instances. If you insist you can invoke these by quoting the Perl function name
&{"Tkx::._configure"}(-background => "black");
but the real solution is to use Tkx::widget
to wrap these as
described below.
The arguments passed can be plain scalars, array references, code references, or scalar references.
Array references are converted to Tcl lists. The arrays can contain other plain scalars or array references to form nested lists.
For Tcl APIs that require callbacks you can pass a reference to a Perl function. Alternatively an array reference with a code reference as the first element, will allow the callback to receive the rest of the elements as arguments when invoked. If the second element of the array is an Tkx::Ev() object, then the templates it contain will be expanded at the time of the calllback. Some callback examples:
Tkx::after(3000, sub { print "Hi" }); Tkx::button(".b", -command [\&Tkx::destroy, "."]); Tkx::bind(".", "<Key>", [sub { print "$_[0]\n"; }, Tkx::Ev("%A")]); Tkx::bind(".", "<Button-1>", [ sub { my($x, $y) = @_; print "Clicked at $x $y\n"; }, Tkx::Ev("%x", "%y"), ]);
For Tcl APIs that require variables to be passed, you might pass a reference to a Perl scalar. The scalar will be watched and updated in the same way as the Tcl variable would.
The Tcl string result is returned in both scalar and array context. Tcl errors are propagated as Perl exceptions.
If the boolean variable $Tkx::TRACE is set to a true value, then a
trace of all commands passed to Tcl will be printed on STDERR. This
variable is initialized from the PERL_TKX_TRACE
environment
variable. The trace is useful for debugging and if you need to report
errors to the Tcl maintainers in terms of Tcl statements. The trace
lines are prefixed with:
Tkx-$seq-$ts-$file-$line:
where $seq is a sequence number, $ts is a timestamp in seconds since the first command was issued, and $file and $line indicate on which source line this call was triggered.
All these functions can be exported by Tkx if you grow tired of typing
the Tkx::
prefix. Example:
use strict; use Tkx qw(MainLoop button pack destroy);
pack(button(".b", -text => "Press me!", -command => [\&destroy, "."])); MainLoop;
No functions are exported by default.
The class Tkx::widget
is used to wrap Tk widget paths.
These objects stringify as the path they wrap.
The following methods are provided:
This register $class as the one implementing $widget widgets. See Megawidgets.
This constructs a new widget handle for a given path. It is not a problem to have multiple handle objects to the same path or to create handles for paths that does not exist yet.
Returns a hash that can be used to keep instance specific data. This
is useful for holding instance data for megawidgets. The data is
attached to the underlying widget, so if you create another handle to
the same widget it will return the same hash via its _data()
method.
The data hash is automatically destroyed when the corresponding widget is destroyed.
Returns a handle for the parent widget. Returns undef
if there is
no parent, which will only happen if $w is ".", the main window.
Returns a handle for a kid widget with the given name. The $name can contain dots to access grandkids. There is no check that a kid with the given name actually exists; which can be taken advantage of to construct names of Tk widgets to be created later.
Returns all existing kids as widget objects.
Sets the widget handle class for the current path. This will both
change the class of the current handle and make sure later handles
created for the path belong to the given class. The class should
normally be a subclass of Tkx::widget
. Overriding the class for a
path is useful for implementing megawidgets. Kids of $w are not
affected by this, unless the class overrides the _nclass
method.
This returns the default widget handle class that will be used for
kids and parent. Subclasses might want to override this method.
The default implementation always returns Tkx::widget
.
This method determine the Tk widget path that will be invoked for
m_foo method calls. The argument passed in is the method name
without the m_
prefix. Megawidget classes might want to override
this method. The default implementation always returns $w
.
This creates a new foo widget as a child of the current widget. It will call the foo Tcl command and pass it a new unique subpath of the current path. The handle to the new widget is returned. Any double underscores in the name foo is expanded as described for Tkx::foo() above.
Example:
$w->new_label(-text => "Hello", -relief => "sunken");
The name selected for the child will be the first letter in the
widget. If that name is not unique a number is appended to ensure
uniqueness among the children. If a -name
argument is passed it is
used to form the name and then removed from the arglist passed to Tcl.
Example:
$w->new_iwidgets__calendar(-name => "cal");
If a megawidget implementation class has be registered for foo,
then its _Populate
method is called instead of passing widget
creation to Tcl.
This will invoke the foo subcommand for the current widget. This is the same as:
$func = "Tkx::$w"; &$func(expand("foo"), @args);
where the expand()
function expands underscores as described for
Tkx::foo() above.
Example:
$w->m_configure(-background => "red");
Subclasses might override the _mpath()
method to have m_foo forward
the subcommand somewhere else than the current widget.
This will invoke the foo Tcl command with the current widget as first argument. This is the same as:
$func = "Tkx::foo"; &$func($w, @args);
Any underscores in the name foo are expanded as described for Tkx::foo() above.
Example:
$w->g_pack_forget;
If the method does not start with "new_" or have a prefix of the form /^_/ or /^[a-zA-Z]_/, will just forward to the method "m_foo" (described above). This is just a convenience for people that have grown tired of the "m_" prefix.
The method names with prefix /^_/ and /^[a-zA-Z]_/ are reserved for future extensions to this API.
Megawidgets can be implemented in Perl and used by Tkx. To declare a megawidget make a Perl class like this one:
package Foo; use base 'Tkx::widget'; Foo->_Mega("foo");
sub _Populate { my($class, $widget, $path, %opt) = @_; ... }
The megawidget class should inherit from Tkx::widget
and will
register itself by calling the _Mega()
class method. In the example
above we tell Tkx that any "foo" widgets should be handled by the Perl
class "Foo" instead of Tcl. When a new "foo" widget is instantiated
with:
$w->new_foo(-text => "Hi", -foo => 1);
then the _Populate()
class method of Foo
is called. It will be
passed the widget type to create, the full path to use as widget
name and any options passed in. The widget name is passed in so that a
single Perl class can implement multiple widget types.
The _Populate()
class should create a root object with the given $path
as name and populate it with the internal widgets. Normally the root
object will be forced to belong to the implementation class so that it
can trap various method calls on it. By using the _class()
method to
set class _Populate()
can ensure that new handles to this megawidget
also use this class.
The implementation class can define an _mpath()
method to delegate any
m_foo method calls to one of its subwidgets and it might want to
override the m_configure()
and m_cget()
methods if it implements
additional options or want more control over delegation. The class
Tkx::MegaConfig
provide implementations of m_configure()
and
m_cget()
that can be useful for controlling delegation of
configuration options.
See the Tkx::LabEntry manpage for a trivial example megawidget.
The PERL_TKX_TRACE
environment variable initialize the $Tkx::TRACE setting.
The PERL_TCL_DL_PATH
environment variable can be set to override
the Tcl/Tk used.
If you have questions about this code or want to report bugs send a message to the <tcltk@perl.org> mailing list. To subscribe to this list send an empty message to <tcltk-subscribe@perl.org>.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Copyright 2005 ActiveState. All rights reserved.
the Tkx::Tutorial manpage, the Tkx::MegaConfig manpage, the Tcl manpage
At http://www.tkdocs.com/tutorial/ you find a very nice Tk tutorial that uses Tkx for the Perl examples.
More information about Tcl/Tk can be found at http://www.tcl.tk/. Tk documentation is also available at http://aspn.activestate.com/ASPN/docs/ActiveTcl/at.pkg_index.html.
The official source repository for Tkx is http://github.com/gisle/tkx/.
Alternative Tk bindings for Perl are described in the Tcl::Tk manpage and Tk.
ActivePerl bundles a Tcl interpreter and a selection of Tk widgets
from ActiveTcl in order to provide a functional Tkx module out-of-box.
If you are using ActivePerl see the Tcl::tkkit manpage to figure out what
version of Tcl/Tk you get and the selection of extra widget packages.
You need to set the PERL_TCL_DL_PATH
environment variable to make
Tkx reference other Tcl installations.