NAME

Tk::TM - User interface for database applications. Tk::TM - Tk Transaction Manager - screen transactions with user.

SYNOPSIS

Using SQL and Widget Generator:

use Tk::TM::Lib;
Tk::TM::Common::DBILogin('dsn', 'user', '');
my $mw  =new Tk::MainWindow;
my $mnu =$mw->tmMenu;
my $do  =new Tk::TM::DataObject();
$do->set(-sqgfd=>[
     ['cruptb',undef,'id',   undef,  undef,'ID',   'Entry']
    ,['crub',  undef,'class','    3',['select class from entity where x=?',1],'Class','Entry']
    ,['crutb', undef,'name', undef,  undef,'Name', 'Entry']
    ]
  ,-sqgsf=>'entity'
  ,-sqgso=>'id'
  ,-sqgscr=>$mw
  ,-sqgpt=>[-rowcount=>5]
  )->form(-t=>$mnu);
$mnu->Retrieve;
Tk::MainLoop;

Using SQL Statements:

use Tk::TM::Lib;
Tk::TM::Common::DBILogin('dsn', 'user', '');
my $mw =new Tk::MainWindow;
my $mnu =$mw->tmMenu;
my $tbl =$mw->tmTable(-rowcount=>3, -colspecs=>
                       [['col1','Entry']
                       ,['col2','Entry']
                       ,['col3','Entry']]
                      )->form(-t=>$mnu);
my $bln =$mw->tmBlank(-wgspecs=>
                       [['col1','Entry']
                       ,['col2','Entry']
                       ,['col3','Entry',-width=>30]]
                      )->form(-t=>$tbl);
new Tk::TM::DataObject(-wgtbl=>$tbl, -wgbln=>$bln
                      ,-sqlsel=>['select...',value...]
                      ,-sqlins=>['insert...',fieldnumber...]
                      ,-sqlupd=>['update...',fieldnumber...]
                      ,-sqldel=>['delete...',fieldnumber...]
                      ); 
$mnu->Retrieve;
Tk::MainLoop;

Low Level:

use Tk::TM::Lib;
Tk::TM::Common::DBILogin('dsn', 'user', '');
my $mw =new Tk::MainWindow;
my $mnu =$mw->tmMenu;
my $tbl =$mw->tmTable(-rowcount=>3, -colspecs=>
                       [['col1','Entry']
                       ,['col2','Entry']
                       ,['col3','Entry']]
                      )->form(-t=>$mnu);
my $bln =$mw->tmBlank(-wgspecs=>
                       [['col1','Entry']
                       ,['col2','Entry']
                       ,['col3','Entry',-width=>30]]
                      )->form(-t=>$tbl);
my $sub =sub{ my $self =shift;
   if    ($_[0] eq 'dbRead') {$self->DBICmd('select * from table')}
   elsif ($_[0] eq 'dbIns')  {$self->DBICmd('insert...')}
   elsif ($_[0] eq 'dbUpd')  {$self->DBICmd('update...')}
   elsif ($_[0] eq 'dbDel')  {$self->DBICmd('delete from table...')}
   else                      {$self->doDefault(@_)}
};
new Tk::TM::DataObject(-cbcmd=>$sub, -wgtbl=>$tbl, -wgbln=>$bln); # or:
# $mnu->set(-dos=>[
# new Tk::TM::DataObject(-cbcmd=>$sub, -wgtbl=>$tbl, -wgbln=>$bln)
# ]);
$mnu->Retrieve;
Tk::MainLoop;

DESCRIPTION

This module is something like 'Transaction Manager' in JYACC JAM RAD.

It releases user interface for database applications - screen transactions with user.

It contains data manipulation object (Tk::TM::DataObject), data widgets (tmTable, tmBlank), menu and action bar widgets (tmMenu, tmActionBar, based on Tk::TM::DataObjSet).

See also:

Tk::TM::wApp - Tk Transaction Manager Application Window. This is level above Tk::TM::Lib.

Tk::TM::Try - Tk Transaction Manager Error processing functions. Implements error processing functions may be used (or not be used) in application.

MODULES

Tk::TM::Lib - to import all TM components (modules) into a program, it have not own data or functions.

Tk::TM::Common - common data and functions

Tk::TM::Lang - language localisation

Tk::TM::DataObject - objects to manipulate with tabular data: retrieve, navigate, edit, save... Tk::TM::DataObject uses Tk widgets to present data, it can also simmultaniosly use one tmTable and one tmBlank widgets, mentioned below. DBI can be used to interact with databases in several levels. The base level is using defined by programmer function(s) for database and user interactions. More developed levels are autogeneration of SQL. Next more developed levels may be based on prepared in database metadata. Inherited from Tk::TM::DataObject may be developed Tk::TM::DataObjTixGrid that uses tixGrid widget and Tk::TM::DataObjSeq that uses sequentialy accessible data files as xBase files.

Tk::TM::wgTable - table widget tmTable, populated with Tk widgets. It may be replaced with tixGrid in future.

Tk::TM::wgBlank - blank widget tmBlank, presents data row-by-row with Tk widgets.

