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 Palm 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.ValueMatic(r,2)=2
Grid.ValueMatix(r,3)=1
Next
You can also populate your grid with information from a
database. To do this, you'll need to do a bit of preparation. First, you will
need to DIM a database variable to identify which database will be loading from.
Use the DIM WITH RECORD 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 database on our Palm called
"Blues". The database variable (we will refer to the database using
this) is called dbBlues1. Each record in the database has the field in
dbBluesLayout. When we read a record in, it will be put into the variable
dbBluesRec. The key to the database 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 database, 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 database referred to by
dbBlues1 into our grid, Grid1. The
next three arguments list the fields in the database 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 database 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
databases.
As the records are read into each row, the rowData value of each row is set to the record number in
the database. This is useful if
you want to recall a database 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 database 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
database automatically in a grid that is bound to a database. To update the
database, use the rowData property to locate the database 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.
DIM varname AS type
DIM varArray(nnn) AS type
DIM varname AS type*length [,decimalPlaces]
DIM varArray(nnn) AS type*length[,decimalPlaces]
DIM varName AS DATABASE dbName,
dbRec, dbLayout [, key]
Description
Defines a variable to be used within a function or
subroutine. If the variable is an array , then nnn defines the number of elements to be reserved.
|
Type |
|
|
Byte |
a single character of data. On database input/output, a
single character is written.(without the Terminating null character). |
|
Database |
used to define a database reference that will be used in
database commands. If the database is to be bound to a grid control,
additional arguments are needed. |
|
Date |
used to store date values. This is not the Palm internal format.
Database i/o results in a 64-bit floating point number. Dates are stored
internally as (year-1900)*10000+month*100+ day |
|
Double |
Same in all respects to Float |
|
Float |
used to store numbers that may have both integer and
fractional digits. On input/output to databases, a 64-bit (8-byte) double
precision floating point is used |
|
Integer |
used to store whole numbers (no decimal positions to the
right of the decimal point). On input/output to databases, a 32-bit(4-byte)
integer is used. |
|
Short |
Similar to Integer except that database i/o results in a
16-bit(2-byte). |
|
Single |
Same as Float except database i/o results in a 32-bit(
4-byte)single-precision floating point. |
|
String |
Maximum size is 32767 characters. |
|
Time |
used to store time values. This is not the Palm internal
format. Databae i/o results in a 64-bit floating point number. Times are
stored internally as hour*10000+minute*100+seconds |
|
UserType |
see the TYPE and END TYPE statements |
|
Variant |
see SysTrapFunc and SysTrapSub functions |
Length defines how many digits get displayed. DecimalPlaces is the number of digits to the right of the decimal
point. This must be at least 2 less than length.
If we are declaring a database for use in a grid. VarName is the name of the
variable. DbName is the name of the
database on the Palm OS device. DbRec is a global variable which will be created to contain the contents of
the current record of the database. It should not be dimensioned already. DbLayout is the layout of the record: it should already be
defined using a TYPE statement. Key
is an optional variable that must already be dimensioned: it is the key that is
used for the dbName database. This
form is only used to define Varname when used as the first argument of a
BindToDataBase method for a Grid control.
Example
Dim income as float*12,2
Dim count as integer
Dim yesterday as date
Dim appt as time
Dim rates(12) as float
Dim Orders as database
Type dbBluesLayout
Name as
String
age as
Integer
active
as Integer
End Type
Dim blueKey as Integer
Dim dbBlues1 as Database
"Blues" Creator "Grid" Keyed With Record BlueKey,
dbBluesRec as dbBluesLayout
The Grid object allows you display a table of data, supplied either
from your program or automatically loaded from a database. 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 Section 9 of 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 database. DbName is a database variable, set up by a previous DIM
WITH RECORD statement. DbFIeldNameList is a list of fieldnames in the database, or the name of a Type
structure in the database. 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