.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Tkx 3pm"
.TH Tkx 3pm "2010-11-24" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Tkx \- Yet another Tk interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\& use Tkx;
\& my $mw = Tkx::widget\->new(".");
\& $mw\->new_button(
\& \-text => "Hello, world",
\& \-command => sub { $mw\->g_destroy; },
\& )\->g_pack;
\& Tkx::MainLoop();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Tkx\*(C'\fR module provides yet another Tk interface for Perl. Tk is a
\&\s-1GUI\s0 toolkit tied to the Tcl language, and \f(CW\*(C`Tkx\*(C'\fR provides a bridge to
Tcl that allows Tk based applications to be written in Perl.
.PP
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.
.PP
This is the \*(L"reference manual\*(R" for Tkx. For a gentle introduction please
read the Tkx::Tutorial. The tutorial at
is also strongly recommended.
.SS "Functions"
.IX Subsection "Functions"
The following functions are provided:
.ie n .IP "Tkx::AUTOLOAD( @args )" 4
.el .IP "Tkx::AUTOLOAD( \f(CW@args\fR )" 4
.IX Item "Tkx::AUTOLOAD( @args )"
All calls into the \f(CW\*(C`Tkx::\*(C'\fR namespace not explicitly listed here are trapped
by Perl's \s-1AUTOLOAD\s0 mechanism and turned into a call of the corresponding Tcl or
Tk command. The Tcl string result is returned as a single value in both scalar
and list context. Tcl errors are propagated as Perl exceptions.
.Sp
For example:
.Sp
.Vb 1
\& $res = Tkx::expr("3 + 3")
.Ve
.Sp
This will call the Tcl command \f(CW\*(C`expr\*(C'\fR passing it the argument \f(CW"3 + 3"\fR and
return the result back to Perl. The value of \f(CW$res\fR after this call should be \f(CW6\fR.
.Sp
The exact rules for mapping functions names into the Tcl name space and the
details of passing arguments to Tcl is described in \*(L"Calling Tcl and Tk
Commands\*(R" below.
.Sp
Don't call \fITkx::AUTOLOAD()\fR directly yourself.
.Sp
The available Tcl commands are documented at
. The available Tk commands are
documented at .
.ie n .IP "Tkx::Ev( $field, ... )" 4
.el .IP "Tkx::Ev( \f(CW$field\fR, ... )" 4
.IX Item "Tkx::Ev( $field, ... )"
This creates an object that if set up as the first argument to a callback will
expand the corresponding Tcl template substitutions in the context of that
callback. \*(L"Callbacks to Perl\*(R" below explain how callback
arguments are provided.
.Sp
The \f(CW$field\fR should be a string like \*(L"%A\*(R" or \*(L"%x\*(R". The available
substitutions are described in the Tcl documentation for the \f(CW\*(C`bind\*(C'\fR
command; see .
.IP "Tkx::MainLoop( )" 4
.IX Item "Tkx::MainLoop( )"
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.
.ie n .IP "Tkx::SplitList( $list )" 4
.el .IP "Tkx::SplitList( \f(CW$list\fR )" 4
.IX Item "Tkx::SplitList( $list )"
This will split up a Tcl list into a Perl list. The individual elements of the
list are returned as separate elements. This function will croak if the
argument is not a well formed list or if called in scalar context.
.Sp
Example:
.Sp
.Vb 2
\& my @list = Tkx::SplitList("a {b c}");
\& # @list is now ("a", "b c")
.Ve
.Sp
This function is needed because direct calls Tcl don't expand lists even if
called in list context, so if you want to process the elements returned
as a Tcl list you need to wrap the call in a call to SplitList:
.Sp
.Vb 3
\& for my $file (Tkx::SplitList(Tkx::glob(\*(Aq*.pm\*(Aq))) {
\& # ...
\& }
.Ve
.Sp
Since Perl also have a built in glob function there is no need to actually
let Tcl do the globbing for you. The example above is purely educational.
.Sp
The \fITkx::list()\fR function would invoke the Tcl command that does the reverse
operation \*(-- creating a list from the arguments passed in. You seldom need to
call \fITkx::list()\fR explicitly as arrays are automatically converted to Tcl lists
when passed as arguments to Tcl commands.
.PP
All these functions, even the autoloaded ones, can be exported by Tkx if you
grow tired of typing the \f(CW\*(C`Tkx::\*(C'\fR prefix. Example:
.PP
.Vb 2
\& use strict;
\& use Tkx qw(MainLoop button pack destroy);
\&
\& pack(button(".b", \-text => "Press me!", \-command => [\e&destroy, "."]));
\& MainLoop;
.Ve
.PP
No functions are exported by default.
.SS "Calling Tcl and Tk Commands"
.IX Subsection "Calling Tcl and Tk Commands"
Tcl and Tk commands are easily invoked by calling the corresponding function
in the Tkx:: namespace. Calling the function \f(CW\*(C`Tkx::expr()\*(C'\fR will invoke the
\&\f(CW\*(C`expr\*(C'\fR command on the Tcl side. Function names containing underlines are a bit
special. The name passed from the Perl side undergo the following
substitutions:
.PP
.Vb 3
\& foo_bar \-\-> "foo", "bar" # break into words
\& foo_\|_bar \-\-> "foo::bar" # access Tcl namespaces
\& foo_\|_\|_bar \-\-> "foo_bar" # when you actually need a \*(Aq_\*(Aq
.Ve
.PP
This allow us conveniently to map the Tcl namespace to Perl. If this mapping
does not suit you, an alternative is to use \f(CW\*(C`Tkx::i::call($cmd, @args)\*(C'\fR.
This will invoke the command named by \f(CW$cmd\fR with no name substitutions or magic.
.PP
Examples:
.PP
.Vb 5
\& 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") { ... }
.Ve
.PP
One part of the Tcl namespace that is not conveniently mapped to Perl
using the rules above are commands that use \*(L".\*(R" as part of their name, mostly Tk
widget instances. If you insist you can invoke these by quoting the
Perl function name
.PP
.Vb 1
\& &{"Tkx::._configure"}(\-background => "black");
.Ve
.PP
or by invoking this as \f(CW\*(C`Tkx::i::call(".", "configure", "\-background",
"black")\*(C'\fR; but the real solution is to use \f(CW\*(C`Tkx::widget\*(C'\fR objects to wrap
these as described in \*(L"Widget handles\*(R" below.
.PP
\fIPassing arguments\fR
.IX Subsection "Passing arguments"
.PP
The arguments passed to Tcl can be plain scalars, array references, code
references, scalar references, or hash references.
.PP
Plain scalars (strings and numbers) as just passed on unchanged to Tcl.
.PP
Array references, where the first element is not a code reference, are converted into Tcl
lists and passed on. The arrays can contain strings, numbers, and/or array
references to form nested lists.
.PP
Code references, and arrays where the first element is a code reference, are
converted into special Tcl command names in the \*(L"::perl\*(R" Tcl namespace that
will call back into the corresponding Perl function when invoked from Tcl. See
\&\*(L"Callbacks to Perl\*(R" for a description how how this is used.
.PP
Scalar references are converted into special Tcl variables in the \*(L"::perl\*(R" Tcl
namespace that is tied to the corresponding variable on the Perl side.
Any changes to the variable on the Perl side will be reflected in the value
on the Tcl side. Any changes to the variable on the Tcl side will be reflected
in the value on the Perl side.
.PP
Hash references are converted into special Tcl array variables in the \*(L"::perl\*(R" Tcl
namespace that is tied to the corresponding hash on the Perl side. Any changes to
the hash on the Perl side will be reflected in the array on the Tcl side. Any
changes to the array on the Tcl side will be reflected in the hash on the Perl side.
.PP
Anything else will just be converted to strings using the Perl rules for
stringification and passed on to Tcl.
.PP
\fITracing\fR
.IX Subsection "Tracing"
.PP
If the boolean variable \f(CW$Tkx::TRACE\fR is set to a true value, then a
trace of all commands passed to Tcl will be printed on \s-1STDERR. \s0 This
variable is initialized from the \f(CW\*(C`PERL_TKX_TRACE\*(C'\fR environment
variable. The trace is useful for debugging and if you need to report
errors to the Tcl/Tk maintainers in terms of Tcl statements. The trace
lines are prefixed with:
.PP
.Vb 1
\& Tkx\-$seq\-$ts\-$file\-$line:
.Ve
.PP
where \f(CW$seq\fR is a sequence number, \f(CW$ts\fR is a timestamp in seconds since
the first command was issued, and \f(CW$file\fR and \f(CW$line\fR indicate on which
source line this call was triggered.
.SS "Callbacks to Perl"
.IX Subsection "Callbacks to Perl"
For Tcl APIs that require callbacks you can provide a reference to a
Perl subroutine:
.PP
.Vb 1
\& Tkx::after(3000, sub { print "Hi" });
\&
\& $button = $w\->new_button(
\& \-text => \*(AqPress Me\*(Aq,
\& \-command => \e&foo,
\& );
.Ve
.PP
Alternately, you can provide an array reference containing a subroutine
reference and a list of values to be passed back to the subroutine as
arguments when it is invoked:
.PP
.Vb 1
\& Tkx::button(".b", \-command => [\e&Tkx::destroy, "."]);
\&
\& $button = $w\->new_button(
\& \-text => \*(AqPress Me\*(Aq,
\& \-command => [\e&foo, 42],
\& );
.Ve
.PP
When using the array reference syntax, if the \fIsecond\fR element of the
array (i.e. the first argument to the callback) is a \fITkx::Ev()\fR object
the templates it contains will be expanded at the time of the callback.
.PP
.Vb 3
\& Tkx::bind(".", "", [
\& sub { print "$_[0]\en"; }, Tkx::Ev("%A")
\& ]);
\&
\& $entry\->configure(\-validatecommand => [
\& \e&check, Tkx::Ev(\*(Aq%P\*(Aq), $entry,
\& ]);
.Ve
.PP
The order of the arguments to the Perl callback code is as follows:
.IP "1." 4
The expanded results from \fITkx::Ev()\fR, if used.
.IP "2." 4
Any arguments that the command/function is called with from the Tcl
side. For example, in callbacks to scrollbars Tcl provides values
corresponding to the visible portion of a scrollable widget. Tcl
arguments are passed regardless of the syntax used when specifying the
callback.
.IP "3." 4
Any extra values provided when the callback defined; the values passed after
the \fITkx::Ev()\fR object in the array.
.SS "Widget handles"
.IX Subsection "Widget handles"
The class \f(CW\*(C`Tkx::widget\*(C'\fR is used to wrap Tk widget paths.
These objects stringify as the path they wrap.
.PP
The following methods are provided:
.ie n .IP "$w = Tkx::widget\->new( $path )" 4
.el .IP "\f(CW$w\fR = Tkx::widget\->new( \f(CW$path\fR )" 4
.IX Item "$w = Tkx::widget->new( $path )"
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 do not yet exist.
.ie n .IP "$w\->_data" 4
.el .IP "\f(CW$w\fR\->_data" 4
.IX Item "$w->_data"
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 \fI_data()\fR method.
.Sp
The data hash is automatically destroyed when the corresponding widget
is destroyed.
.ie n .IP "$w\->_parent" 4
.el .IP "\f(CW$w\fR\->_parent" 4
.IX Item "$w->_parent"
Returns a handle for the parent widget. Returns \f(CW\*(C`undef\*(C'\fR if there is
no parent, which will only happen if \f(CW$w\fR is \*(L".\*(R", the main window.
.ie n .IP "$w\->_kid( $name )" 4
.el .IP "\f(CW$w\fR\->_kid( \f(CW$name\fR )" 4
.IX Item "$w->_kid( $name )"
Returns a handle for a kid widget with the given name. The \f(CW$name\fR 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.
.ie n .IP "$w\->_kids" 4
.el .IP "\f(CW$w\fR\->_kids" 4
.IX Item "$w->_kids"
Returns all existing kids as widget objects.
.ie n .IP "$w\->_class( $class )" 4
.el .IP "\f(CW$w\fR\->_class( \f(CW$class\fR )" 4
.IX Item "$w->_class( $class )"
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 \f(CW\*(C`Tkx::widget\*(C'\fR. Overriding the class for a
path is useful for implementing megawidgets. Kids of \f(CW$w\fR are not
affected by this, unless the class overrides the \f(CW\*(C`_nclass\*(C'\fR method.
.ie n .IP "$w\->_nclass" 4
.el .IP "\f(CW$w\fR\->_nclass" 4
.IX Item "$w->_nclass"
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 \f(CW\*(C`Tkx::widget\*(C'\fR.
.ie n .IP "$w\->_mpath( $method )" 4
.el .IP "\f(CW$w\fR\->_mpath( \f(CW$method\fR )" 4
.IX Item "$w->_mpath( $method )"
This method determine the Tk widget path that will be invoked for
m_\fIfoo\fR method calls. The argument passed in is the method name
without the \f(CW\*(C`m_\*(C'\fR prefix. Megawidget classes might want to override
this method. The default implementation always returns \f(CW$w\fR.
.ie n .IP "$new_w = $w\->new_\fIfoo\fR( @args )" 4
.el .IP "\f(CW$new_w\fR = \f(CW$w\fR\->new_\fIfoo\fR( \f(CW@args\fR )" 4
.IX Item "$new_w = $w->new_foo( @args )"
This creates a new \fIfoo\fR widget as a child of the current widget. It
will call the \fIfoo\fR 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 \fIfoo\fR is expanded as described in
\&\*(L"Calling Tcl and Tk Commands\*(R" above.
.Sp
Example:
.Sp
.Vb 1
\& $w\->new_label(\-text => "Hello", \-relief => "sunken");
.Ve
.Sp
The name selected for the child will be the first letter of the widget type;
for the example above \*(L"l\*(R". If that name is not unique a number is
appended to ensure uniqueness among the children. If a \f(CW\*(C`\-name\*(C'\fR argument is
passed it is used as the name and then removed from the arglist passed on to
Tcl. Example:
.Sp
.Vb 1
\& $w\->new_iwidgets_\|_calendar(\-name => "cal");
.Ve
.Sp
If a megawidget implementation class has be registered for \fIfoo\fR,
then its \f(CW\*(C`_Populate\*(C'\fR method is called instead of passing widget
creation to Tcl.
.ie n .IP "$w\->m_\fIfoo\fR( @args )" 4
.el .IP "\f(CW$w\fR\->m_\fIfoo\fR( \f(CW@args\fR )" 4
.IX Item "$w->m_foo( @args )"
This will invoke the \fIfoo\fR subcommand for the current widget. This
is the same as:
.Sp
.Vb 2
\& $func = "Tkx::$w";
\& &$func(expand("foo"), @args);
.Ve
.Sp
where the \fIexpand()\fR function expands underscores as described in
\&\*(L"Calling Tcl and Tk Commands\*(R" above.
.Sp
Example:
.Sp
.Vb 1
\& $w\->m_configure(\-background => "red");
.Ve
.Sp
Subclasses might override the \fI_mpath()\fR method to have m_\fIfoo\fR forward
the subcommand somewhere else than the current widget.
.ie n .IP "$w\->g_\fIfoo\fR( @args )" 4
.el .IP "\f(CW$w\fR\->g_\fIfoo\fR( \f(CW@args\fR )" 4
.IX Item "$w->g_foo( @args )"
This will invoke the \fIfoo\fR Tcl command with the current widget as
first argument. This is the same as:
.Sp
.Vb 2
\& $func = "Tkx::foo";
\& &$func($w, @args);
.Ve
.Sp
Any underscores in the name \fIfoo\fR are expanded as described in
\&\*(L"Calling Tcl and Tk Commands\*(R" above.
.Sp
Example:
.Sp
.Vb 1
\& $w\->g_pack_forget;
.Ve
.ie n .IP "$w\->\fIfoo\fR( @args )" 4
.el .IP "\f(CW$w\fR\->\fIfoo\fR( \f(CW@args\fR )" 4
.IX Item "$w->foo( @args )"
If the method does not start with \*(L"new_\*(R" or have a prefix of the form
/^_/ or /^[a\-zA\-Z]_/, the call will just forward to the method "m_\fIfoo\fR\*(L"
(described above). This is just a convenience for people that have
grown tired of the \*(R"m_" prefix.
.Sp
The method names with prefix /^_/ and /^[a\-zA\-Z]_/ are reserved for
future extensions to this \s-1API.\s0
.ie n .IP "Tkx::widget\->_Mega( $widget, $class )" 4
.el .IP "Tkx::widget\->_Mega( \f(CW$widget\fR, \f(CW$class\fR )" 4
.IX Item "Tkx::widget->_Mega( $widget, $class )"
This register \f(CW$class\fR as the one implementing \f(CW$widget\fR widgets. See
\&\*(L"Megawidgets\*(R".
.SS "Subclassing Tk widgets"
.IX Subsection "Subclassing Tk widgets"
You can't subclass a Tk widget in Perl, but you can emulate it by
creating a megawidget.
.SS "Megawidgets"
.IX Subsection "Megawidgets"
Megawidgets can be implemented in Perl and used by Tkx. To declare a
megawidget make a Perl class like this one:
.PP
.Vb 3
\& package Foo;
\& use base \*(AqTkx::widget\*(Aq;
\& Foo\->_Mega("foo");
\&
\& sub _Populate {
\& my($class, $widget, $path, %opt) = @_;
\& ...
\& }
.Ve
.PP
The megawidget class should inherit from \f(CW\*(C`Tkx::widget\*(C'\fR and will
register itself by calling the \fI_Mega()\fR class method. In the example
above we tell Tkx that any \*(L"foo\*(R" widgets should be handled by the Perl
class \*(L"Foo\*(R" instead of Tcl. When a new \*(L"foo\*(R" widget is instantiated
with:
.PP
.Vb 1
\& $w\->new_foo(\-text => "Hi", \-foo => 1);
.Ve
.PP
then the \fI_Populate()\fR class method of \f(CW\*(C`Foo\*(C'\fR 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.
.PP
The \fI_Populate()\fR class should create a root object with the given \f(CW$path\fR
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 \fI_class()\fR method to
set the class \fI_Populate()\fR can ensure that new handles to this megawidget
also use this class.
.PP
To make Tk aware of your megawidget you must register it by providing a
\&\f(CW\*(C`\-class\*(C'\fR argument when creating the root widget. Doing this sets the
value returned by the \f(CW\*(C`$w\->g_winfo_class\*(C'\fR method. It also makes it
possible for your megawidget to have to have class-specific bindings and
be configurable via Xdefaults and the options database. By convention
class names start with a capital letter, so Tkx megawidgets should have
names like \*(L"Tkx_Foo\*(R". If you don't register your megawidget with Tk,
\&\f(CW\*(C`g_winfo_class\*(C'\fR will return the class of whatever you use as a root
widget and your megawidget will be subject to the bindings for that
class.
.PP
Of the standard Tk widgets only frames support \f(CW\*(C`\-class\*(C'\fR which means
that (practically speaking) Tkx megawidgets must use a frame as the root
widget. The ttk widgets do support \f(CW\*(C`\-class\*(C'\fR, so you may be able to
dispense with the frame if your megawidget is really just subclassing
one of them.
.PP
The implementation class can (and probably should) define an \fI_mpath()\fR
method to delegate any m_\fIfoo\fR method calls to one of its subwidgets.
It might want to override the \fIm_configure()\fR and \fIm_cget()\fR methods if it
implements additional options or wants more control over delegation. The
class \f(CW\*(C`Tkx::MegaConfig\*(C'\fR provide implementations of \fIm_configure()\fR and
\&\fIm_cget()\fR that can be useful for controlling delegation of configuration
options.
.PP
Public methods defined by a megawidget should have an \*(L"m_\*(R" prefix. This
serves two purposes:
.IP "\(bu" 4
It makes them behave the same as native widget methods. That is, they
may be called either with or without the \*(L"m_\*(R" prefix as the user of the
widget prefers.
.IP "\(bu" 4
It enables the megawidget to accept method delegation from another
widget via the parent widget's \fI_mpath()\fR method.
.PP
See Tkx::LabEntry for a trivial example megawidget.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
The \f(CW\*(C`PERL_TKX_TRACE\*(C'\fR environment variable initialize the \f(CW$Tkx::TRACE\fR setting.
.PP
The \f(CW\*(C`PERL_TCL_DL_PATH\*(C'\fR environment variable can be set to override
the Tcl/Tk used.
.SH "SUPPORT"
.IX Header "SUPPORT"
If you have questions about this code or want to report bugs send a
message to the mailing list. To subscribe to this
list send an empty message to .
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.PP
Copyright 2005 ActiveState. All rights reserved.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Tkx::Tutorial, Tkx::MegaConfig, Tcl
.PP
At you find a very nice Tk tutorial that
uses Tkx for the Perl examples.
.PP
More information about Tcl/Tk can be found at .
Tk documentation is also available at .
.PP
The official source repository for Tkx is .
.PP
Alternative Tk bindings for Perl are described in Tcl::Tk and Tk.
.PP
ActivePerl bundles a Tcl interpreter and a selection of Tk widgets from
ActiveTcl in order to provide a functional Tkx module out-of-box.
Tcl::tkkit documents the version of Tcl/Tk you get and whats available in
addition to the core commands. You need to set the \f(CW\*(C`PERL_TCL_DL_PATH\*(C'\fR
environment variable to make Tkx reference other Tcl installations.