NAME

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.

REQUIRES

QuickTk requires Perl ver. 5.002, and uses modules: Tk, Text::TreeFile (optionally, but by default), FileHandle, Carp, Exporter and AutoLoader.

DESCRIPTION

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.

OPTIONS

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.

EXAMPLE

  ------ 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 ---------------------

FILE FORMAT

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.

Indentation

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.

Comments

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.

Continuation Lines

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.

Include Files

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.

WIDGET SPECIFICATIONS

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.

Widget ID

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};

Widget Arguments

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.

CAVEATS

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.

BUGS

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

Support is available from the author, by email, as below.

AUTHOR

    John Kirk
    CPAN ID: JNK
    Dystan Hays Studios
    jnk@cpan.org
    http://perl.dystanhays.com/jnk

COPYRIGHT

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.

SEE ALSO

(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.