Tk::TM::DataObjSet - base object for menu and action bar widgets, mentioned below. It contains several Tk::TM::DataObjects and uses current Tk::TM::DataObject or all Tk::TM::DataObjects to achieve required by user operations.

Tk::TM::wgActionBar - the simplest widget tmActionBar with user actions as 'retrieve', 'save', 'next', 'previous'...

Tk::TM::wgMenu - more complex widget tmMenu with more user actions - menu and toolbar in CUA-style.

COMMON OBJECT METHODS

perlobj and perltoot recommends common object methods new, initialize, DESTROY. The only DESTROY word is special.

Tk introduces it`s manner of constructing and creating widgets and methods Populate, configure, cget, destroy, OnDestroy.

So, it was needed to specify for TM objects sufficient and unified range of common object methods: new, initialize, set, setpush, destroy, destroybind, DESTROY. And there was a little problem - should first letters of words be capitalised (f.e. 'setpush' or 'SetPush')? Now it is not for better focusing on parameters of such methods as new and set and for common manners of perl programming. But in future there may become compatible names as 'New', 'Set', etc..

new Class (parameters) -> object

Creates and returns a new object with given parameters. This is as in perlobj. Derived from Tk objects have not this function.

initialize

$obj->initialize (parameters) -> object

Initializes object as initialize in <perlobj>. Usually initialize is called from new. initialize is useful in inherited objects, that can not use ancestor`s function new but need to do ancestor`s initialise code

set

$obj->set () -> @names_of_parameters

$obj->set (parameter) -> value

$obj->set (list of parameters and values) -> object

Gets or sets parameters of object as cget and configure in Tk. set is called from initialize or outside object.

setpush

$obj->setpush (parameter, value) -> object

Pushes given value into given parameter of type 'reference to array' or 'reference to hash'. This is useful method when filling list parameters without using interim variables.

destroy

$obj->destroy

Finishing using of object, disposing or destroying it as in Tk. It was impossible to use DESTROY because of losing object inside it. For Tk widget objects destroybind is used instead of destroy.

DESTROY

$obj->DESTROY

Standard object`s destructor, see perlobj. Due to problem of losing object inside DESTROY, and thankfully to absence of needs, it is not used.

destroybind

$obj->destroybind

Destruction method, called from Tk OnDestroy event. Used only for widgets, for other objects destroy is used.

Tk::TM::Lib MODULE

Tk::TM::Lib

Tk::TM::Lib module imports all TM components (modules) into a program.

use Tk::TM::Lib

Imports all TM components (modules) into a program

Tk::TM::Common MODULE

Tk::TM::Common

Tk::TM::Common module contains common data and functions.

use Tk::TM::Common

Imports Tk::TM::Common module into application. This does Tk::TM::Lib module.

$Tk::TM::Common::About

Default 'Help / About' text: reference to list of rows or sub. See also -about

$Tk::TM::Common::DBH

Default database connection handle, undef in default. Example: $Tk::TM::Common::DBH =DBI->connect("DBI:XBase:.")

$Tk::TM::Common::Debug

Debug level: 0 -none (default), 1 -print actions to STDOUT.

$Tk::TM::Common::Echo

Echo mode - printing commands to be executed: 0 -none, 1 -print (default).

$Tk::TM::Common::Edit

Default mode for application: 0 -view only, 1 -allow edit data (default). See -mdedt

$Tk::TM::Common::Help

Default 'Help / Help' text: reference to list of rows or sub. See also -help

Tk::TM::Common::DBILogin (dsn, user, password, ?opt, ?dbopt) -> dbh

Tk::TM::Common::DBILogin (screen, dsn, user, password, ?opt, ?dbopt)

Database login dialog, see DBI->connect. Options (default none): '#dsn' or '#edit' - allow to edit dsn, '#return' - instead of modifying $Tk::TM::Common::DBH only return dbh and return instead of exit when 'cancel' button pressed, '#center' - center login dialog on screen. Screen parameter is used for calls from Tk::TM::wApp.

Tk::TM::Lang MODULE

Tk::TM::Lang

Tk::TM::Lang module contains language localisation. The functions of this module are used par excellence internally by Tk::TM, application may only specify required localisation in $Tk::TM::Lang::Lang.

use Tk::TM::Lang

Imports Tk::TM::Lang module into application. This does Tk::TM::Lib module.

$Tk::TM::Lang::Lang

Switch of language localisation: false - international (no localisation), other - turn on localisation - language name such as 'ru' may be used.

Tk::TM::Lang::txtHelp -> \@help_text

Returns reference to array of rows of embedded help text.

Tk::TM::Lang::txtMenu -> \@menu_items_texts

Returns reference to array of texts of menu items

Tk::TM::Lang::txtMsg (msg) -> lang_msg

Returns given string translated into used localisation.

Tk::TM::DataObject MODULE

Tk::TM::DataObject

Tk::TM::DataObject module implements object to manipulate with tabular data: retrieve, navigate, edit, save... This object contains data store (data system) may be filled with SQL select and updated synchronously with SQL inserts, updates, deletes. Tk::TM::DataObject may be classified into:

