Tk::QuickTk::scripts - exhaustive description of the syntax
(example script, actually)
exec /usr/bin/perl -M'Tk::QuickTk=app' -e app $0;exit m MainWindow title:'QuickTk Minimal Demo' mb Frame side:top fill:x : f Menubutton side:left : text:File o command label:Open sub:my($wid)=@_; ...my $out=$$w{mts};my $tf=$$w{mtf}; ...$$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 command label:Quit sub:print "ok 8\n";exit; t Menubutton side:left : text:Tool d command label:'Directory Listing' ... sub:$$gl{widgets}{mts}->insert('end', ... `pwd`);$$gl{widgets}{mts}->insert('end', ... `ls -alF`);print "ok 3\n"; s command label:Satisfaction sub:print "ok 4\n"; h Menubutton side:right : text:Help a command 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:.
A nearly identical version of this script is delivered in ready-to-execute form as a file called "test.pl" for testing the install of the current module. Before "make install" is performed this script should be runnable with "make test". After "make install" it should work as "perl test.pl".
The differences are that the executable form lacks the first line, above, and is embedded as an explicitly-coded data structure -- and when it is executed, it displays instructions for a series of actions to take to test a few of its behaviors. Several of these actions add information to the main (bottom) text window, that you'd need to scroll-down to view. Executing that script, as described, works if your current directory is the one in which the module build occurred. Try executing the command, "locate Tk::QuicTk" to find where the build occurred (which would depend on your having the "locate" command installed as well).
This document attempts to completely specify the QuickTk mini-language. Everything you need to know to write GUI applications with this module should appear here, assuming you are familiar with the perl-tk (the Tk.pm module, and friends) library to which QuickTk provides simpler access.
Note 1: The best way to get acquainted with how to write scripts is, of course, to look at examples. Several of them are provided, chosen to be representative of a wide range of features exercised. A plan is afoot to reference them directly in documentation, where features are described and, perhaps, vice-versa.
Note 2: Current documentation describes a number of unix-specific features and ways of operating, without identifying them as non-portable. (witness the next couple of paragraphs, for instance) QuickTk works well in other contexts, but we've been slow about properly flagging the caveats. The plan is to correct the documentation soon.
The most common way to use QuickTk is to make a script in a file whose first line is the following (Make sure the absolute path reference to your perl binary executable is correct, though.):
exec /usr/bin/perl -M'Tk::QuickTk=app' -e app $0;exit
When the script is executed by your shell, this should cause perl to be started (without creating a new process), bringing in the QuickTk module and asking it to import the app() function into the main:: namespace. Then it executes app() and makes the name of your script ($0, above) the first (the only) command-line argument to the executing perl program. The app() function will request module Text::TreeFile to come back and read your script into a tree-of-text-strings data structure (respecting comments, continuation lines, include-file requests, and strict two-space-per-level indentation to indicate parent-child nesting of tree nodes) which will then be interpreted and executed by QuickTk as a GUI application specification, where each text string is taken to specify a widget or event binding. See Text::TreeFile(3pm) for more details of that format, and Tk(3pm) and manpages for the other Tk::*(3pm) modules, for information about the functionality available to your application.
QuickTk provides a hash, returned by the new() constructor, which is blessed into the Tk::QuickTk class as a namespace for variables which are "global" to the application. Perl code included in the script will be evaluated in a context which provides both a reference to this hash (as variable, $gl), and a reference to another hash within it (as variable, $w, which is short for, and synonymous with, $$gl{widgets}) for convenience.
The upshot of this is that the following conventions are enabled, for referring to variables (objects) in QuickTk. First, to use a global variable named "var", you specify the syntax, "$$gl{var}". Second, to indicate a variable by reference (used in "-textvariable" options, for instance) you specify the syntax, "\$$gl{var}", for the example variable mentioned above. Third, to refer to a widget previously created, you use the name you specified as the very first field in the spec for that widget ("m", in the first example line, below) as the key to either the "$gl->{widgets}" hash (e.g. $$gl{widgets}{m}, or $gl->{widgets}->{m}) or for short, to the "$w" hash (e.g. $$w{m}, or $w->{m}), for the MainWindow widget specified in the first example line, below. This is commonly done for the purpose of accessing object methods of a widget.
Here are several examples of using application variables:
First, a QuickTk spec makes a main window, with a title:
m MainWindow title:'QuickTk Demonstration Application'
then, later, some code (in a callback, perhaps) gets executed:
$$w{m}->configure(-title=>'QuickTk (updated) Demo App'); print "The MainWindow title is now: ", $$gl{widgets}{m}->cget(-title),"\n";
Note that, above, the "m" in $$w{m} and in $$gl{widgets}{m} is a direct reference to the "m" which is the first field in the QuickTk widget spec shown just previously.
Also note that the MainWindow is referred-to both via the short $$w{m} form and the longer, more explicit, $$gl{widgets}{m} form, in different places.
The name by which you refer to a widget in your code ("m", in the example above) will be the concatenation of all the ancestors' names, and the one for the current widget, as specified in the name field of your script's widget spec. Thus, note in the example in "SYNOPSIS", a widget is accessed using the name, "mts", as: "$$gl{widgets}{mts}" while the widget is identified with only "ts" in the script. This is because the "ts" widget is a child of parent "m", yielding "mts" as the fully qualified, complete name.
These two QuickTk widget specs may occur in widely separated parts of the user interface for an application:
mce Entry pack:left : textvariable:\$$gl{inp} mcp Label pack:left : textvariable:\$$gl{inp}
As text is typed into the Entry widget, it will show immediately (simultaneously) in the Label widget.
Text entered into the Entry widget will be kept in the variable named "input", and the Label widget will show text from the variable named "display". Only when the Button is pressed will the text in the variable named "input" get copied into the variable named "display" and, thus, be displayed by the Label.
mce Entry pack:left : textvariable:\$$gl{input} mcp Label pack:left : textvariable:\$$gl{display} mcb Button pack:left : text:Update sub:$$gl{display}=$$gl{input};
The remainder of this document is devoted to enumerating and describing use of the (mostly syntactic) features that the QuickTk language provides. We will call each node of the tree representing your GUI specification either a "node", a "widget spec", or a "spec" (for short). There are some commonalities among all specs, but differences are important among the formats of the four basic spec types:
Either a MainWindow or a TopLevel widget spec.
This type refers to widgets that are children of a Menubutton or Menu widget. The Tk library provides five of these, as described subsequently in this document.
This is sometimes referred to as an event or binding, for short. This type is a spec that's not a widget but, rather, a binding of an action to a particular event that may occur in the parent widget's window.
This type of spec is sometimes called just widget, for short. This is the most common spec, referring to any other widget in the Tk library's repertoire not mentioned in the first three categories.
All specs are of the form:
<ID section> <arguments section>
and the arguments section can have either or both of:
<packing options> : <configuration options>
although the composition of each (ID or arguments) section will be somewhat different among the four main spec types. Options are all specified as:
<option name>:<option value>
but note that the colon (":") character, above, must not have any surrounding spaces while the one separating the configuration options from the packing options (shown previously) must be surrounded by spaces.
Looking at the examples provided will give the best introduction to writing specifications, but this document offers precise definition of the conventions for reference use. Of course, the module code is relatively brief, so reading that can be a practical arbiter in case of failure to communicate on the part of this document.
We'll describe the differences among the four main spec types first for the ID section, and next for the arguments section. Then, we will enumerate the details (held in common among all the spec types) of specifying option arguments.
The ID section always follows the indentation and is delimited from any following arguments by spaces. The differences, for each main spec type are as follows:
The ID section for these specs has two parts, delimited by spaces. The first part is a name that will be used as a hash key to allow the application to refer directly to the widget subsequently to its creation. The second part is the name of the widget type (chosen from the perl-tk library documentation) for the widget to be created. e.g. Button, Menubutton, MainWindow, or TopLevel.
The ID section for these specs has two parts, delimited by spaces. The first part is a name that will be used to construct a hash key to allow the application to refer directly to the widget subsequently to its creation. The second part can be either a single character indicating one of the five widget types provided by Tk, or the name that Tk uses, itself, as shown in the chart below. The widget types allowed are:
letter Tk name description of effect when menu item is chosen ------ ----------- ----------------------------------------------- c command -- an action to perform m cascade -- a submenu to post - separator -- no action (separates groups of menu items) k checkbutton -- sets values of any of several boolean variables r radiobutton -- sets one of several values for a variable
The ID section for these specs has only a single part, recognized by surrounding angle brackets ("<" and ">"). This part identifies the event (which may occur in the parent widget's window) that is to be bound to the action specified in the arguments section. Examples of events are: "<Tab>", "<CR>", "<Button>", "<Double-Click>", "<Right-Click>", "<A>" and "<Ctrl-A>".
There are three formats, depending on whether you have options in both, or just one category:
<packing options> : <configuration options> : <configuration options> <packing options>
These widget types take no <packing options>, so the format is simple:
<configuration options>
This kind of spec only needs the action to be bound to the event:
<action bound to event>
There are six variations of the form of a single item in the list of <packing options> or <configuration options> in the <arguments section>, as follows. The <option name> and <option value>, except where noted as otherwise, are always chosen from available possibilities documented in the perl-tk documentation. The six syntax variations are:
The most generic case, if none of the other cases applies, has an <option name> and an <option value>, neither of which contains embedded space characters. These are separated by a colon (":") character which has no space characters adjacent to it. The format is:
The <option value> may be single-quoted, to allow embedded space characters within it. The format is:
<option name>:'<option value>'
<option value> may be null or not. This is handled differently, depending on whether it occurs as a packing or configuration option.
The <option value> may be absent. This is used for lone (not of the <name>=><value> form) leading arguments to the configuration or geometry manager functions in perl-tk. The format is:
<option name>:
This is handled differently, depending on whether it occurs as a packing or configuration option.
The <option value> may be absent, and the colon delimiter omitted, in certain cases (for the ones not specially introduced by QuickTk). The format for these option items is, simply:
<option name>
This applies to any option name that's not a <special option>
QuickTk introduces some special-function <option name> choices, to enable a way for a script to invoke functionality the generic form of the syntax doesn't provide. These occur only in a list of <packing options>. The format for these option items is, simply:
<special option>
There are five of these special-function <option name> choices. Their names and meanings are:
This widget spec should be remembered for use later, but should not be created on startup. A callback specified as the action for some widget or event may call the createwidget function to create instances of this widget when it is needed.
This widget should be created, but not mapped to the screen to become visible on startup. It may be made visible on demand, later.
This is the default case, and is usually omitted. The possibility for specifying it explicitly is included only for consistency.
The place() geometry management function should be used instead of pack(). The other <packing options> are passed to the placer, rather than the packer.
The grid() geometry management function should be used instead of pack(). The other <packing options> are passed to the gridder, rather than the packer.
QuickTk introduces a some additional special-function <option name> choices, that may occur only as the very last option in a spec node. These, thus, allow embedded spaces, and are processed specially for extra convenience. As it turns out, these occur only in the <configuration options> list of the <arguments section>. The format is:
<last option>:<everything to the end of the spec>
There are four of these special <option name> choices, each of which applies only to certain widget types, as indicated:
The entire string after the colon will be executed as perl code, immediately. This allows a script to initialize variables, etc.
The entire string after the colon will become the "-title" configuration option for the widget. This allows long titles to contain embedded space characters, without having to be explicitly quoted.
The entire string after the colon will be parsed as of either of the following forms:
<function> ( <args> ) or: <function>
where <function> must not contain embedded space or parenthesis ("(") characters and may be followed by space characters, and a character string surrounded by parentheses ("(" and ")") may optionally be present. This will be reformatted to become a "-command" configuration option to the widget which specifies a callback in the form:
"-command"=>[main::<function>,$gl,<args>]
This makes the callback refer to a function defined in the main:: namespace, which is called with an implicit reference to the QuickTk blessed hash as its first argument (somewhat like an object method), to allow the function code to access effectively "global" variables for the application. (See "APPLICATION VARIABLES", above.)
The entire string after the colon will be surrounded with "sub { " and " }", and thus evaluated as an anonymous function callback as the value of a "-command=>" configuration option to the widget.
The generated perl-tk code, for arguments to the widget configuration function or the geometry management function will be as:
<option name> becomes "-<option name>"=> if it has a value specified. Otherwise, it (a stand-alone option) is simply surrounded by double-quote characters.
All values specified for packing options are surrounded with double-quote characters.
Generally, values for configuration options will be surrounded with double-quote characters. The exceptions are:
A value which has "$" as its first character is taken to indicate a variable in QuickTk's hash whose key is what follows the "$", so it is modified to: $$gl{<option value without "$">}.
A value which has "\" as its first character is taken to indicate a variable in QuickTk's hash whose key is what follows the "\", so it is modified to: \$$gl{<option value without "\">}.
A value which is surrounded with "[" and "]" is taken to be a reference to an anonymous array specifying a callback and its arguments, and is used as-is.
A value which is a null string specified as "''" will be used as-is. This is a way of making sure the option name is not interpreted specially as a lone option even when the value should be empty.
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.