Home > Language Reference > Classes

Grid Class

  + Object
    + Display
      + UIComponent
        + Control
          + Grid

Description

The Grid class implements the behaviours specific to the grid. Like all the classes derived from UIComponent, this class is not instantiable, cloneable or derivable. The only instances available to the programmer are those automatically generated by HB++ when you place a control on a form.

A grid is a control that allows the display and entry of data in the form of rows and columns. Each column can appear in multiple forms.

Columns types are defined at design time and can be the following ones :

• Label : the cells of this column are labels, they can display text but cannot have text entered directly by the user.
• Text : the cells of this column are fields and allow the display and direct entry of text.
• Text with note : the cells of this column are of fields and allow the display and direct entry of text. They also display a 'note' symbol on the righthand side. It is possible to determine if the user has clicked on the text zone or on the 'note' symbol.
• Checkbox : the cells of this column are Checkboxes and allow the display and direct entry of Boolean values.
• Popup : the cells of this column are of Popups and allow the display and direct entry via a list.
• User draw : the cells of this column must be drawn by the programmer. They allow a customizable way of displaying and / or entering data.

The Grid object is a complex object particularly adapted for the Palm OS^® plateform. It displays data and supports in place editing. It is especially useful for displaying data in a list where the number of items is important. Unlike the List object, it is not necessary to populate the whole control, the items only need to be loaded in memory when being displayed. This considerably reduces the memory occupied - In other words, you don't populate a Grid object with data, but with references that will be subsequently used to obtain the data on the fly.

The number of columns as well as their types and attributes must be specified at design time as well as the number of Visible items:

Properties window	Columns definition dialog box

Note: The 'Extra properties' frame contains specific attributes for each type of column selected in the dialog box. Thus a column of type 'Text' will not have the same extra properties as a column of type 'Popup' (see also Columns design time properties). The 'Preview' frame shows the appearance of the Grid object depending on the attrributes entered in this dialog box.

There are two ways to specify the number of rows in the Grid object; either by using the Rows property or by adding rows one by one with the AddItem method which also allows to specify for each line added an associated value in the ItemData property. When you use the Grid class to display the contents of a database, it is useful to store in the ItemData property a unique identifier allowing the record to be retrieved from this value. For records accessed from the StreamRecord class, you store the value of its UniqueId property in ItemData. For records accessed with the Recordset class, you store the value of its UniqueId property in ItemData.

Whichever method is used to set the number of rows in the Grid object, the Rows property returns the number of items in the Grid object.

The LoadItem event is raised for each row displayed indicating the index of the relevant row, the value ItemData associated with the row as well as a Variant array corresponding to the different columns in the row that are affected.

For columns of type 'User Draw', the DrawItem event is received for each one that must be drawn, indicating the index of the row and the index of the relevant column, the ItemData value associated with the row as well as the coordinates and size of the drawing area.

The Click event is raised when the user clicks on the Grid control. It allows the application to know the row and column clicked on as well as the the value of the ItemData property associated with this row.

The Change event is raised when a cell is edited. The types of column that allow editing are 'Text', 'Text with note', 'CheckBox' and 'Popup'.

For columns of type 'Text' or 'Text with note', the Change event is raised if a change occurs in the edit zone and uniquely when another cell becomes active. This implies that a PenDown event event is raised for the new cell before the Change event is raised for the 'Text' or 'Text with note' zone has been modified. One of the parameters of the Change event is a Variant vNewValue which contains the new value of the cell.

For columns of type 'Popup', the List property references a List object for which items should be added using the AddItem method.

The Masked property sets or reads whether a row in the Grid object must be masked or not. For a cell to be masked, the corresponding column must be set with this attribute ( see columns design time properties) and the Masked property of the row must be also set to True.

The RemoveItem method deletes rows from the Grid object using their index.

The Scrollbar property associates a grid with a Scrollbar control or SpinButton control, allowing the user to scroll the rows contained in the Grid control.

The TopItem property defines the index of the first row displayed in a Grid.

The Row and Col properties return the row and column index of the currently selected Grid item. Row is in the range of 0 to Rows -1 and Col is in the range of 0 to the count of columns (see Columns) -1.

The SelectItem method allow to select a cell and the HighLight method allow to highlight a cell.

Members

System requirements