Object data: -wgtbl, -wgbln, -wgarr, -wgmnu, -wgind, -mdedt, -dsdtm, -cbcmd, -cbXXX, -dbh, -dbfnm, -dbfds, -dbfaw, -sqlsel, -sqlins, -sqlupd, -sqldel, -sqgscr, -sqgfd, -sqgsf, -sqgsj, -sqgsc, -sqgso, -sqgpt, -sqgpb, -parm, -parmc

Options of Tk::TM::DataObject operation: "#end", "#force", "#reread", "#save", "#silent", "#undo", "#wgs", "#dta"

Common object methods: new Tk::TM::DataObject, $do->initialize, $do->destroy, $do->DESTROY, $do->set, $do->setpush

Data system dependent level methods with prefix 'ds', that implementation reflects data storage type - array of rows or tixGrid; many of this commands are used internally only, externally used variants (mentioned below) has not prefix 'ds' and observes modification flags: $do->dsReset, $do->dsDisplay, $do->dsDispWg, $do->dsFocus $do->dsRowCount, $do->dsRowDta, $do->dsRowFeed, $do->dsRowFeedAll, $do->dsRowGo, $do->dsRowNew, $do->dsRowDel, $do->dsRowUpd, $do->dsFldDta, $do->dsFldUpd

Abstract level methods without prefix 'ds' does not depends on data system implementation (array of rows or tixGrid) and observes modification flags. Method with 'ds' prefix should not be used by programmer if there is abstract level method with the same name. Function $do->Stop plays important role within codes of abstract level functions, they often calls it to finish data editing if it is.

Internally used widget level methods with 'wg' prefix: $do->wgFldFocusIn, $do->wgFldFocusOut, $do->wgFldHelper, $do->wgIndicate

Commands, used outside data objects to control them: $do->Display, $do->Stop, $do->Save, $do->Sleep, $do->Clear, $do->Retrieve, $do->RowGo, $do->RowNew, $do->RowDel, $do->RowUndo, $do->Export, $do->Find, $do->FindNxt, $do->Import, $do->Print, $do->Action

Implementations of commands above with prefix 'do', used inside data object: $do->doDefault, $do->doExport, $do->doImport, $do->doPrint

Useful methods for programming events (callbacks) used in implementations above: $do->DBICmd, $do->DBICnd, $do->DBIGen, $do->DBIHlp

Events (callbacks) and transaction scheme: dbRead, dbIns, dbUpd, dbDel, rwChg0, rwChg1, rwIns0, rwIns1, rwUpd0, rwUpd1, rwDel0, fdChg0, fdChg1, fdHelp, fdUpd0, fdUpd1, doEnd, doExport, doImport, doPrint, usAct

use Tk::TM::DataObject

Imports Tk::TM::DataObject module into application to use data objects. This does Tk::TM::Lib module.

new Tk::TM::DataObject (parameter=>value...)

Creates and returns data object with parameters specified (see Parameters of Tk::TM::DataObject). Includes newly created data object into list of all data objects @$Tk::TM::DataObject::Available.

Parameters of Tk::TM::DataObject

Parameters may be set or get with new Tk::TM::DataObject and $do->set methods of data object (see also new and set). There may be described only most used parameters.

-cbcmd

Callback function for all events (see Events of Tk::TM::DataObject). Default value is $do->doDefault. Slots for particular events -cbXXX may be used instead of -cbcmd.

-cbXXX

Callbacks for particular events. Optional. 'XXX' means name of event, f.e. dbRead. Callbacks -cbXXX are implemented within $do->doDefault method of data object, and so programmer should use -cbcmd or -cbXXX, but not both.

-dbfaw

Widget width adaptation to database fields switch. Contains margin of widget width.

-dbfds

Reference to array of references to hashes with descriptions of fields. Filled in $do->DBICmd('select...').

-dbfnm

Reference to hash "fieldName => fieldNumber". Filled in $do->DBICmd('select...').

-dbh

Database handle (see DBI) to use with database methods. If not set, $Tk::TM::Common::DBH will be used, or other may be programmed.

-dsdtm

Data store margin - max number of rows to keep in it.

-mdedt

Enable edit actions for user (edit mode). Values: 0 or '' - disable, digit -enable, 'c'reate or 'i'nsert enable, 'u'pdate enable, 'd'elete enable. Default is $Tk::TM::Common::Edit.

-parm

Programmer`s parameters, hash reference. Does`nt used by Tk::TM, may be used for programmer`s needs.

-parmc

Common to Tk::TM::DataObjSet object programmer`s parameters, hash reference. This is also available via $do->{-wgmnu}->{-parm}.

-sqgxxx - SQL and Widget Generator parameters

-sqgscr = screen to generate widgets on, generation trigger

If -sqgscr and -sqgsf specified, widget required will be generated and returned by $do->set.

-sqgfd = [['cruvpktb', table, field, filter value, helper select, ?inccol, label, ?colSpan, ?rowSpan, wgType, ?wgOpt]]

