GRIDPLUS - Tablelist
Home Reference Manpage Examples Download License Contact

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. A selected line in the GRIDPLUS tablelist can be read, in the same manner as other GRIDPLUS widgets, from the "null" array.

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.

Examples

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

Window:

Source Code:

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

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

pack .main

Comments:

This example creates a tablelist with a default size (40 characters wide, 10 lines deep). The -wrap option is set to "word" by default.

The tablelist has three columns: "Column1" and "Column2" are "4" units wide. 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 column details of the GRIDPLUS tablelist are based on the tablelist package -columns option.


Tablelist Example 2

Window:

Source Code:

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

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

pack .main

Comments:

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

Window:

Source Code:

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

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

pack .main

gpset .mytable {
   {000001 {Fred Smith} 120.45}
   {000004 {Mary Jones} 5156.67}
   {000003 {Susan Freeman} -987.03}
   {000002 {David Miles} 10654.84}
}

Comments:

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 ("gp: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 and 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 are indexed from zero, for example, "%2" is the third column. For this example ("{%2 < 0}") the expression is true if the value of the third column is less than zero. If the expression evaluates to true the options specified by -insertoptions are applied to the row. Each "insertoption" consists of three parts; The column number, the option and the value. To have the option apply to a whole row an asterisk ("*") should be used as the column number.

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

The -selectfirst 1 option causes the first row in the tablelist to be automatically slected 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.

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 {
   {000001 {Fred Smith} 120.45}
   {000004 {Mary Jones} 5156.67}
   {000003 {Susan Freeman} -987.03}
   {000002 {David Miles} 10654.84}
}


Copyright © 2004 Adrian Davis.