Tk::QuickTk - Simple, declarative syntax for a Perl/Tk GUI =head1 SYNOPSIS
use Tk; use Tk::QuickTk # need to set $filename, e.g.: my $filename='miniapp.qtk'; my $app=Tk::Quicktk->new($filename); die "QuickTk constructor unable to read GUI spec: $filename\n" unless defined $app; MainLoop;die "QuickTk fell through past MainLoop\n";
or, alternatively, make a QuickTk script directly executable, with the following first line (see full demo script in EXAMPLES, below:
exec /usr/bin/perl -M'Tk::QuickTk=app' -e app $0;exit This executes the "app" method of the QuickTk module as a top-level application which re-reads the script, executing it (by pre-processing it into code that the Perl Tk module knows how to handle) via Perl-Tk.
QuickTk requires Perl ver. 5.002, and uses modules: Tk, Text::TreeFile (optionally, but by default), FileHandle, Carp, Exporter and AutoLoader.
QuickTk supports a simplified, declarative, syntax for specifying GUI-based applications using perl-tk (module Tk.pm and friends). A companion module, Text::TreeFile, supports comments, include-files, continuation lines and special interpretation of a strict indentation convention to indicate tree-like hierarchical nesting. Each node of a QuickTk GUI specification is a character string which succinctly and clearly specifies the properties of a GUI widget or event binding. Such specification documents are quick and easy to write, read and maintain.
Stub documentation for this module was created by ExtUtils::ModuleMaker.
The GUI specification can be provided to QuickTk in any of several forms, the generated code can be logged to a file, and execution of the code can be avoided, to allow code-generation only.
------ executable as a shell script in a Unix-like environment --------- exec /usr/bin/perl -M'Tk::QuickTk=app' -e app $0;exit # file: miniapp m MainWindow title:'QuickTk Minimal Demo' mb Frame side:top fill:x : f Menubutton side:left : text:File o c label:Open sub:my($wid)=@_; ...my $out=$$w{mts};my $tf=$$w{tf}; ...$$gl{efile}=$tf->Show;$$gl{eww}=0; ...my $fh=new FileHandle "<$$gl{efile}"; ...while(<$fh>) { $out->insert('end',$_); } ...close $fh;$out->yview('1.0');print "ok 2\n"; q c label:Quit sub:print "ok 8\n";exit; t Menubutton side:left : text:Tool d c label:'Directory Listing' ... sub:$$gl{widgets}{mts}->insert('end', ... `pwd`);$$gl{widgets}{mts}->insert('end', ... `ls -alF`);print "ok 3\n"; s c label:Satisfaction sub:print "ok 4\n"; h Menubutton side:right : text:Help a c label:About sub:$$gl{widgets}{mts}->insert('end', ... 'this is a demo of perl module Tk::QuickTk'); ... print "ok 5\n"; tb Frame side:top fill:x : d Button side:left : text:Dir ... sub:$$w{mts}->insert('end',`ls -alF`); ... print "ok 6\n"; q Button side:left : text:Geom sub:$$w{mts}->insert('end', ... "geom: ".$$w{m}->geometry."\n"); ... print "ok 7\n"; ts Scrolled side:top fill:both expand:1 : Text: scrollbars:osoe tf FileSelect nopack : directory:. -------------- end of executable shell script example ---------------------
You specify a complete application in the QuickTk mini-language usually as a hierarchy (outline, or tree) of "widgets", one nested within another, in a file. By default, Tk::QuickTk uses the Text::TreeFile module to read the file. It provides file inclusion, a way of writing comments, and interpretation of your indentation to indicate hierarchical nesting.
The language for specifying each widget is described, below, in "WIDGET SPECIFICATIONS".
The low-level format of a Text::TreeFile file is as follows. Each widget is specified as a node of the hierarchy in such a file.
The file format supported relies upon indentation of text strings, to indicate hierarchical nesting for the tree structure. Strict indentation (of two space characters per nesting level) is used to indicate parent-child structure.
A line consisting exclusively of whitespace, or a line beginning with either the pound-sign ("#"), the semicolon (";"), or the forward slash ("/") character will be ignored as a comment. In the very first line of a file, the initial characters, "exec ", will indicate a comment line.
A line beginning with whitespace followed by three period (".") characters, will be concatenated to the previous line, as a continuation. The preceding end-of-line, the initial whitespace and the ellipsis ("...") will be removed and otherwise ignored, to allow long strings to be represented within line-length constraints.
In addition, any line consisting of indentation followed by "include" will be interpreted as a file-include request. In this case, succeeding whitespace followed by a file specification will cause the contents of the named file to be substituted at that point in the tree. The included file will be sought in the same directory as the file including it.
The basic format for GUI widget specifications is a text string that has two parts. The first is an ID section which identifies the widget, and the second is an arguments section which provides the specifics of how the widget is to be configured.
There are four kinds of specifications, each with a variation in the details of these two parts. In the most common case (that for MainWindow and most other widgets), the ID section is made of two subparts. First is the name your script can use to reference the widget later, and second is the widget type name, chosen from the many available in the Tk widget library (e.g. Button, MainWindow, Menubutton).
In the special case of a menu item, the second part of the ID section can be a single letter identifying one of five types of available menu items, for short, or the name of the type itself. The name subpart must be unique only within the same level of indentation under a parent widget, because the name you will use to refer to the widget will usually (automatically) be the concatenation of its name with all its ancestors' names.
For specifications of bindings of events to actions, the ID part is a single event identifier enclosed in angle brackets ("<" and ">").
See "EXAMPLES", or Tk::QuickTk::scripts(3pm), for clarification and more detail.
Here is a sample of each of the four kinds of specifications (note it's as if there were four "columns" or "fields" possible):
m MainWindow title:'QuickTk Demo' f Menubutton side:left : text:File o c label:Open sub:exit; <CR> sub:$$gl{command}=$$gl{inputline};
Each of the four kinds of specifications can have arguments provided. There are two categories of arguments, and these are separated by a colon (":") character which, itself, is surrounded by spaces. The first type of arguments is the "packing options" and the second is the "configuration options". The packing options (and the colon delimiter) are not specified for three of the four kinds of specifications. These are the MainWindow, the menu items, and the event bindings. The packing options are used for the most common widget specifications -- the ones for generic widgets -- so these specifications will always have the space-surrounded colon delimiter unless no configuration option arguments need to be specified.
To write these specifications you must be acquainted with the perl-tk (module Tk.pm) library of widgets and how to use the widgets you want. The QuickTk module provides a good many simplifications of syntax, though, and details of these are described in Tk::QuickTk::details(3pm), Tk::QuickTk::scripts, and demonstrated in the example scripts.
QuickTk provides none of the GUI-building widgets, functions or other facilities. It provides only a simplified syntax for accessing the capabilities and features of perl-tk (the perl module, Tk(3pm) and friends), so familiarity with those materials is prerequisite to using QuickTk.
Documentation is incomplete (although the module code is very short, thus somewhat accessible) and examples are not very thorough.
The code is ready for an overhaul to reduce near-duplication and improve modularity.
Also, exceptions are handled poorly, inconsistently and unclearly. The behavior should be made more clear, and the exceptions should be handled in a consistent manner.
Support is available from the author, by email, as below.
John Kirk CPAN ID: JNK Dystan Hays Studios jnk@cpan.org http://perl.dystanhays.com/jnk
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
(scripts: puzzle, pickhues, miniapp, ...)
Tk::QuickTk::scripts(3pm) - for exhaustive description of the syntax,
Tk::QuickTk::details(3pm) - for precise definition of usage details,
Tk::QuickTk::internals(3pm) - for implementation details,
Text::TreeFile(3pm) - for the low-level file format it supports,
Text::TreeFile::details(3pm) - for more explicit detail,
Text::TreeFile::internals(3pm) - for internal code information,
Tk::UserGuide(3pm) - for an introduction to perl-tk,
Tk(3pm) - for the Perl Tk (sometimes called perl-tk) module,
widget(1) - for examples of most of the perl-tk widgets, etc.,
and http://perl.dystanhays.com/jnk - for related material on this module.
perl(1) - for the Perl language.
To install Tk::QuickTk, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tk::QuickTk
CPAN shell
perl -MCPAN -e shell install Tk::QuickTk
For more information on module installation, please visit the detailed CPAN module installation guide.