'crupktb' is field usage: 'c'reate or 'i'nsert, 'r'ead or 's'elect, 'u'pdate, 'v'iew only, 'p'rimary key, 'k'ey for commands, 't'able widget, 'b'lank widget. If table name is empty string, it will be automatically filled if possible; undefined table name will not be used in 'select' generation. Field name may be also expression to select. Filter value or sub will be used in 'where' clause and in $do->RowNew if defined. Helper select is value compliant to $do->DBIHlp and $do->DBIGen interfaces, it may be 'sql select' string, reference to array with 'sql select' string and numbers of fields or subs, reference to array of references to arrays with data strings. Values after 'helper select' are used for table or blank widget fields.

-sqgsf = 'select from' clause

-sqgsj = 'select where/join' subclause

-sqgsc = 'select where/condition' subclause with/without parameters

-sqgso = 'select order by' clause

All clauses are strings to be placed after keyword mentioned. Where/condition parameter -sqgsc may be also reference to array with string subclause and values or subs for SQL statement parameters.

-sqgpt = parameters for table widget

See Tk::TM::wgTable.

-sqgpb = parameters for blank widget

See Tk::TM::wgBlank.

-sqlxxx - SQL templates for simplest SQL generator

-sqlsel = SQL 'select' statement and parameters

-sqlins = SQL 'insert' statement and parameters

-sqlupd = SQL 'update' statement and parameters

-sqldel = SQL 'delete' statement and parameters

SQL templates for simplest SQL generator - strings, array refs, refs to arrays of refs.

Simple string is SQL statement. 'insert', 'update', 'delete' will be automatically supplied with all data values of current row as parameters. 'update' will be also supplied with old data values.

Reference to array with string as first element is SQL statement with parameters. 'select' parameters may be values or subs to evaluate. 'insert', 'update', 'delete' parameters are subs to evaluate or column numbers, negative values are treated like slices (f.e. ['insert into table values (?,?,?)',0,-2] tells use columns 0,1,2). 'update' old values are discovered as decrease of numbering (f.e. ['update table set xxx=?, yyy=? where k=?',0,-1,0]).

Reference to array with reference as first element is treated as sequence of SQL statements to execute within single transaction.

-wgarr

Widgets for row-by-row data performance. Alternative or addition to -wgbln. There no need of widget for each field, absent widgets should be replaced with undefs. Optional.

-wgbln

tmBlank widget for data object use. Optional.

-wgind

Indicator widget for data object use with $do->wgIndicate. Optional.

-wgmnu

Navigator widget - ancestor of Tk::TM::DataObjSet. This may be used instead of -dos of Tk::TM::DataObjSet, but -dos is more recommended.

-wgscr

Parent screen for data object. Default is parent of widgets used.

-wgtbl

tmTable widget for data object use. Optional.

Options of Tk::TM::DataObject operation

This describes options of data object operations. This options are used as parameters of methods as $do->Retrieve, $do->Stop, $do->doDefault, $do->doImport, $do->DBICmd... There may be several options catenated within one option string, f.e. '#force#end'. Some of this options are used internally, some may be used by programmer.

"#dta"

Drop data buffer. Used in $do->Sleep

"#end"

End of data object operation. It is no need to redisplay data. Used in $do->Stop

"#force"

Cancel of operation is not allowed, answer should be certain - 'yes' or 'no'. Used in $do->Stop

"#reread"

Keep current position of data store. Used in $do->Retrieve

"#save"

Save modified data without ask of user. Used in $do->Stop

"#silent"

Do not display error message box. Used in $do->doImport, $do->DBICmd

"#undo"

Undo unsaved modification of current record of data. Used in $do->Stop

"#wgs"

Destroy linked widgets. Used in $do->Sleep

Methods of Tk::TM::DataObject

$do->Action (actionName)

Executes callback usAct. This is used for may be added by programmer menu 'Actions'.

$do->Clear (?opt) -> success

Clears data inside data object`s data store. Saves modified data if needed via $do->Stop($opt .'#end'). Data object become ready for insertion and editing new records of data.

$do->DBICmd (?dbh, ?opt, command, arguments) -> result

$do->DBICmd (?dbh, ?opt, command, [arguments], command, [arguments]...) ->result

Simplest DBI interface, executes dbh command. Database connection handle dbh may be specified as argument, or may be given from data object`s property -dbh or from $Tk::TM::Common::DBH. Option '#silent' declines usage of message box to display error occurred. Command may be any dbh method (as 'selectrow' or 'do') or string incipient with 'select', 'selectrow', 'insert', 'update', 'delete'. Commands 'select' and 'selectrow' retrieves data directly into data object`s data store. Several commands may be specified to execute them within one database transaction. With one command specified autocommit is assumed.

$do->DBICnd() -> success

Query condition and sort dialog. Works with all modes of SQL generation.

$do->DBIGen(sql, opt, ?command) -> sql command

SQL generator. In simplest mode it uses -sqlsel, -sqlins, -sqlupd, -sqldel. In complex mode it uses -sqgscr, -sqgfd, -sqgsf, -sqgsj, -sqgsc, -sqgso, -sqgpt, -sqgpb.

$do->DBIHlp (?SQL, \@parameters, ?\@out_fields) -> success

Displays entry helper screen for -fdHelp event, updates fields if chosen. Parameters may be for SQL command if it is, or to directly display. Output field numbers are relative to current field number. If output field numbers omitted, current field is used for output.

$do->destroy

Destructs data object, see destroy. Saves modified data if needed via $do->Stop('#force#end'). Excludes data object from list of all data objects @$Tk::TM::DataObject::Available

$do->DESTROY

Destructor, see DESTROY. Does nothing.

$do->Display -> success

Displays current data on screen. This is not very useful method because all high-level methods keep screen actual.

$do->doDefault (operation, options, args...) -> success

Implements default actions for all programmable events, evaluates appropriate piXXX code if it exists. This is default value for -cbcmd data object`s parameter. Events and options are described in Events of Tk::TM::DataObject and Options of Tk::TM::DataObject operation

