NAME

Tk::QuickTk::internals - implementation details

DESCRIPTION

  This document describes the internal workings of the B<TK::QuickTk> module, by detailing
the primary input data structure the module expects and, then, the private subroutines the
module uses to accomplish its work.

SYNOPSIS

  use Tk::QuickTk;

  sub _loadwidget;
  _loadwidget($gl,$spec,$level,$momname); (The last two items are optional)

  sub _getargs;
  _getargs($gl,$pakq,$inp,$cmds);

  sub _docode;
  _docode($gl,$level,$code);

  sub _bindevent;
  _bindevent($gl,$spec,$level,$momname);

  sub _loadmenitm;
  _loadmenitm($gl,$spec,$level,$momname,$momidx);

  sub _getttl;
  _getttl;

  sub _getcmd;
  _getcmd;

  sub _getsub;
  _getsub;

  sub _getini;
  _getini;

SPECIFICATION DATA STRUCTURE

Module TK::QuickTk takes as input a specification for a GUI application, and implements the application by translating the specification into method calls for the Tk module and executing them. That input specification is a very simple data structure and is generated, by default, by the companion module, Text::TreeFile.

The data structure consists of a strict hierarchy, or tree, of nodes. It starts, at the top or root of the tree, with a single node (corresponding to the MainWindow widget for the application) which consists of a two-element array.

 The first element of the array is a text string containing the specification for the
MainWindow widget, in the QuickTk language -- as documented in B<Tk::QuickTk::details>
and summarized in other QuickTk documents.  The second element of the node array is a
reference to another array of pointers to similar nodes, which are the widgets to be
immediately nested within the MainWindow widget.

The tree structure fans out in this way, until terminal nodes in which the second element of the node has no sub-node references (i.e. is an empty array).

PRIVATE FUNCTIONS

_loadwidget()

Purpose : Recursively implements a widget hierarchy from a specification data structure Arguments : $gl,$spec,$level,$momname (the last two are optional) The first is the hash of "global" variables made available to all code. The second is the two-element node array specifying a widget and its sub-widgets The third is the level of nesting of this widget (default is zero, being for the MainWindow) The fourth is the (accumulated) name of the parent of this widget (default is no parent) Called From : new(),createwidget(),_loadwidget()--recursively Calls : _getargs(),_docode(),_bindevent(),_loadmenitm(), _loadwidget()--recursively Return Value(s) : none Throws, Exits... : 1. Croaks if level zero widget isn't MainWindow (but fixes it, instead, if it's a TopLevel or Frame) 2. Carps and ignores if MainWindow is specified "nocreate" 3. Carps and ignores packing options for MainWindow, other than "nopack" 4. Croaks if _docode() for creating MainWindow returns failure 5. Croaks if _docode() for configuring MainWindow returns failure 6. Substitutes TopLevel if MainWindow is specified below level zero 7. Croaks if level nonzero widget creation _docode() returns failure 8. Croaks if _docode() creating MenuButton returns failure 9. Croaks if _docode() packing menu item returns failure "Side" Effects : Loads and optionally configures and packs a widget from its specification and hierarchy level and recursively does the same for widgets nested within it, and creates an entry in $$gl{widgets} for any widget for which 'nocreate' was specified so that it may be created, on the fly, later, during execution via createwidget()

_getargs()

Purpose : Parses the options for the widget, from the input specification string, using four helpers for different parts of a specification Arguments : $gl,$pakq,$inp,$cmds The first is the hash of "global" variables made available to all code. The second is boolean, indicating whether current widget allows packing The third is the text string input from which arguments should be parsed The fourth is a hash of subroutines potentially to be called Called From : loadwidget(), loadmenitm() Calls : _getttl,_getini,_getsub,_getcmd, chosen from fourth argument (hash) passed-in, depending on options parsed from $inp Return Value(s) : A three-item list of text strings: The first item is 'create' or 'nocreate' The second is a comma-delimited list of configuration options The third is either 'nopack' or a comma-delimited list of packing options Throws, Exits... : none "Side" Effects : none

_docode()

