NAME

Tk::TM::wApp - Tk Transaction Manager Application Window. See Tk::TM::Lib for main descriptions and principles.

SYNOPSIS

use Tk::TM::wApp;
use DBI;

my $mw  =new Tk::TM::wApp;

$mw->setscr(0,'Login');
$mw->setscr(0,'Screen 1',   \&Screen1);
$mw->setscr(1,'Screen 1.1', \&Screen1_1);
$mw->setscr(0,'Screen 2',   \&Screen2);
$mw->Start();

Tk::MainLoop;

..............................

sub Screen1_1 { # two subs - for screen and for data object
 my ($self, $cmd, $opt, $mst) =@_;
 return(1) if $cmd =~/stop/;

 my $wgt=$self->{-wgscr}->tmTable(
          -rowcount=>10
         ,-colspecs=>[['Col1' ,'Entry']
                     ,['Col2' ,'Entry']
                     ,['Col3' ,'Entry']
                     ,['Col4' ,'Entry']]
         )->pack;

 my $do;
 if (!$self->{-dos}) {
    $do =new Tk::TM::DataObject();
    $self->{-dos} =[$do];
 }
 else {
    $do =$self->{-dos}->[0];
 }

 my $rwm =$mst->{-dos}->[0]->dsRowDta();
 my $flt =$rwm->[0];
 $self->{-title} =$flt;

 $do->set(-wgtbl=>$wgt
         ,-mdedt=>0
         ,-cbdbRead=>
             sub{$_[0]->DBICmd("select * from table where field=?",$flt)}
         );

 $do->Retrieve('#reread')
}

..............................

sub Screen1_2 { # unified sub for screen with single data object
 my ($self, $cmd, $opt, $row, $fld, $wg, $dta, $new) =(shift, shift, @_);

 if    ($cmd eq 'stop')   {
       return(1)
 }
 elsif ($cmd eq 'start')  {

       my $wgt=$self->{-wgscr}->tmTable(
            -rowcount=>10
           ,-colspecs=>[['Name','Entry']]
           )->pack;

       my $do;
       if (!$self->{-dos}) {
          $do =new Tk::TM::DataObject();
          $self->{-dos} =[$do];
       }
       else {
          $do =$self->{-dos}->[0];
       }

       my $rwm =$row->{-dos}->[0]->dsRowDta();
       $do->{-parm}->{XXX} =$rwm->[0];
       $self->{-title} =$do->{-parm}->{dsn};

       $do->set(-wgtbl=>$wgt
               ,-mdedt=>0
               ,-cbcmd=>\&DataSources
               );
       $do->Retrieve('#reread')
 }
 elsif ($cmd eq 'dbRead') {
       $self->DBICmd("select...", $self->{-parm}->{XXX})
 }
 else  {return $self->doDefault($cmd, @_)}
}

..............................

DESCRIPTION

This module implements application window with Tk Transaction Manager features. Tk::TM::wApp is level above Tk::TM::Lib, see there other descriptions and principles. There is no need to call 'use' for Tk::TM::Lib, this is done by using Tk::TM::wApp.

The components of application window are:

Data editing bar menu with toolbar, implemented with Tk::TM::wgMenu (tmMenu widget).

Navigation pane with list of screen names to open, implemented with Tk::Tree.

Screen pane for widgets of application screens, implemented with Tk::Frame.

PARAMETERS

Tk parameters of Tk::TM::wApp window may be set via configure Tk method. They may be all parameters of Tk::MainWindow.

TM parameters may be accessed via set method of Tk::TM. They are: -wgmnu, -wgnav, -wgscr, -title, -mdnav, -parm

-mdnav = 'treee' || 'tree' || 'lst'

Mode of navigation between application screens. Default is 'treee' ('tree exact'), that means that detail screen may be opened only if it`s master screen is current; this mode may be excluded in future. Mode 'tree' means that detail screen should be opened for it`s master screen and if master was previously used. Mode 'lst' means that screens are using -parm values filled in 'stop' command of screen`s sub or doEnd event of data object.

-parm = {}

Programmer`s parameters. This hash is also accessible via parameter -parm of tmMenu widget (Tk::TM::wgMenu), accessible via -wgmnu.