$do->doExport (?file, ?format) -> filename

Exports data from data object`s data store to specified file. If no file specified, uses Tk::FileSelect to ask user for filename. Returns filename on success or empty string on failure. See also $do->Export

$do->doImport (?file, ?format) -> filename

Imports data from file into data object. If no file specified, uses Tk::FileSelect to ask user for filename. Importing each row of data is implemented via insert attempt and update attempt. Returns filename on success or empty string on failure. See also $do->Import

$do->doPrint (?file, ?format) -> filename

Prints data on printer device or into file specified. See also $do->Print. Not implemented yet.

$do->dsDisplay -> success

Displays current data on screen: -wgtbl, -wgbln, -wgarr. Calls $do->dsDispWg.

$do->dsDispWg -> success

Displays current data in by-row widgets: -wgbln, -wgarr

$do->dsFldDta (?field) -> data

Returns data from current or specified widget. Parameter may be data widget or field number or field name.

$do->dsFldUpd (field, data) -> success

Replaces (updates) data in specified field, displays it on screen. Field may be identified by number or name.

$do->dsFocus

Sets focus (focusForce) to current widget.

$do->dsReset (?) -> success (always)

Resets data store, drops all rows of data. Does not displays data on screen, but may this in different releases.

$do->dsRowCount -> number_of_rows

Returns number of data rows in data store.

$do->dsRowDel -> success

Deletes current row of data in data store. Displays changes on screen.

$do->dsRowDta (?row) ->\@data_row

Returns reference to array containing data of current or specified row

$do->dsRowFeed (\@data_row) -> success

Pushes specified data row into data store. Does not displays data on screen.

$do->dsRowFeedAll (\@data) -> success

Replaces all data in data store with specified. Does not displays data on screen.

$do->dsRowGo (?row) -> success

Make specified row current and display this on screen. If no row specified, only redisplays data on screen. Row may be specified absolutely or with commands 'next', 'prev', 'pgdn', 'pgup', 'top', 'bot'. Data on screen will be redisplayed in all cases except 'next' and 'prev' optimisations.

$do->dsRowNew -> success

Creates (appends) new row into data store, makes it current, displays it on screen, sets focus to it.

$do->dsRowUpd (\@data) -> success

Replaces (updates) data in the current row with data specified, displays it on screen.

$do->Export (?file, ?format) -> filename

Exports data from data store into file. Saves modified data if needed via $do->Stop(''). If no file specified, uses Tk::FileSelect to ask user for filename. Returns filename on success or empty string on failure. See involved: -cbcmd, doExport, $do->doExport

$do->Find -> success

Presents Find dialog to user and finds in current column first occurrence. See also $do->FindNxt

$do->FindNxt (?offset) -> success

Finds next occurrence of Find string in current column, goes to row found. Default and usual offset is 1, 0 is used for call from $do->Find.

$do->Import (?file, ?format) -> filename

Imports data from file into data object. Saves modified data if needed via $do->Stop(''). If no file specified, uses Tk::FileSelect to ask user for filename. Importing each row of data is implemented via insert attempt and update attempt. Returns filename on success or empty string on failure. See involved: -cbcmd, doImport, $do->doImport

$do->initialize (parameters)

Initialises object, see initialize.

$do->Print (?file, ?format)

Prints data of data object. Saves modified data if needed via $do->Stop(''). See involved: -cbcmd, doPrint, $do->doPrint.

$do->Retrieve (?opt) -> success

Retrieves data into data store. Saves modified data if needed via $do->Stop(''). Option string may contain $do->Stop('') options and '#reread' that keeps current row in data store unchanged. Without option '#reread' method $do->RowGo ('top') is used. See involved: -cbcmd, dbRead, $do->dsRowFeed, $do->dsRowFeedAll, $do->DBICmd.

$do->RowDel -> success

Deletes current row of data. Saves modified data if needed via $do->Stop('#save'). See involved: -cbcmd, rwDel0, dbDel, rwChg1 $do->dsRowDel, $do->DBICmd

$do->RowGo (row) -> success

Goes to specified row of data: 'top', 'bot', 'pgup', 'pgdn', 'prev', 'next', directly defined row identifier. Saves modified data if needed via $do->Stop('#save'). See involved: -cbcmd, rwChg1, $do->dsRowGo

$do->RowNew -> success

Creates (appends) new row of data. Saves modified data if needed via $do->Stop('#save'). See involved: -cbcmd, rwIns0, rwIns1, rwChg1, $do->dsRowNew

$do->RowUndo -> success

Undoes editing of current row of data via $do->Stop('#undo'). See involved: rwChg1

$do->Save (?opt) -> success

Saves modified data via $do->Stop($opt .'#save'). See involved: rwChg1

$do->Sleep (?opt) -> success

Makes data object inactive, frees resources engaged by it. Saves modified data via $do->Stop($opt .'#end'). Option "#wgs" destroys data widgets. Option "#dta" drops data buffer. $do->Retrieve (#reread) will awake sleeping data object. Sleep procedure may be need application to control resources used.

$do->set (parameter) -> value

$do->set (parameter=>value...) -> data object

Gets or sets parameters of data object. See set, Parameters of Tk::TM::DataObject

$do->setpush (parameter, value) -> data object

Pushes list parameter into data object. See setpush, Parameters of Tk::TM::DataObject

$do->Stop (?opt) -> success

Stops data editing user transaction if it is. Other methods often calls it. See involved: -cbcmd, rwChg0, dbIns, dbUpd, rwUpd1, doEnd, $do->wgFldFocusOut

$do->wgFldFocusIn (widget, ?fieldNo, ?screenRowNo)

Callback for FocusIn Tk event. All used for data object widgets are bind to it.

$do->wgFldFocusOut (?widget, ?fieldNo, ?screenRowNo)

Callback for FocusOut Tk event. All used for data object widgets are bind to it. This method is called also by $do->Stop

$do->wgFldHelper (?widget, ?fieldNo, ?screenRowNo)

Callback for '<Key-F4>' Tk event. All used for data object widgets are bind to it. This method may be called also outside callbacks.

$do->wgIndicate (?string)

Indicates current state of data object in -wgind

Events of Tk::TM::DataObject

This describes programmable events (callbacks) of Tk::TM::DataObject and transaction scheme of them. This events may be implemented by programmer with -cbcmd or -cbXXX routines. See also $do->doDefault.

Chains of events:

Change current row: rwChg0, rwChg1, fdChg1

Begin to modify row: rwUpd0, fdUpd0, fdUpd1

Begin to insert row: rwChg0, rwIns0, rwIns1, rwChg1, fdChg1

Save modified row: dbIns | dbUpd, rwUpd1, rwChg1

Delete row: rwChg0, rwDel0, dbDel, rwChg1

dbDel (opt, rowNo, undef, undef, \@old_data)

Delete row of data into database. This may be $do->DBICmd('delete ...', @old_data)

dbIns (opt, rowNo, undef, undef, \@old_data, \@new_data)

Insert new row of data into database. This may be $do->DBICmd($opt, 'insert ...', @new_data)

dbRead (opt)

Read data from database. This may be $do->DBICmd($opt, 'select ...')

dbUpd (opt, rowNo, undef, undef, \@old_data, \@new_data)

Update row of data into database. This may be $do->DBICmd($opt, 'update ...', @old_data, @new_data)

doEnd (opt, rowNo, undef, undef, \@row_data)

End of using data object, -parm may be modified. Invoked from $do->Stop ("#end").

doExport (file, format)

Export data from data store. In default this is $do->doExport

doImport (file, format)

Import data into data store. In default this is $do->doImport

doPrint (file format)

Print data from data store. In default this is $do->doPrint

fdChg0 (?)

Before changing current field (should current field be changed?). Not implemented.

fdChg1 (opt, rowNo, fieldNo, widget)

After current field was changed. This may occur after rwChg1.

fdHelp (opt, rowNo, fieldNo, widget)

After key F4 (field fill help) was pressed, this may be entry helper screen displayed. Before this is occurred rwUpd0, fdUpd0

fdUpd0 (opt, rowNo, fieldNo, widget)

Before updating (modifying) current field (should field be updated?). In current implementation this occurs after user have been modified data in a widget. This may occur after rwUpd0.

fdUpd1 (opt, rowNo, fieldNo, widget, old_value, new_valie)

After current field was modified (accept changes?). In current implementation this occurs after user have been modified data in a widget and exited this widget.

rwChg0 (opt, rowNo)

Before changing current row in data store (should current row be changed?). Detail data objects should be saved in this event with $do->Save

rwChg1 (opt, rowNo)

After current row in data store was changed. Detail data objects should be retrieved in this event with $do->Retrieve

rwDel0 (opt, rowNo)

Before deleting current row (should row be deleted?) This occurs after rwChg0 and before dbDel.

rwIns0 (opt)

Before inserting (appending) new row (should new row be inserted?). This occurs after rwChg0. Master data objects should be saved in this event with $do->Save.

rwIns1 (opt, rowNo)

After new row is inserted (appended) into data store. New row is current row. This occurs before dbIns. Default values should be supplied for this row.

rwUpd0 (opt, rowNo)

Before updating (modifying) current row (should row be modified?). This occurs after rwChg0 and before dbUpd.

rwUpd1 (opt, rowNo, undef, undef, \@old_data, \@new_data)

After current data row was updated (modified). This occurs after dbIns or dbUpd and before rwChg1. Here may be $do->DBICmd('selectrow ...', @old_data)

usAct (actionName, rowNo, fieldNo, widget)

Called by $do->Action when user shoosed item from 'Actions' menu.

Tk::TM::wgTable MODULE

Tk::TM::wgTable

Module Tk::TM::wgTable contains table widget tmTable, populated with Tk widgets.

tmTable

Widget tmTable is implemented by module Tk::TM::wgTable. It is inherited from Tk::Frame.

use Tk::TM::wgTable

Imports Tk::TM::wgTable module into application to use data objects. This does Tk::TM::Lib module.

$mw->tmTable (parameter=>value...)

Creates and returns table widget with parameters specified. Parameters may be Tk options (use configure) or tmTable (use set).

-do

Data object to use with this widget

-colspecs

Specifications of columns: [[header, widgetType, widgetOption,...],...]. Header may be text for Label widget or reference to array of options for Label widget, the first value in this array should be text. Other parameters of column are type of widget (f.e.Entry) for data and options for this widget creation. There no need of widget for each field, absent widgets should be replaced with undefs.

-rowcount

Number of on-screen rows of widgets in table

$tbl->Display -> success

Displays data from data object -do within this table widget.

$tbl->Focus -> success

Sets focus (focusForce) to current widget within this table widget.

Tk::TM::wgBlank MODULE

Tk::TM::wgBlank

Module Tk::TM::wgBlank contains blank widget tmBlank, that presents data row-by-row with Tk widgets.

tmBlank

Widget tmBlank is implemented by module Tk::TM::wgBlank. It is inherited from Tk::Frame.

use Tk::TM::wgBlank

Imports Tk::TM::wgBlank module into application to use data objects. This does Tk::TM::Lib module.

$mw->tmBlank (parameter=>value...)

Creates and returns table widget with parameters specified. Parameters may be Tk options (use configure) or tmBlank (use set).

-do

Data object to use with this widget

-wgspecs

Specifications of widgets: [[?incCol, label, ?colSpan, ?rowSpan, widgetType, widgetOption,...],...].

Label may be text for Label widget or reference to array of options for Label widget, the first value in this array should be text.

Parameter 'widgetType' is type of widget (f.e.Entry) for data, followed with options for this widget creation.

Optional 'incCol' parameter is digit to add to current column number in grid geometry manager. Default column number is 0 for label and 1 for widget.

Optional 'colSpan' parameter is digit - number of columns for widget in grid geometry manager. Default is 1.

Optional 'rowSpan' parameter is digit - number of rows for widget in grid geometry manager. Default is 1.

There no need of widget for each field, absent widgets should be replaced with undefs.

$bln->Display -> success

Displays data from data object -do within this widget.

$bln->Focus -> success

Sets focus (focusForce) to current widget within this widget.

Tk::TM::DataObjSet MODULE

Tk::TM::DataObjSet

Module Tk::TM::DataObjSet implements base object for menu and action bar widgets, described below. Descriptions of Tk::TM::wgActionBar and Tk::TM::wgMenu modules does not contains parameters and methods, described for Tk::TM::DataObjSet. So read it here.

Tk::TM::DataObjSet object contains several Tk::TM::DataObjects and uses current Tk::TM::DataObject or all this Tk::TM::DataObjects (see -mdscr) to achieve required by user operations.

Tk::TM::DataObjSet may be classified to:

Parameters: -dos, -wgind, -mdmnu, -mdtbr, -mdedt, -mdnav, -mdscr, -about, -help, -parm

Common object methods: new, initialize destroybind, DESTROY, set, setpush

Methods of itself: $dos->DataObject, $dos->doAll, $dos->doCurrent, $dos->Help

Procedures to transfer to all data objects (see description of data object): $do->Stop, $do->Save, $do->Clear, $do->Retrieve, $do->Reread

Procedures to transfer to current data object (see description of data object): $do->Find, $do->FindNxt, $do->FldHelp, $do->RowGo, $do->RowNew, $do->RowDel, $do->RowUndo, $do->Export, $do->Import, $do->Print, $do->Action

use Tk::TM::DataObjSet

Imports Tk::TM::wgBlank module into application to use data objects. This does Tk::TM::wgActionBar, Tk::TM::wgMenu, Tk::TM::Lib modules.

new Tk::TM::DataObjSet (parameter=>value...)

Creates and returns Tk::TM::DataObject widget with parameters specified. Parameters may be specified with set also. Tk options for inherited widgets may be specified with configure). Do not use this method, use $mw->tmActionBar or $mw->tmMenu.

-about

Text or routine to produce about text for 'Help / About' menu.

-dos

Reference to array of data objects managed by this object. Default value is @Tk::TM::DataObject::Available - list of all existed data objects in application.

-help

Text or routine to produce help text for 'Help / Help' menu.

-mdedt

Enable edit actions for user (edit mode). Value is controlled by current data object.

-mdmnu

Type of menu to use: 'bar' - menu bar Tk::Menu (default), 'button' - menu with Tk::Menubuttons, '' - no menu.

-mdnav

Enable only navigation buttons for user (navigation mode). Default is disabled (false).

-mdscr

Restrict operations on all data objects to data objects in the same parent widget as current. Default is disabled.

-mdtbr

Type of toolbar (action bar) to use: true - use toolbar (default), false - no toolbar.

-parm

Programmer`s parameters, hash reference. Does`nt used by Tk::TM, may be used for programmer`s needs. Default value is $Tk::TM::DataObjSet::Parm, and so all data object sets in application shares the same area of parameters.

