isCOBOL Evolve : User Interface : Controls Reference : GRID
GRID
A Grid is a two-dimensional table. It can be customized to meet programmer's needs and cells can hold controls, such as Combo-Boxes, Push-Buttons and Entry-Fields.
Information is organized in rows and columns, and the cells are addressed by row and column coordinates.
Colors and Fonts
Since each element of a Grid can be rendered with different colors and fonts and elements can be overlapped, priority rules are needed.
Colors are applied according to the following list of priorities. Items are listed from the most important to the least important:
Fonts are applied according to the following list of priorities. Items are listed from the most important to the least important:
• Font
Protections are applied according to the following list of priorities. Items are listed from the most important to the least important:
Filtering and finding data
Grids provide a integrated "find all" feature that is activated by pressing CTRL+F when the focus is on the Grid. When CTRL+F is pressed, the following panel is shown at the top of the Grid:
The X button on the left allows you to close the panel. When the panel is closed, the Grid data is restored.
The Combo-Box in the middle allows you to input the text you’re looking for. As you type text in the field, the Grid rows that don’t include your text are made invisible. The other rows show the matching text highlighted unless the Alignment of the column is "H".
Pressing Enter stores your text in the Combo-Box. If you wish to search the same text later, you can select it from the Combo-Box instead of typing it from scratch. The text remains stored until the Grid is destroyed.
Clicking the Clear button clears the text area of the Combo-Box and restores all the data in the Grid.
Clicking the Case button allows you to switch between a case insensitive search ("AA") and a case sensitive search ("Aa").
The integrated "find all" feature can be disabled by setting the Search-Panel property to -1.
The Filterable-Columns style and the Filter-Types property, instead, allow you to filter data according to the content of a Grid column.
The Row-Hiding property is automatically set to 1 for the rows discarded by data filtering and 0 for the rows that were left visible.
The search panel and the filter dialogs inherit the font from the Grid heading.
Embedding controls
Other graphical controls can be shown in Grid cells using the DISPLAY statement. The value of these controls becomes the Cell-Data of the cell.
The following program, creates a Grid control that uses Check-Boxes to display and accept data on the first column and Combo-boxes to accept data on the second column:
       program-id. grid-sample.
       working-storage section.
       copy "iscrt.def".
       copy "isgui.def".
       77 MainWindow handle of window.
       77 My-Combo-Box handle of combo-box occurs 10.
       77 My-Check-Box handle of check-box occurs 10.
       77 idx pic 9(2) value 0.
       77 keystatus pic 9(5) special-names crt status.
           88 esc value 27.
       screen section.
       01 Screen1.
           03 My-Grid grid LINE 2, COL 2, SIZE 70 CELLS, LINES 5,
              DISPLAY-COLUMNS (1, 11, 26, 46), NUM-ROWS 10,
              hscroll vscroll
              event procedure My-Grid-Event-Handler.
       procedure division.
       Main-Logic.
           display standard graphical window background-low
                 handle MainWindow
           display Screen1
           perform varying idx from 1 by 1 until idx > 10
              display Check-Box
                      handle My-Check-Box(idx)
                      event check-evt
                      upon My-Grid(idx, 1)
              display Combo-Box lines 5
                      handle My-Combo-Box(idx)
                      ITEM-TO-ADD ("Item1", "Item2", "Item3",
                                   "Item4", "Item5", "Item6")
                      notify-selchange
                      event combo-evt
                      upon My-Grid(idx, 2)
           end-perform
           perform until esc
              accept Screen1 on exception continue end-accept
           end-perform
           perform varying idx from 1 by 1 until idx > 10
              destroy My-Check-Box(idx)
              destroy My-Combo-Box(idx)
           end-perform
           stop run
           .
 
       My-Grid-Event-Handler.
           display " grid event-type [" event-type "]"
                   upon sysout
           .
       check-evt.
           display " check-box event-type [" event-type "]"
                   upon sysout
           .
       combo-evt.
           display " combo-box event-type [" event-type "]"
                   upon sysout
           .
 
