GRIDPLUS Tablelist

In order to simplify creation of screens GRIDPLUS provides a GRIDPLUS tablelist command mode. This uses a simple syntax to create a Tablelist with optional scrollbars. The GRIDPLUS Tablelist can have its contents set using the gpset command. Rows can also be inserted using gpinsert, updated using gpupdate and deleted using gpdelete. A selected line in the GRIDPLUS Tablelist can be read, in the same manner as other GRIDPLUS widgets, from the "null" array -or- by using the widget command. A row can be selected either by using the mouse -or- the gpselect command.

The GRIDPLUS Tablelist is created using the Tablelist package created by Dr Csaba Nemethi. Most of the GRIDPLUS Tablelist options are directly taken from, or based on, those detailed in the Tablelist documentation.

It is possible to have a menu pop-up when a row is selected using a right-click. The menu is created using the GRIDPLUS menu command and is associated with the tablist by specifying the -menu option.

Using Tablelist "Native" Options

It is possible to use any "native" Tablelist options provided that the Tablelist option does not have the same name as a GRIDPLUS option.

Taking Example 3 below, it is possible to set the -arrowcolor option simply by specifying the option to the "gridplus tablelist" command:-

gridplus tablelist .mytable                         \
   -arrowcolor    red                               \
   -width         50                                \
   -height        8                                 \
   -action        double                            \
   -insertexpr    {%balance < 0}                    \
   -insertoptions {{balance -fg red}                \
                   {balance -selectforeground red}} \
   -tableoptions  stripe                            \
   -relief        groove                            \
   -scroll        y                                 \
   -selectfirst   1                                 \
   -sortfirst     1                                 {
   6 "Account"       integer
   0 "Name"
   0 "SecurityCode"  hide
   6 "Balance" right real
}

This behaviour can be disabled by setting the "Gridplus.unknown" option database option to "0".

Column Options

When configuring the Tablelist Columns, options can be specified which effect the layout and/or sort order.

right	Column is right justified.
hide	Column is hidden (Hidden data is returned when row is selected).
asciinocase	Column is sorted as case insensitive ascii.
dictionary	Column is sorted as dictionary.
integer	Column is sorted as integer.
real	Column is sorted as real number.
=name	Column to have name.

Note: By default column contents are left justified and sorted as ascii.

Setting Tablelist Column Titles/Names

Column Titles

The column titles would normally be set, when the Tablelist is created, as part of the Tablelist layout as demonstrated in the Samples/Examples on this page.

It is also possible to change the column titles of a previously created Tablelist using the gpset command.

Example:

gpset -titles .mytable {"Title One" "Title Two" "Title Three"}

Column Names

Column names (See Tablelist documentation for details/usage) are automatically generated.

The name is based on the column title with the following rules applied:-

• The title is converted to all lowercase.
• Spaces are replaced with underscore ("_").
• All characters with are not "a-z", "0-9" or "_" are removed.

In GRIDPLUS it is possible to override the default column names in three ways:-

1) When the Tablelist is created as part of the layout:-

Column options begining with "=" can be used to define column names.

Example:

gridplus tablelist .mytable -width 50 -height 8 -relief groove -scroll y {
   0 "Column0" =myname0 hide
   4 "Column1"
   4 "Column2" "=myname two" right
   4 "Column3"
   0 "Column4" =myname4
}

2) When the Tablelist is created using the -names option:-

Column options begining with "=" can be used to define column names.

Example:

gridplus tablelist .mytable -width 50 -height 8 -relief groove -scroll y -names {myname0 "myname one" myname2} {
   0 "Column0" hide
   4 "Column1"
   4 "Column2" right
}

3) After the Tablelist has been created using the gpset command.

Example:

gpset -names .mytable {Name1 "Name Two" Name3}

Note: If a name is to contain spaces it must be quoted.

Invoking a Command When Selecting a Row

The -action option allows a command to be invoked when a Tablelist row is selected. By default the row is selected and no command is invoked.

There are two -action options which invoke a command:-

-action single	A single-click will select the row and invoke the item command.
-action double	A single-click will select the row and a double-click invoke the item command.

By default the name of invoked command is based on the name of the Tablelist item. If the Tablelist is called ".mytable" the command invoked will be "mytable".

The -command option can be used to explicitly specify the name of the command to be invoked.

Widget Command

When a GRIDPLUS Tablelist is created a widget command with the same name as the GRIDPLUS Tablelist item is also created which can be used to return the values of specified columns of the selected Tablelist row.

In order to maintain backward compatibility, if the widget command is either "cget" or "configure" the widget command will effect the frame in which the Tablelist is contained -otherwise- it is assumed that the command specifies the names of the Tablelist columns to be returned.

The column values to be returned can be specified in three ways:-

column1,column2,...

Returns a Tcl list of the specified columns in the specified order. A single column may be returned.

column1+column2

Returns the concatenation of the specified columns separated by space.

column1>column2

Returns a Tcl list of all columns from column1 through to column2 inclusive.

This section contains examples which illustrate the main GRIDPLUS tablelist command mode features.

The following example assumes that the reader is familiar with the contents of the Grid/Layout page. Information given on that page will not be duplicated here.

Note: The examples assume that the GRIDPLUS package has already been "required" and the commands imported.

Tablelist Example 1

