BBj Grid Enhancements

 

For this topic's original documentation, see Grid Controls.

 

In BBj 15.0 and higher, the new Enhanced Grid Selection Model builds upon legacy grid features and functions.

 

Prior to BBj 15.0, many enhancements were made to the BBj Grid to improve usability and simplify syntax. These areas of enhancement included:

  • Data storage and display

  • Setting attributes of grid cells

  • Cell editing

  • Checkbox and button style cell handling

  • Drag and drop handling

  • Main and Heading Grid Relationships

  • BBjGrid methods also improve syntax and offers an alternative to SENDMSGs

These topics are described in further detail below.

Some of the behavior for the BBj grid is considerably different from VPRO/5 grid behavior, and older programs may not work correctly using some of the grid enhancements. The grid can be made backwards-compatible so that VPRO/5 behavior is used, and older programs will work. In order to set backwards-compatibility, set the Grid Backwards Compatibility setopts bit (8,$10$). For more information, see the SETOPTS Verb. The following line added at the beginning of a program containing grids will set backwards-compatibility on, and some BBj behavior will be turned off.

LET OPTS$=OPTS; LET OPTS$(8,1)=IOR(OPTS$(8,1),$10$); SETOPTS OPTS$

Behaviors that are controlled by this setopts bit will be specified in the descriptions below.

The following are tutorials for the BBj Grid:

Grid Data Storage And Display

The BBj grid stores the cell data internally. Once data is set in a cell at a particular row and column, it will remain in that cell until the data is changed by the program, or edited by the user. Because of this feature, it is no longer necessary to rely on the table update event in order to display data in the grid. Data can be set in the entire grid during grid setup. For more information on setting up data in a grid, see the BBj Grid Tutorial: Standard Grid.

By default, table update events are generated as they are in BBx. BBj SENDMSG 110  (Set Update Cached Cells) will set the option to not send table update events, if there is data already in the cell. This sendmsg will improve speed in the BBj grid, because the program will not have to update data in cells that already have data. A table update event for all visible cells is generated when the grid is displayed on the screen for the first time. When the number of rows or columns increases, a table update event is generated for the added rows and columns. When the number of rows or columns decreases, an update event is generated for any rows or columns with a higher index value than the removed rows or columns. An update event is also generated when the user scrolls the grid, for the newly displayed rows and columns. If SENDMSG 110 is used to set cached cells not to be updated, then an update event will only be generated the first time a row or column is made visible.

Setting Attributes Of Grid Cells

A number of SENDMSGs have been added to make it easier to set text, styles, and other properties in the grid. These are intended to replace SENDMSG 54 (draw cell), which is still available in BBj, but not recommended. The SENDMSGs can be used during grid setup, and the grid does not have to be visible. The SENDMSGs can be used to set properties on an entire column, or can be used to set only text in an individual cell. The SENDMSGs are:

102: Set Column Background Color. The default background color is dependant on the operating system. For Windows it is light gray.

103: Set Column Text Color. The default text color is black.

104: Set Column Style. The default column style is InputE.

105: Set Column Alignment. The default alignments is center.

109: Set Cell Text.

It is recommended that these SENDMSGs be used to set up the grid instead of waiting for the table update event to draw a cell. Because the SENDMSGs can be used while the grid is hidden, the grid can be shown after the grid appearance has been set up and data has been loaded. This will make it appear that the grid is displaying faster because it is not setting up cells while it is visible.

In BBj, using an entry of $10$ in the style parameter causes the cell to function as an edit control. This functionality is not available in Visual PRO/5.

Get Cell Text - SENDMSG() Function 113 has been added to retrieve the text in a cell.

Grid Cell Editing (Controlled By Grid Backwards Compatibility Setopts Bit)

The BBj grid will by default automatically handle cell editing without requiring programs to use the Start Edit - GRID SENDMSG() Function 31. When a cell is double-clicked on, it will be put into edit mode if the cell has not been set as un-editable using SENDMSGs() 106,107, 108 or 81 with option $01$ for data-aware grids. Editing will end on the cell when focus is moved off the cell by moving to another cell or a different control. If the cell text is modified by the user, then the modified value will remain in the cell. The Start Edit (31) and End Edit(26) SENDMSGs will be ignored.

By default, the grid is not editable. To set the grid editable, use SENDMSGs listed below (or their BBj method counterparts). The number of clicks needed to start editing can be changed using SENDMSG() Function 111.

The start edit and edit kill notify event will still be generated when editing starts and ends, respectively on a cell.

Several SENDMSGs have been added to control cell editability. By default, all cells of style InputE, InputN and Text are editable. The following SENDMSGs can be used to set them to be un-editable:

This behavior is by default. However, grids can be made to behave like VPRO/5 by setting the Grid Backwards Compatibility setopts bit (8,$10$) SETOPTS Verb. This will require the program to use start edit to begin editing on a cell in a grid. To make grids backwards compatible, simple add the following line to the beginning of the program or set the setopts bit in the config file:

LET OPTS$=OPTS; LET OPTS$(8,1)=IOR(OPTS$(8,1),$10$); SETOPTS OPTS$