-wgind

Indicator widget for data objects. See -wgind in it`s description.

$dos->DataObject -> current data object

Returns current data object

$dos->doAll (sub, args) -> success

Executes given sub for all data objects or restricted with -mdscr

$dos->doCurrent (sub, args) -> success

Executes given sub for current data object.

$dos->Help (-about|-help)

Executes help screen.

Tk::TM::wgActionBar MODULE

Tk::TM::wgActionBar

Module Tk::TM::wgActionBar implements the simplest widget tmActionBar with user actions as 'retrieve', 'save', 'next', 'previous'... It inherits from Tk::TM::DataObjSet, and below are only description of Tk::TM::wgActionBar features.

tmActionBar

Widget tmActionBar is implemented by module Tk::TM::wgActionBar.

use Tk::TM::wgActionBar

Imports Tk::TM::wgActionBar module into application to use action bar objects. This does Tk::TM::Lib module.

$mw->tmActionBar (parameter=>value...)

Creates and returns action bar widget with parameters specified. Parameters may be Tk options (use configure) or Tk::TM::DataObjSet (use set).

$mw->setActions (@actions)

Sets 'Actions' menu. Each action may be string with action name to use with $do->Action call (usAct callback), or reference to array of [name, type, options for Tk::Menu].

Tk::TM::wgMenu MODULE

Tk::TM::wgMenu

Module Tk::TM::wgMenu implements widget tmMenu - menu and toolbar in CUA-style, more complex then tmActionBar, with more user actions. It inherits from Tk::TM::DataObjSet, and below are only description of Tk::TM::wgMenu features.

tmMenu

Widget tmMenu is implemented by module Tk::TM::wgMenu.

use Tk::TM::wgMenu

Imports Tk::TM::wgMenu module into application to use menu objects. This does Tk::TM::Lib module.

$mw->tmMenu (parameter=>value...)

Creates and returns menu widget with parameters specified. Parameters may be Tk options (use configure) or Tk::TM::DataObjSet (use set).

$mw->setActions (@actions)

Sets 'Actions' menu. Each action may be string with action name to use with $do->Action call (usAct callback), or reference to array of [name, type, options for Tk::Menu].

VERSION

"16-18/11/2000"

Bug 'bad event type or keysym "~"' fixed in 'wgMenu.pm'.

Status Line support implemented, but without comments for fields.

Bug of incorrect 'pgup' within table fixed in 'wgTable.pm'.

Scrollbar in 'wgTable.pm' implemented.

"22/10-03/11/2000"

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

Key-F4 bindings moved from Tk::TM::DataObject, Tk::TM::wgBlank, Tk::TM::wgTable to Tk::TM::wgMenu to avoid conflict with 'Alt-F4'.

Tk::TM::Common::DBILogin unified for Tk::TM::wApp use.

Sleeping DataObject can operate with data in current row: $do->Sleep and $do->Retrieve uses new DataObject`s parameter -dsslp to indicate sleeping and save -dsrid.

