NAME

Tk::DBI::DBGrid - grid for browse and edit database.

SYNOPSIS

 use DBI;
 use Tk;
 use Tk::DBI::DBGrid;

 my $dbh = DBI->connect( $dbhstr, $name, $pas, {AutoCommit => 0, RaiseError => 0}) or die DBI::errstr;
 my $w = $MW->Toplevel(-title => 'dbgrid');
 .....
 my $sql = "SELECT field0, field1, field2 FROM table0";

 # read only

 my $grid = $w->DBGrid( -dbh => $dbh, -sql => $sql )->pack;

 # with edit, without INSERT and DELETE

 my @pkey = ('field0');

 my $upd = sub {
     my @row = @_;
     ..... # any kod before UPDATE, if need
     $dbh->do("UPDATE table0 SET  WHERE field0 = $row[0]");
     $dbh->commit;
     ..... # any kod after UPDATE, if need
     0;    # zero is nnecessary for future
 };

 my $grid = $w->DBGrid( -dbh => $dbh, -sql => $sql, -maxrow => 10, -edit => 1,
     -pkey => \@pkey, -updfunc => $upd, -font => 'Courier 10' )->pack;

 # with INSERT, DELETE and formating sells

 my @pkey = ('field0');

 my @cell;
 $cell[0]{width} = 5;
 $cell[0]{edit} = 0;        # primary key need read only
 $cell[0]{name} = 'title0'  # new title for field0
 $cell[1]{width} = undef;   # width field read from table 
 $cell[1]{edit} = 1;
 $cell[2]{width} = 7;
 $cell[2]{edit} = 1;
 $cell[2]{justify} = 'left';


 my $ins = sub {
     my @row = @_;
     ......
     $dbh->do("INSERT INTO table0 (field0, field1, field2) VALUES ($row[0], $row[1], $row[2])");
     $dbh->commit;
     ......
     0;
 };

 my $upd = sub {
     my @row = @_;
     ..... 
     $dbh->do("UPDATE table0 SET  WHERE field0 = $row[0]");
     $dbh->commit;
     ..... 
     0;
 };

 my $del = sub {
     my ($pkey) = @_;
     .....
     $dbh->do("DELETE FROM table0 WHERE field0 = $pkey");
     $dbh->commit;
     .....
     0;
 };

 my %fkey;
 $fkey{ins} = 'Key-F5';
 $fkey{del} = 'Key-F8';

 my $grid = $w->DBGrid( -dbh => $dbh, -sql => $sql, -maxrow => 10, -edit => 1,
     -pkey => \@pkey, -insfunc => $ins, -updfunc => $upd, -delfunc => $del,
     -font => 'Courier 10', -cellformat =>\@cell, -fkeys => \%fkey )->pack(-fill => 'x');

DESCRIPTION

DBGrid allows to browse/edit any table to which a query can be applied. The query may join several tables.

Edit table

Every record should be monosemantically defined by some field perfoming a primary key function for editing. So as to transfer changes to the database one may use the functions, pointers to which have been delivered to the constructor ( -insfunc, -updfunc & -delfunc ). The functions themselves are described in the basic program text. If a pointer is not for delivering or undef is transferred the action is not worked up. If the key words of group operation or UNION are found in the query, DBGrid will turn to browse mode ( -edit => 0 ). The data are not refreshed after calling functions in this DBGrid version.

Formating cells

Table parameters define every field parameter of reflection (the length and type - char, numeric or others - are read). Editing for the field defined through -pkey is inaccessible. All DBGrid cells are the control elements Label or Entry and after visibility one may rule them separately, for example $grig->{rowframee}->[$i][$j]->configure( -font => 'Courier 12').

OPTIONS

-dbh: contains database handle object. It is a required item.
-sql: contains query, DBGrid defines the result of which. The result of the query is inserted into the array $grid->{table}->{data}->[row_number][field_number]. This array is zero based. It is a required item.
-maxrow: defines the maximum quantity of records displayed in the DBGrid. Default is 10.
-edit: defines the mode DBGrid being reflected (it must be 0 for browse mode or 1 for edit mode). Default is 0.
-pkey: must be defined for edit mode. If -pkey is not defined or its meaning is not found in the query then edit => 0.
-incfunc: defines the pointer to the function which is called for a new record insertion. The array containing the record for insertion into table is transferred to the function. The sequence of the fields is the same as it is in the received query through -sql. If the function is not defined a new record will not be added. If the function returns 1 (true) then data from database are refreshed after this call. Default is undef.
-updfunc: serves as -insfunc but with one difference: when it means undef it still allows to change cell contents although these changes are not transferred to the database. If the data are not modified ih the function then it is better not to refresh the data of module cache (to return 0). Default is undef.
-delfunc: serves as -insfunc.
-titlbg: defines the background color of field titles. Default for windows SystemButtonFace, for other OS is #f0f0f0.
-seltitlbg: defines the background color of the title of the active field. Default for windows SystemHighlight, for other OS is gray.
-font: Specifies the font used in cells. Since the width of the elements Entry & Label is set in symbols the font must be monospaced, for example Courier. Default value is 'Courier 9'.
-cellformat: Specifies the pointer to the array the first element of which defines the field number and the second one is an item of field formating. width is a field width in symbols, edit sets the possibility of editing this field (and so -edit => does), justify defines the text position in the cell (it must be one of left, center, right).
-fkeys: Specifies the hash pointer where new key combinations of record insertion, deleting and coping to clipboard are kept. The insertion of a new record is kept in the {ins}. The deleting of a current one is kept in the {del}. The coping of current record to clipboard is kept in the {copy}, {copy2}, {copy3}. If the meaning of -fkeys is not defined F5 is set for inserting, F8 is set for deleting and Ctrl+C & Ctrl+Ins is set for coping the current record to clipboard .
-encodes: specifies the pointer of the function which is called to encode the data from the database codepage into desktop codepage. For example, NLS_LANG=CL8MSWIN1251 is used in the database and UTF8 is used in Gnome 2.x. If the function is not defined the data will not be encoded. Default undef.

AUTHORS

Vadim Likhota vadim-lvv[at]yandex.ru

KEYWORDS

dbgrid, entry, label, database, table

main