Perl/Tk FAQ

The Perl/Tk extension to the Perl programming language is copyrighted by its author Nick Ing-Simmons <nik@tiuk.ti.com> whose COPYING file reads as follows:

Copyright (c) 1995-1996 Nick Ing-Simmons. All rights reserved.
This package is free software; you can redistribute it and/or
modify it under the same terms as Perl itself, with the exception
of the files in the pTk sub-directory which have separate terms
derived from those of the orignal Tk4.0 sources and/or Tix.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS.

See pTk/license.terms for details of this Tk license, 
and pTk/Tix.license for the Tix license.

This compilation of Frequently Asked Questions & answers (FAQ) is intended to answer several of the first (and largely more basic) questions posted to the comp.lang.perl.tk newsgroup and the ptk mailing list.

This document concerns itself with the Perl/Tk programming language (or, if you prefer, the Tk extension to Perl). Please be aware that this is not the Perl FAQ, this is not the Tcl FAQ, nor is this the Tcl/Tk FAQ. Each of those other documents is a useful source of information for Perl/Tk programmers but they are completely different from this one.

This is a dynamic document and contributions, clarifications, and corrections are most welcome! Please send e-mail to <claird@phaseit.net>.

Please note: from 1997-2000, this FAQ was largely quiescent. On 25 September 2000, Cameron Laird assumed its responsibility from Peter Prymmer, established a new home URL (see above; the phaseit.net copy is always at least as current as the others) for it, and began to update its content. As 2001 closes, I'm still correcting out-of-date information, ensuring that all hyperlinks are live, and erratically folding in contributed material that arrives. I've abandoned the search for a more permanent custodian for the Perl/Tk FAQ. I do have ambitions, though, of combing the Web for outdated copies of this document and co-operating with site managers to bring them to the present.

Perl/Tk [or "Perl/Tk"?] FAQ

1. What is Perl/Tk?
2. What is the difference between Perl/Tk and Tkperl? Are there ways beside Perl/Tk to do graphics with Perl?
3. Do I need Tcl/Tk in order to build Perl/Tk?
4. Where is it?
5. What/Where is CPAN?
6. How do I build it?
7. Where is the Documentation? What training is available?
8. How do I write scripts in Perl/Tk?
9. What widget types are available under Perl/Tk?
10. How do I get widget X to do Y ?
    1. How do I get a Button to call a Perl subroutine?
    2. How do I get a Button to actively change under my mouse pointer?
    3. How do I arrange the layout of my widgets?
    4. How do I get a Popup to popup?
    5. How do I bind keyboard keys?
    6. How do I add bindings? How do I change or remove bindings?
    7. How do I bind the action of a slider (sic) to ... ?
    8. How do I configure a Scrollbar to scroll multiple widgets?
    9. How do I display a bitmap?
    10. How do I display an image?
    11. What Image types are available?
    12. Is there any way to have more than one Listbox contain a selection?
    13. How do I select a range of tags in a Text widget?
    14. How do I group Radiobuttons together?
    15. How do I specify fonts?
    16. How do I get the entry in an Entry?
    17. How do I hide a password Entry?
    18. How do I limit an Entry's insertion width?
    19. How do I obtain Menus that do not tear off?
    20. How do I replace the default window icon?
    21. How do I prevent a window from closing when a user clicks on the 'cross-field' in the upper-right corner?
    22. How do I implement 'drag-n-drop'?
    23. How do I write the contexts of a text widget to an external file?
    24. How do I center a window?
    25. How do I prevent iconification of a window, or otherwise manage minimization and maximization?
    26. How do I keep a window on top of the screen?
11. How do I get a Canvas to ... ?
    1. Display a bitmap?
    2. Erase a display?
    3. Display an Image?
    4. What things can be created on a Canvas?
    5. How do I redraw a line on a Canvas?
    6. How do I use the Canvas as a geometry manager?
    7. How do I get a Canvas to output PostScript(c)?
    8. How do I get a PostScript(c) output of a Canvas w/ widgets?
    9. How do I get the size of a Canvas? After a re-size?
    10. How do I bind different actions to different areas of the same Canvas?
    11. How do I rotate text?
12. Common Problems.
    1. What do the ->, => and :: symbols mean?
    2. What happened to the ampersands &?
    3. What happened to the quotation marks?
    4. Must I use "my" on all my variables?
    5. Is there a way to find out what is in my Perl/Tk "PATH"?
    6. What is the difference between use and require?
    7. How do I change the cursor/color?
    8. How do I ring the bell?
    9. How do I determine the version of Perl/Tk that I am running?
    10. How do I call perl from C?
    11. How do I call Tcl code from Perl/Tk?
    12. How do I determine the screen resolution?
    13. Is there a fileevent problem?
13. What are some of the primary differences between Tcl/Tk and Perl/Tk?
14. How do I install new scripts | modules | extensions?
15. How do I write new modules?
16. Composite Widgets.
    1. How do I get a Dialog box?
    2. Is there a file selector?
    3. Is there a color editor?
    4. Is there a round Scale?
    5. Is there something equivalent to tkerror?
    6. Are there Tables?
17. Programming/development tools.
    1. Is there a Tcl/Tk to Perl/Tk translator?
    2. Is there something equivalent to wish in Perl/Tk?
    3. Is there a debugger specifically for Perl/Tk?
    4. Is there a GUI builder in Perl/Tk?
    5. How do I compile Perl/Tk scripts?
18. Processes & Inter-Process Communication under Perl/Tk.
    1. How does one get Perl/Tk to act on events that are not coming from X?
    2. Is there a send and do I need xauth?
    3. How can I do animations using after?
    4. How do I update widgets while waiting for other processes to complete?
    5. How do you fork?
19. How do I "clear the screen"?
20. Is there a way to have an X application draw inside a Perl/Tk window?
21. Is there a version for Microsoft Windows(tm)? MacOS? Is there a browser plugin?
22. Are there any international font packages for Perl/Tk?
23. Are there any other ways to create event based interfaces from perl?
24. Where can I get more information on graphics (modules|scripts)?
25. Are there any major applications written in Perl/Tk?
26. What is the history of pTk and Perl/Tk?
27. What can we expect the future to hold?
28. How do I obtain the latest version of this FAQ?
29. Acknowledgements & maintainer.

Return to table of contents

1. What is Perl/Tk?

Perl/Tk (also known as pTk or ptk) is a collection of modules and code that attempts to wed the easily configured Tk 8 widget toolkit to the powerful lexigraphic, dynamic memory, I/O, and object-oriented capabilities of Perl 5. In other words, it is an interpreted scripting language for making widgets and programs with Graphical User Interfaces (GUI). (Examples of widget programs [not necessarily written in Perl/Tk] include xterm, xclock, most web-browsers, etc.. They are programs with "GUI" interfaces of one sort or another and are subject to the effects of your window manager.)

The current release (as of February 2003) of Perl/Tk is based on Tk8.0 (first released in 1998), the widget Toolkit originally associated with the Tcl (Tool command language) scripting language. However, from a Perl perspective, Perl/Tk does not require any familiarity with Tcl, nor does its installation depend on any Tcl code apart from that packaged within Perl/Tk. Perl/Tk uses perl 5 syntax, grammar, and data structures. On the other hand, this distinction means little to those just beginning with Perl; for them, there's simply a large mass of material that must be learned, and no particularly comprehensive exposition of it is available online. It often happens that those in search of Perl/Tk documentation are sent to Tcl/Tk for specific aspects.

The production release of Perl/Tk was written primarily by Nick Ing-Simmons <Nick.Ing-Simmons@tiuk.ti.com> at Texas Instruments in Northampton, England, to work with the latest version of Larry Wall's ``perl''. Plans are afoot to track such enhancements as Tk 8.4 and Perl 6.

The pTk code proper is an externally callable Tk toolkit (i.e. a re-write of the Tk 8.0 code that allows easier external linking & calling, especially by perl). Ptk can then be called from Perl 5 via the Tk.pm et al perl glue modules. Hence "ptk" does not necessarily refer to Perl Tk but could be taken to mean portable Tk - given a glue package to another language. The stated goal of the pTk code is to have its library usable from perl, Tcl, LISP, C++, python, etc.. It just so happens that present work is concentrating on perl.

Historical note: "ptk" was known as "ntk" before about 11:30 EST 4 May 1995.

The Perl/Tk language is itself further extensible via the standard perl 5 module mechanism. A number of composite widget and special character extensions to the language have been written using perl modules.

Return to table of contents

