|
|
Tech Note 33: Using the Grid ControlMay 01, 2008© NSB Corporation. All rights reserved. |
The Grid control provides an easy way to display your data in a formatted table. It is made up of horizontal rows and vertical columns. The intersection of a row and a column is called a cell. Have a look at the sample "Grid.prj" in the Samples project to see how this control works. In the description below, the words in bold below are properties and methods of the grid control. To use them, preface them by the name of your control followed by a period.
To place a Grid on a form in your project, select the Grid object and click in the Design Screen at the top right hand corner where you want it to be placed. Set the number of Cols and Visible Rows you wish to have. Changing the number of Visible Rows will increase the Height of the grid with rows the same size. Change the Height of the Grid to change the size of each row. The columns are all equally spaced at Grid creation time: you can change the width at runtime. You cannot have the grid automatically hidden when the form is loaded.
If you choose the Has Scrollbar option, make sure the Width leaves room for the scrollbar to appear to the right of the object. Allow about 10 pixels for this.
You can complete the setup of your grid at runtime in the Form After code. It's a good idea to start by doing a Hide, so the updates you do to the table do not constantly update the screen. You can then set the column widths, types and initial values for the grid before doing a Show.
Set the column widths by using the ColWidth(colNo)=p function, where colNo is the column number and p is the number of pixels the column should be wide. Columns can hold text, number or check boxes.
To set the type of each columns, use the ColType colNo, type, formatString call. Type can be "text","numeric" or "checkbox".
If the type of a column is "text", you can put string values into it. The formatString is used for the initial value of any new rows that you Add. It is normally "", an empty string. "text" is the default column type. Data is left justified in a text column.
If the type of a column is "numeric", the formatString defines how numbers are shown in it, using the same conventions as the FORMAT statement. For example, a formatString of "nnn" will display a 3 digit right justified number. The default value of a new row is 0.
If the type of a column is "checkbox", the formatString is used for an optional string value that is shown to the right of the checkbox. The default value is "", an empty string. For checkboxes without any text, a colWidth is 12 works well. String or numeric values can be assigned to a checkbox column cell. If the value assigned is 0 or "0", the checkbox is unchecked; otherwise it is checked. The default is that a column is unchecked.
'set up a grid with 3 columns: text, numeric and checkbox grid1.hide grid1.colwidth(1)=121 grid1.ColType 1,"text","" grid1.colwidth(2)=14 grid1.ColType 2,"numeric","nnn" grid1.colWidth(3)=12 grid1.ColType 3,"checkbox","" displayGrid 'call another function to set initial values grid1.show
Once you have the grid set up, you can populate the cells with data using the Text, Value, TextMatrix and ValueMatrix functions. Text and Value set string and numeric values respectively to the current cell. The current cell is defined as the cell that is at row Row and column Col. You can change the current cell by assigning new values to the grid's Row and Col properties.
A quicker way to do this is to use the TextMatrix and ValueMatrix functions. These take the row and column values as arguments and do not require you to set the Row and Col properties separately. The Redraw method can then be used after all cells are updated.
To add a row, use the Add method. The RowData property can be used to store a unique value for each row, that does not get displayed. To get rid of all the rows in a grid, use the Clear method. The value of Rows will then be 0. You can also add or delete rows to a grid by changing the value of Rows. To get rid of one particular row, use the Remove method.
MyGrid.Clear For r=1 to 10 MyGrid.add Grid.TextMatrix(r,1)="some data" Grid.ValueMatrix(r,2)=2 Grid.ValueMatrix(r,3)=1 Next
You can also populate your grid with information from a file. To do this, you'll need to do a bit of preparation. First, you will need to DIM a file variable to identify which file you will be loading from. Use the DIM AS DATABASE statement. Here's an example:
Dim blueKey as Integer Type dbBluesLayout Name as String age as Integer active as Integer End Type Dim dbBlues1 as Database "Blues", DbBluesRec, dbBluesLayout, BlueKey
We want to read in data from a file on our device called "Blues". The file variable (we will refer to the file using this) is called dbBlues1. Each record in the file has the field in dbBluesLayout. When we read a record in, it will be put into the variable dbBluesRec. The key to the file Is blueKey, an integer. This statement should be done in the same routine that you do your BindToDatabase call, since dbBluesRec is automatically dimensioned as a regular variable (not a global).
Now that we have defined our file, we can copy the information directly into our grid using the BindToDatabase call
Grid1.bindToDatabase(dbBlues1, dbBluesRec.name, dbBluesRec.Age, _ dbBluesRec.active) Where dbBluesRec.age>=70
This statement copies data from the file referred to by dbBlues1 into our grid, Grid1. The next three arguments list the fields in the record which go into each of the columns. The columns do not need to be in the same order as the fields in the record layout (dbBluesLayout), nor do you need to use all the fields. The optional WHERE clause allows you to select which records to copy to the grid. You may use any expression that you could put into a normal IF statement.
If there are more records in the file selected than Visible Rows and you have Has ScrollBar set, a scrollbar will appear allowing you to see all the rows. Keep in mind that if you have a large number of rows, the scroll arrows do not work very precisely. Records are only copied into the grid as they are displayed, so there is no speed penalty for displaying large files.
As the records are read into each row, the rowData value of each row is set to the record number in the file. This is useful if you want to recall a record for a selected row in the grid:
Dim recNo as integer Dim err as integer recNo=Grid1.rowData(Grid1.Row) 'get rowData for the selected row err=dbPosition(dbBlues, recNo) err=dbRead(dbBlues, dbBluesLayout)
When a user taps on a grid, the code for the grid object is executed. Data cannot be typed directly into a cell. There are several useful variables that can be checked in that routine to determine what to do. The Row and Col properties will have the current row and column. You can use Row to get the RowData value to get back to the original record (if it is a bound grid) or to access other data.
You can modify the values in a grid using Text, Value, TextMatrix and RowMatrix. However, changing these values will not update the file automatically in a grid that is bound to a file. To update the file, use the rowData property to locate the record, read it in, modify it and write it out again using your own code.
TopRow is a useful value when dealing with grids which scroll. It gives the row number of the top row that is currently displayed. You can also force a grid to scroll by changing the value of TopRow.
The Grid object allows you display a table of data, supplied either from your program or automatically loaded from a file. You define the basic appearance of the grid at design time and populate it with data at runtime.
When a cell in the grid is tapped, the grid's row and col properties are set and can be used in your program. While the fields in the grid cannot be directly edited by the user, you can change their values using TextMatrix and ValueMatrix for string and numeric fields respectively. Text and Value can be used for the currently selected cell.
Please see the Handbook for a more detailed description of the use of this object.
Properties and Methods Specific to this Object
.BINDTODATABASE dbName, dbFieldNameList [Where condition]
Automatically loads a grid with data from a file. DbName is a file variable, set up by a previous DIM AS DATABASE statement. DbFIeldNameList is a list of fieldnames in the file, or the name of a Type structure in the file. Condition is an optional argument which selects which records to display. The format is the same as in an IF statement.
.COL Get or set the current column. Range is 1 to COLS.
.COLS Get the number of columns
.COLTYPE colNo, type, formatString
Set the type and format of a column. Columns default to text with null values. If you want a different type of data in a column, you must use this method to set it at runtime. ColNo is an existing column number in the Grid. Type is either "text","numeric" or "checkbox". FormatString depends on type: for "text", it will be the default value of the cell. For "numeric", it is a format string as used in the FORMAT statement. For "checkbox", the formatString is displayed to the right of a checkbox.
.COLWIDTH(colNo) Get or set the width of column columnNo
.ROW Get or set the current row. Range is 1 to ROWS.
.ROWDATA Get or set the rowdata value of the row. This is a user defined value.
.ROWS Get or set the number of rows.
.TEXT Get or set the value of the current cell with text in it.
.TEXTMATRIX(rowNo, ColNo) Get or set the text value of the cell at rowNo, ColNo.
.VALUE Get or set the value of the current cell with a number in it.
.VALUEMATRIX(rowNo, ColNo) Get or set the numeric value of the cell at rowNo, ColNo.
Properties Supported (Set at design time)
Cols, Has Scrollbar, Height, Left, Top, Visible Rows, Width
Other Methods Supported (See "Methods")
Add, Clear, Hide, Redraw, Remove, Show