DBGRID.TXT

============
Introduction
============

The DBGrid control is a data-bound Visual Basic custom control.  Like a 
spreadsheet, the DBGrid control displays data as a series of rows and 
columns representing records and fields from a database.

DBGrid binds to the standard Data control, so you can use it with any 
database supported by the Jet database engine,including native Jet and 
Microsoft Access databases, ISAM databases and ODBC databases such as 
Microsoft SQL Server.

Because the DBGrid control was still under development when the Visual 
Basic version 4.0 documentation went to press, it is not covered in the 
Data Access Guide or the Programmers Guide.  This file (DBGRID.TXT) 
presents a conceptual overview and step-by-step instructions for common 
DBGrid operations.  In addition, you can find summary information and a 
complete reference listing of all DBGrid properties, methods, and events 
in online Help.

==================
The Quickest Start
==================

The DBGrid control can be highly customized and directly manipulated in 
code to give you great flexibility in creating custom database applications.  
In many cases, however, you will want to use DBGrid to quickly and 
easily display and browse through all the records in a database table.  
This can be accomplished in minutes without writing any code.

Before using the DBGrid control, you must add the control to the project 
using the Add Custom Controls dialog box.  You should also make sure the 
Data Access Object (DAO) library is registered in the Add References 
dialog box.

To use DBGrid to display and browse through an existing database table, 
follow the steps below:

1.  Add a Data control to a new form, and set its DatabaseName and 
    RecordSource properties to the database and table you want to
    display.

2.  Add a DBGrid control to the form, and set its DataSource property
    to the Data control you just created.

3.  Run the application.

When your program runs, the database table you specified is displayed in 
the DBGrid, complete with column headers (from the Data control's 
Recordset) and scrollbars. You can immediately scroll through all the 
records and fields of the table.  In addition you can edit any cell in 
the table, and it will automatically be updated when you move to a new 
row (assuming that the underlying Recordset is updatable and the DBGrid's 
AllowUpdate property is set to True).  With the Allow AddNew, AllowDelete 
properties set to True, you can delete records by selecting and deleting 
the entire row.

==============
Basic Concepts
==============

The DBGrid control depends on two other objects: 

- the Recordset object of the Data control

- the Columns collection of the DBGrid itself

DBGrid is actually a collection of Column objects, each with a variable 
number of rows.  Each column corresponds to a field in the database 
table, while each row corresponds to a record.  The Count property of 
the control's Columns collection determines the number of columns and 
the RecordCount property of the Data control's Recordset determines the 
number of rows.

In operation, the Row and Col properties specify the current cell in a grid.
You can specify the current cell in code, or the user can change it at run 
time using the mouse or the arrow keys.  When the user changes the current 
cell, the underlying Data control's Recordset is automatically repositioned 
to the record containing the selected cell.

Cells can be edited interactively, by typing into the cell, or 
programatically, by changing the Value property of the currently selected 
Column object.

======================
Design-time operations
======================

When first created, the DBGrid control has a single column and a single row.
It also contains n empty row (designated by the asterisk (*) at runtime, 
which is used to add new records. You can change any of the DBGrid's visible 
attributes through settings in the Properties window. 

When you set the DataSource property, the DBGrid control binds itself to 
the Recordset created by the Data control and sets the number of columns 
and other column properties from the corresponding properties of the Field 
objects in the Data control's Recordset.

The Properties window displays the properties for the DBGrid control as a 
whole and the control can be moved and sized.  To set properties for the 
individual Column objects, you must make the DBGrid control UI-active by 
choosing Edit from the control's pop-up menu, which can be selected with 
the right mouse button.  The pop-up menu can be used to insert or delete 
columns, or to cut and paste columns to and from the Clipboard.

Each DBGrid control has a single property page; however, each Column object 
also has its own page.  You can use these property pages to interactively 
set properties for the DBGrid control as a whole or for individually 
selected columns.

The General property page shows properties that apply to the entire DBGrid 
control and can be assessed at design time.  These properties are also 
available in the standard Properties window.

The Columns property page shows properties for an individual column.  If 
multiple columns are selected, the leftmost column in the columns property 
page is selected.  Setting Column object properties doesn't affect overall 
DBGrid control properties.

The Colors property page allows selection of overall DBGrid control colors.
Column object colors aren't affected by these settings.

The Fonts Property page allows selection of overall DBGrid control and 
heading fonts.  Column object fonts aren't affected by these settings.

==========
Formatting
==========

Each column of the DBGrid control has its own font, border, word-wrap, 
color and other attributes that can be set without regard to other columns.
At design time you can set the column width and row height and establish 
columns that are not visible to the user.  You can also prevent users from 
changing the formatting at run time.

If a cell's text is too long to be displayed in the cell, the text will 
automatically wrap to the next line within the same cell.  To display the 
wrapped text, you can increase either the Width property of the cell's 
Column object or the RowHeight property of the DBGrid control itself.  At 
design time, you can change the column width interactively by resizing the 
column or by changing the column's width in the Column object's property 
page.

===================
Run-time operations
===================

The DBGrid control displays records from the underlying Recordset object 
at run time.  There is always a single current record in the DBGrid control,
even if multiple rows in the control are selected. The current record 
corresponds to the Data control's current record, and can be set or 
retrieved with the DBGrid control's Bookmark property.

As with other data-bound controls, when you cahnge a record (or any field 
in a record) in the DBGrid, the underlying Recordset is updated when you 
move to a new record (row), assuming that it is updatable and the DBGrid's 
AllowUpdate property is set to True.  Otherwise, a trappable error results.

If you set the MultiSelect property to True, the selected columns can be 
accessed using the SelBookmarks collection returned in the SelBookmarks 
property.  If the RecordSelectors property is True, the user can select 
an entire row by clicking the record selector icon for that row.

=========================================
Selecting cells, columns, rows and ranges
=========================================

When you select a cell, the ColIndex property is set, thus selecting one 
of the Column objects in the DBGrid object's Columns collection.  The Text 
and Value properties of the Column object reference the contents of the 
current cell.  The data in the current row can be accessed using the 
Bookmark property, which provides access to the underlying Recordset 
object's record.

===================
Working with Ranges
===================

(To be added.)

============================
Displaying calculated fields
============================

(To be added.)