Grid Tutorial 2 - Standard Grid Using BBjGrid Methods

For Visual PRO/5 Grid Tutorials, see Data-Aware Grid Tutorial, Standard Grid Control Tutorial 1: Display-Only Grid and Standard Grid Tutorial 2: User-Modifiable Grid.

Suggested Procedures for Using the BBjGrid Control with BBjGrid methods:

1. Create the basic grid control using BBjWindow::addGrid.

2. Define various grid attributes using BBjGrid methods.

3. Set cell text using BBjGrid::setCellText(row, column, text$) or setCellText(BBjVector) using a BBjVector object. If the data has a large amount of rows and/or columns, setting cell text in response to the table update event may still be faster since it will not have to initialize the data for all cells at once. Using setCellText(BBjVector) will be faster than setCellText(row, column, text$) because less method calls are needed.

4. Use BBjGrid::setUpdateCached(FALSE) to turn on the option to not send notify 22 when cells already contain data. This will reduce the number of table update events sent from the grid.

5. Set the editability of the grid using BBjGrid::setGridEditable. If grid editing is desired for all cells, nothing needs to be done.

6. Set drag and drop option if desired using BBjGrid::setDragAccept.

7. Show the grid.

8. Register Callbacks for handling events or use read record to read events. This tutorial will use Callbacks. No handling of events is required to manage data, editing, or drag and drop when the grid is in use. Although, all of the regular and notify events are supported.

   The following tutorial will create a grid that displays weather information for a week.

   The grid will be editable if the editable check box is checked and editing will begin when a cell is double-clicked. If the editable check box it is checked off, the program will display a message box showing the cell contents if a cell is double-clicked. The results of this tutorial are the same as the results from BBjGrid Tutorial 1.

9. Setup window:

   REM Open SYSGUI Channel and Window
   LET SYSGUI=UNT
   OPEN (SYSGUI)"X0"
   REM create window with event loop for check event
   PRINT (SYSGUI)'WINDOW'(100,100,600,300,"Grid Tutorial 2",$$,$02000000$)

10. Set Case sensitivity on (if desired) to allow text to remain as typed. Also, retrieve BBjSysGui and BBjWindow objects.

    REM SET_CASE_SENSITIVITY_ON not really needed for this tutorial but it helps
    REM make the method names more readable
    SET_CASE_SENSITIVE_ON
    
    REM Get Window and SysGui Objects
    LET BBJ! = BBjAPI()
    LET SYSGUI! = BBJ!.getSysGui()
    LET WINDOW! = SYSGUI!.getWindow(0)
    

11. Set variables and create other controls:

    REM Set true/false constants
    LET TRUE=1
    LET FALSE=0
    
    REM Initialize variables
    LET GRID=100
    LET COLID=101
    LET ROWID=102
    LET NUMROW=7
    LET NUMCOL=9
    LET CONTEXT = 0
    LET EDITABLE=TRUE; REM option to set grid editable
    
    PRINT (SYSGUI)'TEXT'(97,10,5,150,25,"Weather Forecast",$$)
    PRINT (SYSGUI)'FONT'(97,"",12,DEC($01$))
    PRINT (SYSGUI)'TEXT'(98,160,10,200,25,"Temperature in Degrees Fahrenheit",$$)
    REM Display a checkbox to allow Grid editing to be toggled
    LET CHECK_FLAGS$=$$
    IF EDITABLE THEN
        LET CHECK_FLAGS$=$04$
    FI
    PRINT (SYSGUI)'CHECKBOX'(99,450,5,100,25,"Grid Editable",CHECK_FLAGS$)

12. Create the basic grid control on the window using BBjWindow::addGrid:

    REM Create grid using Object Syntax
    LET GRID!=WINDOW!.addGrid(GRID,20,30,544,230,$8856$,NUMROW,NUMCOL)

13. Set attributes in the grid:

    GRID!.setFitToGrid(TRUE)
    REM Set some properties on the grid
    GRID!.setRowHeaderWidth(100)

14. Set header titles using BBj Object syntax. Create a BBjVector to add the headers.

    REM Set header titles using setColumnHeaderCellText()
    REM First create a BBjVector and add header strings to it
    
    LET VECTOR!=SYSGUI!.makeVector()
    VECTOR!.add("8 AM")
    VECTOR!.add("9 AM")
    VECTOR!.add("10 AM")
    VECTOR!.add("11 AM")
    VECTOR!.add("12 PM")
    VECTOR!.add("1 PM")
    VECTOR!.add("2 PM")
    VECTOR!.add("3 PM")
    VECTOR!.add("Rain")
    GRID!.setColumnHeaderText(VECTOR!)
    
    VECTOR!.clear()
    VECTOR!.add("Sunday")
    VECTOR!.add("Monday")
    VECTOR!.add("Tuesday")
    VECTOR!.add("Wednesday")
    VECTOR!.add("Thursday")
    VECTOR!.add("Friday")
    VECTOR!.add("Saturday")
    GRID!.setRowHeaderText(VECTOR!)

15. Set the style of the last column:

    REM set style of last column to checkbox
    GRID!.setColumnStyle(NUMCOL-1,8)

16. Set individual cells to checked:

    REM set the style of a couple checkboxes to checked
    GRID!.setCellStyle(1,NUMCOL-1,4)
    GRID!.setCellStyle(4,NUMCOL-1,4)