gridplus tablelist .mytable {
   4 "Column1"
   4 "Column2"
   0 "Column3"
}

gridplus layout .main -wtitle "Tablelist Example" {
   .mytable
}

pack .main

Note: The column details of the GRIDPLUS Tablelist are based on the tablelist package -columns option.

Tablelist Example 2

gridplus tablelist .mytable -width 50 -height 8 -relief groove -scroll y {
   0 "Column0" hide
   4 "Column1"
   4 "Column2" right
   0 "Column3"
}

gridplus layout .main -wtitle "Tablelist Example" {
   .mytable
}

pack .main

This example creates a Tablelist with a width of "50" characters and a height of "8" lines. As with GRIDPLUS Grids/Layouts, the Tablelist can have a border. In this case the -relief groove option adds a "groove" style border.

The -scroll y option adds a "Y" direction (vertical) scollbar.

The Tablelist has four columns: "Column1" and "Column2" are "4" units wide. "Column2" is "right" justified and "Column0" is hidden. Although the content of "Column0" is not shown in the display it will be included in the value set when a row is selected. The "0" (zero) width setting for "Column3" causes the column to automatically size. In this case it will fill the remaining width of the Tablelist.

Note: The "hide" column option is not part of the standard tablelist package syntax.

Tablelist Example 3

gridplus tablelist .mytable                         \
   -width         50                                \
   -height        8                                 \
   -action        double                            \
   -insertexpr    {%balance < 0}                    \
   -insertoptions {{balance -fg red}                \
                   {balance -selectforeground red}} \
   -tableoptions  stripe                            \
   -relief        groove                            \
   -scroll        y                                 \
   -selectfirst   1                                 \
   -sortfirst     1                                 {
   6 "Account"       integer
   0 "Name"
   0 "SecurityCode"  hide
   6 "Balance"       right real
}

gridplus layout .main -wtitle "Tablelist Example" {
   .mytable
}  

pack .main

gpset .mytable {
   {1 {Fred Smith} AZ98765 120.45}
   {4 {Mary Jones}  DT8524 5156.67}
   {3 {Susan Freeman} PX89654 -987.03}
   {10 {David Miles} ZB1304 10654.84}
}

This example creates a Tablelist with a width of "50" characters and a height of "8" lines. As with GRIDPLUS Grids/Layouts, the Tablelist can have a border. In this case the -relief groove option adds a "groove" style border.

The -scroll y option adds a "Y" direction (vertical) scollbar.

A single-click on a row in the Tablelist will select the row. The value of the "null array" item (in this case ".mytable") will be set to the contents of the row. When the -action double option is set a command will also be invoked when a row is double-clicked. The command name is based on the name of the Tablelist, in this case ("mytable").

The -insertexpr and -insertoptions options allow column/row options to be set depending on the contents of the row when setting the content of the Tablelist using the gpset command. -insertexpr specifies an expression to be tested for each row when added to the Tablelist. The expression must be in the format expected by the if command. A percent subsitution facility is available to refer to column values in the line. The column values can be referenced by name or numeric column number. Column numbers are indexed from zero, for example, "%3" is the fourth column. For this example ("{%balance < 0}") the expression is true if the value of the column with name "balance" is less than zero. If the expression evaluates to true the "true" options specified by -insertoptions are applied to the row. Each "insertoption" consists of three parts; The column name/number, the option and the value(s). To have the option apply to a whole row an asterisk ("*") should be used as the column number.

The -tableoptions stripe causes option alternate lines to have a background highlight.

The -selectfirst 1 option causes the first row in the Tablelist to be automatically selected when the contents of the Tablelist are set using the gpset command.

The -sortfirst 1 option causes the Tablelist to be sorted on the first column when the contents of the Tablelist are set using the gpset command. This option also enables column sorting by clicking on the column labels.

The Tablelist Columns are specified such that the "Account" column is sorted as an integer, the "SecurityCode" column is hidden, the "Balance" column is right justified and will sort in real number order.

Note: This example also sets the contents of the Tablelist to demonstrate the effect of some of the previous options.

Reading and Setting GRIDPLUS Tablelist Values

The values of the GRIDPLUS widgets are stored in a global array with a null name.

For Example:

global {}

For GRIDPLUS Tablelist widgets the array element has the same name as the widget frame: Thus the value of ".mytable" is referenced as "$(.mytable)".

Note: For the GRIDPLUS Tablelist only the value of the selected row is stored in the array. If no row is selected there is no entry in the array.

The recommended method to set GRIDPLUS Tablelist values is to use the gpset command.

For Example:

gpset .mytable {
   {1 {Fred Smith} AZ98765 120.45}
   {4 {Mary Jones}  DT8524 5156.67}
   {3 {Susan Freeman} PX89654 -987.03}
   {10 {David Miles} ZB1304 10654.84}
}

It is possible to specify ICONS images to be displayed in the Tablelist data.

For Example:

Using the Tablelist from Example 3 the following...

gpset .mytable {
   {1 {:edit16 Fred Smith} AZ98765 120.45}
   {{:actcross16 4} {Mary Jones}  DT8524 5156.67}
   {3 {Susan Freeman} PX89654 {:filesave16 -987.03}}
   {{:actcheck16 10} {David Miles} ZB1304 10654.84}
}

...Will display...