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 that 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 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)
You can also specify DATA-COLUMNS using the RECORD-POSITION construct. This is discussed in detail in Chapter 5.2.5 of the Reference Manual.
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 = (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:
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. To illustrate, suppose that 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 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.
The automatic handling provided here will correctly handle grids whose data is coming from an indexed data file if 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. When row-headings are used, HSCROLL-POS returns the column number that would appear in column 1 of the grid if there were no headings. (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.
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.
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 Storage 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 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" when 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 both 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. If the search fails, the cursor is not moved. When this is set to false, the cursor is not moved by a successful search.
GRID-SEARCH-COLUMN When GRID-SEARCH-ALL-COLUMNS is set to 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
| 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 |
The following sample code searches a grid for the word "science", starting at the cell where the cursor is currently located:
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".
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.
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)