2. What is the difference between Perl/Tk and Tkperl? Are there ways beside Perl/Tk to do graphics with Perl?

[OBSOLETE; move to historical section.] TkPerl was originally the name of a (now unsupported) perl 4 package that Malcolm Beattie <mbeattie@sable.ox.ac.uk> at Oxford University gave to his code to wed the Tk X toolkit with Perl. (He has since referred to that package as a different "kettle of fish" from Perl/Tk.)

Since that beginning Malcolm has also come up with a Tcl module for perl 5 that has a Tcl::Tk module extension. That module allows the use of Tcl within a Perl script (i.e. you must know both languages to get your widgets to work.) If you are interested in that package instead, see the necessary kits for Malcolm Beattie's Tcl/Tk extensions to Perl, which have been distrubuted as Tcl-b#.tar.gz and TclTk-b#.tar.gz files in the authors/id/MICB/ directory at CPAN sites (locations given in a separate question in this FAQ).

The name "tkperl" is sometimes applied to the "Perl/Tk" or "ptk" package that is the subject of this FAQ. Nick Ing-Simmons prefers "Perl/Tk" as the name of the package, with "pTk" or "ptk" as contractions of that name as well as referring to something technically distinct: given the extensibility of the pTk code the "p" could also be taken to mean 'portable' or 'pure' (not to be confused with either the Helsinki University of Technology portTk, nor with Brian Warkentine's Rivet). In this document the code of interest is either referred to as "Perl/Tk", "pTk", or "ptk" though the primary focus is on Perl/Tk.

Warning: do not attempt to install both Perl/Tk and Tcl/Tkperl in the same perl installation. The names in the respective modules overlap. In particular the Tcl::Tk module is declared in a Tk.pm file - so a statement like:

    use Tk;

A more extensive comparison of the differences between the Tkperl and the Perl/Tk code is given in the Tcl-perl.pod file that is distributed with Perl/Tk (see the following questions for locations).

Lastly, it should be mentioned that if you build your Perl/Tk statically rather than dynamically it will make a new perl interpreter called tkperl (confusing isn't it? :-).

Are there modern ways to do graphics with Perl besides Perl/Tk? Absolutely--quite a few, in fact. [CL will document these more completely in 2003.] Among the alternatives are:

• PerlQt, at release 3 as of early 2003;
• Web applications [...];
• GNOME binding [...];
• ...
• [describe book];

Return to table of contents

3. Do I need Tcl/Tk in order to build Perl/Tk?

Short answer: No not at all. Perl/Tk is completely independent of Tcl/Tk.

Longer answer: In order to build Perl/Tk from source code you do need a recent version of perl, the Perl/Tk source code kit, a graphical user interface library such as Xlib, Presentation Manager, or Win32; a C or C++ compiler, and a make utility. In some rare cases Perl/Tk binaries are distributed for some platforms but that is more the exception than a general rule (see below).

If you will be attempting to port Perl/Tk to your platfrom then you might want to consult the document at:

    http://w4.lns.cornell.edu/~pvhp/ptk/ptkPORT.html

where each of these components is discussed in a bit more detail (with an emphasis on Xlib).

Return to table of contents

4. Where is it?

Source code

ActiveState Corporation has taken over the chore of maintaining what originated as Gurusamy Sarathy's binary distribution for WinNT, Win95, Win98, and Win2000. [Mention license considerations here?] This is what you must do to "use Tk" with ActivePerl:

1. Download and install version 1.1 or greater of the Windows Installer (while the installation claims a reboot is necessary, Cameron Laird found it not to be so for WinNT);
2. Download the ActivePerl 618 distribution:
3. From Windows Explorer, activate the distribution just downloaded; from the command line, start ActivePerl-5.6.0.618-MSWin32-x86-multi-thread.msi. This installs ActivePerl;
4. From a command line, invoke ppm install Tk;
5. At this point, you can perl -e "use Tk" from a command line, and you're ready to code Perl/Tk source.

ppm should work fine for Perlites behind firewalls, as it's SOAP-transported. ActivePerl 623 exploits SOAP-lite to fix all known firewall and proxy-service problems with ppm retrieval. Other possibilities (while you should always check your ActivePerl license before taking any of these actions, in general use that doesn't involve resale is OK) include:

• locating the appropriate .ppm on the ActiveState Web site (anyone taken the time to track it down?), and manipulating it locally once it's passed through the firewall; or
• making a working ActivePerl+Tk image on a personal machine, and importing required files through sneakernet or a morally-equivalent means.

(While the next question treats CPAN in detail, the remainder of this answer points out some non CPAN resources, as well as some historical resources.)

Tk-b8: The Tk-b8 kit remains on CPAN since it was compatible with the widely distributed and installed Perl (5.001m)

Binaries

Australia (please be patient and only try during off hours)
    ftp://syd.dit.csiro.au/pub/perl5/local/perl5.001m+Tk-b8-Linux-ELF.tar.gz

Binaries for the old Perl 5 & Tk-b6 are available for a number of UNIX platforms courtesy of Thomas Schlagel and Alan Stange of Brookhaven Lab at:

USA
    http://pubweb.bnl.gov/~ptk/

Physical media (mostly source code)

Perl Developer's Toolkit from Advice Press; 366 Cambridge Ave.; Palo Alto, CA 94306

ISBN: 1-889671-15-0 $39.95, is also available via a subscription plan. This CD is organized by Jon Orwant (the organizer of comp.lang.perl.tk and the publisher of The Perl Journal.

Walnut Creek Perl CD from Walnut Creek CDROM; 4041 Pike Lane, Suite E; Concord, CA 94520

This CD specifies a release date. $39.95

Cosmos Engineering Company

Offers Linux plus perl for sale on a 1 Gigabyte IDE hard drive for PC-like computers. $279.00 (Fall 1996)

Unix Review System Administration

A CD that contains "Perl 5.0" (and much other stuff including Tcl/Tk and Expect) for $49.95. Telephone: (800) 444-4881.

InfoMagic Mother of Perl

This 2 CD set contains perl 5.001 and sells for $35.00

Ready to Run

Perl (unknown version) available for sale for many types of Unix and other operating systems.

Return to table of contents

5. What/Where is CPAN?

"CPAN" = Comprehensive Perl Archive Network a worldwide collection of anonymous ftp sites for Perl et al (not to be confused with CTAN which is for TeX, nor CSPAN which rarely deals with computer software). The files of particular interest to a Perl/Tk programmer would include:

• The latest Tk release should be in the modules/by-authors/Nick_Ing-Simmons/ directory at any CPAN ftp site (listed below).
• The latest official Perl release should be in the src/ directory in a file called latest.tar.gz at any CPAN ftp site (listed below).
• A recent binary distribution of perl+Tk+many other modules should bin in the modules/by-authors/Gurusamy_Sarathy/ at any CPAN ftp site (listed below).
• If you need something older or newer than the "latest supported release" of Perl try the src/5.0/ directory at any CPAN ftp site (listed below).

• Alan Scheinine's SelFile.pm is in the modules/by-authors/Alan_Scheinine/ directory at any CPAN ftp site (listed below).
• The widget collection Graham Barr originally wrote can be found with a CPAN search for "Tk-GBARR".
• Guy Decoux's BLT_Table geometry manager is in the modules/by-authors/id/GUYDX/ directory at any CPAN ftp site (listed below).
• Ilya Zakharevich's eText plug in replacement for the Text widget is in the modules/by-authors/id/ILYAZ/etext/ directory at any CPAN ftp site (listed below).
• Brent B. Powers' Tk-FileDialog and Tk-WaitBox are available from the modules/by-authors/id/BPOWERS/ directory at any CPAN ftp site (listed below).

• To run the ptknews script you will need Mail/Internet.pm from the Mailtools module kit, available from the modules/by-authors/id/GBARR/ directory at any CPAN ftp/http site (listed below). While there pick up the latest libnet-* module bundle too.
• The build of recent versions of Perl/Tk requests that you have the URI::URL and HTML::Parse modules already installed. These modules are part of the libwww-perl-*.tar.gz kit, available from the modules/by-authors/id/GAAS/ at any CPAN ftp/http site (listed below).

• Assorted documentation for perl is in the doc/ directory at any CPAN ftp site (listed below).
• Fairly up-to-date versions of some Perl/Tk external documentation (such as this FAQ) is in the modules/by-authors/id/PVHP/ directory at any CPAN ftp/http site (listed below).
  (for Perl/Tk official documentation check the Tk/doc/*.htm files that are built with Nick's Tk kit on your computer.)

• Most things Perl/Tk (with certain exceptions) are also linked to a modules/by-module/Tk/ directory at any CPAN ftp/http site (listed below).
• The long version of Tim Bunce and Andreas Koenig's module list helps you sort out things like "which kit is HTML::Parse a part of?". It is in modules/00modlist.long.html and is also posted periodically to newsgroups.

Updated: Sun Dec 8 17:12:55 EST 1996

Africa
  South Africa    
    ftp://ftp.is.co.za/programming/perl/CPAN/           196.4.160.12
Asia
  Hong Kong       
    ftp://ftp.hkstar.com/pub/CPAN/                      202.82.7.4
  Japan           
    ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/           150.65.7.5
    ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/             192.26.91.6
  South Korea     
    ftp://ftp.nuri.net/pub/CPAN/                        203.255.112.6
  Taiwan          
    ftp://dongpo.math.ncu.edu.tw/perl/CPAN/             140.115.25.3
Australasia
  Australia       
    ftp://coombs.anu.edu.au/pub/perl/CPAN/              150.203.76.2
    ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/              128.250.209.2
  New Zealand     
    ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/             202.49.6.24
Europe
  Austria         
    ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/     128.130.34.160
  Belgium         
    ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/    134.58.127.2
  Czech Republic  
    ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/      194.50.23.220
  Denmark         
    ftp://sunsite.auc.dk/pub/languages/perl/CPAN/       130.225.51.30
  Finland         
    ftp://ftp.funet.fi/pub/languages/perl/CPAN/         128.214.248.6
  France          
    ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/  157.99.64.12
  Germany         
    ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/  131.159.0.252
    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/           134.147.32.42
    ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/   134.100.32.54
  Greece          
    ftp://ftp.ntua.gr/pub/lang/perl/                    
  Hungary         
    ftp://ftp.kfki.hu/pub/packages/perl/CPAN/           148.6.0.5
  Italy           
    ftp://cis.utovrm.it/CPAN/                           160.80.22.17
  the Netherlands 
    ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/                  131.211.80.17
    ftp://ftp.EU.net/packages/cpan/                     134.222.91.7
  Norway          
    ftp://ftp.uit.no/pub/languages/perl/cpan/           129.242.4.34
  Poland          
    ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/             149.156.132.152
    ftp://sunsite.icm.edu.pl/pub/CPAN/                  148.81.209.3
  Portugal        
    ftp://ftp.ci.uminho.pt/pub/lang/perl/               193.136.16.247
    ftp://ftp.telepac.pt/pub/CPAN/                      194.65.5.98
  Russia          
    ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/            158.250.29.1
  Slovenia        
    ftp://ftp.arnes.si/software/perl/CPAN/              193.2.1.72
  Spain           
    ftp://ftp.etse.urv.es/pub/mirror/perl/              193.144.20.6
    ftp://ftp.rediris.es/mirror/CPAN/                   130.206.1.2
  Sweden          
    ftp://ftp.sunet.se/pub/lang/perl/CPAN/              130.238.253.4
  Switzerland     
    ftp://sunsite.cnlab-switch.ch/mirror/CPAN/          193.5.24.1
  UK              
    ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/        158.152.1.44
    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/           193.63.255.1
    ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/           129.12.200.129
North America
  Ontario         
    ftp://ftp.utilis.com/public/CPAN/                   207.34.209.49
    ftp://enterprise.ic.gc.ca/pub/perl/CPAN/            192.197.182.100
  California      
    ftp://ftp.digital.com/pub/plan/perl/CPAN/           204.123.2.4
    ftp://ftp.cdrom.com/pub/perl/CPAN/                  165.113.58.253
  Colorado        
    ftp://ftp.cs.colorado.edu/pub/perl/CPAN/            128.138.243.20
  Florida         
    ftp://ftp.cis.ufl.edu/pub/perl/CPAN/                128.227.205.206
  Illinois        
    ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/    128.174.5.14
  Massachusetts   
    ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/  206.15.105.99
  New York        
    ftp://ftp.rge.com/pub/languages/perl/               157.225.178.12
  North Carolina  
    ftp://ftp.duke.edu/pub/perl/                        152.3.233.7
  Oklahoma        
    ftp://ftp.ou.edu/mirrors/CPAN/                      129.15.2.40
  Oregon          
    ftp://ftp.orst.edu/pub/packages/CPAN/               128.193.4.12
  Texas           
    ftp://ftp.sedl.org/pub/mirrors/CPAN/                198.213.9.194
    ftp://ftp.metronet.com/pub/perl/                    192.245.137.6
South America
  Chile           
    ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/     146.83.5.204

    http://perl.com/cgi-bin/cpan_mod?module=Tk
    http://perl.com/cgi-bin/cpan_mod?module=Tk&readme=1

    ftp> get Tk400.202.tar

    http://www.cdrom.com/pub/perl/CPAN/
    http://www.metronet.com/perlinfo/

    perl -MCPAN -e 'install "Tk"'

Return to table of contents

6. How do I build it?

"GUI construction with Perl" is a modern treatment of what's involved in use of Perl/Tk. It specifically details how first-time Perl/Tk programmers can install Perl/Tk usefully.

Assuming you are not running a binary distribution then, in general, building Perl/Tk requires:

1. A made & installed perl (requires a C language compiler). You may need different versions of perl depending on which version of Tk you wish to run.
2. A C language compiler for the Tk code itself.
3. A linkable Xlib (.o, .so, .a, etc.) for X-windows.

[OBSOLETE] Step - by - step the commands to build the Tk extension to Perl are (for the dynamically linked version) roughly as follows:

1. make install # the appropriate version of perl.
2. uninstall # prior versions of the Tk extension to perl.
3. gunzip -c Tk400.*.tar.gz | tar xvf - (tar options may vary esp. on SysV)
4. cd Tk400.*
5. read INSTALL
6. perl Makefile.PL
7. make
8. make test
9. make install

Note carefully that this process leaves behind a large amount of documentation and examples in various sub-directories. You are strongly encouraged to look carefully through your build tree for docs, examples, etc. and keep those valuable files in a safe place. You might consider tar-ing them off and installing in a webserver directory tree.

A relatively easy way to determine if the perl on your system allows for dynamic linking was mentioned by Kenneth Albanowski <kjahds@kjahds.com>. If any of the following does not say "dl_none.xs" then you probably do have dynamically linked perl (or perhaps a very non-Unixy perl):

    perl -V:dlsrc
or
    perl -MConfig -e 'print $Config{dlsrc},"\n"'
or
    perl -e 'use Config; print $Config{dlsrc},"\n"'

Here is a little more detailed discussion of each the steps just given:

• Install Perl Read the Tk files (Tk*/README, etc.) for info on which version of perl is required for the Perl/Tk kit you obtained.) For code locations see a CPAN site (separate question in this FAQ), the actual installation instructions come bundled in the perl***.tar.gz distribution file. (Perl Configure & make troubles are beyond the scope of this FAQ - please see the Perl FAQ itself or the INSTALL file for more help with this critical step.)
  You can install perl almost anywhere you like by specifying the -Dprefix=/path argument to sh Configure
• [OBSOLETE] Unpack Perl/Tk outside the Perl distribution
  (i.e. outside the perl build, perl install, or perl lib areas).
  gunzip Tk400.*.tar.gz
  tar -xvf Tk400.*.tar
  (Your tar program may not take -xvf. The resultant directory area will be referred to as your ``Tk build'' directory throughout this document.)
  
• [OBSOLETE] Read INSTALL carefully
  cd Tk400.*
  pager INSTALL
  where pager is the program you use to scroll through text files more or less. Be sure to read it and don't just pound away on the spacebar.
• If necessary remove any previously installed version of Perl/Tk
  If you had a previously working version of Tk installed, you may need to resurrect the Makefile for it and execute:
  make uninstall
  make realclean
  before you unpack the new version. (The uninstall target of MakeMaker is relatively new so please be careful here.)
  
• Have perl generate a custom Makefile.
  perl Makefile.PL
  (see below for more on this step.)
  
• Compile.
  make
  (if and only if building static: make tkperl
  
• Test.
  make test
  
• Install.
  make install
• Play with it.
  basic_demo
  (modify #! line if necessary, or specify /path/to/perl ./basic_demo)
  (warning if you build Tk-b9.01 with perl5.002gamma then change the line in basic_demo from
  use lib ./blib;
  to
  use lib qw(blib/arch blib/lib);)
• Save the documentation and examples in a safe accessible place.
  use tar, cp, mv, chmod or whatever you prefer to save the valuable ancillary files from your Tk build tree.
  

    perl Makefile.PL X11=/usr/local/X11R5

    perl Makefile.PL X11INC=/usr/local/share/X11R5/include \
                     X11LIB=/usr/local/arch/X11R5/lib

If you still run into trouble take a look at the INSTALL, the README and the README file for your specific system (e.g. README.AIX, README.OSF, etc.). You might also find your system mentioned in the ptk hyper-mail archive at:

    http://www.rosat.mpe-garching.mpg.de/mailing-lists/ptk/
or
    http://pubweb.bnl.gov/~ptk/
or
    ftp://ftp.ccd.bnl.gov/pub/ptk/archives/

    http://www.rosat.mpe-garching.mpg.de/mailing-lists/Perl5-Porters/
    http://www.hut.fi/~jhi/perl5-porters.html

Presented here are the beginnings of a list of problems associated with building Perl/Tk on various platforms (for help building perl itself please refer to the Perl FAQ). This list is in no way complete nor authoritative (nor is it necessarily even up-to-date!) but simply lists problems people have reported. Keep in mind that your installation may differ (e.g. location differences such as /usr/bin/perl vs. /usr/local/bin/perl) even if its the same platform listed here:

A Sampling of Perl/Tk Platforms:

AIX:

As of perl5.002b & Tk-b9.01 README.AIX says no patching is necessary.

For Tk-b8: modifying the perl.exp file may be necessary. There is a patch in Tk-b8/README.AIX. It may be necessary to make regen_headers after the patch.

FreeBSD:

[OBSOLETE] Nate Patwardhan <nvp@nfic.com> reports no trouble at all with Tk400.200 on FreeBSD-2.1.5 or FreeBSD-2.2.1.

HPUX:

For Tk-b11: One person reports a need to add #define TIMEOFDAY_TZ to the tkConfig.h header file in order to compile on HPUX 9.05.

Previous versions: Most people seem to prefer the dynamic linking afforded by a recent version of the gcc compiler on this system.

Linux:

John C. Wingenbach indicates that should you encounter an error message like Cannot find -lX11 anywhere at ./myConfig line 184 when running your perl Makefile.PL (under Slakware 3.0) that you should be more specific about -l/path/to/libX11.a.
Adam Wasserman <awasser@hermes.sgc.com> has graciously provided a compilation of Linux compilation trials & tribulations. It is an (as yet un-edited) document available at: http://w4.lns.cornell.edu/~pvhp/ptk/hints/linux_compile.txt

MachTen:

Mark Pease <pease@act.sps.mot.com> mentions that:
I was able to get Tk-b11.02 running under MachTen 2.2 perl5.002_01. I did need to make one change to get a round a MachTen problem. In pTk/tclUnix.h, pwd.h is included, but it is also included in pTk/tkPort.h (which is included in Lang.h, which is use by tclUnixUtil.c, whew!)

MachTen's pwd.h can't be included more that once or you get an error.

It looked to me like tclUnix.h was only used in tclUnixUtil.c, so I commented out the #include <pwd.h> in tclUnix.h.

NetBSD:

Jesus M. Gonzalez <jgb@gsyc.inf.uc3m.es> mentions success with:
Tk-b11.01 compiles, installs and runs just out of the box in NetBSD-1.1/i386. I just followed the INSTALL instructions.

NeXTSTEP:

Gerd Knops recently posted a discussion of the steps to get perl running on several NeXTSTEPs to p5p.

OS/2:

Ilya Zakharevich <ilya@math.ohio-state.edu> has compiled a modified form of Tk-b11.02 to work with the Xfree86 client/server package, as well more advanced versions working with the Open32 PM package.

OSF/1:

As of perl5.002b & Tk-b9.01 you will probably be able to follow the usual instructions. John Stoffel <john@wpi.edu> reports that if you use gcc (rather than cc) you should use at least version 2.7.2

For Tk-b8: make is reputedly not up to the task on this system. Tk-b8/README.OSF recommends gmake instead.
Stephane Bortzmeyer <bortzmeyer@pasteur.fr> reports a successful build with Perl 5.001m, xsubpp 1.922, MakeMaker 4.23. He points out that it was necessary for him to upgrade the xsubpp and MakeMaker that he received with his copy of Perl5.001m.

SCO:

For Tk-b8: Eric J. Bohm <bohm@cs.Buffalo.EDU> reported a need to comment out line(s) from myConfig and GNUMakefiles using GNU make 3.67. (See Tk-b8/README.SCO for specifics.)

SGI (Irix):

For Tk-b11.02: Phillip Moore <wpm@morgan.com> reports a clean build on IRIX 5.3.

Matthew Black <black@csulb.edu> recently mentioned a need to apply "patchSG0000596" to get perl sockets to work. His message was copyrighted and is not included here. Send e-mail to him to find out where the get "patchSG0000596".

Suns:

SunOS (BSD):
For Tk-b10 on SunOS 4.1.3_U1
using SparcWorks acc 3.0.1 Frederick L. Wagner <derf@ti.com> reports needing to use the perl malloc rather than the system malloc() when building perl.
For Tk-b8: Tom Tignor <tpt2@BBN.COM> reports the following on SunOS (sun4m sparc): Tue, 28 Nov 1995 13:19:42
In trying to make, I got a "write: argument mismatch" error for the file ptK/Lang.h. I looked at the file and found the offending function, Tcl_GetOpenFile, which has a third argument called "doWrite" (not "write") in tkGlue.c. I changed the argument from "write" to "doWrite" in Lang.h and it's compiling fine (for the moment. :)
Solaris (System V):
For Tk-b8: There is trouble getting perl to use Socket routines (i.e. trouble with make perl itself not necessarily trouble with Tk-b8). See the perl FAQ for more info or the .shar file that Tom Christiansen occasionally posts to comp.lang.perl.misc. Further information on perl inter process communication can be found in the perlipc* files at: ftp://ftp.perl.com/perl/info/everything_to_know/.

SVR4:

For Tk-b8: Martha G. Armour and Len Reed report on two separate hardware platforms running SVR4 - extensive details in Tk-b8/README.SVR4. Interestingly, they report no trouble at all on Linux.

Ultrix:

Peter Prymmer reports that with Tk-b11 it was necessary to change the line in Makefile.PL that reads:
'LIBS' => ["$xlib -lX11 -lpt -lsocket -lnsl -lm"],
to read:
'LIBS' => ["$xlib -lX11 -lpt -lsocket -lnsl -lm -ldnet"],
because of a newer X11 in /usr/local that needed the DECnet protocol linking.

John Stoffel reports a successful build of static Tk-b10 on Ultrix 4.5.

Windows NT:

[OBSOLETE] Nick Ing-Simmons reports success with the alpha Tk404.000 kit, perl5.004, and Visual C++. Gurusamy Sarathy has distributed a binary kit with perl,Tk,etc. precompiled for Windows 32. Support is continuing to allow extension by the Borland C++ compiler as well as cross compiler extendability.

non-Unix(ish)es:

    http://www.rosat.mpe-garching.mpg.de/mailing-lists/Perl5-Porters/
    http://www.hut.fi/~jhi/perl5-porters.html

    http://w4.lns.cornell.edu/~pvhp/ptk/ptkPORT.html

Return to table of contents

7. Where is the Documentation?

A great deal of Perl/Tk documentation gets installed as part of the Tk extension building process. Hence, a great deal of documentation is probably residing on your computer already. The best place to start is with the first two entries in `perldoc Tk`. It's worth installing ActivePerl just for its HTMLized documentation of Perl and its modules.

The one book easiest to recommend is Lidie and Walsh's Mastering Perl/Tk, published in February 2002. Until then, Nancy Walsh's Learning Perl/Tk: Graphical User Interfaces with Perl was the standard. While the latter is intended as an introduction, and it's generally agreed that it doesn't "go beyond the obvious", as Robert Boyd Skipper put it, its competent index makes it valuable also for more experienced Perl/Tk users. The book deserves a second edition; it doesn't represent the current situation of, for example, Perl/Tk under Windows at all justly.

Srinivasan's Advanced Perl Programming has a single chapter on Perl/Tk which matches the quality of the rest of the book--that is, it's quite dense yet readable. It's hardly appropriate as a general introduction, though. Several people cite Lidie's Perl/Tk Pocket Reference as indispensable. Also, one of Larry Virden's Tcl FAQs aims to catalogue Perl books with coverage of Tk.

More documentation is "in the works": there are several books dealing with Perl/Tk in progress (one from Steve Lidie?), an ongoing magazine column and a growing FAQ (the document you are presently reading).

The additional material you may want to look at can be split into Perl/Tk, Perl, Tcl/Tk, and X documentation categories:

Perl/Tk Specific Documentation

The man pages

In your Tk build directory there should be a doc/ sub-directory in which there are a number of .htm files (after you make install). These files were originally Tcl/Tk man pages (from the man* sub-directories), but the *.htm files have been converted to Perl syntax and rendered in HTML format. You can use the Perl/Tk web browser to view them locally with a command like:

    tkweb index.html

    http://w4.lns.cornell.edu/~pvhp/ptk/doc/

The newsgroup

For background on the theory and operation of Usenet newsgroups, see the references maintained as part of the Tcl-ers' Wiki. Information there includes tips on how to read and write to newsgroups such as comp.lang.perl.tk.

The nTk/pTk mailing list

The nTk/pTk Mailing List Archive is a very useful source of information too, and is accessible at either

    http://groups.yahoo.com/group/ptk/
(but will someone please change the out-of-date introduction?),

    http://pubweb.bnl.gov/~ptk/

    ftp://ftp.ccd.bnl.gov/pub/ptk/archives/

    http://www.rosat.mpe-garching.mpg.de/mailing-lists/ptk/

    subscribe ptk joe.user@somewhere (Joe D. User)

To send a message to all recipients of the mailing list send e-mail to <ptk@lists.stanford.edu>.

To remove yourself from the mailing list send e-mail to majordomo@lists.stanford.edu (i.e. <majordomo@lists.stanford.edu>) with the following command in the body of your e-mail message:

    unsubscribe ptk joe.user@somewhere (Joe D. User)

(Please note: one does not send unsubscribe messages to the ptk list. One does send "unsubscribe ptk" messages to a special e-mail list administration program. In the case of the ptk list you send to majordomo@lists.stanford.edu. You must of course do this from the account and computer from which you initially subscribed. In particular if you are viewing the hypertext version of this FAQ you may not be able to unsubscribe from majordomo@lists.stanford.edu by following the mailto: hyperlinks - if your web-browser account/computer is different from your subscribe to e-mail-lists account/computer (the details of this might depend on which browser you use though). Thank you for your cooperation on this.)

The demo programs

• or perl5/site_Perl/Tk/demos/ or perl5/site_Perl/Tk/demos/widget_lib/ directories (recent Tk's).
• Tk#/ or perl5/Tk/demos/ or perl5/Tk/demos/widget_lib/ directories (older versions e.g. Tk-b8).

In order to determine where on your system the perl5/ directory is located type the following one-line perl command (at your shell prompt - this is not a line from a perl script):

    perl -e 'print join("\n",@INC,"");'

More on the pod & man documentation

The raw pod files that come with the Tk kit are examples of the perl "plain old documentation" format and are just about human readable as they are (e.g. you may more, cat, or less them; or send them to a printer). Many (not all) of the Perl/Tk pod documents get are converted to *roff format and are installed in you perl man page area as part of the Perl/Tk build process.

If you have a recent version of Perl/Tk try something like man 3 Tk::Tk. If this does not work check your manual page path with

    perl -MConfig -e 'print $Config{man1dir},"\n",$Config{man3dir},"\n"'

"Raw" .pod (such as UserGuide.pod) can be viewed with the tkpod hypertext pod viewer. Raw .pod may also be run through any one or more of a large numbers of re-formatting perl filters. Such programs include pod2man, pod2text, pod2html, pod2latex, etc. (these get installed when you install perl). Other translators pod2texinfo, pod2fm, pod2pdf, etc., also exist. Check a CPAN site for these scripts if you do not already have them.

A command line like the following (but subject to local variations) should work for you:

    tkpod site_Perl/Tk/UserGuide.pod

    pod2man perl5/Tk/UserGuide.pod | nroff -man | more

    pod2man UserGuide.pod | nroff -man | more

    perldoc UserGuide

    tkpod ColorEditor.pm

If you have misplaced your tkpod program but still want that GUI look and feel (like xman) make the appropriate changes to the following script:

    #!/usr/bin/perl
    use Tk;
    use Tk::Pod;
    my $m = new MainWindow;
    $m -> Pod(-file => 'ColorEditor.pm');
    # or use command line path/filename:
    # $m -> Pod(-file => $ARGV[0]);
    MainLoop;

A miscellany of internet Perl/Tk resources includes:

World Wide Web - Perl/Tk man pages
    http://pubweb.bnl.gov/~ptk/doc/index.html
    http://w4.lns.cornell.edu/~pvhp/ptk/doc/
    http://w4.lns.cornell.edu/~pvhp/ptk/pod/
The Perl/Tk Newsgroup
    comp.lang.perl.tk
Perl Newsgroups
    comp.lang.perl.misc
    comp.lang.perl.anounce
    comp.lang.perl.modules
Tcl Newsgroups
    comp.lang.tcl
    comp.lang.tcl.announce
Miscellaneous Newsgroups
    comp.answers
    news.answers
Perl/Tk FAQ-Archives (ftp sites) [Note: FAQ may be many separate files]
 (see also CPAN sites)
    ftp://rtfm.mit.edu/pub/usenet/comp.lang.perl.tk
    ftp://rtfm.mit.edu/pub/usenet-by-hierarchy/comp/lang/perl/tk
    ftp://ftp.uu.net/usenet/news.answers/perl-faq/ptk-faq
    ftp://ftp.ccd.bnl.gov/pub/ptk/                   130.199.54.188
    ftp://ftp.ccd.bnl.gov/pub/ptk/ptkFAQ.txt         130.199.54.188
    ftp://ftp.wpi.edu/perl5/pTk-FAQ                  130.215.24.209
    ftp://perl.com/pub/perl/doc/ptkFAQ.gz            199.45.129.30
    ftp://perl.com/pub/perl/doc/ptkFAQ.ps.gz         199.45.129.30
WWW-FAQ for Perl/Tk
    http://w4.lns.cornell.edu/~pvhp/ptk/ptkTOC.html
    http://w4.lns.cornell.edu/~pvhp/ptk/ptkFAQ.html
World Wide Web - Perl/Tk info sites
    http://pubweb.bnl.gov/~ptk/
    http://fxfx.com/kgr/compound/ (Perl Tk Compound Widget Page)
    http://w4.lns.cornell.edu/~pvhp/ptk/ptkIMG.html (FAQ image supplement)
    http://w4.lns.cornell.edu/~pvhp/ptk/etc/
    http://w4.lns.cornell.edu/~pvhp/ptk/misc/
    http://w4.lns.cornell.edu/~pvhp/ptk/PNMTYAK/
    http://www.mirai.com/wks/
The Mailing list
    majordomo@lists.stanford.edu 
    ptk@lists.stanford.edu 

Perl Specific Documentation

    http://www.perl.com/perl/info/books.html

Programming Perl 2nd Edition
Larry Wall, Tom Christiansen, & Randal L. Schwartz with Stephen Potter
(c) 1996 O'Reilly & Associates Inc.
ISBN 1-56592-149-6 (English)

Advanced Perl Programming
By Sriram Srinivasan
1st Edition August 1997 (est.)
O'Reilly & Associates Inc.
ISBN: 1-56592-220-4, Order Number: 2204
440 pages (est.), $34.95 (est.)

Learning Perl, 2ndEdition
Randal L. Schwartz
June 1997 (est.) O'Reilly & Associates Inc.
ISBN 1-56592-284-0 (English)

Learning Perl (The Llama)
Randal L. Schwartz
Copyright (c) 1993 O'Reilly & Associates Inc.
ISBN 1-56592-042-2 (English)
ISBN 2-84177-005-2 (French)
ISBN 3-930673-08-8 (German)
ISBN 4-89502-678-1 (Japanese)

Programming Perl (The Camel)
Larry Wall and Randal L. Schwartz
Copyright (c) 1991 O'Reilly & Associates Inc.
ISBN 0-937175-64-1 (English)
ISBN 3-446-17257-2 (German) (Programmieren in Perl, translator: Hanser Verlag)
ISBN 4-89052-384-7 (Japanese)

    http://www.metronet.com/1h/perlinfo/perl5/

Perl 5 Interactive Course
Jon Orwant
(c) 1996 The Waite Group Press
A Division of SAMS Publishing, Corte Madera, CA USA
ISBN: 1-57169-064-6

    http://www.xs4all.nl/~jvromans/perlref.html

Perl 5 Desktop Reference
Johan Vromans
Copyright (c) February 1996 O'Reilly & Associates Inc.
ISBN: 1-56592-187-9; Order number: 1879

Eric F. Johnson has a book that discusses many perl5 for Unix vs. perl5 for Windows NT issues. He includes a final chapter with extensive discussion of the Tk extension and the ->Text() widget in particular. The information on that book is:

Cross-Platform Perl
(c) 1996 Eric F. Johnson
MIS:Press/M&T Books
ISBN: 1-55851-483-X

Kamran Husain and Robert F. Breedlove have written a perl 5 book that includes a chapter on Tk with some discussion of Menu()s. That book is:

Perl 5 Unleashed
Kamran Husain and Robert F. Breedlove
(c) 1996 Sams Publishing, Indianapolis, IN
ISBN: 0-672-30891-6

There is also a "Perl 5 How-To" book available that contains a great deal of erroneous information about Perl/Tk. Among other things that book wrongly claims that it is necessary to have a complete Tcl/Tk library installed on one's system to compile the Tk extension to perl. (They are incorrect - it is only necessary to have the appropriate perl version, libc and Xlib, the Tk extension is otherwise "self-contained").

There is also a book on perl web client. It features a a chapter on Perl/Tk that was written by Nancy Walsh:

Web Client Programming with Perl
Clinton Wong
1st Edition March 1997
O'Reilly & Associates Inc.
ISBN: 1-56592-214-X; Order number: 214X

Additional book information may be found at Tom Christiansen's perl & cgi books page, or at his Perl-related Book Reviews page.

The multi-part perl 5 manual pages are available (assuming they have been installed in your MANPATH, type man perl, man perlmod etc.).

The perl 5 man pages are also available on the web at a number of locations. In general the more recent the documentation the more helpful it is.

In addition to the CPAN ftp source sites, a miscellany of internet perl resources includes:

Newsgroups
    comp.lang.perl.misc
    comp.lang.perl.announce
    comp.lang.perl.modules
    comp.infosystems.www.authoring.cgi
    comp.answers
    news.answers
Perl FAQ-Archives (ftp sites) [Note: FAQ may be many separate files]
(as of 5.004 the FAQ ships in pod format with perl)
    (see also the CPAN sites)
  North America
    ftp://rtfm.mit.edu/pub/usenet/news.answers/perl-faq/
    ftp://ftp.uu.net/usenet/news.answers/perl-faq  192.48.96.9
    ftp://ftp.khoros.unm.edu/pub/perl/faq.gz       198.59.155.28
  Europe 
    ftp://ftp.cs.ruu.nl/pub/NEWS.ANSWERS/perl-faq/ 131.211.80.17
    ftp://src.doc.ic.ac.uk/packages/perl/FAQ       146.169.2.10
Gopher Perl FAQ 
    gopher://gopher.metronet.com/11/perlinfo/faq
WWW-FAQ for Perl
    http://www.perl.com/perl/faq/
    http://www.smartpages.com/bngfaqs/comp/lang/perl/top.html
    http://www.smartpages.com/bngfaqs/comp/lang/perl/misc/top.html
    http://www.smartpages.com/bngfaqs/comp/lang/perl/announce/top.html
    http://www.cis.ohio-state.edu/hypertext/faq/usenet/perl-faq/top.html
Perl for Win32 FAQ  (discusses Win95)
    http://www.perl.org/CPAN/doc/FAQs/win32/Perl_for_Win32_FAQ.html

Perl info sites
Gopher (gopher:70) perl info sites
  USA
    gopher://gopher.metronet.com/11h/perlinfo
World Wide Web (http:80) perl info sites
  USA
    http://www.yahoo.com/Computers_and_Internet/Languages/Perl/index.html
    http://www.perl.com/
    http://www.khoros.unm.edu/staff/neilb/perl/home.html
    http://www.khoros.unm.edu:80/staff/neilb/perl/metaFAQ/
    http://www.metronet.com/perlinfo/
    http://www.metronet.com/perlinfo/perl5.html (Perl 5)
    http://www.eecs.nwu.edu/perl/perl.html
    http://cesr39.lns.cornell.edu/public/perl/
    http://www.virtualschool.edu/mon/Perl.html
    http://www.hermetica.com/technologia/unexec/
    http://www.oac.uci.edu/indiv/ehood/perlWWW/
    http://web.sau.edu/~mkruse/www/scripts/
    http://orwant.www.media.mit.edu/the_perl_journal/
    http://www.perl.com/Architext/AT-allperl.html
    http://www.mispress.com/introcgi/
    http://www.walrus.com/~smithj/webcan/
    http://web.syr.edu/~chsiao05/cps600_project.html
    http://www.iftech.com/classes/webdev/webdev_perl.htm
    http://www.cc.iastate.edu/perlmenu/
    http://www.ora.com/www/item/cgi_prog.html
    http://www.netaxs.com/~joc/perlring.html
  UK
    http://pubweb.nexor.co.uk/public/perl/perl.html
    http://www.bio.cam.ac.uk/web/form.html
  Elsewhere
    http://www.oasis.leo.org/perl/00-index.html
Web references to Perl mailing lists
    http://www.perl.com/perl/info/mailing-lists.html
    http://www.nicoh.com/cgi-bin/lwgate/PERL5-PORTERS/
    http://www.hut.fi/~jhi/perl5-porters.html
    http://www.rosat.mpe-garching.mpg.de/mailing-lists/

Tcl/Tk Specific Documentation

Tcl and the Tk Toolkit
John K. Ousterhout
Copyright (c) 1994 Addison-Wesley Publishing Company
ISBN 0-201-63337-X (alk. paper)
LOC QA76.73.T44097 1994; 005.13'3--dc20

Practical Programming in Tcl and Tk
Brent Welch
Copyright (c) 1995 Prentice Hall
ISBN 0-13-182007-9

Within the tclsh or wish shells your manpath includes the tcl/tk man pages (which may not be in your login MANPATH). Thus from the % prompt within either shell type commands like:

    % man -k Tk

The Tcl/Tk Reference Guide is also a source of useful information. Although it's Tcl specific most Perl/Tk commands can be, more or less, easily derived from it. [Note that in Perl/Tk the names of some functions and some configuration options have changed slightly from their Tcl/Tk counterparts. With recent versions of Perl/Tk a great many functions start with an upper case letter and continue with all lower case letters (e.g. there is a Perl/Tk Entry widget but no entry widget), and many configuration options are all lower case (e.g. there is a Perl/Tk highlightthickness option but no highlightThickness option).] You may fetch the Tcl/Tk Reference Guide (may require LaTeX for installation) from:

  ftp://ftp.slac.stanford.edu/software/TkMail/tkref-4.0.1.tar.gz 134.79.18.30
  ftp://ftp.aud.alcatel.com/tcl/docs/tkref-4.0.1.tar.gz          198.64.191.10

Newsgroups
    comp.lang.tcl
    comp.lang.tcl.announce
    comp.infosystems.www.authoring.cgi
    comp.answers
    news.answers
FAQ-Archive (ftp) [Note: Tcl FAQ may be many files, Tk FAQ is one file]
    ftp://ftp.aud.alcatel.com/tcl/docs/                          198.64.191.10
    ftp://rtfm.mit.edu/pub/usenet/news.answers/tcl-faq
    ftp://rtfm.mit.edu/pub/usenet/news.answers/tcl-faq/tk
WWW-FAQ for Tcl/Tk
    http://www.teraform.com/%7Elvirden/tcl-faq/
    http://www.smartpages.com/faqs/tcl-faq/top.html
    http://www.smartpages.com/bngfaqs/comp/lang/tcl/top.html
    http://www.cis.ohio-state.edu/hypertext/faq/usenet/tcl-faq/top.html
  http://www.cis.ohio-state.edu/hypertext/faq/bngusenet/comp/lang/tcl/top.html
    http://www.sco.com/Technology/tcl/Tcl.html
World Wide Web - Tcl/Tk info sites
  Canada
    http://web.cs.ualberta.ca/~wade/Auto/Tcl.html
  UK
    http://http2.brunel.ac.uk:8080/~csstddm/TCL2/TCL2.html
    http://www.cis.rl.ac.uk/proj/TclTk/
  USA
    http://www.yahoo.com/Computers_and_Internet/Languages/Tcl_Tk/index.html
    http://www.sunlabs.com/research/tcl/docs.html
    http://www.sunlabs.com/research/tcl/4.0.html
    http://www.sco.com/Technology/tcl/Tcl.html
    http://www.neosoft.com/tcl/
    http://www.elf.org/tcltk-man-html/contents.html
Tcl/Tk - miscellaneous extensions
    ftp://ftp.cme.nist.gov/pub/expect/
    http://www.cs.hut.fi/~kjk/porttk.html
    http://tix.sourceforge.net
    http://www.ece.cmu.edu/afs/ece/usr/svoboda/www/th/homepage.html
    http://www.tcltk.com/ [incr Tcl]
    http://www.neosoft.com/tcl/TclX.html
    http://www.eolas.com/eolas/webrouse/tcl.htm [WebWish]
    http://www.se.cuhk.hk/~hkng2/big5tk/big5tk.html
    http://www.cs.uoregon.edu/~jhobbs/work/ [BLT etc.]

X Documentation

There are a number of X resources on the internet including:

Newsgroups
    comp.windows.x
    comp.windows.x.announce
    comp.windows.x.apps
X FAQs:
    ftp://ftp.x.org/contrib/faqs/
X FAQ on the World Wide Web:
    http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-1
    http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-2
    http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-3
    http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-4
    http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-5
    http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-6
    http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-7
X Window System book info on the Web:
    http://www.x.org/ftp/contrib/docs/Xbibliography.OReilly
    http://www.ora.com/catalog/v1/
    http://www.ora.com/catalog/v2/
    http://www.ora.com/catalog/v3/
    http://www.ora.com/catalog/v4/
    http://www.ora.com/catalog/v5/
    http://www.ora.com/catalog/v6a/
    http://www.ora.com/catalog/v6b/
    http://www.ora.com/catalog/v6c/
    http://www.ora.com/catalog/r6/noframes.html
    http://www.ora.com/oracom/prog/flanart.html
World Wide Web - X Window System info sites
    http://www.x.org/
    http://www.x.org/consortium/GettingX.html
    http://www.x.org/consortium/x_info.html
    http://www.x.org/consortium/R6.1doc/man/X11/
    http://www.wolfram.com/~cwikla/widget/
    http://www.zeta.org.au/~rosko/pigui.htm
    http://www.rahul.net/kenton/xsites.html
    http://www.unx.com/DD/txaCurrent.shtml

Return to table of contents

7.B. What training is available? Many suppliers offer Perl classes. CL knows of no current list that even pretends to be comprehensive.

Few of these training sessions cover Perl/Tk. CL knows of none currently scheduled in 2001.

Return to table of contents

8. How do I write scripts in Perl/Tk?

Start your script as you would any perl script (e.g. #!/usr/bin/perl, #!/usr/local/bin/perl, #!/opt/bin/perl, [built static? then #!/usr/bin/tkperl], whatever, see the perlrun(1) man page for more information).
Throwing the -w warning switch is recommended.
The use of the statement use strict; is recommended.
Use of the statement use Tk; is required.

A simple "Hello World!" widget script could be written as follows:

    #!/usr/local/bin/perl -w

    use strict;
    use Tk;

    my $main = new MainWindow;
    $main->Label(-text => 'Hello World!'
                 )->pack;
    $main->Button(-text => 'Quit',
                  -command => sub{exit}
                  )->pack;
    MainLoop;

Note the use of the -> infix dereference operator. Most things in calls to Perl/Tk routines are passed by reference.

Note also the use of the => operator which is simply a synonym for the comma operator (well it is a bit more than that :-). In other words, the arguments that get passed to Label and Button in the above example are good old perl associative arrays (perl 5 people prefer to call them "hashes" however). Indeed, we might have written the above as:

    #!/usr/local/bin/perl -w

    use strict;
    use Tk;

    my $main = new MainWindow;
    $main->Label(-text , 'Hello World!'
                 )->pack;
    $main->Button(-text , 'Quit',
                  -command , sub{exit}
                  )->pack;
    MainLoop;

    #!/usr/local/bin/perl -w
    use strict;
    use Tk;
    my $main = new MainWindow;

    my %hello = ('-text','Hello World!');
    my %quit_com = ('-text' => 'Quit', '-command' => sub{exit});

    $main->Label(%hello)->pack;
    $main->Button(%quit_com)->pack;
    MainLoop;

Lastly, we note the extensive use of the my function in most Perl/Tk programs. my is roughly equivalent to local in Perl 4 - but is purported to be "faster and safer" as well as much more strictly local in scope. See perlfunc(1) manpage for more information on my.

Other examples of code may be found in the perl5/Tk/demos/ directory and in perl5/Tk/demos/widget_lib/.

(A variant on this scipt called hello is available in the file perl5/Tk/demos/hello in your own pTk distribution. Also, Source code for this and other examples from UserGuide.pod may be found at http://w4.lns.cornell.edu/~pvhp/ptk/pod/. To load code from the web save as a local filename, edit the first line to point to your perl interpreter, then: chmod u+x filename, then execute: filename.)

Return to table of contents

9. What widget types are available under Perl/Tk?

The following Tk widget primitives are available under Perl/Tk:

• Button
• Canvas
• Checkbutton
• Entry
• Frame
• Label
• Listbox
• Menu
• Menubutton
• Message
• Radiobutton
• Scale
• Scrollbar
• Text
• Toplevel

• HList
• InputOnly

A good introduction to the primitives and how they may be used in conjunction with each other may be found in the widget demo script. Note that all the widget demos have a "Show Code" button. To help figure out what is happening in the script you may, when the window appears, edit the text and instrument the code with print statements and then simply press "Rerun Demo". Another place to see examples of the primitives (on the web) is at the image supplement to this FAQ at the following URL:

    http://w4.lns.cornell.edu/~pvhp/ptk/ptkIMG.html

Return to table of contents

10. How do I get widget X to do Y ?

There are a number of tasks that can be accomplished with Perl/Tk widgets, configurations, and bindings (a few that can't and a few that require specific tricks). Beginners are encouraged to work through the examples in UserGuide.pod. Some examples from UserGuide.pod are addressed in this document among those that follow.

Basically a widget can be "created" by simply calling the sub of the same name:

    my $main = new MainWindow;

    $main->Button();

    my $button = $main->Button();

    $button -> pack;

    #!/usr/bin/perl -w
    use Tk;
    use strict;
    my $main = new MainWindow;
    my $button = $main -> Button();
    $button -> pack;
    MainLoop; 

    #!/usr/bin/perl -w
    use Tk;
    use strict;
    my $main = new MainWindow;
    my $button = $main->Button();
    $button -> configure(-text => 'Press me!');
    $button -> pack;
    MainLoop; 

    #!/usr/bin/perl -w
    use Tk;
    use strict;
    new MainWindow -> Button(-text => 'Press me!') -> pack;
    MainLoop; 

Do not overlook the - sign in front of some options (like -text in the above example) Another commonly overlooked problem is that elements in a hash are supposed to be strings hence a configuration option like -length +> 5, really ought to be specified as either '-length' +> 5, or "-length" +> 5, etc., rather than perl's builtin length() function.

Return to table of contents

10.1. How do I get a Button to call a Perl subroutine?

You may specify the -command option in the call to create & pack the button as in:

    $main->Button(-text => 'Print',
                   -command => sub{do_print($filename, $font)}
                   )->pack;

(Full source code for this and other examples from UserGuide.pod may be found at http://w4.lns.cornell.edu/~pvhp/ptk/pod/. To load code from the web save as a local file say ex1.pl, edit the first line to point to your perl interpreter, then change permission: %chmod u+x ex1.pl, then execute the script: %ex1.pl.)

The above method is called the "anonymous subroutine (closure)" method. As discussed in Callback.pod one might have re-written that statement to use the "reference to a sub" method thusly:

    $main->Button(-text => 'Print',
                   -command => [ \&do_print , $filename, $font ]
                   )->pack;

Return to table of contents

10.2. How do I get a Button to actively change under my mouse pointer?

You should specify both an '-image' and an '-activeimage' configuration option either when calling the ->Button() method or in a later separate call to the ->configure() method.

Here is an example excerpted from the basic_demo script that comes with the Tk kit:

    #!/usr/local/bin/perl -w
    
    use Tk;
    
    $main = MainWindow->new;
    
    $QPBFile  = "demos/images/QuitPB.xpm";
    $QPBaFile = "demos/images/QuitPBa.xpm";
    
    $QuitPB  = $main->Pixmap('-file' => Tk->findINC("$QPBFile"));
    $QuitPBa = $main->Pixmap('-file' => Tk->findINC("$QPBaFile"));
    
    my $but  = $main->Button('-image'       => $QuitPB,
                             '-activeimage' => $QuitPBa,
                             '-command'     => sub { $main->destroy }
                            ) -> pack;
    
    MainLoop;
    
    __END__
    

Return to table of contents

10.3. How do I arrange the layout of my widgets?

To control the layout and appearance of widgets in a window one makes use of a geometry manager, as well as -padding, -fill, -expand, and -anchor options of individual widgets.

A geometry manager is any Tk procedure for controlling the arrangement of widgets in your application window. The predominant geometry manager used in both Tcl/Tk and Perl/Tk is pack also known informally as the "packer" (other geometry managers are the "placer" and the canvas widget itself but are much less popular. There is also Nick Ing-Simmon's Table widget [discussed in a later question] and BLT_Table [which made it's way into Perl/Tk thanks to Guy Decoux - but is also discussed in a later question]. So far tixForm is for Tcl/Tk only, but a Perl/Tk version of Tix is in the works. You can invoke pack at the time of widget creation via calls like:

    $widget->pack;

    $widget(-option0 => value0,-option1 => value1)->pack;

    my $top2 = $main->Toplevel;
    my $frame = $top2->Frame;
    $frame->pack;
    $frame->Label(-text => 'Left2')->pack(-side => 'left');
    $frame->Label(-text => 'Right2')->pack(-side => 'right');
    $top2->Label(-text => 'Bottom2')->pack(-side => 'bottom');
    MainLoop;

(Full source code for this and other examples from UserGuide.pod may be found at http://w4.lns.cornell.edu/~pvhp/ptk/pod/. To load code from the web save as a local file say ex2.pl, edit the first line to point to your perl interpreter, change permission using: chmod u+x ex2.pl, then type the name of your script: ex2.pl.)

One of the more helpful options to pass to pack when trying to get a given widget layout "just right" is through padding: either -padx or -pady. The details of the use of pad depend on which specific widget you are trying to pack. In fact you can often add the -pad in the call to create the widget rather than in the call to pack.

There is also the -anchor configuration option for widgets. A good introduction to the 9 possible -anchor (and -overanchor) values is given by the popup demo in your Perl/Tk build directory.

When setting a widget within a frame next to another widget one may wish to make use of the -fill => 'style' (where style = none | x | y | both) options of either pack or the widget itself. A typical situation where this is used is in setting up the Scrollbar next to a Canvas or Text widget.

Another aspect to consider when laying out your widgets is their behavior under resize operations (grabbing a part of the window frame and making it bigger or smaller - details depend on your window manager). This may be controlled by the -expand option of either pack or the widget itself.

Return to table of contents

10.4. How do I get a Popup to popup?

For things like a simple "are you sure?" dialog box you might want to take a look at Dialog.pm which is discussed in a later question within this FAQ [16.1].

If you don't wish to require Tk::Dialog, you need something more complicated, or you simply want to create your own independent window with widgets; you must first setup a Toplevel in Perl/Tk. The fourth example in UserGuide.pod gives a simple example of how to call Toplevel. Quoting from that script:

    my $main = new MainWindow;
    fill_window($main, 'Main');
    my $top1 = $main->Toplevel;

The use of Toplevels brings up the issue of grab - or which independent window is presently "active" and which are activatable. To make a Toplevel window active call grab thusly:

    $Top_widget->grab(grab_option);

    $Top_widget->grab;

The use of Toplevels may also bring up the issue of focus - or which window - even which widget within a window - is presently "hot". You may call focus on an entire Toplevel:

    $Top_widget->focus;

To de-iconify a widget there is in fact a Popup function that may be called thusly:

    $Top_widget->Popup();

Return to table of contents

10.5. How do I bind keyboard keys?

There are many default key bindings built in to the widgets of Perl/Tk. Making proper use of them often involves setting up the right callback. (You may wish to consult the examples in BindTable.pod for help with this subject.)

The basic idea is:

    $widget -> bind('<keyname>' => action);

    <Key> or <KeyPress> or <Any-KeyPress>
    <KeyRelease>
    <Button> or <ButtonPress>
    <ButtonRelease>
    <Button-1> or <B1> 
    <Double-1>
    <Enter>
    <Leave>
    <Motion>

    perl -ne 'print if s/.*(<[^>]*>).*/$1/g;' Button.pm

To get an idea of what the code is for a key that you are interested in try running the xlib_demo that comes in your Perl/Tk build directory. Hold your mouse pointer over the window that appears and simply type the key that you are interested in. The code should appear in the window. If you do not have Perl/Tk up and running yet try "xmodmap -pk" or look directly at the /usr/include/X11/keysymdef.h file where keysym names are given with an XK_ pre-pended. Do not try things like the Tcl/Tk %k symbols in perl scripts. %Ks will be mis-interpreted as non-existant perl hashes. Instead look at the Xevent function.

Ali Corbin <corbin@adsw.fteil.ca.boeing.com> recently posted a great little script for determining keyboard key bindings on a MainWindow:

    #!/usr/local/bin/perl -w
    use Tk;
    $top = MainWindow->new();
    $frame = $top->Frame( -height => '6c', -width => '6c',
                            -background => 'black', -cursor => 'gobbler' );
    $frame->pack;
    $top->bind( '<Any-KeyPress>' => sub
    {
        my($c) = @_;
        my $e = $c->XEvent;
        my( $x, $y, $W, $K, $A ) = ( $e->x, $e->y, $e->K, $e->W, $e->A );

        print "A key was pressed:\n";
        print "  x = $x\n";
        print "  y = $y\n";
        print "  W = $K\n";
        print "  K = $W\n";
        print "  A = $A\n";
    } );
    MainLoop();

    #!/usr/local/bin/perl
    use Tk;
    $top = MainWindow->new;
    $lb = $top->Listbox(-height => 10);
    for($i=0; $i < 120; $i++) {
      $lb->insert('end', $i);
    }
    $f = $top->Frame;
    $up = $f->Button(
           -text => "Up",
           -command => [ $lb->bind(ref $lb, '<Up>'), $lb]
           );
    $down = $f->Button(
             -text => "Down",
             -command =>sub {&{$lb->bind(ref $lb, '<Down>')}($lb)}
             );
    $up->pack(-side => 'left');
    $down->pack;
    $f->pack;
    $lb->pack;
    MainLoop;

Return to table of contents

10.6. How do I add bindings? How do I change or remove bindings?

On Fri, 15 Sep 95 10:30:56 BST Nick Ing-Simmons <Nick.Ing-Simmons@tiuk.ti.com> writes:

Re: Multiple binds to a single widget?
**************************************

On Thu, 14 Sep 1995 14:57:54 -0400
Alain St <astdenis@cmc.doe.CA> writes:
!In the tcl/tk doc I have, they say that prepending the script 
!with '+' appends the new binding to the current one.
!
!How do I do that in perlTk? 
!

You cannot do that that way (yet?) - one issue is what it would mean to prepend '+' to a Perl/Tk callback :

    $widget->bind('<A>','+',[\&subname,$arg]); 
    # did not look right to me

Other issue is that I would need to manage a list-of-callbacks in glue code.

Bind your new command to a new tag:

    $widget->bind('Extra',....);

And add Extra to the widgets bindtags:

    $widget->bindtags([ref($widget),$widget,'Extra',
                        $widget->toplevel,'all']);

1. Make a subclass for the widget and put the changed and removed bindings into the ClassInit method:

       package Tk::NewTextClass;
       use base qw(Tk::Text);
       Construct Tk::Widget 'NewTextClass';
       sub ClassInit {
   	my($class,$mw) = @_;
   	$class->SUPER::ClassInit($mw);
   	$mw->bind($class,'' => \&Tk::NoOp); # remove
   	$mw->bind($class,'<1>' => sub { warn "B1 pressed" }); # change
       }
     

2. Change the binding order by using the bindtags() method. In contrast to Tcl/Tk, Perl/Tk class bindings normally precede widget bindings:
   • Tk::WidgetClass
   • .toplevel.widgetpathname (that is, the string $widget->PathName returns)
   • .toplevel
   • all
   Use bindtags() to change the order, and bind() to overwrite or remove bindings:

        $widget->bindtags([$widget,ref $widget,$widget->toplevel,'all']);
        $widget->bind(...);
   

Return to table of contents

10.7. How do I bind the action of a slider (sic) to ... ?

Technically speaking they are called Scrollbars (not sliders) and one must configure the action of the desired widget to ca