-parmc DataObject`s parameter created.

-wgnav DataObject`s parameter renamed to -wgmnu for unification with Tk::TM::wApp.

Error processing for callbacks added.

$do->DBICmd corrected - undefined attributes inserted into 'do' arguments.

-dsrd0 DataObject`s parameter corrected - now it is filled with copy of $do->dsRowDta.

-sqlsel, -sqlins, -sqlupd, -sqldel DataObject`s parameters added - simplest sql generator features implemented, see also $do->DBIGen.

-sqgscr, -sqgfd, -sqgsf, -sqgsj, -sqgsc, -sqgso, -sqgpt, -sqgpb DataObject`s parameters added - SQL and Widget generator created, see also $do->DBIGen.

-mdedt may contain 'c'reate or 'i'nsert, 'u'pdate, 'd'elete.

$do->DBICnd - Query condition and sort dialog created.

-dbfaw DataObject`s parameter added - widget width adaptation to database fields implemented.

"12/08/2000" - fixed "bad event type or keysym 'ä'"

"06/02/2000" - first documented release

TO DO:

- Test and Debug

- tmDialogBox - approve and document?

- Conflict of 'F4' and 'Alt+F4' callbacks

"12/12/1999" - documentation was began

This documentation was began.

Some reviewing done.

Modules Lib, Common, Lang created.

TO DO:

- Review api and naming

- Approve code

- Debug

- Document realised

- Action interfaces- methods to customise additional actions

- DataObjSet actions for all DataObjects (as reread or query) may involve only DataObjects on current screen - window or panel.

AUTHOR

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

cpanm Tk::TM::Try

perl -MCPAN -e shell
install Tk::TM::Try