=head1 NAME

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

=cut
***********************************************************************
=pod

=head1 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->dsRowFeedAll("select...", $self->{-parm}->{XXX})
  }
  else  {return $self->doDefault($cmd, @_)}
 }

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

=cut
***********************************************************************
=pod

=head1 DESCRIPTION

=over

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

The components of application window are:

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

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

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


=back


=cut
***********************************************************************
=pod

=head1 PARAMETERS

=over

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

TM parameters may be accessed via C<set> method of C<Tk::TM>. They are:
C<-wgmnu>, C<-wglst>, C<-wgscr>, C<-title>,
C<-mdlst>,
C<-parm>


=item -mdlst = 'lst' || 'tree'

Mode of navigation between application screens.
Default is 'tree', that 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 C<-parm> values filled in
'stop' command of screen`s sub or C<doEnd> event of data object.


=item -parm = {}

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


=item -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.


=item -wglst

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


=item -wgmnu

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


=item -wgscr

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


=back


=cut
***********************************************************************
=pod

=head1 METHODS

=over

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

Special methods are C<setscr>, C<Start>.


=item setscr (level, title, ?sub, ?opt)

Defines screen of application.
Level is number of nest of screen in tree, where 0 is top level.
Sub is code to create widgets and data objects of screen.
Opt is options (scalar or ref), used within sub.
Special title 'Login' is used for predefined login screen.


=item Start

Opens the first screen of application.

=back


=cut
***********************************************************************
=pod

=head1 CALLBACK INTERFACE

=over

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

C<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
C<-cbcmd>, C<-cbnme>, C<-dos>, C<-opt>, 
C<-wgapp>, C<-wgmnu>, C<-wgscr>,
C<-label>, C<-title>,
C<-parm>


=item start

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


=item stop

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


=item -cbcmd


Reference to this callback sub.


=item -cbnme

Name of this callback sub for dynamic loading.


=item -dos

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


=item -label

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


=item -opt

Options, defined with C<setscr>.


=item -parm

Programmer`s parameters of screen, hash.


=item -title

Title of the screen, represents data displayed on screen.
This is the third part of application window title. Other
parts are the title of the application and the label of the screen C<-label>.


=item -wgapp

Application window, provided by C<Tk::wApp>.


=item -wgmnu

Application`s menu bar, provided by C<Tk::wApp>.


=item -wgscr

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


=back


=cut
***********************************************************************
=pod

=head1 VERSION

=over


=item "06/02/2000"

TO DO:

- Approve

- Debug and Test



=item "31/01/2000"

Created.



=back


=cut
***********************************************************************
=pod

=head1 AUTHOR

=over

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

=back

=cut