Purpose : Passes-on to the Tk library the code generated, logging it if requested to Arguments : $gl,$level,$code, and uses $$gl{lfh} as a file handle for logging if it exists The first is the hash of "global" variables made available to all code. The second is the hierarchical nesting level for the current widget The third is the code to execute in a protected environment Called From : new(),createwidget(),_loadwidget,_bindevent(),_loadmenitm() Calls : eval() to avoid and report potential exceptions Return Value(s) : Returns the eval() return, or undef if $$gl{genonly} so no eval() done Throws, Exits... : Carps if the eval of the code passed-in fails "Side" Effects : None

_bindevent()

Purpose : Binds an action to take when the specified event happens on the parent widget Arguments : $gl,$spec,$level,$momname The first is the hash of "global" variables made available to all code. The second is the text string specification of the bind request The third is the hierarchical nesting level for this event The fourth is the (accumulated) name of the parent of this event Called From : createwidget(),_loadwidget() Calls : _docode() Return Value(s) : None Throws, Exits... : Croaks if _docode() on the bind command fails for the widget, event and action "Side" Effects : The action is bound to the event, when it should occur on the parent widget

_loadmenitm()

Purpose : Loads an widget which is an item of a menu Arguments : $gl,$spec,$level,$momname,$momidx The first is the hash of "global" variables made available to all code. The second is the text string specification of the bind request The third is the hierarchical nesting level for this event The fourth is the (accumulated) name of the parent of this event The fifth is the sequential index of this menuitem in the parent menu Called From : createwidget(),_loadwidget(),_loadmenitm()--recursively Calls : _getargs(),_docode(),_loadmenitm()--recursively Return Value(s) : None Throws, Exits... : Croaks if the menu item: 1. type is unrecognizable 2. has no label 3. can't be created 4. can't be configured 5. has sub-menu items, but their menu widget can't be created 6. can't have its sub-menu-holding item created "Side" Effects : Puts a non-created-widget entry in $$gl{widgets} under the parent name and index for creation via createwidget() later during execution, and creates a menu item widget, and if it has sub-menu items, creates a sub-menu widget, and creates the sub-menu items, via recursive calls to _loadmenitm()

_getttl()

Purpose : Extracts the title from the input specification fragment, and adds quotes to the value Arguments : $gl,$opt,$inp The first is the hash of "global" variables made available to all code. The second is the option, 'ttl' The third is the text string to be set as the title Called From : _getargs() indirectly, as requested by _loadwidget() Calls : None Return Value(s) : A two-item list of text strings: The first is 'title' The second is the value of $inp, surrounded by double quote characters Throws, Exits... : None "Side" Effects : None

_getcmd()

Purpose : Extracts the function call to be executed as a callback, from the input specification fragment, and formats it for output to a Tk call Arguments : $gl,$opt,$inp The first is the hash of "global" variables made available to all code. The second is the option, 'cmd' The third is the text string containing a function name followed by arguments, to be executed as a callback Called From : _getargs() indirectly, as requested by _loadwidget() and _loadmenitm() Calls : None Return Value(s) : A two-item list of text strings: The first is 'command' The second is the name of the function to be executed as a callback, preceded by '[\&main::' and followed by ',$gl,' and followed by the arguments to the callback function, followed by ']'. Throws, Exits... : None "Side" Effects : None

_getsub()

Purpose : Extracts the code to be executed as a callback from the input specification fragment, and formats it for output to a Tk call Arguments : $gl,$opt,$inp The first is the hash of "global" variables made available to all code. The second is the option, 'sub' The third is a text string comprising code to be executed as a callback Called From : _getargs() indirectly, as requested by _loadwidget() and _loadmenitm() Calls : None Return Value(s) : A two-item list of text strings: The first is 'command' The second is the value of $inp, preceded by 'sub { ' and succeeded by '}' Throws, Exits... : None "Side" Effects : None

_getini()

Purpose : Saves the application initialization in $gl code for later execution, after MainWindow is created Arguments : $gl,$opt,$inp The first is the hash of "global" variables made available to all code. The second is the option, 'ini' The third is the text string comprising code to be executed to initialize the application Called From : _getargs() indirectly, as requested by _loadwidget() Calls : None Return Value(s) : A two-item list of undef,undef Throws, Exits... : None "Side" Effects : Sets $$gl{inicode} to initialization code from the input specification