17. Set the colors of the columns. Color objects are generated using BBjSysGui::makeColor.

    REM set column colors
    FOR COL=0 TO NUMCOL-1
        IF COL<3 THEN
            LET COLOR!=SYSGUI!.makeColor("green")
         ELSE
            IF COL<6 THEN
                LET COLOR!=SYSGUI!.makeColor("yellow")
             ELSE
                IF COL<8 THEN
                    LET COLOR!=SYSGUI!.makeColor(255,50,50)
                 ELSE
                    LET COLOR!=SYSGUI!.makeColor("blue")
                 FI
             FI
         FI
        GRID!.setColumnBackColor(COL,COLOR!)
    NEXT COL

18. Set the text in the grid cells using BBjGrid::setCellText(BBjVector):

    REM Set text in cells using setCellText(BBjVector)
    REM First load the vector. Cells are loaded in rows starting from
    REM row 0, column 0 for as many strings are in the BBjVector
    VECTOR!.clear()
    FOR ROW=0 TO NUMROW-1
        FOR COL=0 TO NUMCOL-1
            IF COL = NUMCOL-1
                buff$=""; REM no text for last col
            ELSE
                buff$=STR(50+ROW+COL)
            FI
            VECTOR!.add(buff$)
        NEXT COL
    NEXT ROW
    GRID!.setCellText(VECTOR!)

19. Set grid properties:

    REM Set grid to not send notify event 22 if cells already contain data
    GRID!.setUpdateCached(FALSE)
    
    GOSUB SET_EDITABLE
    REM Set drag and drop
    GRID!.setDragAccept(TRUE)

20. Show the grid:

    GRID!.setVisible(TRUE)

    Grid appearance after shown:

    

    Appearance of grid when cell edited:

    

21. Register Callbacks and begin event loop. Event loop is necessary for optional grid handling.

    REM Register callbacks to handle some events
    REM Only need to register events that we want to handle
    CALLBACK(ON_CHECK_ON,ENABLE_EDITING,CONTEXT,99)
    CALLBACK(ON_CHECK_OFF,DISABLE_EDITING,CONTEXT,99)
    CALLBACK(ON_GRID_DOUBLE_CLICK,GRID_DOUBLE_CLICKED,CONTEXT,GRID)
    CALLBACK(ON_CLOSE,EXIT,CONTEXT)
    
    REM Set event template
    DIM EVENT$:TMPL(SYSGUI)
    DIM GENERIC$:NOTICETPL(0,0); REM ' Generic Notice Template
    
    REM Process Events loop.
    REM Subroutines will get called when the registered events occur
    REM And methods will return to continue event loop
    PROCESS_EVENTS

22. When editable check box is toggled one of these subroutines will be called. Set editability in grid.

    ENABLE_EDITING:
        EDITABLE = TRUE
        GOSUB SET_EDITABLE
    RETURN
    
    DISABLE_EDITING:
        EDITABLE = FALSE
        GOSUB SET_EDITABLE
    RETURN

23. Cell was double clicked so that if grid is not editable, use methods to retrieve state or text in cell then display a message box indicating cell contents. BBjSysGui::getLastEventString is used to retrieve the event string that would be retrieved using READ RECORD. This allows the method to retrieve more information from the event; in this case the row and column of the clicked cell.

    GRID_DOUBLE_CLICKED:
    REM If editable, do nothing, otherwise show a window containing contents of cell
        IF EDITABLE = FALSE THEN
    REM Get contents of cell. First get event string in order to get cell clicked on
            REM Could also use GRID!.getSelectedCell()
            GOSUB GET_GRID_NOTIFY
            ROW = GRID_NOTICE.ROW
            COL = GRID_NOTICE.COL
    
            REM First check if last column
            IF COL = NUMCOL-1 THEN
                REM Get cell state (TRUE= Checked)
                CHECKED = GRID!.getCellState(ROW,COL)
                IF CHECKED = FALSE THEN
                    DISPLAY$="No rain forcasted"
                ELSE
                    DISPLAY$="Rain forecasted"
                FI
            ELSE
                REM Get cell text
                CELL$= GRID!.getCellText(ROW,COL)
                DISPLAY$="The temperature at this time will be "+$0A$ +CELL$+ $0A$+"degrees Fahrenheit"
            FI
            REM Display a message box
            LET V=MSGBOX(DISPLAY$)
        FI
    RETURN

24. Subroutine used to set grid editability to EDITABLE:

    SET_EDITABLE:
    REM Set editability of grid
        GRID!.setGridEditable(EDITABLE)
    RETURN
    END

25. Subroutine used to retrieve grid notify event info:

    GET_GRID_NOTIFY:
    REM Get last event string
    EVENT$= SYSGUI!.getLastEventString()
    LET GENERIC$=NOTICE(SYSGUI,EVENT.X%)
    DIM GRID_NOTICE$:NOTICETPL(GENERIC.OBJTYPE%,EVENT.FLAGS%)
    LET GRID_NOTICE$=GENERIC$
    RETURN

26. Subroutine called on exit and program end handling:

    EXIT:
        PRINT(SYSGUI)'DESTROY'(0)
        RELEASE
    RETURN
    
    SET_CASE_SENSITIVE_OFF
    END

    Appearance of grid after double-clicking on non-editable grid: