The GRID control is a two-dimensional table of data fields. Each element of this table, called a "cell," can hold either text or a bitmap, or both. Grids are relatively complex controls with many properties that you can use to customize their appearance and behavior.
Grids are organized into rows, columns and records. In a grid, a "row" is a grouping of cells that appear on one line in the control. A "record" is one or more rows that are treated as a logical unit. A "column" identifies a particular cell in a record.
By default, a record occupies one row in a grid, but you can arrange for a record to "wrap around" to the next row when it passes the right edge of the grid. When this occurs, a record will occupy more than one row in the grid. You might want to construct a grid like this when you want to see many fields in a data record at once. Alternatively, you can have the grid use scroll bars to access cells past the right edge of the control. Column, row and record numbers all start at "1".
Grids come in two different formats: with horizontal scrolling and without. When you opt for horizontal scrolling, each record may occupy only one row in the grid. Grids with horizontal scrolling appear much like a spreadsheet. Without horizontal scrolling, a record may occupy more than one row. In either case, vertical scroll bars appear automatically when needed (providing you allow them with the VSCROLL style).
A grid's capacity is limited by available memory. The grid uses a sparse storage technique in which records with no data have no memory allocated for them. A grid may not have more than 100 columns. Under 32-bit (or larger) systems, there are no other practical limits (2 giga records and 2 GB text per record). Under 16-bit systems, the number of records is limited to 32766, and the total amount of text in any one record is limited to 32766 bytes. In both 16- and 32-bit systems, a single cell may contain no more than 32766 bytes of text.
The grid operates in two different modes: navigate mode and entry mode. While it is in navigate mode, the arrow keys move the cursor around the grid. This is the default mode. The grid shifts to entry mode when the user starts to modify data. In this mode, the arrow keys are used to edit the current cell's data. When the user finishes a cell, the grid returns to navigate mode.
The exact set of keys understood by the grid depends on the host system. Under Windows, the following keys are used in navigate mode:
Up/Down Arrow moves cursor to the same column in the previous/next record
Left/Right Arrow moves cursor to the previous/next column in the record
Tab (with USE-TAB) moves cursor right, wrapping to next record when at last cell in record
Backtab (with USE-TAB) moves cursor left, wrapping to the previous record when at the first cell in record
Home moves to first column in record
Ctl-Home moves to first column of first record
End moves to last column in record
Ctl-End moves to first column in last record
Page Up/Down moves cursor up/down one page
Enter shifts to entry mode for the current cell; highlights contents for editing
Shift-Enter moves cursor to the first column of the next record
Any printable character shifts to entry mode for the current cell; overwrites contents with character
When in entry mode, the user types into an entry-field control. All of the editing keys usable by an entry field are usable here. The user leaves entry mode by typing Enter or Tab/Backtab, or by clicking on another cell with the mouse.
Clicking a mouse on a cell moves the cursor to that cell. Double-clicking on a cell shifts to entry mode.
Grids can have row and column headers. Use the ROW-HEADINGS style to establish row headers and the COLUMN-HEADINGS style to make column headers. Headers are normal cells with certain special traits as follows:
1. Headers are always visible regardless of how the user scrolls the grid.
2. The cursor does not move into a header cell.
3. The special properties HEADING-COLOR, HEADING-FONT and HEADING-DIVIDER-COLOR only apply only to header cells. The style TILED-HEADINGS applies only to header cells.
4. The events MSG-HEADING-CLICKED, MSG-HEADING-DBLCLICK, and MSG-HEADING-DRAGGED apply only to header cells.
Otherwise, headers are normal cells. When you use column headers, record "1" becomes the column headers. When you use row headers, column "1" of each record supplies the row headers.
The grid control can have different colors and fonts assigned to each cell. For convenience, there are several ways this can be done. For example, you can set the color for the grid as a whole, for a particular row or column, or for a particular cell (in addition to other techniques). For a particular cell, there could be several colors or fonts specified for it. The grid picks the color or font to use by applying a priority list. The first item in the list that provides the color or font is the one that is used. For colors, this is determined independently for foreground and background colors.
For colors, the list of priorities is as follows (highest applying first):
CURSOR-COLOR
REGION-COLOR
CELL-COLOR
HEADING-COLOR
ROW-COLOR
COLUMN-COLOR
ROW-COLOR-PATTERN
Grid's overall color
For fonts, the following priority list is used:
CELL-FONT
HEADING-FONT
ROW-FONT
COLUMN-FONT
Grid's overall font
Currently, the grid control is available only under Windows.
Common Properties
TITLE
Grids do not have titles.
VALUE
A grid does not have a (single) value. You can set or inquire the contents of each cell using the CELL-DATA property described below. You can also retrieve an entire record at once with the RECORD-DATA property described below.
SIZE
The SIZE of a grid is the number of characters across that you want to be visible in the grid. This is measured using the grid's default font. The LINES of a grid is the number of rows you want to be visible. Note that this is not the same as the number of records in the case where a record occupies more than one row. Normally, you should ensure that the LINES setting of a grid is an even multiple of the number of rows per record.
Space is added as needed to accommodate the grid's scroll bars and any border or grid lines.
COLOR
Grids will use any specified foreground or background color. If either color is omitted, then that color uses a system-dependent default value. Under Microsoft Windows, the default values are determined by the settings defined by the user in the Control Panel (usually black on bright-white). Note that the grid's "color" is its default color. You can override this default for a specific row, column, or cell using various special properties (see ROW-COLOR, COLUMN-COLOR, CELL-COLOR, CURSOR-COLOR, HEADING-COLOR and ROW-COLOR-PATTERN below). The grid uses a priority rule for determining which color to use when several are specified for a cell (for example, a cell that has a ROW-COLOR and a different COLUMN-COLOR specified for it). This is discussed in detail in the introduction to the grid above.
Styles
3-D - Displays 3-D shading around the border of the control. (create, modify)
ADJUSTABLE-COLUMNS - allows the user to change the size of the columns by dragging the column dividers with the mouse. The grid must have only one row per record for this style to have any effect. When the grid has column headers, then the user will be able to change the column widths only by dragging the header dividers (this is to reduce the likelihood of the user's accidentally changing a column's width when just clicking on a cell). If the grid does not have column headers, then the user can drag any part of the divider.
The minimum column size is "1". The maximum is the visible portion of the grid. If the grid allows for horizontal scrolling, then the VIRTUAL-WIDTH property will change as the user changes column sizes. When the user changes a column size, your program will be informed via a MSG-COL-WIDTH-CHANGED message. Because grids use integer character widths for measuring columns, the user will not be able to place the column divider at just any pixel location. The grid, will adjust the location given by the user to the nearest character position. (create, modify)
BOXED - Displays a border around the grid. If neither BOXED nor NO-BOX is specified, then the default is machine-dependent. Under Windows, a box is displayed. (create, modify)
CENTERED-HEADINGS - draws column headings centered, regardless of the alignment of the rest of the column. If this is not specified, then the column headings match the alignment of the corresponding column. Note that the alignment of row headings is specified as the first entry in the ALIGNMENT property, so there is no need for any special row heading alignment styles. (create, modify)
COLUMN-HEADINGS - Causes the first record to be treated as column headers. See the discussion on headers above for details. (create, modify)
HSCROLL - Specifies a horizontally scrolling grid. A grid with this style may not specify more than one row per record (see DISPLAY-COLUMNS below). (create, modify)
NO-BOX - Causes the grid to display without a surrounding border. See BOXED. (create, modify)
PAGED Makes the grid a "paged" grid. Paged grids are typically used when the number of records in the grid is too many for a normal grid. When you set this style for a grid that contains data, records above the first visible record and records after the last visible record are deleted. See Chapter 3, section 3.10 for a complete description of paged grids. (create, modify)
ROW-HEADINGS - Treats the first column of each record as a row header. Note that this is typically useful only when you have one record per row. See the discussion on headers above for more details. (create, modify)
TILED-HEADINGS - Draws the headings with some shading that causes the headings to look like tiles. This gives a light 3-D look to the grid. This style is effective only if the background color for the heading cells is low-intensity and not black. This looks best if you set the heading's background color to low-intensity white (i.e., gray) and set the heading's divider color to black. Using the constants found in the COPY library "acucobol.def", you can most easily specify this with:
HEADING-COLOR = BCKGRND-WHITE,
HEADING-DIVIDER-COLOR = BLACK
(create, modify)
USE-TAB - Causes the grid to use the Tab and Backtab keys as navigation keys within the grid. Without this style, the Tab and Backtab keys move between the grid and other controls in the grid's window. (create, modify)
VSCROLL - Specifies a vertical scroll bar for the grid. Grids without vertical scroll bars may still contain more records than seen on the screen, and the user can still reach these records using the keyboard. The usual reason for creating a grid without a vertical scroll bar is if you are going to limit the number of records to an amount that fits on the screen (see NUM-ROWS below). (create, modify)
Special Properties
ACTION (alphanumeric) Used only with paged grids, this property causes the grid to invoke its paging logic in one of several ways. This simplifies the task of filling the grid with its initial data. After creating a grid, you would typically assign one of the following values to ACTION to load the initial page of data the user will see. The values of the following are level 78 data names found in "acugui.def":
- ACTION-FIRST-PAGE (value 10) generates the grid's MSG-PAGED-FIRST event. This fills the grid with the first page of data from the data source.
- ACTION-LAST-PAGE (value 11) generates the grid's MSG-PAGED-LAST event. This fills the grid with the last page of data from the data source.
- ACTION-CURRENT-PAGE (value 12) empties the grid of any data except for column headers and generates the grid's MSG-PAGED-NEXTPAGE event. If you position a data file using the START statement before performing this action, the grid will fill the page of data starting with the record selected by the START. (create, modify)
ALIGNMENT - (alphanumeric) Describes the alignment of each column in the grid. Each time you set this property, you describe the alignment for the next column in the grid, starting with the first. Setting this property to spaces clears the previously specified alignments. Valid values are as follows (case does not matter):
'L' left justified
'R' right justified
'C' centered
'U' unaligned
Unaligned data is displayed in the cell "as is." Otherwise, leading and
trailing spaces are removed from the data, and it is justified as specified. The
default for unspecified columns is "unaligned."
The following example sets various alignments for a three-column grid:
ALIGNMENT = ( `L', `R', `C' )
(create, modify)
BITMAP - (numeric) Places a bitmap in the cell identified by the X and Y properties. This should be set to the handle of a bitmap loaded in memory (using the WBITMAP-LOAD option of W$BITMAP). If it is set to zero, then any existing bitmap is removed. You may place a bitmap in the same cell as text. The bitmap is concatenated to the text (with a small separation), and the whole unit is aligned as specified by the ALIGNMENT property. When the user performs text entry in the cell, the bitmap is hidden until the entry is complete. The same bitmap may be placed in more than one cell. You should not destroy the bitmap handle while any cells contain the bitmap. (create, modify)
BITMAP-NUMBER - (numeric) Identifies a particular image when you specify a bitmap strip as the BITMAP for a cell. The first image in the strip is number "1", the second is number "2", and so on. Images in a bitmap strip must be uniform width, as specified by BITMAP-WIDTH. The cell affected is identified by the X and Y properties. The default value is "1". (create, modify)
BITMAP-TRAILING - (numeric) When set to "1", this property indicates that the bitmap should follow the text in the cell. When it is set to zero (the default), the bitmap precedes the text. Other values have undefined effects. The cell affected is identified by the X and Y properties. (create, modify)
BITMAP-WIDTH - (numeric) Identifies the width, in pixels, of the bitmap identified by BITMAP. If the width is not set, then the entire bitmap is used. Used in conjunction with BITMAP-NUMBER to select an image out of a bitmap strip. The cell affected is identified by the X and Y properties. (create, modify)
CELL-COLOR - (numeric) Sets the color for the cell identified by the X and Y properties. The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid is ignored--the value is treated as the final color value. See COLOR above for related information. (create, modify)
CELL-DATA - (alphanumeric) When set, replaces the text data at the cell identified by the X and Y properties with the specified value. When inquired, returns the text data at that cell. (create, modify, inquire)
CELL-FONT - (numeric) Sets the font for the cell identified by the X and Y properties. This should be set to a valid font handle. (create, modify)
COLUMN-COLOR - (numeric) Sets the color for the entire column identified by the X property. The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid is ignored--the value is treated as the final color value. For example, to set column three's color to dark blue (2) on bright white (512), you could do the following:
MODIFY GRID-1, X = 3, COLUMN-COLOR = 514
You should be sure to set the X property before setting COLUMN-COLOR. See COLOR above for related information. (create, modify)
COLUMN-DIVIDERS - (numeric) Sets the width, in pixels, of the column dividers. Each time you set this property, you describe the width of the next column's trailing separator, starting with the first column. Setting this property to "-1" clears the previously specified values. Unspecified columns use a system-dependent default value. On graphical systems, the default divider is one pixel wide. On character systems, the default divider is omitted (zero pixels wide). (create, modify)
COLUMN-FONT - (numeric) Sets the font to use for the column identified by the X property. This should be set to a valid font handle. (create, modify)
CURSOR-COLOR - (numeric) Sets the color for the cell containing the cursor. The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid is ignored--the value is treated as the final color value. Note that the cursor is normally hidden when the grid loses the focus. This causes the cell containing the cursor to revert to its normal color. The default cursor color is "0". See COLOR and CURSOR-FRAME-WIDTH for related information. (create, modify, inquire)
CURSOR-FRAME-WIDTH - (numeric) Determines how the cursor should display in the grid. When this is set to a positive value, the cursor displays a frame that many pixels thick around the cursor's cell. The frame extends partially into the cell, and partially outside the cell. When this property is set to a negative value, a light dotted line is drawn around the cell's contents. The absolute value of this property is the number of blank pixels between the cell's border and the dotted line. When it is set to zero, no cursor frame is drawn. The default value is "3". (create, modify, inquire)
CURSOR-X - (numeric) Identifies the column where the cursor is located. Setting this property moves the cursor. Inquiring this property returns the cursor's location. Note that you may MODIFY this property during a MSG-VALIDATE-CELL event to direct where the cursor should go after the user finishes an entry into a cell. However, you should do this only if you are not also forcing the user to stay in entry mode on the current cell. If you move the cursor in response to other events while the user is in entry mode, the results can be confusing. (create, modify, inquire)
CURSOR-Y - (numeric) Identifies the record where the cursor is located. Setting this property moves the cursor. Inquiring this property returns the cursor's location. See CURSOR-X for additional comments. (create, modify, inquire)
DATA-COLUMNS - (numeric) This property describes where each column begins in records added to the grid (see RECORD-TO-ADD). Columns are defined by character positions in the raw data, with the first character being position "1". For example, the following data item:
01 LIST-DATA.
03 NAME PIC X(20).
03 PHONE-NUMBER PIC X(15).
03 STATE PIC X(2).
would normally be displayed in three columns, one at position "1" (NAME), one at position "21" (PHONE-NUMBER), and one at position "36" (STATE). Each time you set DATA-COLUMNS to a positive value, a new column is created at that position. Setting DATA-COLUMNS to zero clears all the existing column definitions. Note that there is always a column at position "1", so setting position "1" is not required. An example DATA-COLUMNS setting that would match the LIST-DATA group item would be:
DATA-COLUMNS = (21, 36)
(create, modify)
DATA-TYPES - (alphanumeric) Describes various entry characteristics of each column. Each time you set this property, you describe the data type for the next column in the grid, starting with the first. Setting this property to spaces clears the previously specified data types.
A data type specification contains two components. The first is a single character that describes the set of legal characters that the user may type in this column. The set of possible values is:
| Character
| Description
| Characters Allowed |
| 'X'
| Alphanumeric
| All characters |
| 'U'
| Uppercase alphanumeric
| All characters - automatically converted
to uppercase |
| 'L'
| Lowercase alphanumeric
| All characters - automatically converted
to lowercase |
| '9'
| Number
| Digits, local decimal point, sign, space |
| 'Z'
| Edited number
| Digits, sign, period, comma, local
currency symbol, '$', '*', '/', '%', space |
| 'I'
| Integer
| Digits, sign, space |
| 'P'
| Positive integer
| Digits, space |
| 'D'
| Date
| Digits, '/', hyphen
|
You may omit either part of the specification. If the data type part is omitted, it defaults to 'X' (all characters allowed). If the size is omitted, it defaults to '0' (match the size of the column). These defaults also apply to columns for which DATA-TYPES has not been specified.
For example, to specify that a column should allow 30 uppercase characters, specify "U(30)". To create a column that allows only digits for the width of the column, use "P(0)", or just "P".
DISPLAY-COLUMNS - (numeric) This property describes the number of columns and their location in the grid. The first column always displays in column "1". Additional columns display at the locations set by DISPLAY-COLUMNS. Columns are measured with the standard font. Each time you set DISPLAY-COLUMNS to a positive value, a new display column is defined. Setting DISPLAY-COLUMNS to "0" clears all of the columns (except column 1). Usually, you set DISPLAY-COLUMNS in a list, like this:
DISPLAY-COLUMNS = (1, 21, 35)
This example sets three columns, one starting at column "1", the next starting at column "21" and the last starting at column "35". The last column extends to the end of the grid (but see VIRTUAL-WIDTH below).
In a grid without horizontal scrolling specified (see HSCROLL above), you can have a record occupy multiple rows in a grid. To do this, restart numbering columns at "1" after setting the first row's columns. For example, the following describes a grid with records that span two rows, with three columns on the first row and two columns in the second:
DISPLAY-COLUMNS = (1, 21, 35, 1, 21)
On the screen, one record of this grid would look something like this:
DIVIDER-COLOR - (numeric) Sets the color of the dividers for the grid. Set this to the color number of the desired color (e.g. "1" for black, "9" for dark gray). The color ignores the grid's foreground and background intensity--it is treated as the final color value. When this property is set to zero (the default), a system-specific divider color is used. This color depends on the background color for the grid. (create, modify, inquire)
END-COLOR - (numeric) Controls the color of the grid in the area past the end of the last column or the end of the last row. In some cases, a blank area is visible. If this property is set to zero (the default), this area is filled with the "button face" color configured for the host machine (this is set in the Control Panel under Windows). If it is set to a non-zero value, this value represents the exact ACUCOBOL-GT color to use. These values range from "1" (black) to "16" (bright white). (create, modify, inquire)
FILE-POS (numeric) This property is used only for paged grids. The value of FILE-POS is the grid's record number that matches the current file position in the corresponding data file. It is used to simplify the paging logic in your program. FILE-POS computes the number of records that need to be read in order to find the record needed by the grid. The grid uses this value when generating MSG-PAGED-NEXT or MSG-PAGED-PREV events.
The FILE-POS value will often be either the last visible record in the grid or the first non-heading record visible. Suppose you have a four line grid with no headings. When you are moving forward through the file, FILE-POS will usually be "4", matching the record number of the last record added to the grid. If the user clicks on the "Next Record" button, the MSG-PAGED-NEXT event will indicate that only one READ NEXT is needed to retrieve the appropriate record. However, if the user clicks the "Previous Record" button, then the MSG-PAGED-PREV event will indicate that four READ PREVIOUS statements are needed to get the desired record. In this case, FILE-POS will change to "1", indicating that only one READ PREVIOUS is needed to get another "previous" record while four READ NEXT statements are needed to get the "next" record.
In addition, FILE-POS has three special values that are level 78 data names defined in "acugui.def". These values are listed below.
- PAGED-AT-START (value 2147418113) When FILE-POS is set to this value, the grid will not generate MSG-PAGED-PREV and MSG-PAGED-PREVPAGE events.
- PAGED-AT-END (value 2147418114) When FILE-POS is set to this value, the grid will not generate MSG-PAGED-NEXT and MSG-PAGED-NEXTPAGE events.
- PAGED-EMPTY (value 2147418115) When FILE-POS is set to PAGED-EMPTY, it will not generate MSG-PAGED-NEXT, MSG-PAGED-NEXTPAGE, MSG-PAGE-PREV and MSG-PAGED-PREVPAGE. Since it is possible that other users will add records to the file (that could be seen by re-reading it), this value will still generate MSG-PAGED-FIRST and MSG-PAGED-LAST events
The grid automatically manages the FILE-POS, using the following rules:
1) When a record is added to the grid in the topmost non-heading position, FILE-POS is set to that position.
2) When a record is added to the grid or past the last grid record, FILE-POS is set to that position.
3) If you set EVENT-ACTION-FAIL in response to a MSG-PAGED-NEXT event, FILE-POS is set to PAGED-AT-END.
4) If you set EVENT-ACTION-FAIL in response to a MSG-PAGED-PREV event, FILE-POS is set to PAGED-AT-START.
5) If you set EVENT-ACTION-FAIL in response to a MSG-PAGED-FIRST or MSG-PAGED-LAST event, FILE-POS is set to PAGED-EMPTY.
6) If a MSG-PAGED-FIRST event sets EVENT-ACTION (this is the default), FILE-POS is set to PAGED-AT-START.
7) If a MSG MSG-PAGED-LAST event sets EVENT-ACTION, FILE-POS is set to PAGED-AT-END.
8) If you reset the grid, FILE-POS is set to PAGED-EMPTY. Adding records to the grid will change this value.
This automatic handling will work correctly for data coming from an indexed data file provided that you move the file's record pointer only in response to grid events (and only as required by those events). In cases where you move the file's record pointer independent of a grid request, you will need to do one of the following:
1) Modify FILE-POS to reflect the actual record position. You may use FILE-POS numbers outside of the range of available grid records if needed. For example, if you position the file pointer one record before the first record in the grid, set FILE-POS to "0". Set FILE-POS to "1" to point to the first record in the grid, "0" to point to the record before that, "-1" to point to two records before it, and so on. You can also use numbers larger than the last grid record to indicate a position beyond the end of the grid.
2) Reposition the current file pointer to match the FILE-POS value. You can do this by reading the appropriate record from the data file again. Note that a START may not be good enough. START positions the file pointer so that the next READ NEXT or READ PREVIOUS returns the selected record. It may not return the record positioned at either side of that record.
3) Ignore the positioning information passed into the MSG-PAGED-NEXT and MSG-PAGED-PREV events, and the positioning information supplied by the grid control. Supply your own positioning logic. In this case, FILE-POS may be incorrect; but FILE-POS is irrelevant at this point because you are not using it. If you ignore the value of FILE-POS, you must decide whether or not you will use the at-end or at-start feature of FILE-POS. If you do not wish to use this feature, then do not set EVENT-ACTION-FAIL in MSG-PAGED-NEXT and MSG-PAGED-PREV events.
Any of the techniques mentioned above will work. Note, however, that FILE-POS may be difficult to compute with the first technique because it is often hard to tell how far apart two records are in an indexed file. (create, modify, inquire)
HEADING-COLOR - (numeric) Sets the color for header cells (both column and row headers). The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid is ignored--the value is treated as the final color value. See COLOR above for related information. (create, modify, inquire)
HEADING-DIVIDER-COLOR - (numeric) Sets the color to use for drawing row and column dividers in the headings. Set this to the color number of the desired color. The color ignores the grid's foreground and background intensity--it is treated as the final color value. When this property is set to zero (the default), the dividers in the headings are drawn using the same color as the dividers in the rest of the grid. (create, modify, inquire)
HEADING-FONT - (numeric) Sets the font to use for row and column headings. This should be set to a valid font handle. Note that HEADING-FONT takes precedence over ROW-FONT and COLUMN-FONT, but not CELL-FONT. (create, modify, inquire)
HIDDEN-DATA - (alphanumeric) Allows the program to store data that is not displayed in a cell. A cell can contain both displayed data (see CELL-DATA) and hidden data. Hidden data is limited to 255 bytes per cell. Hidden data may be any format, including non-printing characters. (create, modify, inquire)
HSCROLL-POS - (numeric) Returns the column number of the leftmost column currently visible in the grid. (inquire)
INSERT-ROWS (numeric) When set to a positive value, this property inserts that many blank records. These are added immediately before the record identified by INSERTION-INDEX. See INSERTION-INDEX. (create, modify)
INSERTION-INDEX - (numeric) Setting this property to a positive value affects the location of records added via RECORD-TO-ADD. When it is set to zero (the default), records are added to the end of the grid. When INSERTION-INDEX is positive, records are added immediately before the corresponding item instead. For example, setting this to "1" causes the record to be inserted as the first record of the list. When you finish adding the next record, INSERTION-INDEX automatically resets itself to a value of zero.
MODIFY GRID-1,INSERTION-INDEX = 1,
RECORD-TO-ADD = GRID-DATA-1
When you are inserting a record, the following properties are also affected: ROW-COLOR, ROW-FONT, CELL-COLOR, CELL-FONT. If these are specified for a record past the insertion point, then they will be moved "down" one record. For example, if you have ROW-COLOR specified for record "5", and you insert record "3", then the ROW-COLOR will move to record "6". This causes row and cell properties to follow their data. (create, modify, inquire)
LAST-ROW - (numeric) When inquired, returns the record number of the last non-blank record in the grid. Row headings are ignored in determining if a record is blank. If the grid contains no non-blank records, LAST-ROW returns zero. (inquire)
MASS-UPDATE - (numeric) When set to a non-zero value, this property inhibits most (but not all) updates to the screen by the control. This allows you to make multiple changes to the grid faster, and with a smoother screen appearance. When set to zero (the default), changes made to the grid are reflected on the screen. Note that the act of setting this property to zero causes the grid to repaint. (create, modify, inquire)
NUM-COL-HEADINGS (numeric) This property determines the number of rows that will be treated as column headings. When it is set to zero, the grid columns will not have headings. When it is set to a positive value, this value will correspond to the number of rows that will be treated as column headings. For example, if you set the value of this property to "2", the first two records in the grid will be headings. Headings are always visible and can be colored differently from the body of the grid. Specifying more column headers than rows visible in the grid has undefined effects.
This property effectively supersedes the COLUMN-HEADINGS style. If you specify COLUMN-HEADINGS, then a NUM-COL-HEADINGS value of "0" is treated as if it were "1". The COLUMN-HEADINGS style has no effect when NUM-COL-HEADINGS is set greater than zero. This rule provides backwards compatibility with COLUMN-HEADINGS while still allowing for a multi-row column header. (create, modify, inquire)
NUM-ROWS - (numeric) Determines the total number of records in the grid. When this property is set to a positive value, the grid allows for exactly NUM-ROWS records. When it is set to zero (the default), the grid extends to the last record which has data defined for it. When it is set to "-1", the grid extends to one record past the last record which has data defined for it. This provides a blank record at the end of the grid in which the user can add new data. In the case of "0" and "-1", the grid will grow as needed when more records are added. (create, modify, inquire)
RECORD-DATA - (alphanumeric) When set, replaces an entire record of text in the grid at
once. You must set DATA-COLUMNS beforehand to denote where each column's data
starts. You must also set the "Y" property to indicate which row you want to
overwrite. If you specify a row that is past the current end of the grid, the
effect is the same as adding a new record at that point. Otherwise, the row's
existing record is overwritten with the new one.
When inquired, RECORD-DATA returns the data contained in the row identified by
property "Y". This data is formatted according to DATA-COLUMNS. If the
requested row does not exist, the returned value will be entirely spaces. (create, modify, inquire)
RECORD-TO-ADD - (alphanumeric) Adds an entire record of text to the grid at once. You must set DATA-COLUMNS beforehand to denote where each column's data starts. The record is usually added at the end of the grid, but you can change this by using INSERTION-INDEX. Note that the new record is added to the grid - it does not overwrite any existing data. See CELL-DATA for a way to add individual cells to a grid. (create, modify)
RECORD-TO-DELETE - (numeric) Deletes an entire record from the grid. The value of this property is the record number to delete. Deleting a record affects not only data, but also ROW-COLOR, ROW-FONT, CELL-COLOR and CELL-FONT. If any of these are specified for records following the one deleted, they are moved "up" one record. This causes them to follow their current data. So, for example, if record "5" has a ROW-COLOR specified for it, and you delete record "3", then the ROW-COLOR will now apply to record "4". (create, modify)
REGION-COLOR - (numeric) Sets the color for the region bounded by the rows START-Y and Y and
the columns START-X and X (inclusive). When you set REGION-COLOR, any
previous region color is removed and a new region set. The boundaries of the region
are set when REGION-COLOR is set. Subsequent changes to X, START-X, Y or
START-Y has no effect on the region until the next time that REGION-COLOR is set.
Region color is normally used to highlight an area being marked by the user
while dragging the mouse. To do this, usually all you need to do is set
REGION-COLOR to the desired color in response to a MSG-GOTO-CELL-DRAG event. Note that
when this event is generated, START-X, X, START-Y and Y all have sensible
values in them, and they usually do not need to be set by your program.
RESET-GRID - (numeric) When set to a non-zero value, empties the grid of data. In addition, any ROW-FONT, ROW-COLOR, CELL-FONT and CELL-COLOR settings are cleared. The cursor is positioned at the home cell (the home cell is the uppermost, leftmost, non-heading cell) and the grid is scrolled to the home position. RESET-GRID is a one-time action. Note that this clears the headings as well as the body of the grid. Also note that both text and bitmap data are cleared. (create, modify)
ROW-COLOR - (numeric) Sets the color for the entire record identified by the Y property. The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid are ignored--the value is treated as the final color value. Note that although the property is called "ROW-COLOR", it actually refers to a full record, not just a row. See COLOR above for related information. (create, modify)
ROW-COLOR-PATTERN - (numeric) Establishes a repeating color pattern to apply to the rows in
the grid. The first time you set this property, the specified color is applied
to the top row of the grid. The next setting is applied to the second row, and
so on. The pattern established then repeats throughout the grid's visible
rows. The color value specified uses the COLOR phrase values for both foreground
and background colors. The foreground and background intensity of the grid are
ignored--the value is treated as the final color value. Note that the color pattern is
fixed to the visible rows in the grid independently from the current vertical
scroll position. Scrolling through the grid does not change the visible
aspects of the color pattern. This prevents a "jittery" display while the user
scrolls vertically.
This example sets a two-row pattern where the first row will be background
white (512) and the second will be background yellow (480). In both cases, the
foreground is unspecified (zero added to the value) and will come from some other
source:
ROW-COLOR-PATTERN = ( 512, 480 )
See COLOR above for related information. (create, modify)
ROW-DIVIDERS - (numeric) This property establishes the width (in pixels) of the row dividers. Each time you set this property to a nonnegative value, you set the width of the divider for one row of a record. The first setting applies to the first row, the second to the second row, and so on. The pattern established for one record repeats throughout the grid. You can clear the list of divider settings by assigning a value of "-1". Unspecified dividers use a system-dependent default width. The default divider is one pixel wide.
Assuming two rows per record, the following example would create a pattern where records were divided from each other by a two-pixel border, and the two rows within the record were divided by a one-pixel border:
ROW-DIVIDERS = (1, 2)
(create, modify)
ROW-FONT - (numeric) Sets the font for the record identified by the Y property. This should be set to a valid font handle. Note that ROW-FONT refers to the font used for an entire record, not just a row. (create, modify)
SEARCH-OPTIONS (alphanumeric) This property controls how searches are performed in the grid.
The SEARCH-OPTIONS property should be assigned from a structure with the following layout:
01 GRID-SEARCH-OPTIONS.
03 GRID-SEARCH-DIRECTION PIC 9.
88 GRID-SEARCH-FORWARDS VALUE ZERO,
FALSE 1.
03 GRID-SEARCH-WRAP-FLAG PIC 9.
88 GRID-SEARCH-WRAP VALUE ZERO,
FALSE 1.
03 GRID-SEARCH-CASE-FLAG PIC 9.
88 GRID-SEARCH-IGNORE-CASE VALUE ZERO,
FALSE 1.
03 GRID-SEARCH-MATCH-FLAG PIC 9.
88 GRID-SEARCH-MATCH-ANY VALUE ZERO.
88 GRID-SEARCH-MATCH-LEADING VALUE 1.
88 GRID-SEARCH-MATCH-ALL VALUE 2.
03 GRID-SEARCH-LOCATION-FLAG PIC 9.
88 GRID-SEARCH-VISIBLE VALUE ZERO.
88 GRID-SEARCH-HIDDEN VALUE 1.
88 GRID-SEARCH-ALL-DATA VALUE 2.
03 GRID-SEARCH-SKIP-FLAG PIC 9.
88 GRID-SEARCH-SKIP-CURRENT VALUE ZERO,
FALSE 1.
03 GRID-SEARCH-CURSOR-FLAG PIC 9.
88 GRID-SEARCH-MOVES-CURSOR VALUE ZERO,
FALSE 1.
03 GRID-SEARCH-COLUMN PIC 9(5).
88 GRID-SEARCH-ALL-COLUMNS VALUE ZERO.
A copy of this structure can be found in the COPY library "acugui.def". It contains the default value settings for all the grid search parameters. Use the COPY statement in the Working Storesge section to include this structure with its default values in your program.
To set the SEARCH-OPTIONS property, specify the name of the data structure described above in the screen description entry for the grid or via the "modify" statement. The example below uses the "modify" statement to assign the property:
MODIFY GRID-1
SEARCH-OPTIONS = GRID-SEARCH-OPTIONS
To set new search values for a grid, start by using the "inquire" statement to find out what the current values are (they may have been modified previously). Next, set the desired values to the chosen search parameters with the "set" statement, and finally, "modify" the grid to apply the new values.
The following sample shows how to change the values for two of the search parameters and apply the new search options to the grid.
INQUIRE grid-1, SEARCH-OPTIONS
IN GRID-SEARCH-OPTIONS
SET (option-1) TO TRUE
SET (option-2) TO TRUE
MODIFY grid-1,
SEARCH-OPTIONS = GRID-SEARCH-OPTIONS
The SEARCH-OPTIONS parameters have the following traits:
- GRID-SEARCH-FORWARDS When this is set to true, the search runs from left-to-right and top-to-bottom in the grid. This is the default behavior. When it is set to false, the search runs from right-to-left, bottom-to-top.
- GRID-SEARCH-WRAP When this is set to true (the default), a search "wraps around" it hits the top or bottom of the grid. This causes the search to proceed from the opposite end of the grid. When it is set to false, the search stops if it hits the top or bottom of the grid.
- GRID-SEARCH-IGNORE-CASE When this is set to true (the default), the search ignores case differences between letters when determining if two strings match. When it is set to false, a difference in case between strings will cause them not to match. You should be certain to set this to "false" when searching for data that contains binary information (this could happen if you search the grid's hidden data).
- GRID-SEARCH-MATCH-ANY When this is set to true (the default), a search string will match if the string is contained anywhere in the cell's data (similar to a substring search). For example, a search for "bcd" would match the string "abcde".
- GRID-SEARCH-MATCH-LEADING When this is set to true, a search string will match if the string forms the beginning of the cell's data. For example, a search for "bcd" would match the string "bcde", but not the string "abcde".
- GRID-SEARCH-MATCH-ALL When this is set to true, a search string matches only if it is identical to the string being searched. For example, "bcd" will match "bcd", but not "abcde" or "bcde".
- GRID-SEARCH-VISIBLE When this is set to true (the default), the search is performed only against the grid's visible cell data.
- GRID-SEARCH-HIDDEN When this is set to true, the search is performed only against the grid's hidden data.
- GRID-SEARCH-ALL-DATA When this is set to true, the search is performed against the grid's visible and hidden data.
- GRID-SEARCH-SKIP-CURRENT When this is set to true (the default), the cell where the search starts is not initially searched. If you allow the search to wrap, it will be searched last. If you do not allow the search to wrap, then the starting cell will not be searched. This setting allows a "find next" function to work. When this is set to false, the starting cell is searched first. Note that if you start the search from a cell that is outside the range of existing cells, then the starting cell is searched first regardless of the setting of this flag. This allows you to find the first occurrence of a string by starting your search at row "0" regardless of the setting of this flag.
- GRID-SEARCH-MOVES-CURSOR When this is set to true (the default), the grid's cursor will move to the cell found by the search. The grid will also scroll to make that cell visible. A failed search will not move the cursor. When this is set to false, the cursor is not moved by a successful search.
- GRID-SEARCH-COLUMN When GRID-SEARCH-ALL-COLUMNS is true, the search runs through every column in the grid. Otherwise, if you set GRID-SEARCH-COLUMN to a non-zero value, the search runs through that column number only. Columns other than this column are ignored. Note that row and column headings are not normally searched. You can search the row headings by setting GRID-SEARCH-COLUMN to "1" (assuming that you have row headings). You cannot search the column headings.
If you need to limit your search to two or more columns, but not all the columns, then you will need to program the limited search yourself by first setting GRID-SEARCH-ALL-COLUMNS and GRID-SEARCH-SKIP-CURRENT to true, and GRID-SEARCH-MOVES-CURSOR to false. Then perform the search in a loop. Break out of the loop when GRID-SEARCH-COLUMN equals one of the desired columns or when the search fails. The search fails when it does not find a match or the search returns a cell that is the same cell as the first match it returned (in this case, the data you're searching for appears only in cells outside the desired columns). After finding a successful match, you can place the cursor in that cell using the CURSOR-X and CURSOR-Y properties.
The following example turns off "wrapping" and turns on forward searching for a particular grid. This shows you how to change some settings while leaving others unchanged:
COPY "acugui.def".
INQUIRE GRID-1, SEARCH-OPTIONS IN GRID-SEARCH-OPTIONS
SET GRID-SEARCH-WRAP TO FALSE
SET GRID-SEARCH-FORWARDS TO TRUE
MODIFY GRID-1, SEARCH-OPTIONS = GRID-SEARCH-OPTIONS
SEARCH-TEXT (alphanumeric) When you assign this property, the grid initiates a search using the current search options. The program looks for the value assigned to this property. The search starts in the cell identified by the X and Y properties unless overridden by the GRID-SEARCH-SKIP-CURRENT described under SEARCH-OPTIONS above. If the search is successful, then X and Y are updated to reflect the cell found. The return value of this property is the status of the search:
GRDSRCH-NOT-FOUND(value 0) No matching data found
GRDSRCH-FOUND(value 1) Search succeeded
GRDSRCH-WRAPPED(value 2) Search succeeded but had to wrap
If X and Y identify a cell outside of the range of cells, then the starting cell is determined as if the search "wrapped" from the logical (X,Y) location. For example, if the starting point is a cell past the rightmost cell, a forward search starts at the first cell of the next row. You can use this to force a search of the entire grid by starting a forward search at row "0", or a backward search from a row that is past the end of the grid's data.
The following sample code searches a grid for the word "science", starting at the cell where the cursor is currently at:
INQUIRE GRID-1, CURSOR-X IN CUR-COL,
CURSOR-Y IN CUR-ROW
MODIFY GRID-1 (CUR-ROW, CUR-COL)
SEARCH-TEXT = "science" GIVING RESULT-1
IF RESULT-1 > GRDSRCH-NOT-FOUND
DISPLAY MESSAGE BOX "Search succeeded".
SEPARATION - (numeric) Describes the amount of white space that should be preserved at the end of each column. This space appears between the end of the data and the beginning of the next column. The column divider, if any, appears in the region. This space is expressed as tenths of the standard font width. For example, a value of "5" indicates a half-character width.
Each time you set this property, you set the separation amount for the next column in the grid, starting with the first. Setting this property to "-1" clears the previously specified separation amounts. The default separation used for unspecified columns is set by the COLUMN-SEPARATION configuration variable. This defaults to "5". (create, modify)
START-X - (numeric) The START-X property is used in conjunction with the START-Y, X, and Y properties to define a rectangular region in the grid. This region is used when you are setting REGION-COLOR. START-X holds a column number. The region colored by REGION-COLOR starts at START-X and extends through X. (create, modify, inquire)
START-Y - (numeric). See START-X and REGION-COLOR for a description of this property.
VIRTUAL-WIDTH - (numeric) Sets the overall logical width of the grid. This is used only with grids that have horizontal scrolling. This value is expressed in characters (measured using the standard font width). If not specified, then the grid extends to 10 characters past the last DISPLAY-COLUMN specified (making the last column 10 characters wide). You can create hidden columns by setting this value smaller than some of your columns' starting points. (create, modify, inquire)
VPADDING - (numeric) Sets the amount of vertical white space in each row. This value is
the percentage of the grid's font height to apply as extra white space (i.e., separation between the cell's data and the cell's row dividers). The
default setting is "50". Note that this produces a look similar to a series of entry
fields (because the normal entry field is 50% taller than its font). On
character systems, the VPADDING value is not used.
VSCROLL-POS - (numeric) Returns the row number of the topmost record currently visible in the grid. (inquire)
X - (numeric) The X property holds a column number. It is used by several other properties when they need to know which column to act on. For example, the COLUMN-COLOR property sets the color for the column identified by the X property. Column numbers start at "1". Remember that properties are set in the order specified in a statement. You should be certain to set the X property before setting another property that refers to it. (create, modify, inquire)
Y - (numeric) The Y property is similar to the X property, except that it holds a record number instead of a column number. (create, modify, inquire)
Events
Grid controls can generate the following events:
CMD-GOTO
MSG-VALIDATE
MSG-BEGIN-ENTRY
MSG-FINISH-ENTRY
MSG-CANCEL-ENTRY
MSG-GOTO-CELL
MSG-GOTO-CELL-MOUSE
MSG-GOTO-CELL-DRAG
MSG-BEGIN-DRAG
MSG-END-DRAG
MSG-BITMAP-CLICKED
MSG-BITMAP-DBLCLICK
MSG-HEADING-CLICKED
MSG-HEADING-DBLCLICK
MSG-HEADING-DRAGGED
MSG-BEGIN-HEADING-DRAG
MSG-END-HEADING-DRAG
CMD-HELP
MSG-COL-WIDTH-CHANGED
MSG-INIT-MENU
MSG-MENU-INPUT
MSG-END-MENU
MSG-PAGED-FIRST
MSG-PAGED-NEXTPAGE
MSG-PAGED-LAST
MSG-PAGED-PREV
MSG-PAGED-NEXT
MSG-PAGED-PREVPAGE