-title = $mw->cget(-title)

Title of application, the first part of window`s title. Other parts are combined for current application`s screen. Default value is title of the window.

-wgnav

Widget with list of all available application screens. This is navigation pane of application. Tk::Tree is used.

-wgmnu

Menu and toolbar for data editing. tmMenu widget (Tk::TM::wgMenu) is used.

-wgscr

Widget for application screens, to create application widgets inside it. Tk::Frame widget is used.

METHODS

Common object methods as new, initialize, set are described under Tk::TM::Lib.

Special methods are setscr, Start.

setscr (level, label, ?sub, ?parm, ?opt)

Defines screen of application. Level is number of nest of screen in tree, where 0 is top level. Label of the screen will be displayed at the navigation pane and as part of the title of the window. Special label 'Login' is used for predefined login screen. Sub is code to create widgets and data objects of screen. Sub may also be filename relative to $0 path, it will be executed with do to obtain code. Parm is hash reference with parameters of the screen to use inside sub. Opt is hash reference with screen options, available via screen description, see \&callback.

Start

Opens the first screen of application.

CALLBACK INTERFACE

\&callback (self, command, opt, parent)

setscr method defines callback to start and stop application screen. Parameters are description of this screen, command ('start' or 'stop'), option string, description of parent screen.

The command is string 'start' or 'stop'.

The descriptions are hash references with entries -cbcmd, -cbnme, -do, -dos, -wgapp, -wgmnu, -wgscr, -label, -title, -parm, -parmc, -reread, -rereadc

start

Start performance of screen. If -dos is not defined, this is the first open of screen.

stop

Stop performance of screen. The operation may be declared with 'return(1)' only.

-cbcmd

Reference to this callback sub.

-cbnme

Name of this callback sub for dynamic loading.

-do

Reference to first data object in -dos list, to shorten access from outside.

-dos

Reference to list of data objects of screen. Callback should set it. At the first open of the screen this is not defined.

-label

Label of the screen as displayed in -wgnav. Title of application window is combined with title of application, label of the screen, title of the screen (described below at -title)

-parm

Programmer`s parameters of the screen, defined with setscr hash ref. It is not the same as '-parm' in Tk::TM::wApp or Tk::TM::wgMenu.

-parmc

Common to Tk::TM::wApp or Tk::TM::wgMenu object programmer`s parameters. This is also available via -wgapp or -wgmnu.

-reread

Reread this master screen internally before it's detail open.

-rereadc

Reread this master screen internally before it's detail open and turn off this toggle.

-title

Title of the screen, represents data displayed on screen. Title of application window is combined with title of application, label of the screen (described above at -label), title of the screen.

-wgapp

Application window, provided by Tk::TM::wApp.

-wgmnu

Application`s menu bar, provided by Tk::TM::wApp.

-wgscr

Widget for application screen, to create application widgets inside it. Provided by Tk::TM::wApp. Tk::Frame widget is used.

VERSION

"16-18/11/2000"

Status Line implemented.

"22-25/10/2000"

exit calls replaced with Tk::exit calls to avoid abnormal program terminations.

Tk::TM::Common::DBILogin used for login screen.

setscr - Sub may be filename relative to $0 path, it will be executed with do to obtain code. Opt parameter added.

Master's DataObject data is not retrieved when it's detail opening, as in 'tree' mode was. Application supposes now that only current row of master data is needed and this is unchanged in database by other screens. To do internal reread -reread and -rereadc screen descriptions may be used.

Error processing for callbacks added.

-do screen description created.

-opt screen description removed, -parm should be used instead.

-parmc screen description created.

-wglst parameter of Tk::TM::wApp renamed to -wgnav.

-mdlst parameter of Tk::TM::wApp renamed to -mdnav. New value 'treee' ('tree exact') is set as default.

"06/02/2000"

TO DO:

- Approve

- Debug and Test

"31/01/2000"

Created.

AUTHOR

Andrew V Makarow <makarow@mail.com>, Denis E Medvedyuk <demed@mail.com>