In order to create a control on each row of a column, the special value -1 can be used as y coordinate. According to the above example, this syntax
           perform varying idx from 1 by 1 until idx > 10
              display Check-Box
                      handle My-Check-Box(idx)
                      event check-evt
                      upon My-Grid(idx, 1)
              display Combo-Box lines 5
                      handle My-Combo-Box(idx)
                      ITEM-TO-ADD ("Item1", "Item2", "Item3",
                                   "Item4", "Item5", "Item6")
                      notify-selchange
                      event combo-evt
                      upon My-Grid(idx, 2)
           end-perform
 
Could be rewritten as
              display Check-Box
                      handle My-Check-Box(idx)
                      event check-evt
                      upon My-Grid(-1, 1)
              display Combo-Box lines 5
                      handle My-Combo-Box(idx)
                      ITEM-TO-ADD ("Item1", "Item2", "Item3",
                                   "Item4", "Item5", "Item6")
                      notify-selchange
                      event combo-evt
                      upon My-Grid(-1, 2)
 
Note: Check-Box, Push-Button and Frame are shown permanently on the grid. Other controls are shown only when the user clicks on the cell. Pressing F4 when the focus is on the Combo-Box within a Grid cell doesn’t drop the list of values.
Controls can also be shown only during the editing of a cell by displaying them in the MSG-BEGIN-ENTRY event and destroying them in the MSG-FINISH-ENTRY event, as shown in the below example:
       program-id. Grid1.
       working-storage section.
       copy "iscrt.def".
       copy "isgui.def".
       77  MainWindow      handle of window.
       77  My-Combo-Box    handle of combo-box.
       screen section.
       01  Screen1.
           03 My-Grid grid LINE 2, COL 2, SIZE 70 CELLS, LINES 5,
              DISPLAY-COLUMNS (1, 11, 26, 46), NUM-ROWS 50,
              event procedure My-Grid-Event-Handler.
       procedure division.
       Main-Logic.
           display standard graphical window background-low
                 handle MainWindow
           display Screen1
           perform until 1 = 2
              accept Screen1 on exception continue end-accept
           end-perform
           stop run
           .
       My-Grid-Event-Handler.
           evaluate event-type
           when msg-begin-entry
                display Combo-Box lines 5
                        handle My-Combo-Box
                        ITEM-TO-ADD ("Item1", "Item2", "Item3",
                                     "Item4", "Item5", "Item6")
                        upon My-Grid(event-data-2, event-data-1)
           when msg-finish-entry
                destroy My-Combo-Box
           end-evaluate
           .
 
Note: Controls cannot be displayed over heading cells.
Color and Font of embedded controls
Unless you specify a specific font and color in the DISPLAY statement, the embedded control inherits the font and color of the cell that hosts it.
Best practice for Check-Box handling
In order to respond to every click in the check-box shown in grid cells, rather than have the runtime consider some of the clicks as go-to-cell actions, the best practice is to assign the Check-Box an Exception-Value and the Self-Act style and intercept the click as an exception of the ACCEPT of the screen. The following sample program demonstrates it:
       program-id. GridCheck.
       working-storage section.
       copy "isgui.def".
       copy "iscrt.def".
       77  crt-status special-names crt status pic 9(5).
       77  row pic 999.
       01  rec.
           03 c-1 pic 9   value 1.
           03 c-2 pic xxx value "abc".
           
       screen section.
       01  screen1.
           03 g grid line 2 col 2 lines 10, size 10 cells
              display-columns (1, 3) virtual-width 9
              data-columns (record-position of c-1, 
                            record-position of c-2)
                      .
                            
       procedure division.
       main.
           display standard graphical window.
           display screen1.
           display check-box upon g(-1, 1)
                   self-act, exception-value 100.
           modify g record-to-add rec.
           modify g record-to-add rec.
           perform until exit
             accept screen1 exception crt-status continue end-accept
             if crt-status = 100
                inquire g cursor-y row
                display "click on check-box in grid" upon sysout
             end-if
           end-perform.            
           goback.