Tk::TM - User interface for database applications. Tk::TM - Tk Transaction Manager - screen transactions with user.
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;
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;
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;
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).
Tk::TM::DataObject
tmTable
tmBlank
tmMenu
tmActionBar
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.
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
DBI
Tk::TM::DataObjTixGrid
tixGrid
Tk::TM::DataObjSeq
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.
perlobj and perltoot recommends common object methods new, initialize, DESTROY. The only DESTROY word is special.
perlobj
perltoot
new
initialize
DESTROY
Tk introduces it`s manner of constructing and creating widgets and methods Populate, configure, cget, destroy, OnDestroy.
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..
set
setpush
destroybind
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.
$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
$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.
$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.
$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.
$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.
$obj->destroybind
Destruction method, called from Tk OnDestroy event. Used only for widgets, for other objects destroy is used.
Tk::TM::Lib module imports all TM components (modules) into a program.
Tk::TM::Lib
Imports all TM components (modules) into a program
Tk::TM::Common module contains common data and functions.
Tk::TM::Common
Imports Tk::TM::Common module into application. This does Tk::TM::Lib module.
Default 'Help / About' text: reference to list of rows or sub. See also -about
-about
Default database connection handle, undef in default. Example: $Tk::TM::Common::DBH =DBI->connect("DBI:XBase:.")
Debug level: 0 -none (default), 1 -print actions to STDOUT.
Echo mode - printing commands to be executed: 0 -none, 1 -print (default).
Default mode for application: 0 -view only, 1 -allow edit data (default). See -mdedt
-mdedt
Default 'Help / Help' text: reference to list of rows or sub. See also -help
-help
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.
DBI->connect
$Tk::TM::Common::DBH
Tk::TM::wApp
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.
Tk::TM::Lang
Tk::TM
$Tk::TM::Lang::Lang
Imports Tk::TM::Lang module into application. This does Tk::TM::Lib module.
Switch of language localisation: false - international (no localisation), other - turn on localisation - language name such as 'ru' may be used.
Returns reference to array of rows of embedded help text.
Returns reference to array of texts of menu items
Returns given string translated into used localisation.
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
-wgtbl
-wgbln
-wgarr
-wgmnu
-wgind
-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"
"#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
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
$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.
$do->Stop
Internally used widget level methods with 'wg' prefix: $do->wgFldFocusIn, $do->wgFldFocusOut, $do->wgFldHelper, $do->wgIndicate
$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
$do->Display
$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
$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
$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
dbRead
dbIns
dbUpd
dbDel
rwChg0
rwChg1
rwIns0
rwIns1
rwUpd0
rwUpd1
rwDel0
fdChg0
fdChg1
fdHelp
fdUpd0
fdUpd1
doEnd
doExport
doImport
doPrint
usAct
Imports Tk::TM::DataObject module into application to use data objects. This does Tk::TM::Lib module.
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
@$Tk::TM::DataObject::Available
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.
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.
Events of Tk::TM::DataObject
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.
Widget width adaptation to database fields switch. Contains margin of widget width.
Reference to array of references to hashes with descriptions of fields. Filled in $do->DBICmd('select...').
Reference to hash "fieldName => fieldNumber". Filled in $do->DBICmd('select...').
Database handle (see DBI) to use with database methods. If not set, $Tk::TM::Common::DBH will be used, or other may be programmed.
Data store margin - max number of rows to keep in it.
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.
$Tk::TM::Common::Edit
Programmer`s parameters, hash reference. Does`nt used by Tk::TM, may be used for programmer`s needs.
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.
Tk::TM::wgTable
-sqgpb = parameters for blank widget
See Tk::TM::wgBlank.
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.
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.
tmBlank widget for data object use. Optional.
Indicator widget for data object use with $do->wgIndicate. Optional.
Navigator widget - ancestor of Tk::TM::DataObjSet. This may be used instead of -dos of Tk::TM::DataObjSet, but -dos is more recommended.
-dos
-wgscr
Parent screen for data object. Default is parent of widgets used.
tmTable widget for data object use. Optional.
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.
Drop data buffer. Used in $do->Sleep
End of data object operation. It is no need to redisplay data. Used in $do->Stop
Cancel of operation is not allowed, answer should be certain - 'yes' or 'no'. Used in $do->Stop
Keep current position of data store. Used in $do->Retrieve
Save modified data without ask of user. Used in $do->Stop
Do not display error message box. Used in $do->doImport, $do->DBICmd
Undo unsaved modification of current record of data. Used in $do->Stop
Destroy linked widgets. Used in $do->Sleep
Executes callback usAct. This is used for may be added by programmer menu 'Actions'.
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.
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.
dbh
Query condition and sort dialog. Works with all modes of SQL generation.
SQL generator. In simplest mode it uses -sqlsel, -sqlins, -sqlupd, -sqldel. In complex mode it uses -sqgscr, -sqgfd, -sqgsf, -sqgsj, -sqgsc, -sqgso, -sqgpt, -sqgpb.
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.
-fdHelp
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
Destructor, see DESTROY. Does nothing.
Displays current data on screen. This is not very useful method because all high-level methods keep screen actual.
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
piXXX
Options of Tk::TM::DataObject operation
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
Tk::FileSelect
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
Prints data on printer device or into file specified. See also $do->Print. Not implemented yet.
Displays current data on screen: -wgtbl, -wgbln, -wgarr. Calls $do->dsDispWg.
Displays current data in by-row widgets: -wgbln, -wgarr
Returns data from current or specified widget. Parameter may be data widget or field number or field name.
Replaces (updates) data in specified field, displays it on screen. Field may be identified by number or name.
Sets focus (focusForce) to current widget.
Resets data store, drops all rows of data. Does not displays data on screen, but may this in different releases.
Returns number of data rows in data store.
Deletes current row of data in data store. Displays changes on screen.
Returns reference to array containing data of current or specified row
Pushes specified data row into data store. Does not displays data on screen.
Replaces all data in data store with specified. Does not displays data on screen.
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.
Creates (appends) new row into data store, makes it current, displays it on screen, sets focus to it.
Replaces (updates) data in the current row with data specified, displays it on screen.
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
Presents Find dialog to user and finds in current column first occurrence. See also $do->FindNxt
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.
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
Initialises object, see initialize.
Prints data of data object. Saves modified data if needed via $do->Stop(''). See involved: -cbcmd, doPrint, $do->doPrint.
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.
Deletes current row of data. Saves modified data if needed via $do->Stop('#save'). See involved: -cbcmd, rwDel0, dbDel, rwChg1 $do->dsRowDel, $do->DBICmd
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
Creates (appends) new row of data. Saves modified data if needed via $do->Stop('#save'). See involved: -cbcmd, rwIns0, rwIns1, rwChg1, $do->dsRowNew
Undoes editing of current row of data via $do->Stop('#undo'). See involved: rwChg1
Saves modified data via $do->Stop($opt .'#save'). See involved: rwChg1
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.
#reread
Gets or sets parameters of data object. See set, Parameters of Tk::TM::DataObject
Pushes list parameter into data object. See setpush, Parameters of Tk::TM::DataObject
Stops data editing user transaction if it is. Other methods often calls it. See involved: -cbcmd, rwChg0, dbIns, dbUpd, rwUpd1, doEnd, $do->wgFldFocusOut
Callback for FocusIn Tk event. All used for data object widgets are bind to it.
FocusIn
Callback for FocusOut Tk event. All used for data object widgets are bind to it. This method is called also by $do->Stop
FocusOut
Callback for '<Key-F4>' Tk event. All used for data object widgets are bind to it. This method may be called also outside callbacks.
Indicates current state of data object in -wgind
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.
Module Tk::TM::wgTable contains table widget tmTable, populated with Tk widgets.
Widget tmTable is implemented by module Tk::TM::wgTable. It is inherited from Tk::Frame.
Tk::Frame
Imports Tk::TM::wgTable module into application to use data objects. This does Tk::TM::Lib module.
Creates and returns table widget with parameters specified. Parameters may be Tk options (use configure) or tmTable (use set).
Data object to use with this widget
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.
Label
Entry
Number of on-screen rows of widgets in table
Displays data from data object -do within this table widget.
-do
Sets focus (focusForce) to current widget within this table widget.
Module Tk::TM::wgBlank contains blank widget tmBlank, that presents data row-by-row with Tk widgets.
Widget tmBlank is implemented by module Tk::TM::wgBlank. It is inherited from Tk::Frame.
Imports Tk::TM::wgBlank module into application to use data objects. This does Tk::TM::Lib module.
Creates and returns table widget with parameters specified. Parameters may be Tk options (use configure) or tmBlank (use set).
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.
Displays data from data object -do within this widget.
Sets focus (focusForce) to current widget within this widget.
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::wgActionBar
Tk::TM::wgMenu
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.
-mdscr
Tk::TM::DataObjSet may be classified to:
Parameters: -dos, -wgind, -mdmnu, -mdtbr, -mdedt, -mdnav, -mdscr, -about, -help, -parm
-mdmnu
-mdtbr
-mdnav
Common object methods: new, initialize destroybind, DESTROY, set, setpush
Methods of itself: $dos->DataObject, $dos->doAll, $dos->doCurrent, $dos->Help
$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
$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
$do->FldHelp
Imports Tk::TM::wgBlank module into application to use data objects. This does Tk::TM::wgActionBar, Tk::TM::wgMenu, Tk::TM::Lib modules.
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.
$mw->tmActionBar
$mw->tmMenu
Text or routine to produce about text for 'Help / About' menu.
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.
@Tk::TM::DataObject::Available
Text or routine to produce help text for 'Help / Help' menu.
Enable edit actions for user (edit mode). Value is controlled by current data object.
Type of menu to use: 'bar' - menu bar Tk::Menu (default), 'button' - menu with Tk::Menubuttons, '' - no menu.
Tk::Menu
Tk::Menubutton
Enable only navigation buttons for user (navigation mode). Default is disabled (false).
Restrict operations on all data objects to data objects in the same parent widget as current. Default is disabled.
Type of toolbar (action bar) to use: true - use toolbar (default), false - no toolbar.
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.
$Tk::TM::DataObjSet::Parm
Indicator widget for data objects. See -wgind in it`s description.
Returns current data object
Executes given sub for all data objects or restricted with -mdscr
Executes given sub for current data object.
Executes help screen.
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.
Widget tmActionBar is implemented by module Tk::TM::wgActionBar.
Imports Tk::TM::wgActionBar module into application to use action bar objects. This does Tk::TM::Lib module.
Creates and returns action bar widget with parameters specified. Parameters may be Tk options (use configure) or Tk::TM::DataObjSet (use set).
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].
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.
Widget tmMenu is implemented by module Tk::TM::wgMenu.
Imports Tk::TM::wgMenu module into application to use menu objects. This does Tk::TM::Lib module.
Creates and returns menu widget with parameters specified. Parameters may be Tk options (use configure) or Tk::TM::DataObjSet (use set).
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.
exit calls replaced with Tk::exit calls to avoid abnormal program terminations.
exit
Tk::exit
Key-F4 bindings moved from Tk::TM::DataObject, Tk::TM::wgBlank, Tk::TM::wgTable to Tk::TM::wgMenu to avoid conflict with 'Alt-F4'.
Key-F4
Tk::TM::Common::DBILogin unified for Tk::TM::wApp use.
Tk::TM::Common::DBILogin
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.
-dsslp
-dsrid
-parmc DataObject`s parameter created.
-wgnav DataObject`s parameter renamed to -wgmnu for unification with Tk::TM::wApp.
-wgnav
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.
-dsrd0
-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.
TO DO:
- Test and Debug
- tmDialogBox - approve and document?
- Conflict of 'F4' and 'Alt+F4' callbacks
This documentation was began.
Some reviewing done.
Modules Lib, Common, Lang created.
Lib
Common
Lang
- 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.
Andrew V Makarow <makarow@mail.com>, Denis E Medvedyuk <demed@mail.com>
6 POD Errors
The following errors were encountered while parsing the POD:
You can't have =items (as at line 197) unless the first thing after the =over is an =item
You forgot a '=back' before '=head2'
You can't have =items (as at line 527) unless the first thing after the =over is an =item
You can't have =items (as at line 733) unless the first thing after the =over is an =item
You can't have =items (as at line 1172) unless the first thing after the =over is an =item
Non-ASCII character seen before =encoding in ''ä'"'. Assuming CP1252
To install Tk::TM::Try, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tk::TM::Try
CPAN shell
perl -MCPAN -e shell install Tk::TM::Try
For more information on module installation, please visit the detailed CPAN module installation guide.