/ 
Tk-QuickTk-0.92
River stage zero No dependents
/ Tk::QuickTk::details

NAME

Tk::QuickTk::details - precise definition of usage details

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

DESCRIPTION

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.

GLOBAL VARIABLES: $gl

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.

$$gl{inicode}:

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.

$$gl{widgets}:

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

$$gl{genonly}:

This variable is boolean, and indicates whether the specification requested code generation only and, thus, no execution of the program.

$$gl{menutypes}:

This variable is a list of the known types for menus.

$$gl{lname}:

This variable is the name of the file to which code generation is to be written, if requested.

$$gl{lfh}:

This variable contains the filehandle of the file to which code generation is to be written, if requested.

$$gl{_prop}:

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.

FUNCTION: new [ spec, [ codeout, [ genonly ] ] ]

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.

Parameter: spec

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.

spec parameter: as filename

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.

spec parameter: as Text:TreeFile ref

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.

spec parameter: as tree of strings

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.

Parameter: codeout

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.

Parameter: genonly

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.

Throws: Exceptions and other anomolies

"can't read QuickTk spec file: filename"

Croaks if a file is indicated for the GUI specification, but a file can't be read, with the name given.

"can't make a new Tk::QuickTk from spec: spec"

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

"failed to execute initialization code"

Croaks if initialization code is specified with an "ini" option to the (top-vevel) MainWindow widget, but the code can't be executed.

See Also:

(nothing written, yet.)

FUNCTION: app [ [ genonly ] gfilename ]

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.

(Commandline) Parameter: input spec filename

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 ").

Parameter: gen (optional)

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.

Parameter: gname (optional)

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,

Throws: Exceptions and other anomolies

"Tk::QuickTk::app() found no filename on the command line"

Carps if the commandline has no arguments specified when this function is called.

(Unresolved issue)

It looks as if when the function carps (as above) because no filename was provided on the commandline, it still enters the Tk MainLoop.

See Also:

(Nothing written yet.)

FUNCTION: createwidget args specname

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:

Parameter: args

A reference to an array containing values to which the QuickTk script widget specification refers, by names $0, $1, ...,

Parameter: specname

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:

1. $level

The hierarchical nesting level, from the MainWindow as level 0.

2. $momname

The name of the parent of the widget to create.

3. $momidx

If this widget is a menuitem, the sequential index of the item in the parent menu.

4. $name

The name of the widget to create.

5. $type

The Tk widget type of the widget to create.

6. $cfg

The configuration options for the widget.

7. $pak

The packing options for the widget.

8. $children

The children to create nested within this widget.

Returns: None

Throws: Exceptions and other anomolies

"couldn't find "<widgetname>" widget to create"

croaks if there's no widget by the name given.

"failed to create menu item menuitem name"

croaks if

"failed to configure menuitem name"

croaks if

"failed to create Menu: i<menu name>"

croaks if

"failed to configure menu item menu name"

croaks if

"failed to create widgetname: parent name/widget type"

croaks if

"failed to create menu name for Menubutton menubutton name"

croaks if

"failed to configure Menubutton menubutton name"

croaks if

"failed to pack widget name"

croaks if

See Also:

(Nothing written, yet.)

TEST SCRIPT: test.pl

(Not written yet.)

EXPORTS

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.

EXCEPTIONS

(Not written yet.)

BUGS

(Not written yet.)