Starting editing with keys:
If the grid (or current cell) is editable, then typing the ENTER key will put the cell into edit mode. Hitting the ENTER key when the cell is in edit mode will take it out of edit mode. If currently in edit mode and the TAB key is typed, editing will stop on the current cell and resume on the next cell. If currently in edit mode and SHIFT+TAB is typed, editing will stop on the current cell and resume on the previous cell. The meaning of 'next' and 'previous' cell depends on the value returned by current TabAction of the grid. See BBjGrid::getTabAction and BBjGrid::setTabAction.

Checkbox And Button Style Cells (Controlled By Grid Backwards Compatibility Setopts Bit)

Grid cells that have been given the styles 1, 2, 4 or 8 (See GRID SENDMSG() Function 54 BBj ) will by default behave differently in BBj than in VPRO/5. When these cells are clicked on, the state of the button or checkbox will toggle automatically. If the check box is not checked, and the user clicks on it, then the grid will automatically set the check box to checked. In BBx, the program has to listen for the mouse click notify event and set the style of the cell when the user clicked on it.

In BBj, the entire contents of checkboxes and radio buttons are aligned. In BBx, only the label is aligned and the check box or radio button remains left justified. In BBj, the check box or radio button is aligned along with the label.

Toggling of the check box and button style cells can be turned off in two ways. The first is to set the setopts bit (8,$10$) for Backwards Compatible Grid behavior SETOPTS Verb. The second is to use either SENDMSG 106,107 or 108 to make the cell non-editable, meaning the user will not set the state of the cell. The LCLICKED event will still be sent so that the style of the cell can be changed programmatically in response to a mouse click.

This behavior is by default. However, grids can be made to behave like VPRO/5, which requires the program to set the style of the cell, by setting the Grid Backwards Compatibility setopts bit (8,$10$) SETOPTS Verb. To make grids backwards compatible, simply add the following line to the beginning of the program:

LET OPTS$=OPTS; LET OPTS$(8,1)=IOR(OPTS$(8,1),$10$); SETOPTS OPTS$

Get Cell State - SENDMSG() Function 114 has been added to retrieve the check state of checkbox and button style cells.

Column and Row Change Events (Controlled By Grid Backwards Compatibility Setopts Bit)

The standard rule in Visual PRO/5 is to not fire events in response to program actions. Visual PRO/5 breaks this rule, firing ON_GRID_SELECT_COLUMN in response to Goto Column - GRID SENDMSG() Function 47 and ON_GRID_SELECT_ROW in response to Goto Row - GRID SENDMSG() Function 48.

By default, BBj does not fire the ON_GRID_SELECT_COLUMN event in response to Goto Column - GRID SENDMSG() Function 47, or the ON_GRID_SELECT_ROW event in response to Goto Row - GRID SENDMSG() Function 48. However, grids can be made to behave like VPRO/5 by setting the Grid Backwards Compatibility setopts bit (8,$10) SETOPTS Verb. To make a grid backwards compatible, add the following line to the beginning of the program:

LET OPTS$=OPTS; LET OPTS$(8,1)=IOR(OPTS$(8,1),$10$); SETOPTS OPTS$

Drag and Drop

In BBj, dragging is managed automatically, once the Set Drag Accept SENDMSG has been called to turn on drag and drop. Drag Start - SENDMSG() Function 25 is no longer needed. If it is used, it still changes the drag cursor based on the cursor parameter (see values below) but will not start the drag operation. This cursor overrides any cursor set by Set Cursor - SENDMSG() Function 78. In other words, there is always only one possible cursor for a grid. A cursor cannot be set for one particular drag operation. The text parameter in Drag Start - SENDMSG() Function 25 will be ignored. The text being dragged is always the text that is within the cell that was selected when dragging began.

Dragging operations work between any grids running in the same BASIS IDE that have been registered to accept drag operations using Set Drag Accept - SENDMSG() Function 33.

Main and Heading Grid Relationships

In VPRO/5, in ResBuilder and the GRID mnemonic, the main grid and its header grid(s), if any, are handled as one control. Once the grid is created, Visual PRO/5 treats the main grid and column/header grids as three separate controls. For example, each grid can be moved independently, and the location of each grid queried independently. Because of this, ResBuilder and Visual PRO/5 can become unsynchronized. For example, if a grid is created with a column header in ResBuilder and the x,y coordinates set to 50,50, the entire grid displays at 50,50 in Visual PRO/5. Querying the location of the grid in VPRO/5 returns the position of the main grid, ignoring the location of the column header grid.

In BBj, the grid and its headers are always handled as one unit. Although separate IDs can still be used, getting or setting the location of a header or a main grid always gets the top left of the grid, encapsulating all parts. This may produce different results than Visual PRO/5 if a grid is moved. It may be at a different location than expected, and headers cannot be moved to anywhere other than next to or on top of the grid.

BBjGrid Methods

The grid can be created and modified using BBj Object Syntax. Most grid SENDMSGs have a corresponding BBjGrid method, and there are additional methods for enhanced grid behavior. For general information on BBj Object Syntax see the BBj Object Variables.

For more information on the BBjGrid methods, see the following topics, see BBjGrid.