/ 
Qtk-QuickTk-0.88
/ Qtk::QuickTk

NAME

Qtk::QuickTk - A Simpler Syntax for Perl-Tk GUI Building

SYNOPSIS

use Tk;
use Qtk::QuickTk

# need to set $filename, e.g.:  my $filename='miniapp.qtk';

my $app=Qtk::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'Qtk::QuickTk=app' -e app $0;exit

REQUIRES

QuickTk uses modules: Text::TreeFile (optionally), Tk, FileHandle, Carp, English, Exporter and Autoloader.

DESCRIPTION

QuickTk supports a simplified 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.

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 -------------------------------
exec /usr/bin/perl -M'Qtk::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 Qtk::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

By default, Qtk::QuickTk uses the Text::TreeFile module to read a file containing a GUI specification, in the QuickTk mini-language. The low-level format of this file is as follows. Each widget is specified in a node of the tree in such a file. The language for widget specifications is described further below.

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 represent 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 ("E<lt>" and "E<gt>").

See "EXAMPLES", or Qtk::QuickTk::scripts(3pm), for clarification.

Here are samples of each of the four kinds of specifications:

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 it. The QuickTk module provides a good many simplifications of syntax, though, and details of these are described in Qtk::QuickTk::details(3pm), Qtk::QuickTk::scripts, and demonstrated in the example scripts.

CAVEATS

QuickTk provides none of the GUI-building widgets, functions or other facilities. It provides only for 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.

AUTHOR

John Kirk <johnkirk@dystanhays.com>

COPYRIGHT

Copyright (c) 2000 John Kirk. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Text::TreeFile(3pm) - for the low-level file format it supports,

Qtk::QuickTk::scripts(3pm) - for exhaustive description of the syntax,

Qtk::QuickTk::details(3pm) - for precise definition of usage details,

Qtk::QuickTk::internals(3pm) - for implementation details,

Tk::UserGuide(3pm) - for an introduction to perl-tk,

Widget(1) - for examples of most of the perl-tk widgets, etc.,

and http://perl.dystanhays.com/jnk - for related material on this module.

BUGS

Uses (deprecated for libraries) English(3pm), which should be removed.

Also, exceptions are handled poorly, inconsistently and unclearly. The Carp(3pm) module should be used, the behavior should be made more clear, and the exceptions should be handled in a consistent manner.

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.