Tk::QuickTk::details - precise definition of usage details
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 (in the case of a unix-lookalike operating system) 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 document gives precise and exhaustive usage details for the TK::QuickTk module. It describes the variables available to script code, and the constructor and other user-callable functions available.
A hash of variables that are made available everywhere, is often referred-to by the name, $gl. The name, $w, is also made available as a shorter synonym for $$gl{widgets} because it is so often useful.
This variable is where initialization code for the application will be stored, taken from the "ini" configuration option for the MainWindow widget in an application.
This variable is also available to callback code via the name, $w, for short, because it is so often useful. It is a hash containing references to all the widgets of the application, with keys that are the (full) names of each (as the concatenation of all the names given in the specification for the parents and the widget in question).
This variable is boolean, and indicates whether the specification requested code generation only and, thus, no execution of the program.
This variable is a list of the known types for menus.
This variable is the name of the file to which code generation is to be written, if requested.
This variable contains the filehandle of the file to which code generation is to be written, if requested.
This variable contains a reference to the original prototype for the global variables hash, before its contents are copied to the blessed hash for the module itself.
The constructor (function "new") for module Tk::QuickTk can be invoked with zero, one, two or three parameters. The first is a GUI specification, which can take several forms, as below, under "spec"; the second, a filename for logging generated code; and the third, a generate-only flag. If no parameters are specified, an object (a blessed reference to a hash) will be returned with only the prototype entries present. In this case one might create a GUI spec by other external means and put it into the hash.
If at least one parameter is specified, the first will be taken to be the specification for a GUI based application. This spec may be in one of three forms: (1) a filename, (2) a reference blessed into the Text::TreeFile class, or (3) a reference to a tree of text strings, like the one Text::TreeFile would produce.
If the spec parameter is a scalar, but not a reference, it will be interpreted as a filename and passed to module Text::TreeFile to create a tree of strings. This tree will be used as the GUI specification for further processing.
If the spec parameter is a reference that has been blessed into the Text::TreeFile class, the resulting tree of strings will be used as the GUI specification for further processing.
If the spec parameter is a reference to an array of the correct form to be a string tree node, it will be interpreted as the GUI specification for further processing.
If at least two parameters are specified in the call to new(), the second will be interpreted as a filename for output logging of the generated perl-tk code. If the undef value is specified, then logging will not occur. If this parameter is not specified, the default is not to log generated code to a file at all.
If three parameters are specified in the call to new(), the third will be interpreted as a flag indicating whether to execute the perl-tk code generated. If the undef value is specified or this parameter is not specified, the default is to execute the code generated. If a value is specified, then no generated perl-tk code will be executed.
Croaks if a file is indicated for the GUI specification, but a file can't be read, with the name given.
Croaks if the spec parameter can't be interpreted as one of the known types of specification (filename, Text::TreeFile ref, tree of strings, like Text::Treefile produces).
Croaks if initialization code is specified with an "ini" option to the (top-vevel) MainWindow widget, but the code can't be executed.
(nothing written, yet.)
This function is most frequently the only one directly called for an application. It reads a script file, optionally generates Tk code to an output file, and enters the Tk MainLoop which should never return. Thus this function should not produce a return value.
When it is invoked, a commandline parameter must be present, to indicate a filename from which a specification file is to be read by companion module Text::TreeFile.
It can be invoked with zero, one or two parameters. If the first is present, it indicates whether to generate code output for the Tk module to a file.
A filename must be specified on the commandline, for a specification file to be read by the Text::TreeFile companion module, to use this function. Most frequently, this is the name of the script file that invoked the app() function (see the second example in SYNOPSIS, above -- the line that begins with "exec ").
If a first parameter is specified in calling app(), it may be 'nogen' or any other value (e.g. 'gen'). If 'nogen' is specified, app() will not generate code to a file (the default behavior).
Otherwise, I<app()> will generate Tk code to a file for later perusal or execution. In the latter case, if no output filename is specified in a second parameter, the (commandline) input filename -- with '.pl' appended -- will be used as the filename for the generated code file to be output.
If two parameters are specified, and the first isn't 'nogen', the second will be taken as the name -- with '.pl' appended -- for the generated code file to be output,
Carps if the commandline has no arguments specified when this function is called.
It looks as if when the function carps (as above) because no filename was provided on the commandline, it still enters the Tk MainLoop.
(Nothing written yet.)
Creates and packs a widget specified earlier, but with the 'nocreate' packing option. It's called by a callback function, on the fly, during execution of the application, at the time the widget is to be created and packed to show up on the screen. The createwidget() method takes two parameters:
A reference to an array containing values to which the QuickTk script widget specification refers, by names $0, $1, ...,
The name of the widget specified earlier in the script, with the 'nocreate' packing option set. This would normally be called by a callback function specified somewhere in the script, to create a widget previously specified but not yet created. The description of the widget to create had been saved, at 'nocreate' time, in an array with eight elements:
The hierarchical nesting level, from the MainWindow as level 0.
The name of the parent of the widget to create.
If this widget is a menuitem, the sequential index of the item in the parent menu.
The name of the widget to create.
The Tk widget type of the widget to create.
The configuration options for the widget.
The packing options for the widget.
The children to create nested within this widget.
croaks if there's no widget by the name given.
croaks if
(Nothing written, yet.)
(Not written yet.)
Nothing is exported by default. Functions app() and createwidget(), may be imported on request. The module's new() function returns a blessed reference to a hash which contains a number of data items. (Refer to Tk::QuickTk::internals for details, if you want them.) This hash acts as a global repository for variables accessible to the application. See Tk::QuickTk::scripts for instruction and sample uses of this facility.
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.