Copyright © 1987-2005 ComponentOne LLC. All rights reserved.

Corporate Headquarters
ComponentOne LLC
4516 Henry Street
Suite 500
Pittsburgh, PA 15213 USA
Internet: info@ComponentOne.com
Web site: http://www.componentone.com
Sales
E-mail: sales@componentone.com
Telephone: 1.800.858.2739 or 1.412.681.4343 (Pittsburgh, PA USA Office)

Technical Support
See Technical Support in this manual for information on obtaining technical support.

Trademarks
ComponentOne True DBGrid Pro 8.0 and the ComponentOne True DBGrid Pro 8.0 logo are trademarks, and
ComponentOne is a registered trademark of ComponentOne LLC. All other trademarks used herein are the properties of
their respective owners.

Warranty
ComponentOne warrants that the original CD (or diskettes) are free from defects in material and workmanship, assuming
normal use, for a period of 90 days from the date of purchase. If a defect occurs during this time, you may return the
defective CD (or disk) to ComponentOne, along with a dated proof of purchase, and ComponentOne will replace it at no
charge. After 90 days, you can obtain a replacement for a defective CD (or disk) by sending it and a check for $25 (to cover
postage and handling) to ComponentOne.
Except for the express warranty of the original CD (or disks) set forth here, ComponentOne makes no other warranties,
express or implied. Every attempt has been made to ensure that the information contained in this manual is correct as of
the time it was written. We are not responsible for any errors or omissions. ComponentOne’s liability is limited to the
amount you paid for the product. ComponentOne is not liable for any special, consequential, or other damages for any
reason.

Copying and Distribution

While you are welcome to make backup copies of the software for your own use and protection, you are not permitted to
make copies for the use of anyone else. We put a lot of time and effort into creating this product, and we appreciate your
support in seeing that it is used by licensed users only. Please read the License Agreement in this manual before copying
and redistributing any ComponentOne True DBGrid Pro 8.0 files.
 · iii

Table of Contents
Table of Contents ....................................................................................................................... iii
Overview ........................................................................................................................................ 1
Product Profile ........................................................................................................................ 1
Installation............................................................................................................................... 3
Adding the True DBGrid Pro 8.0 Components to the Toolbox........................................ 3
Upgrading ............................................................................................................................... 4
END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE.............. 5
Redistributable Files............................................................................................................. 12
Technical Support................................................................................................................. 13
The Basics..................................................................................................................................... 15
Specifying a Data Source ..................................................................................................... 15
Choosing a Column Layout ................................................................................................ 16
Configuring Columns at Design Time .............................................................................. 17
Configuring Columns at Run Time ................................................................................... 20
Understanding Bookmarks ................................................................................................. 23
True DBGrid Samples ............................................................................................................... 25
ICursor and OLEDB Samples ............................................................................................. 25
True DBGrid Extra Samples................................................................................................ 25
Tutorials ....................................................................................................................................... 27
Introduction .......................................................................................................................... 27
Tutorial 1 - Binding True DBGrid to a Data Control ....................................................... 27
Tutorial 2 - Using True DBGrid with SQL Query Results .............................................. 29
Tutorial 3 - Linking Multiple True DBGrid Controls ...................................................... 32
Tutorial 4 - Interacting with Code and Other Bound Controls ...................................... 33
Tutorial 5 - Selecting Multiple Rows Using Bookmarks ................................................. 37
Tutorial 6 - Defining Unbound Columns in a Bound Grid............................................. 38
Tutorial 7 - Displaying Translated Data with the Built-in Combo ................................ 42
Tutorial 8 - Attaching a True DBDropDown Control to a Grid Cell ............................. 44
Tutorial 9 - Attaching an Arbitrary Drop-down Control to a Grid Cell ....................... 46
Tutorial 10 - Enhancing the User Interface with In-Cell Bitmaps.................................. 49
Tutorial 11 - Using Styles to Highlight Related Data ...................................................... 51
Tutorial 12 - Displaying Rows in Alternating Colors...................................................... 54
Tutorial 13 - Implementing Drag-and-Drop in True DBGrid......................................... 56
Tutorial 14 - OLE Drag-and-Drop...................................................................................... 61
Tutorial 15 - Creating a Grid with Fixed, Nonscrolling Columns ................................. 63
Tutorial 16 - Displaying Array Data in Unbound Mode................................................. 64
Tutorial 17 - Displaying Array Data in Unbound Extended Mode ............................... 70
Tutorial 18 - Displaying Array Data in Unbound Application Mode........................... 75
Tutorial 19 - Displaying Array Data in Unbound Storage Mode .................................. 79
Tutorial 20 - Sorting and Searching ................................................................................... 81
Tutorial 21 - Displaying Arbitrary Bitmaps...................................................................... 84
Tutorial 22 - Reusable Layouts ........................................................................................... 86
Tutorial 23 - Printing, Print Preview, and Export ............................................................ 88
Tutorial 24 - Displaying Hierarchical Data ....................................................................... 91
Tutorial 25 - Outlook-Style Grouping................................................................................ 97
iv ·

Tutorial 26 - Value Translation ......................................................................................... 100

Tutorial 27 - Range Selection............................................................................................. 103
Tutorial 28 - Transposed Views ........................................................................................ 105
Tutorial 29 - Filter Bar ........................................................................................................ 108
Tutorial 30 - Cell Bordering and Scroll Tips/Tracking ................................................. 111
Object Model ............................................................................................................................. 117
True DBGrid Objects and Collections.............................................................................. 117
TDBGrid Control ................................................................................................................ 118
TDBDropDown Control .................................................................................................... 118
Column Object, Columns Collection ............................................................................... 119
DataObject Object, DataObjectFiles Collection............................................................... 119
Error Object, Errors Collection ......................................................................................... 120
GroupColumns Collection ................................................................................................ 120
Layouts Collection.............................................................................................................. 121
PrintInfo Object, PrintInfos Collection ............................................................................ 121
RowBuffer Object................................................................................................................ 121
SelBookmarks Collection................................................................................................... 121
Split Object, Splits Collection ............................................................................................ 122
Style Object, Styles Collection........................................................................................... 122
ValueItem Object, ValueItems Collection ....................................................................... 123
XArrayDB Object ................................................................................................................ 123
Working with Objects and Collections ............................................................................ 123
Design Time Interaction.......................................................................................................... 129
Context Menu...................................................................................................................... 129
Visual Editing Mode .......................................................................................................... 130
Property Page Overview ................................................................................................... 135
TDBGrid Property Pages ................................................................................................... 147
TDBDropDown Property Pages ....................................................................................... 171
Reusable Layouts................................................................................................................ 178
TDBDropDown at Design Time ....................................................................................... 179
Run Time Interaction ............................................................................................................... 181
Navigation and Scrolling................................................................................................... 181
Selection and Movement ................................................................................................... 184
Sizing and Splitting ............................................................................................................ 188
Database Operations .......................................................................................................... 190
Drag-and-Drop Behavior................................................................................................... 191
Additional User Interaction Features .............................................................................. 193
Bound Mode .............................................................................................................................. 195
Binding True DBGrid to a Data Source ........................................................................... 195
Visual Basic Data Control Considerations ...................................................................... 196
Unbound Columns............................................................................................................. 198
Storage Mode............................................................................................................................. 205
When to Use Storage Mode............................................................................................... 205
Using the XArrayDB Object .............................................................................................. 205
Interactions between True DBGrid and XArrayDB ....................................................... 207
Storage Mode Examples .................................................................................................... 209
Application Mode..................................................................................................................... 211
When to Use Application Mode ....................................................................................... 211
How Application Mode Works ........................................................................................ 211
 ·v

Application Mode Bookmarks.......................................................................................... 212

Application Mode Events.................................................................................................. 214
Application Mode Programming Considerations ......................................................... 216
Application Mode Example .............................................................................................. 217
Unbound Mode......................................................................................................................... 219
When to Use Unbound Mode ........................................................................................... 219
How Unbound Mode Works ............................................................................................ 220
Unbound Mode Bookmarks.............................................................................................. 221
Using the RowBuffer Object ............................................................................................. 221
Unbound Mode Events...................................................................................................... 223
Unbound Mode Programming Considerations ............................................................. 232
Unbound Mode Examples ................................................................................................ 234
Database Programming Techniques ..................................................................................... 235
Changing the Current Record Position ........................................................................... 235
Accessing and Manipulating Cell Data ........................................................................... 236
Validating Cell Data........................................................................................................... 237
Selecting and Highlighting Records ................................................................................ 240
Updating and Deleting the Current Record ................................................................... 241
Refreshing the Display....................................................................................................... 241
Refetching Data from the Data Source ............................................................................ 242
Coordinating with Other Controls................................................................................... 242
Handling Database Errors................................................................................................. 243
Postponing Illegal Operations in Grid Events................................................................ 245
Customizing the Grid's Appearance..................................................................................... 247
Captions, Headers, and Footers ....................................................................................... 247
Three-dimensional versus Flat Display........................................................................... 249
Borders and Dividing Lines .............................................................................................. 251
Unpopulated Regions ........................................................................................................ 252
Highlighting the Current Row or Cell............................................................................. 254
Row Height and Multiple-line Displays ......................................................................... 257
Alternating Row Colors..................................................................................................... 259
Horizontal and Vertical Alignment ................................................................................. 260
Window Animation ........................................................................................................... 261
Data Presentation Techniques ............................................................................................... 263
Text Formatting .................................................................................................................. 263
Automatic Data Translation with ValueItems................................................................ 265
Context-sensitive Help with CellTips.............................................................................. 274
Scroll Tracking and ScrollTips.......................................................................................... 276
Data-sensitive Cell Merging.............................................................................................. 276
Outlook-Style Grouping .................................................................................................... 278
Hierarchical Data Display ................................................................................................. 279
Dropdown Hierarchical Data Display............................................................................. 281
Form Data Display ............................................................................................................. 284
Inverted Data Display........................................................................................................ 284
Owner-drawn Cells............................................................................................................ 285
Filtering Data in Recordsets.............................................................................................. 288
How to Use Splits ..................................................................................................................... 293
Referencing Splits and their Properties ........................................................................... 293
Creating and Removing Splits.......................................................................................... 296
vi ·

Working with Columns in Splits ...................................................................................... 296

Sizing and Scaling Splits.................................................................................................... 299
Creating and Resizing Splits through User Interaction................................................. 302
Vertical Scrolling and Split Groups.................................................................................. 304
Horizontal Scrolling and Fixed Columns........................................................................ 305
Navigation across Splits .................................................................................................... 306
How to Use Styles..................................................................................................................... 307
Built-in Named Styles ........................................................................................................ 307
Working with Style Properties.......................................................................................... 311
Applying Styles to Cells .................................................................................................... 321
Applying Pictures to Grid Elements ................................................................................ 326
Cell Editing Techniques.......................................................................................................... 333
How Cell Editing Works ................................................................................................... 333
Handling Editing Events ................................................................................................... 334
Working with Text ............................................................................................................. 336
Input Masking..................................................................................................................... 337
In-cell Buttons ..................................................................................................................... 339
Drop-down Controls .......................................................................................................... 341
Object Reference....................................................................................................................... 347
True DBGrid All Members ................................................................................................ 347
True DBGrid Properties..................................................................................................... 362
True DBGrid Methods ....................................................................................................... 488
True DBGrid Events ........................................................................................................... 526
TDBDropDown All Members ........................................................................................... 573
TDBDropDown Properties................................................................................................ 577
TDBDropDown Methods .................................................................................................. 612
TDBDropDown Events ...................................................................................................... 625
Constant Reference................................................................................................................... 649
PrintInfo Reference .................................................................................................................. 665
PrintInfo All Members ....................................................................................................... 665
PrintInfo Properties ............................................................................................................ 666
PrintInfo Methods .............................................................................................................. 683
XArrayDB Reference................................................................................................................ 689
XArrayDB All Members .................................................................................................... 689
XArrayDB Properties ......................................................................................................... 689
XArrayDB Methods............................................................................................................ 694
XArrayDB Object Constants.............................................................................................. 705
Index............................................................................................................................................ 707
 Product Profile · 1

Overview
Welcome to ComponentOne True DBGrid® Pro 8. True DBGrid Pro 8.0 is a powerful, versatile, and
easy-to-use data presentation tool. Novice programmers can use True DBGrid Pro 8.0 to create a fully
functional database browser without writing a single line of code. Professional developers can use the
grid control's many properties and events to create sophisticated and user-friendly database front-end
applications.
If you like True DBGrid Pro 8.0, you can check out our other products by visiting our web site at
http://www.componentone.com.
ComponentOne has a user-friendly distribution policy. We want every programmer to obtain a copy of
True DBGrid Pro 8.0 to try for as long as they wish. Those who like the product and find it useful may
buy a license for a reasonable price. The only restriction is that unlicensed copies of True DBGrid Pro 8.0
will display a ComponentOne banner every time they are loaded to remind developers to license the
product.
We are confident that you'll like True DBGrid Pro 8.0. If you have any suggestions or ideas for new
features or tools that you'd like to see included in a future version please call us or write:
Corporate Headquarters
ComponentOne LLC
4516 Henry Street
Suite 500
Pittsburgh, PA 15213 USA
412.681.4343
412.681.4384 (Fax)
http://www.componentone.com

Product Profile
True DBGrid Pro 8.0 is a data-aware ActiveX grid control for Microsoft Visual Studio. Developed by
ComponentOne LLC, True DBGrid Pro 8.0 is the upgrade to the DBGrid control included in this product,
as well as earlier versions of Microsoft Visual Basic and Visual C++.
True DBGrid Pro 8.0 allows end users to browse, edit, add, and delete data in a tabular format. Using the
latest data-binding technologies built into Visual Studio, including OLE DB, True DBGrid Pro 8.0
completely manages the database interface, allowing developers to concentrate on important application-
specific tasks. True DBGrid Pro 8.0 can also be used in unbound or storage mode with a programmer's
own data source.
In addition to being the fastest database grid on the market, True DBGrid Pro 8.0 includes dozens of
advanced data access, data presentation, and user interface features that enable developers to build
intuitive, professional-looking applications:
100% DBGrid compatibility True DBGrid Pro 8.0 supports all of the features of the Microsoft
Data Bound Grid control (DBGrid).
Excel and Word-like styles Style objects encapsulate font, color, picture, and formatting
information, facilitating easy customization of grid components at
design time and run time.
2 · Overview
Excel-like splits
Fixed, nonscrolling columns
In-cell objects
Drop-down objects
Automatic data translation
Data-sensitive display
Drag-and-drop features
Interactive visual editing
Flexible unbound modes
Unbound columns
Array-based storage mode
Reusable grid layouts
Input masking
Multiline displays
Run-time CellTips
Alternating row colors
Excellent documentation
Developers and end users can divide the grid into separate vertical
panes to provide multiple views of the data. The splits can scroll
independently or simultaneously.
Splits can also be used to create nonscrolling columns anywhere
in the grid (at the left or right edges, or in the middle).
The grid supports a variety of in-cell objects for data display and
editing, including bitmaps, command buttons, check boxes, and
radio buttons.
The grid supports a variety of drop-down objects for data entry,
including a data-aware multicolumn control (TDBDropDown), a
combo box, and a multiline text editor. Third-party drop-down
controls also supported.
Database values can be automatically translated into alternate text
or graphics without coding. For example, numeric codes can be
rendered as words or even bitmaps.
A powerful regular expression facility can be used to apply
different styles to individual cells depending upon their contents.
For example, negative numbers can be shown in red, or fields
containing a particular substring can be shown in bold.
Programmers can implement drag-and-drop interfaces that are
sensitive to the grid's rows, columns, or individual cells.
Programmers can create columns, retrieve field layouts from a
bound data source, resize grid components, and configure all
aspects of the grid layout at design time—no coding is required.
Event-driven unbound modes handle any data source and are
ideal for displaying array data, connecting to a proprietary
database, or eliminating the overhead associated with data
controls.
The grid supports unbound columns while other columns are
bound to a data control.
The XArrayDB object included with True DBGrid Pro 8.0 works just
like a Visual Basic array, but also acts as a data source for the
grid. No unbound events to code!
Grid layouts can be saved to a file, then reused in other projects.
Multiple layouts can be stored in a single grid at design time, then
loaded as needed in code. End-user layout preferences can also
be saved to a file, then recalled the next time the application is run.
Input templates similar to Visual Basic format strings can be
assigned to columns in order to reduce end-user data entry errors.
The cells in a single record can now span multiple lines, making all
columns visible.
Provides context-sensitive help for end users.
Enhances the readability of the grid's display.
True DBGrid Pro 8.0 includes an extensive manual and online help
with plenty of tutorials and examples.
 Installation · 3

Responsive technical
support
Free run-time distribution
Free technical support via e-mail, phone, fax, and peer-to-peer
newsgroups. Product updates, sample programs, and answers to
frequently asked questions are also available from the
ComponentOne Web site at http://www.componentone.com/.
No royalty fees required.

Installation
To install True DBGrid Pro 8.0, use the SETUP utility provided on the installation CD. When you are
prompted, enter the registration key exactly as it is printed and click REGISTER to complete the
registration process. You may register any other ComponentOne products for which you have purchased
a registration key at this time, as well.
The following files will be installed into your Windows\Help directory:
tdbg8.chm Contains the True DBGrid online help topics.
The following files will be installed into your Windows\System directory or, if you use Windows NT,
into your WinNT\System and WinNT\System32 directories. To use True DBGrid Pro 8.0 in your Visual
Basic projects, you must include these files in the project:
TDBG8.ocx Contains the TDBGrid and TDBDropDown controls.
TODG8.ocx Contains the TDBGrid and TDBDropDown controls (OLE DB).
TODGUB8.dll Unbound mode support DLL for use with TODG8.OCX.
TDBGPP8.dll Printing, print preview, and export support DLL for use with
TDBG8.OCX and TODG8.OCX.
XADB8.ocx Contains the XArrayDB Object.
The following folders will be created by the setup utility:
ComponentOne Studio
Directory used to store ComponentOne control information.
ComponentOne Studio\True DBGrid Pro 8.0
Contains sample projects and a README.TXT file with information about True DBGrid Pro 8.0.

Adding the True DBGrid Pro 8.0 Components to the Toolbox

TDBGrid and TDBDropDown are the components used to display data in a tabular format that can be
browsed, edited, added to, and deleted.
True DBGrid Pro 8.0 includes two separate grid controls, one for legacy (ICursor) data sources such as the
Visual Basic built-in Data control, and one for OLE DB data sources such as the ADO Data Control. The
two controls are functionally equivalent; they differ only in how they access data. However, you will
need to choose the correct grid depending upon the type of data source used, as the following table
illustrates.
4 · Overview

To use the True DBGrid components, they must be added to the Visual Studio Toolbox:
Open the Visual Basic IDE (Microsoft's Integrated Development Environment). Make sure the Toolbox is
visible (if necessary, select Toolbox in the View menu).
To set up the True DBGrid components to appear on their own tab, right-click anywhere in the Toolbox
and select Add Tab from the context menu. Enter a tab name, for example, “True DBGrid 8”, in the
dialog box. Select the new tab. Right-click the gray area under that tab and select Components from the
context menu. The Components dialog box opens.
In the Components dialog box, find and select ComponentOne True DBGrid Pro 8.0. Click OK.

Note that the class names are the same regardless of which control is used. However, the type library
name used to qualify object references is TrueDBGrid80 for the legacy control, and TrueOleDBGrid80
for the OLE DB control.
Also note that the OLE DB control can only be used with Visual Basic 6.0 or higher.

Upgrading
If you have projects which use versions of True DBGrid other than True DBGrid Pro 8.0, you can easily
convert them to use True DBGrid Pro 8.0 by running the add-in migration utility.
The True DBGrid Pro 8.0 Migration Utility is copied to your system during installation. A single add-in is
provided for both Visual Basic 5.0 and 6.0. To activate the add-in within the design-time environment,
follow these instructions:
• Run Visual Basic and select Add-In Manager… from the Add-Ins menu. The Add-In Manager
dialog will appear.
• If you are using Visual Basic 6.0, select the list item labeled True DBGrid Pro 8.0 Migration
Utility, then check the Loaded/Unloaded box.
• If you are using Visual Basic 5.0, check the box labeled True DBGrid Pro 8.0 Migration Utility.
 END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 5

• Click the OK button to place the migration utility icon on the toolbar.

After you have added the True DBGrid Pro 8.0 Migration Utility to the list of available add-ins, follow
these steps to convert your projects:
• Make backup copies of any projects that you plan to convert.
• Open a project that contains one of the controls listed in the From column in the migration chart.
• Click the migration utility icon on the toolbar.
• Choose the type of migration that applies to your project (for example, from DBGrid 1.0 to True
DBGrid Pro 8.0, or from True DBGrid Pro 7.0 to True DBGrid Pro 8.0 OLE DB), then click OK.
If the conversion succeeds, a message box will appear to inform you that "The current project was
converted successfully." To avoid conflict, the migration utility also removes the From control from the
Visual Basic Toolbox.
Please note that the migration utility may also need to modify your source code. Whenever source code is
modified, the original code will be commented out and the modification will be tagged with the
following comment:
*** ComponentOne Migration Utility Code Change ***

END-USER LICENSE AGREEMENT FOR COMPONENTONE

SOFTWARE
IMPORTANT-READ CAREFULLY: This End User License Agreement (this "EULA") contains the terms
and conditions regarding your use of the SOFTWARE (as defined below). This EULA contains material
limitations to your rights in that regard. You should read this EULA carefully and treat it as valuable
property.
I. THIS EULA.
1. Software Covered by this EULA. This EULA governs your use of the ComponentOne, LLC
("C1") software product(s) enclosed or otherwise accompanied herewith (individually and
collectively, the "SOFTWARE"). The term "SOFTWARE" includes, to the extent provided by C1:
1) any revisions, updates and/or upgrades thereto; 2) any data, image or executable files,
databases, data engines, computer software, or similar items customarily used or distributed with
computer software products; 3) anything in any form whatsoever intended to be used with or in
conjunction with the SOFTWARE; and 4) any associated media, documentation (including
physical, electronic and on-line) and printed materials (the "Documentation").
2. This EULA is a Legally Binding Agreement Between You and C1. If you are acting as an agent
of a company or another legal person, such as an officer or other employee acting for your
employer, then "you" and "your" mean your principal, the entity or other legal person for whom
you are acting. However, importantly, even if you are acting as an agent for another, you may
still be personally liable for violation of federal and State laws, such as copyright infringement.
This EULA is a legally binding agreement between you and C1. You intend to be legally bound
to this EULA to the same extent as if C1 and you physically signed this EULA. By installing,
copying, or otherwise using the SOFTWARE, you agree to be bound by the terms and conditions
contained in this EULA. If you do not agree to all of the terms and conditions contained in this
EULA, you may not install or use the SOFTWARE. If, for whatever reason, installation has
6 · Overview

begun or has been completed, you should cancel installation or un-install the SOFTWARE, as the
case may be. (You may click on the "exit" button or its equivalent to immediately abort
installation.) If you do not agree to all of these terms and conditions, then you must promptly
return the SOFTWARE to the place of business from which you obtained it in accordance with
any return policies of such place of business. Return policies may vary between or among
resellers, and you must comply with your particular reseller's return policies as agreed at the
point of purchase. If the place of business from which you purchased the SOFTWARE does not
honor a complete refund for a period of thirty (30) days from the date of proof of purchase, then
you may return the SOFTWARE directly to C1 for a period of thirty (30) days from the date of
your purchase. To return the product directly to C1, you must obtain a C1 Return Authorization
Number by contacting C1, and you must forward all items purchased, including the proof of
purchase, directly to C1. The return must be postage-prepaid, and post-marked within thirty (30)
days from the proof of purchase, time being of the essence. The return option to C1 is only
available to the original purchaser of an unopened factory packaged item.

II. YOUR LICENSE TO DEVELOP AND TO DISTRIBUTE.

As provided in more detail below, this EULA grants you two licenses: 1) a license to use the SOFTWARE
to develop other software products (the "Development License"); and 2) a license to use and/or
distribute the Developed Software (the "Distribution License"). Both of these licenses (individually and
collectively, the "Licenses") are explained and defined in more detail below.
1. Definitions. The following terms have the respective meanings as used in this EULA:
"Network Server" means a computer with one or more computer central processing units (CPU's)
that operates for the purpose of serving other computers logically or physically connected to it,
including, but not limited to, other computers connected to it on an internal network, intranet or
the Internet. "Web Server" means a type of Network Server that serves other computers more
particularly connected to it over an intranet or the Internet.

"Developed Software" means those computer software products that are developed by or
through the use of the SOFTWARE. "Developed Web Server Software" means those Developed
Software products that reside logically or physically on at least one Web Server and are operated
(meaning the computer software instruction set is carried out) by the Web Server's central
processing unit(s) (CPU). "Developed Legacy Software" means those Developed Software
products that are not Developed Web Server Software, including, for example, stand-alone
applications and applications accessed by a file server only. "Redistributable Files" means the
SOFTWARE files or other portions of the SOFTWARE that are provided by C1 and are identified
as such in the Documentation for distribution by you with the Developed Software. "Developer"
means a human being or any other automated device using the SOFTWARE in accordance with
the terms and conditions of this EULA.

"Developer Seat License" means that each Developer using or otherwise accessing the
programmatic interface or the SOFTWARE must obtain the right to do so by purchasing a
separate End User License.

“Source Code” shall mean computer software code or programs in human readable format, such
as a printed listing of such a program written in a high-level computer language. The term
"Source Code" includes, but is not limited to, documents and materials in support of the
development effort of the SOFTWARE, such as flow charts, pseudo code and program notes.
 END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 7

2. Your Development License. You are hereby granted a limited, royalty-free, non-exclusive right
to use the SOFTWARE to design, develop, and test Developed Software, on the express condition
that, and only for so long as, you fully comply with all terms and conditions of this EULA.
The SOFTWARE is licensed to you on a Developer Seat License basis.

The Developer Seat License means that you may perform an installation of the SOFTWARE for
use in designing, testing and creating Developed Software by a single Developer on one or more
computers, each with a single set of input devices, so long as such computer/computers is/are
used only by one single Developer at any given time and not concurrently. Conversely, you may
not install or use the SOFTWARE on a computer that is a network server or a computer at which
the SOFTWARE is used by more than one Developer. You may not network the SOFTWARE or
any component part of it, where it is or may be used by more than one Developer unless you
purchase an additional Development License for each Developer. You must purchase another
separate license to the SOFTWARE in order to add additional developer seats, whether the
additional developers are accessing the SOFTWARE in a stand-alone environment or on a
computer network.

In all cases, you may not use C1's name, logo, or trademarks to market your Developed Software
without the express written consent of C1; (b) you must include the following C1 copyright
notice in your Developed Software documentation and/or in the "About Box" of your Developed
Software, and wherever the copyright/rights notice is located in the Developed Software
(“Portions Copyright © ComponentOne, LLC 1991-2002. All Rights Reserved.”); (c) agree to
indemnify, hold harmless, and defend C1, its suppliers and resellers, from and against any claims
or lawsuits, including attorney's fees that may arise from the use or distribution of your
Developed Software; (d) you may use the SOFTWARE only to create Developed Software that is
significantly different than the SOFTWARE.

3. Your Distribution License.

License to Distribute Developed Software. Subject to the terms and conditions in this EULA,
you are granted the license to use and to distribute Developed Software on a royalty-free basis,
provided that the Developed Software incorporates the SOFTWARE as an integral part of the
Developed Software in machine-language compiled format (customarily an ".exe", or ".dll", etc.).
You may not distribute, bundle, wrap or subclass the SOFTWARE as Developed Software which,
when used in a "designtime" development environment, exposes the programmatic interface of
the SOFTWARE. You may distribute, on a royalty-free basis, Redistributable Files with
Developed Software only.

4. Specific Product Limitations. Notwithstanding anything in this EULA to the contrary, if the
license you have purchased is for any of the following products, then the following additional
limitations will apply:
a. ComponentOne Reports for .NET Designer Edition. ComponentOne Reports for .NET
Designer Edition includes at least: 1) one dynamic link library (c1.win.c1reportdesigner.dll) file
known as C1ReportDesigner Component, 2) one executable (ReportDesigner.exe) file known as
C1ReportDesigner Application and, 3) the Source Code of the C1ReportDesigner Application.
The C1ReportDesigner Component is subject to the general terms and restrictions set forth in this
EULA. The C1ReportDesigner Application is an executable file used to design and prepare
reports; the C1ReportDesigner Application may be distributed, free of royalties, only in
conjunction with the Developed Software.
8 · Overview

Subject to the terms and conditions in this EULA, C1 hereby grants you the right to use the
C1ReportDesigner Application Source Code. You are hereby also granted the right to modify
such Source Code and to create derivative works that are based on the licensed Source Code. You
may distribute the derivative works that you develop, solely in object code format and
exclusively in conjunction with and/or as a part of the Developed Software. You are expressly
not granted the right to distribute, disclose or otherwise make available to any third party the
licensed Source Code, any modified version, derivative work, or any portion thereof, in source
code format.

C1 shall retain all right, title and interest in and to the licensed Source Code, and all C1 updates,
modifications or enhancements thereof. Nothing herein shall be deemed to transfer any
ownership or title rights in and to the licensed Source Code from C1 to you.

SOURCE CODE IS LICENSED TO YOU AS IS. C1 DOES NOT AND SHALL NOT PROVIDE
YOU WITH ANY TECHNICAL SUPPORT FOR YOUR SOURCE CODE LICENSE.

b. VSView Reporting Edition. VSView Reporting Edition includes at least one executable file
listed as “VSRptX.exe” (where X indicates the version number i.e.7,8, etc.), known as “Designer.”
The file "VSRptX.exe”, or any upgrade or future versions of the Designer, are subject to the
restrictions set forth in this EULA and may not be distributed with your Developed Software or
in any other way.

c. Doc-to-Help and ComponentOne Natural Search. You may use Doc-To-Help to create online
help, manuals or other documentation in electronic or printed format (the "Output Documents").
You may distribute and incorporate in such Output Documents those files identified in the
documentation as Redistributable Files. Except for those specific Redistributable Files, you MAY
NOT distribute the SOFTWARE, in any format, to others.

d. Studio Products. You may not share the component parts of the Studio Products licensed to
you with other Developers, nor may you allow the use and/or installation of such components
by other Developers.

e. ComponentOne Response and SOAP Channel. ComponentOne Response is intended to be

installed on a Network Server. C1 grants to you the following rights to the SOFTWARE: a)
Installation: You may install one copy of the SOFTWARE on a single Network Server; b) Use:
When installed and initialized, the SOFTWARE creates a database file which contains the
embodiment of a solution knowledge base (the database hereinafter referred to as the
"Knowledge Base").

You may use the SOFTWARE to create Knowledge Bases on one Network Server only. To create
or to operate Knowledge Bases in more than one Network Server, you must purchase one
additional SOFTWARE license for each additional Network Server.

5. Updates/Upgrades; Studio Subscription. Subject to the terms and conditions of this EULA, the
Licenses are perpetual. Updates and upgrades to the SOFTWARE may be provided by C1 from
time-to-time, and, if so provided by C1, are provided upon the terms and conditions offered at
that time by C1 in its sole discretion. C1 may provide updates and upgrades to the SOFTWARE
for free or for any charge, at any time or never, and through its chosen manner of access and
distribution, all in C1's sole and complete discretion.
C1 licenses certain of its separately-licensed products bundled together in a product suite, called
the C1 "Studio" product line (the "Studio Products"). The exact separately-licensed products that
 END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 9

are bundled into the Studio Products may change from time-to-time in C1's sole discretion. If the
SOFTWARE is identified as a C1 "Studio" product, then the SOFTWARE is one of the Studio
Products. The SOFTWARE and the Studio Products are revised from time-to-time (meaning, for
example, revised with updates, upgrades and, in the case of Studio products, possibly changes to
which specific products are included in the bundle). For you to be entitled to receive any such
revisions to the SOFTWARE or the Studio Products, as the case may be, you must have a valid
SOFTWARE license or a valid Studio subscription. The original purchaser of the SOFTWARE or
of a Studio product receives a one-year subscription from the date of purchase of the
SOFTWARE. After one year, the Studio subscription and/or the SOFTWARE license must be
renewed to continue to be entitled to receive the SOFTWARE and/or the Studio Products
revisions as the case may be.

6. Serial Number. Within the packaging of the SOFTWARE, a unique serial number (the "Serial
Number") is included, which allows for the registration of the SOFTWARE. The Serial Number is
subject to the restrictions set forth in this EULA and may not be disclosed or distributed either
with your Developed Software or in any other way. The disclosure or distribution of the Serial
Number shall constitute a breach of this EULA, the effect of which shall be the automatic
termination and revocation of all the rights granted herein.
7. Evaluation Copy. If you are using an "evaluation copy" or similar version, specifically
designated as such by C1 on its website or otherwise, then the Licenses are limited as follows: a)
you are granted a license to use the SOFTWARE for a period of thirty (30) days counted from the
day of installation (the "Evaluation Period"); b) upon completion of the Evaluation Period, you
shall either i) delete the SOFTWARE from the computer containing the installation, or you may
ii) contact C1 or one of its authorized dealers to purchase a license of the SOFTWARE, which is
subject to the terms and limitations contained herein; and c) any Developed Software may not be
distributed or used for any commercial purpose.
III. INTELLECTUAL PROPERTY.
1. Copyright. You agree that all right, title, and interest in and to the SOFTWARE (including, but
not limited to, any images, photographs, animations, video, audio, music, text, and “applets”
incorporated into the SOFTWARE), and any copies of the SOFTWARE, and any copyrights and
other intellectual properties therein or related thereto are owned exclusively by C1, except to the
limited extent that C1 may be the rightful license holder of certain third-party technologies
incorporated into the SOFTWARE. The SOFTWARE is protected by copyright laws and
international treaty provisions. The SOFTWARE is licensed to you, not sold to you. C1 reserves
all rights not otherwise expressly and specifically granted to you in this EULA.
2. Backups. You may either: (a) copy the SOFTWARE solely for backup or archival purposes; or (b)
install the SOFTWARE on a single computer, provided you keep the original solely for backup or
archival purposes. Notwithstanding the foregoing, you may not copy the Documentation.
3. General Limitations. You may not reverse engineer, decompile, or disassemble the SOFTWARE,
except and only to the extent that applicable law expressly permits such activity notwithstanding
this limitation.
4. Software Transfers. You may not rent or lease the SOFTWARE. You may transfer the
SOFTWARE to another computer, provided that it is completely removed from the computer
from which it was transferred. You may permanently transfer all of your rights under the EULA,
provided that you retain no copies, that you transfer all the SOFTWARE (including all
component parts, the media and printed materials, any dates, upgrades, this EULA and, if
applicable, the Certificate of Authenticity), and that the recipient agrees to the terms and
10 · Overview

conditions of this EULA as provided herein. If the SOFTWARE is an update or upgrade, any
transfer must include all prior versions of the SOFTWARE.
5. Termination. Without prejudice to any other rights it may have, C1 may terminate this EULA
and the Licenses if you fail to comply with the terms and conditions contained herein. In such an
event, you must destroy all copies of the SOFTWARE and all of its component parts.
6. Export Restrictions. You acknowledge that the SOFTWARE is of U.S. origin. You acknowledge
that the license and distribution of the SOFTWARE is subject to the export control laws and
regulations of the United States of America, and any amendments thereof, which restrict exports
and re-exports of software, technical data, and direct products of technical data, including
services and Developed Software. You agree that you will not export or re-export the
SOFTWARE or any Developed Software, or any information, documentation and/or printed
materials related thereto, directly or indirectly, without first obtaining permission to do so as
required from the United States of America Department of Commerce's Bureau of Export
Administration ("BXA"), or other appropriate governmental agencies, to any countries, end-
users, or for any end-uses that are restricted by U.S. export laws and regulations, and any
amendments thereof, which include, but are not limited to, the following:
Restricted Countries: Restricted Countries currently include, but are not necessarily limited to
Cuba, Iran, Iraq, Libya, Montenegro, North Korea, Serbia, Sudan, and Syria.

Restricted End-Users: Any End-User whom you know or have reason to know will use
SOFTWARE or Developed Software in the design, development, or production of missiles and
missile technology, nuclear weapons and weapons technology, or chemical and biological
weapons. Any national of any of the Restricted Countries, wherever located, who intends to
transmit or transport the SOFTWARE or Developed Software to one of the Restricted Countries.

Restricted End-Uses: Any use of SOFTWARE and Developed Software related to the design,
development, or production of missiles and missile technology, nuclear weapons and weapons
technology, or chemical and biological weapons.

These restrictions change from time to time. You represent and warrant that neither the BXA nor
any other United States federal agency has suspended, revoked or denied your export privileges.
C1 acknowledges that it shall use reasonable efforts to supply you with all reasonably necessary
information regarding the SOFTWARE and its business to enable you to fully comply with the
provisions of this Section. If you have any questions regarding your obligations under United
States of America export regulations, you should contact the Bureau of Export Administration,
United States Department of Commerce, Exporter Counseling Division, Washington DC. U.S.A.
(202) 482-4811, http://www.bxa.doc.gov.

7. U.S. Government Restricted Rights. The SOFTWARE and documentation are provided with
RESTRICTED RIGHTS. For solicitations issued before December 1, 1995, by the United States of
America, its agencies and/or instrumentalities (the "Government"), other than the Department of
Defense, the use, duplication or disclosure of the software and documentation provided to the
Government under this EULA shall be subject to the RESTRICTED RIGHTS as set forth in
subparagraphs (c)(1) and (2) of the Commercial Computer Software - Restricted Rights clause at
48 CFR ch.1 52.227-19. For solicitations issued before September 29, 1995, by the Department of
Defense, the use, duplication or disclosure of the software and documentation provided under
this EULA shall be subject to the RESTRICTED RIGHTS as set forth in subparagraph (c)(1)(ii) of
the Rights in Technical Data and Computer Software clause at 48 CFR ch.2 252.227-7013. You
will comply with any requirements of the Government to obtain such RESTRICTED RIGHTS
protection, including without limitation, the placement of any restrictive legends on the
 END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 11

SOFTWARE, and any license agreement used in connection with the distribution of the
SOFTWARE. Manufacturer is ComponentOne, LLC, 4516 Henry Street, Suite 501, Pittsburgh,
Pennsylvania 15213 USA. For solicitations issued by the Government on or after December 1,
1995 and the Department of Defense on or after September 29, 1995, the only rights provided in
the software and documentation provided herein shall be those contained in this EULA. Under
no circumstances shall C1 be obligated to comply with any Governmental requirements
regarding the submission of or the request for exemption from submission of cost or pricing data
or cost accounting requirements. For any distribution of the SOFTWARE that would require
compliance by C1 with the Government's requirements relating to cost or pricing data or cost
accounting requirements, you must obtain an appropriate waiver or exemption from such
requirements for the benefit of C1 from the appropriate Government authority before the
distribution and/or license of the SOFTWARE to the Government.
IV. WARRANTIES AND REMEDIES.
1. Limited Warranty. C1 warrants that the original media, if any, are free from defects for ninety
(90) days from the date of delivery of the SOFTWARE. EXCEPT AS OTHERWISE PROVIDED
IN THE PRECEDING SENTENCE, AND TO THE MAXIMUM EXTENT PERMITTED BY
APPLICABLE LAW, C1 EXPRESSLY DISCLAIMS ANY WARRANTY FOR THE SOFTWARE,
DOCUMENTATION AND ANYTHING ELSE PROVIDED BY C1 HEREBY AND C1
PROVIDES THE SAME IN “AS IS” CONDITION WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
THE ENTIRE RISK ARISING OUT OF USE OR PERFORMANCE OF THE SOFTWARE AND
DOCUMENTATION REMAINS WITH YOU. THIS LIMITED WARRANTY GIVES YOU
SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS WHICH VARY FROM STATE TO
STATE.
2. Limited Remedy. C1's entire liability and your exclusive remedy under this EULA shall be, at
C1's sole option, either (a) return of the price paid for the SOFTWARE; (b) repair the SOFTWARE
through updates distributed online or otherwise in C1's discretion; or (c) replace the SOFTWARE
with SOFTWARE that substantially performs as described in the SOFTWARE documentation,
provided that you return the SOFTWARE in the same manner as provided in Section I.2 for
return of the SOFTWARE for non-acceptance of this EULA. Any media for any repaired or
replacement SOFTWARE will be warranted for the remainder of the original warranty period or
thirty (30) days, whichever is longer. THESE REMEDIES ARE NOT AVAILABLE OUTSIDE OF
THE UNITED STATES OF AMERICA. TO THE MAXIMUM EXTENT PERMITTED BY
APPLICABLE LAW, IN NO EVENT SHALL C1 BE LIABLE FOR ANY DAMAGES
WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF
BUSINESS PROFIT, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION,
OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE, EVEN IF C1 HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES. BECAUSE SOME STATES/JURISDICTIONS DO NOT ALLOW THE
EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL
DAMAGES IN CERTAIN CASES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.
V. MISCELLANEOUS.
1. This is the Entire Agreement. This EULA (including any addendum or amendment to this EULA
included with the SOFTWARE) is the final, complete and exclusive statement of the entire
agreement between you and C1 relating to the SOFTWARE. This EULA supersedes any prior
and contemporaneous proposals, purchase orders, advertisements, and all other communications
in relation to the subject matter of this EULA, whether oral or written. No terms or conditions,
other than those contained in this EULA, and no other understanding or agreement which in any
12 · Overview

way modifies these terms and conditions, shall be binding upon the parties unless entered into in
writing executed between the parties, or by other non-oral manner of agreement whereby the
parties objectively and definitively act in a manner to be bound (such as by continuing with an
installation of the SOFTWARE, "clicking-through" a questionnaire, etc.) Employees, agents and
other representatives of C1 are not permitted to orally modify this EULA.
2. You Indemnify C1. . You agree to indemnify, hold harmless, and defend C1 and its suppliers
and resellers from and against any and all claims or lawsuits, including attorney's fees, which
arise out of or result from your breach of any of the terms and conditions of this EULA.
3. Interpretation of this EULA. If for any reason a court of competent jurisdiction finds any
provision of this EULA, or any portion thereof, to be unenforceable, that provision of this EULA
will be enforced to the maximum extent permissible so as to effect the intent of the parties, and
the remainder of this EULA will continue in full force and effect. Formatives of defined terms
shall have the same meaning of the defined term. Failure by either party to enforce any provision
of this EULA will not be deemed a waiver of future enforcement of that or any other provision.
Except as otherwise required or superseded by law, this EULA is governed by the laws of the
Commonwealth of Pennsylvania, without regard to its conflict of laws principles. The parties
consent to the personal jurisdiction and venue of the Commonwealth of Pennsylvania, in the
County of Allegheny, and agree that any legal proceedings arising out of this EULA shall be
conducted solely in such Commonwealth. If the SOFTWARE was acquired outside the United
States, then local law may apply.

Redistributable Files
True DBGrid Pro 8.0 is developed and published by ComponentOne LLC. You may use it to develop
applications in conjunction with Microsoft Visual Studio or any other programming environment that
enables the user to use and integrate the control(s). You may also distribute, free of royalties, the
following Redistributable Files with any such application you develop to the extent that they are used
separately on a single CPU on the client/workstation side of the network:

TDBG8.OCX ComponentOne True DBGrid Pro 8.0. This is an ICursor-based control

compatible with the intrinsic data control of Visual Basic and the Microsoft
Remote Data Control.
TODG8.OCX ComponentOne True DBGrid Pro 8.0 (OLE DB). This control is compatible with
OLE DB and ADO (ActiveX Data Objects) data sources, such as the Microsoft
ADO Data Control and the Data Environment of Visual Basic 6.0.
TODGUB8.DLL Unbound mode support DLL for use with TODG8.OCX. This file is not used by
TDBG8.OCX, which contains built-in unbound mode support.
TDBGPP8.DLL Printing, print preview, and export support DLL for use with TDBG8.OCX and
TODG8.OCX. Note: The TDGBPP8.DLL module uses the zlib data
compression library written by Jean-loup Gailly and Mark Adler.
XADB8.OCX ComponentOne XArrayDB Object. This is the enhanced version that supports
sorting and searching.

NOTE: If you use the OLE DB grid (TODG8.OCX) with the DataView property set to 1 - Hierarchical, then
you must also distribute XADB8.OCX, even if you do not use the XArrayDB object explicitly in code.
End users of your applications are not licensed to use True DBGrid for development, and may not
redistribute any of the above control files.
 Technical Support · 13

You are not licensed to distribute any True DBGrid file to users for development purposes. You are not
allowed to add or transfer the True DBGrid license key to the registry of your users' computer(s).
In particular, if you create a control using a True DBGrid component as a constituent control, you are not
licensed to distribute the control you created with the True DBGrid component to users for development
purposes.
It is your responsibility to make such restrictions clear to your users.
Site licenses are available for groups of multiple developers. Please contact Sales@ComponentOne.com
for details.

Technical Support
True DBGrid Pro 8.0 is developed and supported by ComponentOne LLC, a company formed by the
merger of APEX Software Corporation and VideoSoft. You can obtain technical support using any of the
following methods:

ComponentOne Web site

The ComponentOne Web site at www.componentone.com provides a wealth of information and software
downloads for True DBGrid users:
• Descriptions of the various support options available through the ComponentOne Service Team.
• Answers to frequently asked questions (FAQ's) about True DBGrid, organized by functionality.
Please consult the FAQ's before contacting us directly, as this can save you time and also
introduce you to other useful information pertaining to True DBGrid.
• Free product updates, which provide you with bug fixes and new features.

Internet e-mail
For technical support through the Internet, e-mail us at:
support.tdbgrid@componentone.com
To help us provide you with the best support, please include the following information when contacting
ComponentOne:
• Your ComponentOne product serial number.
• The version and name of your operating system.
• Your development environment and its version.
For more information on technical support, go to:
www.componentone.com/support

Peer-to-Peer newsgroup
ComponentOne also sponsors a peer-to-peer newsgroup for True DBGrid users. ComponentOne does not
offer formal technical support in this newsgroup, but instead sponsors it as a forum for users to post and
answer each other's questions regarding True DBGrid. However, ComponentOne may monitor the
newsgroup to ensure accuracy of information and provide comments when necessary. You can access the
newsgroup from the ComponentOne Web site at www.componentone.com/newsgroups.
 Specifying a Data Source · 15

The Basics
This section explains the three fundamental concepts that you need to master in order to use True
DBGrid effectively:
1. Data sources
2. Column layouts
3. Bookmarks

Specifying a Data Source

True DBGrid offers unprecedented flexibility in choosing a data source. You can bind directly to Visual
Basic's intrinsic Data control, OLE DB data sources such as Microsoft's ADO Data Control and Remote
Data Services (RDS), or a third-party data control such as ComponentOne's True DataControl. Using True
DBGrid in bound mode greatly simplifies database development by enabling you to focus on your
application's interface instead of data access details.
However, there are times when binding to a data control is neither practical nor desirable, and an
unbound mode of operation is necessary. By their nature, data controls add layers of overhead, which
may result in performance degradation for large datasets. Bound mode is not an option if you are using a
proprietary database format or one that is not supported by the standard data controls. You may even
need to display a simple two-dimensional array within a grid—why bother with a database?
True DBGrid provides a sensible strategy for handling all of these situations. Regardless of which data
access strategy you choose, you won't be penalized for switching to another one at a later date, as True
DBGrid provides a clean separation between the data source and the grid's programmatic interface. In
other words, if you write data validation or record manipulation code that works in bound mode, it will
continue to work if you switch to unbound mode.
True DBGrid supports the following data access modes:
Bound The grid receives data and notifications from an intrinsic or external data control
according to the Microsoft data binding specifications.
Storage The grid receives data from a ComponentOne XArrayDB object, which can be
redimensioned and populated in code much like a standard Visual Basic array.
Application The grid fires data retrieval and update events for individual grid cells.
Unbound The grid fires data retrieval and update events for a small set of records all at
once.

What is bound mode?

When the DataMode property of a TDBGrid control is set to the default value of 0 - Bound, the grid
communicates directly with an intrinsic or external data control to retrieve and update data. If you are
using a data source that is supported by the Visual Basic built-in Data control, the Remote Data Control
(RDC), the ADO Data Control, or the Data Environment designer, then bound mode is your best option.
Simply configure the data control as you normally would, then attach it to the DataSource property of a
TDBGrid control at design time. If you are using an OLE DB-compliant data source, you may also need
to set the DataMember property to specify a database table or query.
For more information on using True DBGrid in bound mode, see Bound Mode (page 195).
16 · The Basics

What is storage mode?

The easiest way to display two-dimensional array data in a grid is with storage mode. At design time, set
the DataMode property of a TDBGrid control to 4 - Storage. At run time, create an instance of the
ComponentOne XArrayDB object included with True DBGrid, populate it as you would a standard
Visual Basic array, then attach it to the Array property of a TDBGrid control in code.
For more information on using True DBGrid in storage mode, see Storage Mode (page 205).

What is application mode?

If you prefer to work with standard Visual Basic arrays, application mode is recommended, as it is well-
suited to array manipulation. To use application mode, set the DataMode property of a TDBGrid control
to 3 - Application at design time. At a minimum, you will need to write code to handle two events:
ClassicRead and UnboundGetRelativeBookmark. The former is fired whenever the grid requests a
value to be displayed in a particular cell; the latter is fired whenever the grid needs to determine the
bookmark used to identify a particular row.
For more information on using True DBGrid in application mode, see Application Mode (page 211).

What is unbound mode?

If you are working with a database API that supports multiple-row fetches (such as ODBC), or are
converting applications that use unbound DBGrid controls, then the row-based unbound mode should
be used. Although unbound mode is the most difficult data access mode to implement, it tends to be
more efficient than application mode, since fewer events need to be fired.
DataMode setting 2 - Unbound Extended is the preferred method. Setting 1 - Unbound is a remnant of the
original DBGrid control and is included for backward compatibility.
For more information on using True DBGrid in unbound mode, see Unbound Mode (page 219).

Choosing a Column Layout

In a True DBGrid display, each column represents a single field of data. For each column, the grid needs
to know the field name associated with the data, and optionally a heading to be displayed above the data
column.
True DBGrid gets information about field names and headings in one of three ways:
1. Automatic layouts, derived at run time from the Data control's Recordset.
2. Customized layouts, derived at design time from the Data control's Recordset and optionally
tailored using the control's property pages.
3. Run-time layouts, created or modified in code by manipulating the Columns collection and its
Column object members.

Automatic layouts
If you do not define a column layout at design time, True DBGrid will automatically create one based
upon the database used when you run your program. All fields from the Data control's Recordset will be
displayed, using the field names for column captions. At run time, you can perform database actions that
may alter the layout needed to display the data. For example, you may change the DatabaseName,
RecordSource, or Recordset properties of the Data control, resulting in a different Recordset. When the
new Recordset is created the grid will automatically sense the new column layout and reconfigure. This
 Configuring Columns at Design Time · 17

mode is the most automatic and is quite useful for most applications. You can cancel the grid's automatic
layout behavior by invoking the grid's HoldFields method in code.

Customized layouts
At design time, you can cause True DBGrid to configure to the Data control's Recordset by selecting
Retrieve Fields from the grid's context menu. The grid will create a column for each field in the
Recordset, using the corresponding field name for each column's caption. You can customize each
column using the Columns and Splits property pages. The design-time custom layout can be canceled
using the Clear Fields option of the grid's context menu, or by invoking the grid's ClearFields method in
code.

Run-time layouts
True DBGrid gives you complete control over the grid layout at run time via Column object properties
and Columns collection methods. You can always modify the grid layout at run time using code,
regardless of whether you use the grid's automatic layout feature or define your own.

Switching between layout types

If you define a design-time column layout, the grid will not automatically change the layout at run time,
as it assumes that you want total control of the display. The grid considers you to have defined a design-
time column layout if you chose the Retrieve Fields option from the grid's context menu or modified any
properties in either the Columns or Splits property pages.
You can clear the design-time layout by choosing the Clear Fields option of the grid's context menu or by
invoking the grid's ClearFields method in code:
TDBGrid1.ClearFields ' Clear column layout
After this statement is executed, the grid will again respond automatically to layout changes at run time.
Conversely, you can cancel the grid's automatic layout behavior by invoking the grid's HoldFields
method in code:
TDBGrid1.HoldFields ' Cancel automatic layout
After this statement is executed, the grid will stop automatically changing the layout at run time, and
uses the current column layout for all subsequent Recordset display. This is especially useful if you need
to refresh the data control the grid is bound to while maintaining the current grid layout.
By using the ClearFields and HoldFields methods, you can alternate the grid's display between
automatic layout and customized layout.

Configuring Columns at Design Time

True DBGrid provides unique visual editing capabilities that streamline design-time column
configuration. Instead of adding and removing columns with command buttons on a property page, you
manipulate the grid directly on the form with the mouse. You can even copy columns to the Clipboard
and paste them into another grid on a different form!
Once you have created and resized columns to your liking, you can use the Columns and Splits property
pages to further refine their appearance and behavior.
18 · The Basics

Visual editing
At design time, you can use True DBGrid's visual editing mode to perform the following tasks:
• Add and remove columns.
• Copy columns to and from the Clipboard.
• Move and resize columns.
• Adjust the grid's row height.
• Retrieve field layouts from a bound data source.
• Split the grid into separate vertical scrolling regions.
• Save the current grid layout to a file.
• Load an existing grid layout from a file.
• Access the grid's property pages.
To enter visual editing mode, click anywhere on the grid with the right mouse button to display the grid's
context menu, then choose the Edit command.

The grid control is now activated in-place, which means that you can work with its columns directly on
the form. For example, if you point to a dividing line between two columns, the mouse pointer changes to
the following symbol.

This indicates that the column you are pointing to is ready to be resized. If you drag the dividing line to a
different position, the column will change its width accordingly, and the grid will reposition any adjacent
columns.
Similarly, if you point to a column header, the mouse pointer changes again.
 Configuring Columns at Design Time · 19

This symbol indicates that the column is ready to be selected. If you click its header, the entire column is
highlighted. You can also drag the mouse pointer within the column header area to extend the selection
to other adjacent columns. To cancel the selection and return the columns to their normal, unhighlighted
state, click any cell within the grid's data area.
Column selection serves two purposes in visual editing mode:
1. Selected columns can be moved to a different position within the grid by dragging within the
column header (provided that AllowColMove is True for the current split).
2. Selected columns act as arguments for some visual editing menu commands.
If the grid is already in visual editing mode, right-clicking it again displays a different context menu. This
is the visual editing menu, which provides commands for manipulating columns, splits, and layouts.

For more information on visual editing, as well as an explanation of the visual editing menu commands,
see Design Time Interaction (page 129).

Specifying database fields

At design time, the easiest way to bind database fields to grid columns is with the Retrieve Fields
command. However, if the grid is not bound at design time, this command has no effect. Fortunately, you
can still set column properties manually using the grid's property pages, but you must first create blank
columns using the Insert or Append commands of visual editing mode.
To associate a database field with a grid column, choose Properties… from the visual editing menu (or
context menu) to display the Property Pages dialog, then click the Columns tab to display the Columns
property page. Expand a numbered column node in the property tree on the left, then select the
DataField property.
20 · The Basics

Type a value for this property in the edit control labeled Selection or String. Or, if the grid is bound at
design time, you can choose a value from the adjacent list of available fields. You can also enter a value
for the Caption property, which specifies the text to be displayed in the column header.
When you are done specifying column properties, click the OK button.

Specifying other column properties

Not all column properties can be set from the Columns property page. This is because some properties,
such as Width, may differ from split to split. In True DBGrid, a split is similar to the split window
features of products such as Microsoft Excel and Word, and is often used to present data in multiple
vertical panes. Two common applications of splits in True DBGrid are:
1. Independent vertical scrolling panes
2. Fixed nonscrolling columns
If you are just getting started with True DBGrid, you don't need to learn about splits right away, but you
should know that the Splits property page is used to specify split-specific column properties. For more
information, see Columns in property trees (page 142).

Configuring Columns at Run Time

True DBGrid provides complete control over column layouts at run time. Regardless of which data access
mode you are using, you can always add, remove, and manipulate columns in code.
The techniques used to configure columns in code follow the conventions for collection objects in Visual
Basic.
 Configuring Columns at Run Time · 21

Adding and removing columns

By manipulating the Columns collection, you can add or remove columns from the grid at run time. You
can even perform complete grid configurations in code, rather than using the visual editing features.
Here is an example of how a column can be added to the grid using the Columns collection:
' Create a new Column 0
Dim C As TrueDBGrid80.Column
Set C = TDBGrid1.Columns.Add(0)
' Initialize the new Column 0
With C
.Visible = True ' Make it visible
.DataField = "LAST" ' Set the column's database field
.Caption = "Last Name" ' Set the column's caption
End With
' Make Column 0 as wide as Column 1
C.Width = TDBGrid1.Columns(1).Width
Several key points should be noted in this example:
• The Columns collection is referenced as TDBGrid1.Columns, while an individual Column
object is referenced with a numeric index, TDBGrid1.Columns(1). All indexes for a collection
are zero-based, so index position 1 refers to the second column. This is the general syntax for
referencing a collection and its individual elements.
• You can add a new Column object to the Columns collection using the collection's Add method,
which accepts a numeric index and returns the newly created object. This is the general technique
used to add an item to a collection.
• The Visual Basic Set statement is needed to store the new column object in the variable C.
Without it, the run-time error "Object variable or With block variable not set" will occur.
• The newly added column is Column 0 of the grid. The previous Column 0 becomes Column 1,
the previous Column 1 becomes Column 2, and so on.
You can insert a new column at any position. For example:
Set C = TDBGrid1.Columns.Add(3)
After this statement executes, the new column will be Column 3. The previous Column 3 becomes
Column 4, the previous Column 4 becomes Column 5, and so on.
After a new column is added, the Count property of the Columns collection will be automatically
incremented by one. You cannot create a column with an index larger than the current value of the Count
property. The Count property is read-only, so you cannot append columns by setting it to a larger value.
To delete a member of the Columns collection and remove it from the grid's display, use the Remove
method. This is the general technique to remove an item from a collection:
TDBGrid1.Columns.Remove 1
Or, to remove all columns from a grid:
While TDBGrid1.Columns.Count <> 0
TDBGrid1.Columns.Remove 0
Wend
At run time, a newly created column is made invisible to avoid unnecessary flicker when multiple
columns are created. Therefore, you must explicitly set its Visible property to True. Also, you must set
22 · The Basics

the column's DataField and Caption properties, otherwise the grid will display a blank column with no
heading.
Note that when you set the DataField property of a column in code, you must ReBind the grid to the
data source in order for the new column binding to take effect.

Referencing column objects

When a column is added to or removed from a grid, the associated Column object is added to or
removed from the grid's Columns collection. This may cause a change in the index numbers of the
existing columns, making it very inconvenient to reference columns numerically. For this reason, True
DBGrid also allows you to reference columns using either the DataField or Caption strings. Thus, the
following references are identical:
TDBGrid1.Columns(n) ' Reference by the Column index
TDBGrid1.Columns("LAST") ' Reference by the DataField name
TDBGrid1.Columns("Last Name") ' Reference by the Caption string
Referencing column objects by DataField or Caption is not case-sensitive.
TDBGrid1.Columns("LAST") refers to the same column as TDBGrid1.Columns("last").
When you reference a Column object and its properties at run time, Visual Basic creates an instance of the
object. For example, if you duplicate certain properties of a column:
TDBGrid1.Columns("First").Width = _
TDBGrid1.Columns("Last").Width
TDBGrid1.Columns("First").Alignment = _
TDBGrid1.Columns("Last").Alignment
TDBGrid1.Columns("First").AllowSizing = _
TDBGrid1.Columns("Last").AllowSizing
The Columns("First") and Columns("Last") objects will each be created and discarded three times
in the preceding example. The same results are achieved more efficiently by creating object variables that
refer to these columns:
' Declare Column objects
Dim FirstCol As TrueDBGrid80.Column
Dim LastCol As TrueDBGrid80.Column
' Reference First and Last Column objects
Set FirstCol = TDBGrid1.Columns("First")
Set LastCol = TDBGrid1.Columns("Last")
' Copy properties from Last to First
FirstCol.Width = LastCol.Width
FirstCol.Alignment = LastCol.Alignment
FirstCol.AllowSizing = LastCol.AllowSizing
The same technique can be applied to other objects in Visual Basic. For more details, see Object Model
(page 117).

Adjusting column properties in code

Properties of the Column object can be changed at run time using Visual Basic code. For example,
changing the DataField property can be done as follows:
With TDBGrid1.Columns(0)
.DataField = "New DataField"
TDBGrid1.ReBind
.Caption = "New Caption"
End With
 Understanding Bookmarks · 23

Note that after changing the DataField property, you must ReBind the grid columns so that the new data
will appear in the column. You should also change the caption to describe the new field.
Other Column object properties can be changed in a similar fashion. Please refer to Column Object
Properties (page 355) for a complete listing.

Understanding Bookmarks
Both True DBGrid and Microsoft ActiveX Data Objects (ADO) use bookmarks to identify records and
navigate through the database. A bookmark is a variant that uniquely identifies a particular row in a
database. As such, it is a generalization of the concept of row numbers.
Programmers who are accustomed to using row numbers to reference a record (as with dBASE
databases) may need to adjust conceptually. In a relational database, the ordinal position of a record (that
is, its row number) is irrelevant, since the total number of rows in the database or in a query result set is
generally not available. After performing certain operations such as Find, the current record moves an
unspecified number of rows forward and there is no efficient way to determine how many. To avoid
time-consuming counting operations, most relational database systems have abandoned the practice of
using row numbers and have adopted the bookmark approach.
Bookmarks are actually quite simple to use. The following are the basic rules to remember when using
bookmarks in True DBGrid and in Visual Basic:
• Each record, or row, has a unique bookmark.
• You can move to a specific record by setting the Bookmark property of either the grid or the Data
control:
TDBGrid1.Bookmark = SomeBookmark
Data1.Recordset.Bookmark = SomeBookmark
SomeBookmark is usually a bookmark you have obtained from the Data control, a clone, or a
collection of bookmarks, such as True DBGrid's SelBookmarks collection. The Bookmark property of
the grid and the Data control will always contain the bookmark of the current record.

• You navigate through the database by moving to the first or last record, or by moving relative
(next or previous) to the current bookmark:
Data1.Recordset.MoveFirst
Data1.Recordset.MoveLast
Data1.Recordset.MoveNext
Data1.Recordset.MovePrevious
• In bound mode, you generally do not know the format, or semantics, of a bookmark, so do not
attempt to read the details of a bookmark or construct a bookmark yourself. The only legitimate
operations to perform on a bookmark are saving it to a variable, assigning it to an appropriate
property or method, and comparing it to another bookmark to determine if the two are identical:
' Saving a bookmark:
Dim SomeBookmark as Variant
SomeBookmark = Data1.Recordset.Bookmark
' Assigning a bookmark:
Data1.Recordset.Bookmark = SomeBookmark
' To reliably compare bookmarks, you must first convert them
' into strings:
Dim Bk1 As String, Bk2 As String
Bk1 = SomeBookmark1
24 · The Basics

Bk2 = SomeBookmark2
If Bk1 = Bk2 Then
...
End If
Note that to reliably compare two bookmarks in Visual Basic, you must first convert them into strings as
shown in the preceding example. For more information, see Application Mode Bookmarks (page 212).
 ICursor and OLEDB Samples · 25

True DBGrid Samples

Please be advised that this ComponentOne software title is accompanied by various sample projects
and/or demos, which may or not make use of other ComponentOne development tools. While the
sample projects and/or demos included with the software are used to demonstrate and highlight the
product’s features, and how the control may be integrated with the rest of the ComponentOne product
line, some of the controls used in the demo/sample project may not be included with the purchase of
certain individual products.

ICursor and OLEDB Samples

This sample illustrates how to implement a drag-and-drop operation in the grid, how
Apptbook to interactively set the grid's color, and also how to use Unbound Extended mode.
This sample uses the TDBGrid control.

This sample illustrates a number of important points about how splits can be used
GENLEDGR effectively, and how several additional features (such as outlining and updating
unbound columns) can be used. This sample uses the TDBGrid control.

This sample illustrates how styles can be used effectively. It uses the grid's
Invntry AddRegexCellStyle method and FetchRowStyle event. This sample uses the
TDBGrid and TDBDropDown controls.

This is a small sample that shows how you can use GDI calls in grid's OwnerDraw
OwnrDraw
event. This sample uses the TDBGrid control.

This sample illustrates a number of useful database application techniques, including

TRUBRWSE how to save and reload grid layouts stored in a binary file. This sample uses the
TDBGrid control.

True DBGrid Extra Samples

Ads This sample uses the TDBGrid and TDBDropDown controls.

This sample shows how you can populate XArrayDB from an ODBC database. The
APIToX advantage is that there is no overhead of DAO, ADO or RDO. This sample uses the
TDBGrid control.

This sample dumps everything from a recordset to an XArrayDB. The difference

between this sample and the RDOToXarray is only the redimensioning of the
DAOToX
XArrayDB. With the recordset we always know how many records we have so we
can ReDim the XArrayDB up front. This sample uses the TDBGrid control.

This sample shows how you can use ODBC API to populate the list in Unbound
Odbc7
extended mode. This sample uses the TDBGrid control.

This is a small sample that shows how you can use GDI calls in grid's OwnerDraw
OwnerDraw
event. This sample uses the TDBGrid control.
26 · True DBGrid Samples

This sample dumps everything from a resultset to an XArrayDB. The advantage is

that after this is done you can disconnect from the server and all work is done locally.
RDOToX
The obvious disadvantage is the concurrency issues. This sample uses the TDBGrid
control.

This sample allows you to modify, add or delete any number of cells and then
optionally revert to the original values. Before any editing, click the BeginTrans
Transaction button. Use of transaction in this fashion is possible only in unbound mode. In bound
mode the data control will commit all pending transactions when you change rows.
This sample uses the TDBGrid control.

This sample uses Unbound 1 mode and a DBGrid to display records from a
recordset. This unbound mode is provided for compatibility with older products. New
Ub1DAO
applications should use the UnboundExtended mode. This sample uses the TDBGrid
control.

This sample shows how you can populate the grid in Unbound extended mode from
Ub2ADO
an ADO recordset. This sample uses the TDBGrid control.

This sample uses a generic data class. For small data sets you should use
Ub2ARR
DataMode 4 - Storage with XArrayDB. This sample uses the TDBGrid control.

This sample populates the list with the DAO recordset in Unbound extended mode.
Ub2DAO
This sample uses the TDBGrid control.

This sample populates the list with the RDO Resultset in Unbound extended mode.
Ub2RDO
This sample uses the TDBGrid control.
 Introduction · 27

Tutorials
Introduction
Thirty tutorials are presented in this chapter. The tutorials assume that you are familiar with
programming in Visual Basic, know what a Data control is, and know how to use the Visual Basic built-in
Data control with bound controls in general. The tutorials provide step-by-step instructions—no prior
knowledge of True DBGrid is needed. By following the steps outlined in this chapter, you will be able to
create projects demonstrating a variety of True DBGrid features, and get a good sense of what the grid
can do and how to do it.
The tutorials use an Access database, TDBGDemo.MDB. The database files TDBGDemo.MDB,
TDBGDemo.SAV, and the tutorial projects are in the TUTORIAL subdirectory of the True DBGrid
installation directory. TDBGDemo.SAV is a backup copy of TDBGDemo.MDB. If you want to restore
TDBGDemo.MDB after editing, adding, or deleting records while using the tutorials, make a new copy of
TDBGDemo.MDB from TDBGDemo.SAV.
We encourage you to run the tutorial projects in Visual Basic, examine the code, and experiment with
your own modifications. This is the best and quickest way to learn how to realize the full potential of
True DBGrid. You will find that True DBGrid is very easy to use, and it enables you to create powerful
database applications.
The tutorials assume that the database file TDBGDemo.MDB is in the C:\Program Files\ComponentOne
Studio\Common directory, and refer to it by filename instead of the full pathname for the sake of
brevity.
NOTE: Depending on where you store the projects and database files in the TUTORIAL subdirectory,
you may need to change the DatabaseName property of the Data control in the tutorial projects in order
for the projects to work properly.

Tutorial 1 - Binding True DBGrid to a Data Control

In this tutorial, you will learn how to bind True DBGrid to a Visual Basic Data control and create a fully
functional database browser without writing a single line of code. You will also learn about the basic
properties associated with the Data control and True DBGrid. You will then be able to run the program
and observe the run-time features of the grid.
1. Start a new project.
2. From the Visual Basic Project menu, select Components, then check the box labeled
ComponentOne True DBGrid Pro 8.0. Click OK to add the TDBGrid (and TDBDropDown)
control icons to the toolbox. The TDBGrid icon looks like this:

3. Place a Data control (Data1) and a True DBGrid control (TDBGrid1) on the form (Form1) as
shown in the following figure.
28 · Tutorials

4. Set the DatabaseName property of Data1 to TDBGDemo.MDB, and the RecordSource property to
Composer.
5. Set the DataSource property of TDBGrid1 to Data1.
6. Set the AllowAddNew and AllowDelete properties of TDBGrid1 to True (note that the default
value of AllowUpdate is True).
Run the program and observe the following:
• True DBGrid retrieves the database schema information from the Data control and automatically
configures itself to display all of the fields contained in the database table. Note that the field
names are used as the default column headings.
• True DBGrid automatically communicates with the Data control. Any actions taken on the Data
control will be reflected in the grid. Click the navigation buttons on the Data control to move
forward a record, back a record, to the last record, and to the first record. Note that the grid's
current record stays in sync with the Data control.
• You have created a fully functional database browser without writing a single line of code!
Refer to Run Time Interaction (page 181) and try out the instructions for navigating, editing, and
configuring the grid at run time.
To end the program, press the End button on the Visual Basic toolbar.
OLE DB support:
True DBGrid also supports OLE DB data sources such as the ADO Data Control (ADODC). The following
steps demonstrate how to create a simple database browser using the ADO Data Control.
1. Start a new project.
2. From the Visual Basic Project menu, select Components, then check the boxes labeled
ComponentOne True DBGrid Pro 8.0 (OLEDB) and Microsoft ADO Data Control (OLEDB).
Click OK to add the selected control icons to the toolbox. The TDBGrid icon looks like this:
 Tutorial 2 - Using True DBGrid with SQL Query Results · 29

3. Place an ADO Data control (Adodc1) and a True DBGrid control (TDBGrid1) on the form (Form1)
as shown in the following figure.

4. Display the custom property pages for Adodc1. Click the General tab and select the Use
Connection String option. Click Build. The "Microsoft OLE DB Provider for ODBC Drivers"
option should be highlighted. Click Next>>. Enter the datasource name (C:\Program
Files\ComponentOne Studio\Common\TDBGDEMO.MDB) in the Use Data source name text
box. You do not have to enter a user name or password. Test the connection to make sure it
works. Close the dialog window.
Click the OK button to close the property page.
5. Set the CommandType property to 2 - adCmdTable.
6. Set the RecordSource property to Composer.
7. Set the DataSource property of TDBGrid1 to Adodc1.
8. Set the AllowAddNew and AllowDelete properties of TDBGrid1 to True (note that the default
value of AllowUpdate is True).
Congratulations, you have successfully completed Tutorial 1!

Tutorial 2 - Using True DBGrid with SQL Query Results

An important feature of True DBGrid is its ability to automatically sense changes to the database at run
time. In this tutorial, you will learn how to use True DBGrid to display the results of ad-hoc SQL queries.
Note that no code is necessary to tell the grid what to do—the grid will automatically change its field
layout to match the new configuration of the query result. Also note that in order for the grid to
automatically respond to field layout changes, you must not have defined any column properties at
design time. If a layout is already defined, use the grid's Clear Fields context menu command to remove
it. This will cause the grid to configure itself automatically at run time.
1. Start a new project.
2. Place a Data control (Data1), a True DBGrid control (TDBGrid1), a command button
(Command1) and a TextBox control (Text1) on the form (Form1) as shown in this figure.
30 · Tutorials

3. Set the DatabaseName property of Data1 to TDBGDemo.MDB, and the RecordSource property to
Customer.
4. Set the DataSource property of TDBGrid1 to Data1.
5. Set the Caption property of Command1 to Execute SQL and the MultiLine control property of
Text1 to True.
6. Add the following code to Command1:
Private Sub Command1_Click()

' Execute the SQL statement in Text1, and trigger an error

' message if something goes wrong.
On Error GoTo SQLErr
Data1.RecordSource = Text1.Text
Data1.Refresh
TDBGrid1.SetFocus
Exit Sub
SQLErr:
MsgBox "Error Executing SQL Statement"
End Sub
Run the program and observe the following:
• As in Tutorial 1, True DBGrid retrieves the database schema information from the Data control
and automatically configures itself to display the data for all fields in the database table. Note
that the field names are used as the default column headings.
7. In the TextBox control, type the following SQL statement:
SELECT * FROM Customer
then press the Execute SQL command button. The grid display will not change. The above SQL
statement displays all fields from the Customer table and is equivalent to the default display.

8. In the TextBox control, type the following SQL statement:

SELECT Company FROM Customer
 Tutorial 2 - Using True DBGrid with SQL Query Results · 31

then press the Execute SQL command button. The grid responds by displaying only one column
for the Company field.

9. In the TextBox control, type the following SQL statement:

SELECT LastName, Company FROM Customer
then press the Execute SQL command button. This is similar to the previous SQL statement
except that two columns (LastName and Company) are now displayed.

10. In the TextBox control, type the following SQL statement:

SELECT Count(*) FROM Customer
then press the Execute SQL command button. The above SQL statement uses an aggregate
function, Count(*):SQL, to return the total number of records in the Customer table. Even though
the SQL result is not a set of records, the grid faithfully responds by displaying the number of
records in a single column. By default, Expr1000 is used as the column heading, indicating that
the display is the result of an expression.

To display a more meaningful heading, you can type:

SELECT Count(*) AS Count FROM Customer

The column heading will display Count instead of Expr1000.

11. In the TextBox control, type the following SQL statement:

SELECT UCase(LastName) AS ULAST, UCase(FirstName) AS UFIRST FROM
Customer
then press the Execute SQL command button. The above SQL statement produces two calculated
columns which display the LastName and FirstName fields in upper case. The grid also displays
the (assigned) calculated column names, ULAST and UFIRST, as the column headings.

12. In the TextBox control, type the following SQL statement:

SELECT * FROM Customer WHERE FirstName = "Jerry"
then press the Execute SQL command button. The above SQL statement displays only records
with FirstName equal to Jerry.

13. In the TextBox control, type the following SQL statement:

SELECT * FROM Customer ORDER BY LastName
then press the Execute SQL command button. The above SQL statement displays records in
alphabetical order according to the LastName field.

You can also use an SQL statement to join two database tables, as demonstrated in Tutorial 3
(page 32).

This concludes Tutorial 2.

32 · Tutorials

Tutorial 3 - Linking Multiple True DBGrid Controls

This tutorial demonstrates how you can link multiple True DBGrid controls using the RowColChange
event to trigger related actions. This technique is particularly useful for displaying master-detail
relationships.
1. Start a new project.
2. Place two Data controls (Data1 and Data2) and two True DBGrid controls (TDBGrid1 and
TDBGrid2) on the form (Form1) as shown in this figure.

3. Set the DatabaseName property of Data1 to TDBGDemo.MDB, the RecordSource property to

Composer, and the Caption property to Composers.
4. Set the DatabaseName property of Data2 to TDBGDemo.MDB, the RecordSource property to
Opus, and the Caption property to Their Compositions.
5. Set the DataSource properties of TDBGrid1 and TDBGrid2 to Data1 and Data2, respectively.
6. Add the following code to the RowColChange event of TDBGrid1:
Private Sub TDBGrid1_RowColChange(LastRow As Variant, ByVal
LastCol As Integer)
' A query is performed by taking the "LAST" name field from
' the Data1 control and building an SQL query on the LAST
' name field in the Data2 (compositions) file.
' The Second grid will respond automatically when the Data
' Control causes the change. We put up an hourglass so that
' there's a bit of feedback if Access is slow at finishing
' the query.
Dim lastname$
 Tutorial 4 - Interacting with Code and Other Bound Controls · 33

Dim bk1 As String, bk2 As String

' To reliably compare bookmarks, you must first convert them
' into strings. You will also need to test for Null
' Bookmarks being passed by LastRow. This will occur on the
' initial display of the grid and if the user places the
' cursor on the AddNewRow and then moves off.
If IsNull(LastRow) Then
bk1 = ""
Else
bk1 = LastRow
End If
bk2 = TDBGrid1.Bookmark
If bk1 <> bk2 Then
Screen.MousePointer = vbHourglass
lastname$ = Data1.Recordset("Last")
Data2.RecordSource = "SELECT * FROM OPUS WHERE LAST = " _
+ Chr$(34) + lastname$ + Chr$(34)
Data2.Refresh
Screen.MousePointer = vbDefault
End If
End Sub
Run the program and observe the following:
• When Form1 is loaded, TDBGrid1 and TDBGrid2 retrieve the database schema information from
Data1 and automatically configure themselves to display all of the fields in the Composer and
Opus tables, respectively.
• However, when TDBGrid1 receives focus and sets the first row as the current row, the
RowColChange event of TDBGrid1 will be fired. The RecordSource of Data2 will be modified
and TDBGrid2 will reconfigure itself to display only compositions by Isaac Albeniz. If you
observe carefully, when Form1 is first loaded, TDBGrid2 first displays all records in the Opus
table, and then refreshes itself quickly to display only one record.
• Change the current record position of Data1 by clicking on different rows of TDBGrid1. Observe
that TDBGrid2 (the detail grid) will configure itself to display a new record set every time the row
changes in TDBGrid1 (the master grid).
This concludes Tutorial 3.

Tutorial 4 - Interacting with Code and Other Bound Controls

In this tutorial, you will learn how True DBGrid interacts with other bound controls and with Visual
Basic code that manipulates the same Recordset to which the grid is bound.
1. Start a new project.
2. Place the following controls on the form (Form1) as shown in the figure: a Data control (Data1), a
True DBGrid control (TDBGrid1), a DBList control (DBList1), three text controls (Text1 to 3),
seven command buttons (Command1 to 7), and four labels (Label1 to 4).
34 · Tutorials

3. Set the DatabaseName property of Data1 to TDBGDemo.MDB, and the RecordSource property to
Customer.
4. Set the DataSource property of TDBGrid1 to Data1, and the AllowAddNew and AllowDelete
properties to True.
5. Set the DataSource and RowSource control properties of DBList1 to Data1, and the ListField
control, DataField, and BoundColumn control properties to LastName.
6. Set the DataSource properties of Text1, Text2 and Text3 to Data1, and the DataField properties to
FirstName, LastName, and Company, respectively.
7. Set the Caption properties of Label1-Label4 and Command1-Command7 as shown in the
preceding figure.
We will be using code to affect the record position and data of the database. The seven buttons on
this form will contain all of the code we use in this tutorial (the bound controls require no code).

8. Add the following code to the Update button, Command1:

Private Sub Command1_Click()
' True DBGrid will automatically respond to the
' update and will clear the "modified indicator"
' (the pencil icon) on the record selector column
' to indicate that the modified data has been written
' to the database.
Data1.Recordset.Edit
Data1.Recordset.Update
TDBGrid1.SetFocus
End Sub
 Tutorial 4 - Interacting with Code and Other Bound Controls · 35

This button triggers an immediate update of all modified data in the bound controls (the grid and
the three text controls) without moving the current row position.

9. Add the following code to the Delete button, Command2:

Private Sub Command2_Click()
' When the current record is deleted, Jet Engine leaves
' the record pointer at the deleted record. Use MoveNext
' to move the current record to the row after the deleted
' record.
Data1.Recordset.Delete
Data1.Recordset.MoveNext
' If the last record is deleted, move the current record
' to the last record
If Data1.Recordset.EOF = True Then
Data1.Recordset.MoveLast
End If
TDBGrid1.SetFocus
End Sub
When the current record is deleted from code, the Data control leaves the record pointer at the
deleted record. Therefore, the preceding code uses the MoveNext method of the Recordset to
move the current record to the row after the deleted record.

10. Add the following code to the AddNew button, Command3:

Private Sub Command3_Click()
' This "Add New" button moves the cursor to the
' "new (blank) row" at the end so that user can start
' adding data to the new record.
' Move to last record so that "new row" will be visible
Data1.Recordset.MoveLast
' Move the cursor to the "addnew row"
TDBGrid1.Row = TDBGrid1.Row + 1
TDBGrid1.SetFocus
End Sub
The above code demonstrates how to move the current cell to the new (blank) row at the end so
that the user can start adding data to the new record.

11. Add the following code to the First button, Command4:

Private Sub Command4_Click()
' True DBGrid will follow the record movement.
Data1.Recordset.MoveFirst
TDBGrid1.SetFocus
End Sub
This button positions the record pointer to the first record in the Recordset.

12. Add the following code to the Next button, Command5:

Private Sub Command5_Click()
' True DBGrid will follow the record movement.
Data1.Recordset.MoveNext
36 · Tutorials

' Keep the record away from EOF which is not

' a valid position
If Data1.Recordset.EOF = True Then
Data1.Recordset.MovePrevious
End If
TDBGrid1.SetFocus
End Sub
This button moves the current row to the next record.

13. Add the following code to the Previous button, Command6:

Private Sub Command6_Click()
' True DBGrid will follow the record movement.
Data1.Recordset.MovePrevious
' Keep the record away from BOF which is not
' a valid position
If Data1.Recordset.BOF = True Then
Data1.Recordset.MoveNext
End If
TDBGrid1.SetFocus
End Sub
This button moves the current row to the previous record.

14. Add the following code to the Last button, Command7:

Private Sub Command7_Click()
' True DBGrid will follow the record movement.
Data1.Recordset.MoveLast
TDBGrid1.SetFocus
End Sub
This button positions the record pointer to the last record in the Recordset.

Run the program and observe the following:

• Use the mouse or the keyboard to change the current row position in the grid, and observe the
other bound controls (DBList and Text) changing their record positions along with the grid, even
though they contain no code.
• Click the Next, Previous, Last, and First buttons of the Data control and observe that the record
positions on all bound controls are automatically synchronized.
• Click the Next, Previous, Last, and First command buttons and observe that they have the same
effects as the corresponding buttons on the Data control.
• Modify data in a few cells (in the same row) on the grid. Press the Update command button.
Observe that the modified data has been updated to the database and the pencil icon on the
record selector column disappears. Other bound controls on the form now display the modified
data.
• Modify data in one or more of the Text controls. Press the Update or the Next command button.
The grid will automatically update its data to reflect the new changes.
• Move the current cell of the grid to any record you wish to delete, then click the Delete command
button. The record will be deleted and disappears from the grid. The grid automatically moves
 Tutorial 5 - Selecting Multiple Rows Using Bookmarks · 37

the current row to the record after the deleted record. Other bound controls on the form also
respond by moving their record positions.
This concludes Tutorial 4.

Tutorial 5 - Selecting Multiple Rows Using Bookmarks

In this tutorial, you will learn how to select and highlight records that satisfy specified criteria. A group
of similar items is generally implemented as a collection in True DBGrid. When manipulating a group of
items in True DBGrid, use techniques similar to those described here. In this case, a row or record is
represented by a bookmark and a group of selected rows is represented by a SelBookmarks collection.
To make the project a bit more interesting, when setting up the RecordSource property of the Data
control, you will also learn how to use an SQL statement to create a join between two tables in a database.
1. Start a new project.
2. Place the following controls on the form (Form1) as shown in the figure: a Data control (Data1), a
True DBGrid control (TDBGrid1), and two command buttons (Command1 and Command2).

3. Set the DatabaseName property of Data1 to TDBGDemo.MDB, and the RecordSource property to
the following SQL statement:
SELECT * FROM composer, opus, composer INNER JOIN opus ON composer.last
= opus.last
This will create a Recordset containing all records from Composer joined with Opus having the
same values of the data field Last.

4. Set the DataSource properties of TDBGrid1 to Data1.

5. Set the Caption properties of Command1 and Command2 to Select and Clear, respectively.
6. We can easily select and deselect rows in True DBGrid by manipulating the SelBookmarks
collection. To select rows, place the following code in the Click event of Command1:
Private Sub Command1_Click()
' This routine loops through the Recordset to find and
' highlight all records with Country = "Germany"
' We shall use a clone so that we do not move the actual
38 · Tutorials

' record position of the Data control

Dim dclone As Recordset
Set dclone = Data1.Recordset.Clone()
' In case there is a large Recordset to search through
Screen.MousePointer = vbHourglass
' For each matching record, add the bookmark to the
' SelBookmarks collection of the grid. The grid will
' highlight the corresponding rows. Note that the bookmarks
' of a clone are compatible with the original set.
' This is ONLY true of clones.
Dim SelBks As TrueDBGrid80.SelBookmarks
Set SelBks = TDBGrid1.SelBookmarks
Dim Criteria$
Criteria$ = "Country = 'Germany'"
dclone.FindFirst Criteria$
While Not dclone.NoMatch
SelBks.Add dclone.Bookmark
dclone.FindNext Criteria$
Wend
' Restore regular mouse pointer
Screen.MousePointer = vbDefault
End Sub
7. To deselect rows, place the following code in the Click event of Command2:
Private Sub Command2_Click()
' Clear all selected rows by removing the selected records
' from the SelBookmarks collection.

Dim SelBks As TrueDBGrid80.SelBookmarks

Set SelBks = TDBGrid1.SelBookmarks

While SelBks.Count <> 0

SelBks.Remove 0
Wend
End Sub
Run the program and observe the following:
• TDBGrid1 retrieves the database schema information from the Data control and automatically
configures itself to display all of the fields in the joined database tables. This is again similar to
the behavior of the grid in Tutorial 1.
• Click the Select command button and observe that all records with the Country field equal to
Germany will be highlighted.
• To deselect the highlighted records, click the Clear command button. Alternatively, clicking
anywhere on a grid cell will also clear the selected rows.
This concludes Tutorial 5.

Tutorial 6 - Defining Unbound Columns in a Bound Grid

In this tutorial, you will learn how to use the UnboundColumnFetch event to display two fields
(FirstName and LastName) together in one column. You will also learn how to use an SQL statement to
create a join between two tables in a database. The project we set up for this tutorial will also be used in
Tutorials 7 through 12.
 Tutorial 6 - Defining Unbound Columns in a Bound Grid · 39

1. Start a new project.

2. Place a Data control (Data1) and a True DBGrid control (TDBGrid1) on the form (Form1).
3. Set the DatabaseName property of Data1 to TDBGDemo.MDB, and the RecordSource property to
the following SQL statement:
SELECT * FROM Contacts INNER JOIN Customers ON Contacts.UserCode =
Customers.UserCode
The Contacts table contains records of recent customer contacts, but in the table, the customers
contacted are recorded by their internal UserCode only, making the table difficult to use by itself.
The Customers table contains customer data such as UserCode, FirstName, LastName, and so
forth. Therefore, we create a join so that we can view the recent contact information along with
the corresponding customer data.

4. Set the Caption property of Data1 to Customer Contact.

5. Set the DataSource property of TDBGrid1 to Data1.
Configuring the grid at design time
We shall configure the grid using its context menus and property pages. For more details, see Design
Time Interaction (page 129).
6. Right-click the grid to display its context menu.
7. Choose Edit from the context menu. The grid will enter its visual editing mode, enabling you to
interactively change the grid's row and column layout.
8. By default, the grid contains two columns. We are going to create three more. Right-click
anywhere in the grid to display the visual editing menu. Choose the Append command to add a
new column at the end of the grid. Execute this command two more times to create two more
columns. A total of five columns are now in the grid.
9. Right-click again to display the visual editing menu. This time choose Properties… to display the
Property Pages dialog. Select the Columns property page by clicking the Columns tab. The tree
node Columns(00) is selected. Double-click the selection or click the + to the left of Columns(00).
The tree will expand to reveal the available properties for the first column, Column0, which you
will configure as an unbound column. Select the Caption property, then type Customer Name into
the text box on the right side of the page. Keep the default values for the other properties,
including DataField. If the DataField property of a column is blank (that is, equal to an empty
string), but its Caption property is not, True DBGrid considers it an unbound column.
10. Click the – to the left of Columns(00) to close this branch, then open the Columns(01) object. Click
the DataField property to reveal a list of all the fields in the joined table. Choose CustType (the
last item) from the list. The Caption property will default to the same name.
11. Repeat the previous step with the remaining three columns. Columns(02): DataField =
ContactType, Column(03): DataField = Callback, Columns(04): DataField = ContactDate.
12. After configuring the five columns, click the OK button at the bottom of the property page dialog
to accept the changes.
13. Note that you are still in the grid's visual editing mode. Place the mouse cursor over the column
dividers within the column header area. It will turn into a horizontal double-arrow cursor,
indicating that column resizing can now occur. Drag the dividers (use the horizontal scroll bar to
bring a column into view if necessary) so that the grid looks like the one in the following figure.
40 · Tutorials

Notice that there is a gray area between the rightmost column (Contact Date) and the right edge
of the grid. We can eliminate this gray area by setting the ExtendRightColumn property to True.

14. Open the Property Pages dialog again as in step 9. This time, select the Splits property page by
clicking the Splits tab. Expand the Splits(00) object and double-click the ExtendRightColumn
node to toggle its value. Accept the change by clicking the Apply button, which is used to
commit changes without closing the dialog. The rightmost column is now extended to the right
edge of the grid, which now looks like this (move the Property Pages dialog to observe if
necessary).

By default, the grid has one split. Although you have not created any additional splits, you are
still working with the properties of the default split. The ExtendRightColumn property is on the
Splits property page because each split in the grid can have a different value for this property.
Properties such as this are referred to as split-specific properties.

15. Scroll down to the MarqueeStyle property and select 2 - Highlight Cell. For more information on
this property, see Highlighting the Current Row or Cell (page 254).
16. Click the OK button at the bottom of the property page dialog to accept the changes. You have
now finished configuring the grid.
 Tutorial 6 - Defining Unbound Columns in a Bound Grid · 41

Displaying data in the unbound column

In step 9, Column0 of the grid was configured as an unbound column, so you must supply its
data using the UnboundColumnFetch event. When the grid needs to display data in an unbound
column, it fires this event to get the necessary data. The following code shows how to display the
combined FirstName and LastName fields in the unbound column. For more information, see
Unbound Columns (page 198).

17. Declare RSClone as a RecordSet in the General section of Form1 so that the RSClone variable will
be available in all procedures in Form1:
Dim RSClone As Recordset
18. In the Form_Load event, set RSClone to be a clone of Data1.Recordset. The Data1.Refresh
statement is necessary to make sure Data1 is initialized before cloning its RecordSet.
Private Sub Form_Load()
Data1.Refresh
Set RSClone = Data1.Recordset.Clone()
End Sub
19. Finally, define data in the unbound column by combining the FirstName and LastName fields of
the RecordSet in the grid's UnboundColumnFetch event:
Private Sub TDBGrid1_UnboundColumnFetch( _
Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
RSClone.Bookmark = Bookmark
Value = RSClone("FirstName") & " " & RSClone("LastName")
End Sub
When the UnboundColumnFetch event is called, the Bookmark argument specifies which row of
data is being requested by the grid. Note that Bookmark does not usually refer to the current row,
since the grid displays more than one row at a time. Hence we use a clone (RSClone) to get data
from the RecordSet so that we do not change the current row position of the Data control. In this
example, we only have one unbound column, so we ignore the Col argument.

Run the program and observe the following:

• TDBGrid1 displays data from the joined table according to the five columns configured at design
time.
• The first column displays the combined FirstName and LastName fields as defined in the
UnboundColumnFetch event.
• Since the MarqueeStyle is 2 - Highlight Cell, the entire cell is highlighted (not just the cell text)
and there is no blinking cursor—the cell is not in edit-ready mode. If you click the current cell, it
will enter edit mode with the blinking text cursor (caret) appearing at the beginning of the cell's
contents. You can also initiate editing simply by typing, in which case the current cell contents
will be replaced by what you type.
• NOTE: The default MarqueeStyle is 6 - Floating Editor. The floating editor highlights the cell text
(not the entire cell) as does the datasheet in Microsoft Access. The cell is in edit-ready mode with a
blinking caret present at the beginning of the highlighted text. In this mode, you can click
anywhere within the floating editor to position the insertion point.
• The CustType, ContactType and Callback columns display numeric values which are quite
cryptic to users. You might also comment that the data presentation is not so appealing. In the
42 · Tutorials

next three tutorials (7, 8, and 9), we will illustrate techniques to improve both the display and the
user interface.
This concludes Tutorial 6.

Tutorial 7 - Displaying Translated Data with the Built-in Combo

In this tutorial, you will learn how to use the ValueItems collection to display translated text and enable
the grid's built-in drop-down combo for editing—all without writing a single line of code.
1. Start with the project created in Tutorial 6 (page 38.)
2. Right-click TDBGrid1 to display its context menu.
3. Choose Properties… to display the Property Pages dialog. Select the Values property page by
clicking the Values tab. This property page is used to specify the ValueItems collection
associated with a column.
4. Drop down the Column combo box and select Column1 (CustType).
5. Check the Translate box to instruct the grid to translate the data in Column1 before displaying it.
Note that the grid at the bottom of the property page now displays two columns labeled Value
and DisplayValue.
6. Drop down the Presentation combo box and select 2 - Combo Box. This instructs the grid to
display a combo box in Column1 when requested.
7. Now enter the Value - DisplayValue pairs in the grid as follows:
Value Display Value
1 Prospective
2 Normal
3 Buyer
4 Distributor
5 Other
Entries in the Value column are data values from the CustType field in the database table. The
grid treats the Value property as a string. Entries in the DisplayValue column are translated
values to be displayed in the CustType column of the grid. For example, a CustType of 1 will be
displayed as Prospective, 2 will be displayed as Normal, and so forth.

NOTE: Some databases store numbers with a leading space character to hold the place of a minus
sign, so it may be necessary to prefix Value column entries with a space.

When you are finished entering data, the Values property page should look like this.
 Tutorial 7 - Displaying Translated Data with the Built-in Combo · 43

8. Click the OK button at the bottom of the Property Pages dialog to accept the changes.
Run the program and observe the following:
• TDBGrid1 displays data from the joined tables as in Tutorial 6.
• The CustType column now displays the translated text instead of numeric values.
• Click a cell in the CustType column to make it the current cell. Notice that a dropdown button
appears at the right edge of the cell.
• Click the dropdown button or press ALT+DOWN ARROW to display the built-in combo box
containing translated values, as shown in the following figure. You can change the data in the
current cell by selecting the desired item from the combo box.
44 · Tutorials

This concludes Tutorial 7.

Tutorial 8 - Attaching a True DBDropDown Control to a Grid Cell

In this tutorial, you will learn how to attach a multicolumn True DBDropDown control to a grid cell.
Unlike the built-in combo demonstrated in Tutorial 7 (page 42, )the TDBDropDown control can be
bound to a Data control, which makes it ideal for data entry involving a secondary lookup table. The
drop-down control appears whenever the user clicks a button within the current cell. This button appears
automatically when the user gives focus to a column that has a drop-down control connected to it.
1. Start with the project constructed in Tutorial 6 (page 38.)
2. Add a True DBDropDown control (TDBDropDown1) and another Data control (Data2) to the
form (Form1) as shown in the figure:

3. Set the DatabaseName property of Data2 to TDBGDemo.MDB, the RecordSource property to

CustType, and the Visible property to False.
4. Set the DataSource property of True DBDropDown to Data2, and the ListField property to
TypeId.
 Tutorial 8 - Attaching a True DBDropDown Control to a Grid Cell · 45

5. In the Columns property page of TDBGrid1, set the DropDown property of the CustType
column to TDBDropDown1.
Modifying the True DBDropDown control
6. Right-click the True DBDropDown control to display its context menu.
7. Choose Edit to enter visual editing mode just as you would with a True DBGrid control. You can
now interactively change the drop-down control's column layout.
8. Resize the first column so that it is approximately 3/8 of an inch wide.
9. Choose Properties… from the visual editing menu to display the Property Pages dialog for the
True DBDropDown control.
10. In the General property page, check ColumnHeaders and IntegralHeight. Clear AllowColMove,
AllowColSelect, and AllowRowSizing. Set the ScrollBars property to 2 - Vertical. The
IntegralHeight property is only supported by the TDBDropDown control. When set to True, it
prevents the drop-down control from displaying partial rows.
11. In the Columns property page, set the DataField property for Column0 to TypeId and the
DataField property for Column1 to TypeDesc.
12. Set the Caption properties for Column0 and Column1 to Type and Description. The form should
now appear as follows.

Run the program and observe the following:

• TDBGrid1 displays data from the joined table as in Tutorial 6 (page 38.)
• Click a cell in the CustType column to make it the current cell as indicated by the highlight. A
button will be displayed at the right edge of the cell. Click the button to display the True
DBDropDown control as shown in the following figure.
46 · Tutorials

• You can use the UP ARROW and DOWN ARROW keys to move the highlight bar of True
DBDropDown. If you click another cell in the grid, True DBDropDown will lose focus and
become invisible.
• Select any item in True DBDropDown. The current cell in the grid will be updated with the
selected item, and True DBDropDown will disappear until you initiate editing again.
• If you move the current cell to another column, the button will disappear from the cell in the
CustType column.
This concludes Tutorial 8.

Tutorial 9 - Attaching an Arbitrary Drop-down Control to a Grid Cell

In this tutorial, you will learn how to drop down an arbitrary control from a grid cell. This example uses a
ListBox control containing pre-defined input values in order to facilitate user data entry. The list will
drop down whenever the user initiates editing, such as by clicking the current cell. You will also learn
how to place a button in the cell which, when clicked, will cause the ListBox control to appear. You can
drop down any control from a grid cell using techniques similar to those described in this tutorial.
1. Start with the project constructed in Tutorial 6 (page 38.)
2. Add a ListBox control (List1) to the form (Form1) as shown in the figure.
 Tutorial 9 - Attaching an Arbitrary Drop-down Control to a Grid Cell · 47

3. Set the Visible property of List1 to False.

Adding code to drop down a ListBox control
The CustType field in the second column (Column1) of the grid displays numeric values ranging from 1
through 5 which represent the following customer types:
1 = Prospective
2 = Normal
3 = Buyer
4 = Distributor
5 = Other

We shall drop down List1, which will contain textual customer type descriptions, and allow users to
double-click an item in order to enter the associated value into the grid.
4. In the Form_Load event, we place code to add the customer types to List1. We also place a button
in the CustType column using the Button property. The Form_Load event handler now looks like
this:
Private Sub Form_Load()
' Define RSClone as a clone
Data1.Refresh
Set RSClone = Data1.Recordset.Clone()
' Add customer types to List1
List1.AddItem "Prospective"
List1.AddItem "Normal"
List1.AddItem "Buyer"
List1.AddItem "Distributor"
List1.AddItem "Other"
' Place a button in the CustType column
TDBGrid1.Columns("CustType").Button = True
End Sub
5. If a cell in the CustType column becomes current, a button will be placed at the right edge of the
cell. Clicking the button will trigger the grid's ButtonClick event. We will drop down List1
whenever the button is clicked:
Private Sub TDBGrid1_ButtonClick(ByVal ColIndex As Integer)
' Assign the Column object to Co because it will be used
' more than once.
48 · Tutorials

Dim Co As Column
Set Co = TDBGrid1.Columns(ColIndex)
' Position and drop down List1 at the right edge of the
' current cell.
List1.Left = TDBGrid1.Left + Co.Left + Co.Width
List1.Top = TDBGrid1.Top + TDBGrid1.RowTop(TDBGrid1.Row)
List1.Visible = True
List1.ZOrder 0
List1.SetFocus
End Sub
6. In the grid's BeforeColEdit event, we add the following code to drop down List1 if we are editing
the CustType column (Column1). Note that the code below will not work if the MarqueeStyle
property is set to 6 - Floating Editor. See Highlighting the Current Row or Cell (page 254) for more
details.
Private Sub TDBGrid1_BeforeColEdit( _
ByVal ColIndex As Integer, _
ByVal KeyAscii As Integer, Cancel As Integer)
' BeforeColEdit is called before the grid enters into
' edit mode. You can decide what happens and whether
' standard editing proceeds. This allows you to
' substitute different kinds of editing for the current
' cell, as is done here.
If ColIndex = 1 Then
' Let the user edit by entering a key.
If KeyAscii <> 0 Then Exit Sub
' Otherwise, cancel built-in editing and call the
' ButtonClick event to drop down List1.
Cancel = True
TDBGrid1_ButtonClick (ColIndex)
End If
End Sub
7. We allow the user to enter data into the CustType column of the grid by double-clicking the
desired selection in List1:
Private List1_DblClick()
' When an item is selected in List1, copy its index to
' the proper column in TDBGrid1, then make List1
' invisible.
TDBGrid1.Columns(1).Text = List1.ListIndex + 1
List1.Visible = False
End Sub
8. Finally, we make List1 invisible whenever it loses focus or when the user scrolls the grid:
Private Sub List1_LostFocus()
' Hide the list if it loses focus.
List1.Visible = False
End Sub

Private Sub TDBGrid1_Scroll(Cancel As Integer)

' Hide the list if we scroll.
List1.Visible = False
End Sub
Run the program and observe the following:
• TDBGrid1 displays data from the joined table as in Tutorial 6 (page 38.)
 Tutorial 10 - Enhancing the User Interface with In-Cell Bitmaps · 49

• Click a cell in the CustType column to make it the current cell as indicated by the highlight. A
button will be displayed at the right edge of the cell. Click the button to fire the ButtonClick
event. List1 will drop down at the right edge of the cell as shown in the following illustration.

• You can use the mouse or the UP ARROW and DOWN ARROW keys to move the highlight bar of
List1. If you click another cell in the grid, List1 will lose focus and become invisible.
• Double-click any item in List1. The current cell in the grid will be updated with the selected item,
and List1 will disappear until you initiate editing again.
• If you move the current cell to another column, the button will disappear from the cell in the
CustType column.
• Make a cell in the CustType column current again. This time, instead of clicking the button, click
the text area of the current cell to put it in edit mode. Before the grid enters edit mode, it fires the
BeforeColEdit event, and List1 appears at the right edge of the current cell as if you had clicked
the in-cell button. You can use the list to select an item for data entry as in the previous steps.
This concludes Tutorial 9.

Tutorial 10 - Enhancing the User Interface with In-Cell Bitmaps

In this tutorial, you will learn how to use the ValueItems collection to display bitmaps and check boxes in
a cell—without writing a single line of code!
1. Start with the project used in Tutorial 7 (page 42.)
2. First, we will change the captions of the ContactType and Callback columns. Right-click
TDBGrid1 to display its context menu.
3. Choose Properties… to display the Property Pages dialog. Select the Columns property page by
clicking the Columns tab. Expand the ContactType column and change its Caption property from
ContactType to How. Repeat with the Callback column, changing its Caption property from
Callback to Call?
4. Change the Alignment property of these two columns so that the bitmaps will be centered within
each cell. Click the Splits tab and expand the Splits(00) object, its Columns collection, and the
How column. Select the column's Alignment property and change it to 2 – Center. Repeat this
step with the Call? Column.
50 · Tutorials

5. Select the Style Factory property page by clicking the Style Factory tab. Expand the Normal style
and change its VerticalAlignment property from 0 - Top to 2 - Vertical Center. This will ensure
that the text and pictures are vertically centered in each row.
6. Next, we assign bitmaps and check boxes to selected columns by populating the corresponding
ValueItems collection. Select the Values property page by clicking the Values tab.
7. Drop down the Column combo box and select Column2 (ContactType). Check the Translate box
to instruct the grid to translate the data in Column2 before displaying it. Note that the grid at the
bottom of the page now displays two columns labeled Value and DisplayValue. The Value column
is for data values from the database. The DisplayValue column is for translated values you want
the grid to display.
8. Check the CycleOnClick box so that when you click a cell in Column2 at run time, the cell will
automatically cycle through all the values defined in the Value - DisplayValue table.
9. The possible values of the ContactType field are 0, 1, and 2, which represent telephone, mail, and
personal contact, respectively. We shall display bitmaps in the cell instead of these numeric
values. If you installed the full product, you will find the following files in the BITMAPS
subdirectory of the True DBGrid installation directory: PHONE.BMP, MAIL.BMP, and
PERSON.BMP.
Click the first row within the Value column and enter 0 as the first value. Click the same row
within the DisplayValue column to enable the Picture… button on the right. Click this button to
show an open file dialog. To associate a bitmap with the value 0, choose PHONE.BMP and click
the dialog's OK button to accept the selection. The phone bitmap will then appear in the
DisplayValue column. Repeat this step with the following values and bitmaps:

Value DisplayValue
1 MAIL.BMP
2 PERSON.BMP
10. After defining the bitmap entries for Column2 (ContactType), open the Column combo box again
and select Column3 (Callback). This column contains a boolean field with allowable values of 0
and -1 (False and True), which in this case represent whether a call needs to be returned. We shall
display check boxes instead of boolean values.
11. Drop down the Presentation combo box and select 4 – Check Box. True DBGrid will automatically
translate 0 and –1 to a check box.
12. Click the OK button at the bottom of the Property Pages dialog to accept the changes. You should
see the column captions on the grid modified according to the changes you made in step 3.
13. Display the primary context menu again as in step 2, but this time choose the Edit option to enter
the grid's visual editing mode, which enables you to interactively change the grid's row height
and column layout.
14. Place the mouse cursor over a column divider in the column header area, changing it to a
horizontal double-arrow resizing cursor. Drag the divider to the left to shorten the How and Call?
columns.
15. Now place the mouse cursor over the row divider, changing it to a vertical double-arrow resizing
cursor. Drag the divider downward to increase the row size to about double the current height.
16. Click Form1 anywhere outside TDBGrid1 to exit visual editing mode. You have now completed
reconfiguring the grid, which should look like the figure below.
 Tutorial 11 - Using Styles to Highlight Related Data · 51

Run the program and observe the following:

• TDBGrid1 displays data from the joined table as in Tutorials 10 through 11.
• The How and Call? columns now display bitmaps instead of numeric values as shown in the
following figure.

• Click a cell in the How column to make it the current cell. Then click it again several times and
observe how the cell cycles through the PHONE, MAIL, and PERSON bitmaps.
• Click a cell in the Call? Column and observe how the cell cycles through the check box bitmaps.
This concludes Tutorial 10.

Tutorial 11 - Using Styles to Highlight Related Data

In this tutorial, you will learn how to change the grid's display to highlight rows by defining new styles at
run time. True DBGrid uses Style objects to apply font and color characteristics to rows, columns, and
individual cells.
1. Start with the project used in Tutorial 10 (page 49.)
52 · Tutorials

2. Add a control array of three command buttons to the form. Change the captions of Command1(0)
to Prospective Customers, Command1(1) to Distributors, and Command1(2) to Reset the Grid so that
the form appears as follows.

3. Add the following declarations to the General section of Form1:

Dim ButtonFlag As Integer
Dim Prospective As New TrueDBGrid80.Style
Dim Distributors As New TrueDBGrid80.Style
4. Enter the following code in the Click (Visual Basic) event of Command1:
Private Sub Command1_Click(Index As Integer)
Select Case Index
Case 0
ButtonFlag = 0
TDBGrid1.FetchRowStyle = True
Case 1
ButtonFlag = 1
TDBGrid1.FetchRowStyle = True
Case 2
TDBGrid1.FetchRowStyle = False
End Select
TDBGrid1.Refresh
End Sub
5. Enter the following code in the Form_Load event:
Private Sub Form_Load()
Set Prospective = TDBGrid1.Styles.Add("Prospective")
Prospective.Font.Italic = True
Prospective.Font.Bold = True
Prospective.ForeColor = vbBlue
Set Distributors = TDBGrid1.Styles.Add("Distributors")
Distributors.BackColor = vbRed
Distributors.ForeColor = vbWhite
End Sub
6. Enter the following code in the FetchRowStyle event of TDBGrid1:
RSClone.Bookmark = Bookmark
 Tutorial 11 - Using Styles to Highlight Related Data · 53

If ButtonFlag = 0 And RSClone("CustType").Value = 1 Then

RowStyle = Prospective
End If
If ButtonFlag = 1 And RSClone("CustType").Value = 4 Then
RowStyle = Distributors
End If
Run the program and observe the following:
• TDBGrid1 displays data as in Tutorial 10 (page 49.)
• Click the Prospective Customers button. The grid should appear as follows.

• Click the Distributors button. The grid should now appear as follows:

• Finally, click the Reset the Grid button. The grid should now appear as follows.
54 · Tutorials

This concludes Tutorial 11.

Tutorial 12 - Displaying Rows in Alternating Colors

In this tutorial, you will learn how to use the AlternatingRowStyle property and built-in styles to apply
alternating colors to grid rows to improve their readability.
1. Start with the project used in Tutorial 10 (page 49.)
2. Right-click the grid and select Properties… from the context menu to display the Property Pages
dialog. Click the Splits tab and expand the Splits(00) object. Double-click the
AlternatingRowStyle node to toggle its value.
 Tutorial 12 - Displaying Rows in Alternating Colors · 55

The grid has default settings for both the EvenRow and OddRow styles. We will use the default settings
first and then change the settings for the EvenRow style.
Run the program and observe the following:
• TDBGrid1 displays data as in Tutorial 10 (page 49, )except that even-numbered rows have a light
cyan background.

3. Right-click the grid and select Properties… from the context menu to display the Property Pages
dialog. Click the Style Factory tab and expand the EvenRow style.
4. Next, select the BackColor property of the EvenRow style and change it from Cyan to Light Gray.
Click OK to close the property page.
Run the program and observe the following:
• TDBGrid1 displays data as in the previous figure, except that even-numbered rows now have a
light gray background.

This concludes Tutorial 12.

56 · Tutorials

Tutorial 13 - Implementing Drag-and-Drop in True DBGrid

This tutorial demonstrates how you can use the drag-and-drop features of True DBGrid to drag data
from one grid and drop it into another.
1. Start a new project.
2. Place two Data controls (Data1 and Data2), two True DBGrid controls (TDBGrid1 and
TDBGGrid2), and two Labels (Label1 and Label2) on the form (Form1) as shown in this figure:

3. Set the DatabaseName property of Data1 and Data2 to TDBGDemo.MDB, the RecordSource
property of Data1 to Customers, and the RecordSource property of Data2 to CallList.
4. Set the DataSource property of TDBGrid1 to Data1, and the DataSource property of TDBGrid2 to
Data2.
5. Set the DragIcon property of TDBGrid1 to ARW09LT.ICO, which can be found in the BITMAPS
subdirectory of the True DBGrid installation directory, or in the ICONS\ARROWS subdirectory
of the Visual Basic installation directory.
6. Set the Visible property of Data2 to False.
7. Set the Caption property of Label1 to Drag from here: and the Caption property of Label2 to To
here:.
Configuring the grids at design time
We shall configure TDBGrid1 and TDBGrid2 at design time using techniques described in previous
tutorials. We will only briefly outline the steps below. If you are not familiar with the basic techniques,
please refer to Tutorial 6 (page 38 )and Design Time Interaction (page 129) before continuing.
8. Right-click TDBGrid1 to display its context menu. Choose Retrieve Fields to configure
TDBGrid1's layout to the RecordSet defined by the RecordSource property of Data1.
 Tutorial 13 - Implementing Drag-and-Drop in True DBGrid · 57

9. Right-click TDBGrid1 again to display its context menu. This time choose Edit to enter the grid's
visual editing mode.
10. Use the visual editing menu to delete the following columns from TDBGrid1: UserCode, Contacted,
and CustType. To delete a column, first select it by clicking its header, then right-click the grid to
display the visual editing menu, then select Delete from the menu.
11. Adjust the column widths of the grid (by dragging the column dividers in the column header
area) so that all columns will fit within the grid's display area.
12. Right-click the grid to display the visual editing menu and choose Properties… to display the
Property Pages dialog. On the Splits page, expand Splits(00) and set the MarqueeStyle property
to 1 - Solid Cell Border. On the Columns page, expand Column3 (Phone) and select its
NumberFormat node. Type (###)###-#### into the combo box labeled Selection or String. The
grid's NumberFormat property provides the same functionality as Visual Basic's Format
function.
13. Repeat steps 8, 9, and 11 with TDBGrid2. Omit step 10 since we want to keep all three columns
(Customer, Phone, and CallDate) in the grid.
14. Right-click the grid to display the visual editing menu and choose Properties… to display the
Property Pages dialog. On the Splits page, expand Splits(00) and set the MarqueeStyle property
to 1 - Solid Cell Border. On the Columns page, expand Column1 (Phone) and set the
NumberFormat property to (###)###-#### as in step 12. Then expand Column2 (CallDate) and
set the NumberFormat property to MM/DD HH:NNa/p.
15. Click the OK button at the bottom of the Property Pages dialog to accept the changes. The grids
on your form should now look like this.

If you choose, you can also set the ExtendRightColumn property of both grids to True (on the
Splits property page) to eliminate the gray area between the rightmost column and the grid's
right border.
58 · Tutorials

Adding code to your project

This section describes the code needed to drag the contents of a cell or row from TDBGrid1 to TDBGrid2.
The code assumes that if you drag from the Phone column, you want to drag only the phone number data
to another cell in TDBGrid2. If you drag from any other column, however, the code assumes that you
want to drag the entire row of data to TDBGrid2 in order to add a new record there.
16. Add the following subroutine to your project to reset the MarqueeStyle property of each grid,
which is used to provide visual feedback while dragging is in progress. The reset routine will be
called to perform clean-up after a drag-and-drop operation concludes.
Private Sub ResetDragDrop()
' Turn off drag-and-drop by resetting the highlight and data
' control caption.
If TDBGrid1.MarqueeStyle = dbgSolidCellBorder Then Exit Sub
TDBGrid1.MarqueeStyle = dbgSolidCellBorder
TDBGrid2.MarqueeStyle = dbgSolidCellBorder
Data1.Caption = "Drag a row, or just phone #"
End Sub
17. The DragCell event is fired when dragging is initiated in a grid cell. The following code prepares
for dragging data from the cell:
Private Sub TDBGrid1_DragCell(ByVal SplitIndex As Integer, _
RowBookmark As Variant, ByVal ColIndex As Integer)
' DragCell is triggered when True DBGrid detects an attempt
' to drag data from a cell.

' Set the current cell to the one being dragged.

TDBGrid1.Col = ColIndex
TDBGrid1.Bookmark = RowBookmark
' See if the starting cell is in the "Phone" column
Select Case TDBGrid1.Columns(ColIndex).Caption
Case "Phone"
' Highlight the phone number cell to indicate data
' from the cell is being dragged.
TDBGrid1.MarqueeStyle = dbgHighlightCell
Data1.Caption = "Dragging phone number..."
Case Else
' Highlight the entire row to indicate data from the
' entire row is being dragged.
TDBGrid1.MarqueeStyle = dbgHighlightRow
Data1.Caption = "Create new call when dropped..."
End Select

' Use Visual Basic manual drag support

TDBGrid1.Drag vbBeginDrag
End Sub
18. The following code provides different visual feedback to the user when dragging over TDBGrid2:
Private Sub TDBGrid2_DragOver(Source As Control, _
X As Single, Y As Single, State As Integer)
' DragOver provides different visual feedback as we are
' dragging a row, or just the phone number.

Dim dragFrom As String

Dim overCol As Integer
Dim overRow As Long
dragFrom = TDBGrid1.Columns(TDBGrid1.Col).DataField

Select Case State

 Tutorial 13 - Implementing Drag-and-Drop in True DBGrid · 59

Case vbEnter
If dragFrom = "Phone" Then
TDBGrid2.MarqueeStyle = dbgHighlightCell
Else
TDBGrid2.MarqueeStyle = dbgNoMarquee
End If
Case vbLeave
TDBGrid2.MarqueeStyle = dbgHighlightCell
Case vbOver
If dragFrom = "Phone" Then
overCol = 1
Else
overCol = TDBGrid2.ColContaining(X)
End If
overRow = TDBGrid2.RowContaining(Y)
If overCol >= 0 Then TDBGrid2.Col = overCol
If overRow >= 0 Then TDBGrid2.Row = overRow
End Select
End Sub
19. When data is dropped on TDBGrid2, we either update the Phone column of TDBGrid2 or add a
new record:
Private Sub TDBGrid2_DragDrop(Source As Control, _
X As Single, Y As Single)
' Allow phone drops right into the cell, other
' drops cause a new row to be added
If TDBGrid1.Columns(TDBGrid1.Col).Caption = "Phone" Then
TDBGrid2.Columns(TDBGrid2.Col).Value = _
TDBGrid1.Columns(TDBGrid1.Col).Value
Data2.UpdateRecord
Else
Data2.Recordset.AddNew
Data2.Recordset!CallDate = Now
Data2.Recordset!Phone = Data1.Recordset!Phone
Data2.Recordset!Customer = Data1.Recordset!FirstName & _
" " & Data1.Recordset!LastName & ", " & _
Data1.Recordset!Company
Data2.Recordset.Update
Data2.Recordset.MoveLast
End If
ResetDragDrop
End Sub
20. The following code performs clean-up when the mouse returns to TDBGrid1 with the button up:
Private Sub TDBGrid1_MouseMove(Button As Integer, _
Shift As Integer, X As Single, Y As Single)
' If the button is up and we get MouseMove, that means
' we exited the form and tried to drop elsewhere.
' Reset the drag upon returning.
If Button = 0 Then ResetDragDrop
End Sub
Run the program and observe the following:
• Hold down the left mouse button and drag from a cell in the Phone column of TDBGrid1. As you
start dragging, the cell becomes current and is highlighted. The mouse pointer turns into the drag
icon specified in step 5.
60 · Tutorials

• As you drag over TDBGrid2, the current cell in TDBGrid2 moves to the Phone column and is also
highlighted. The current (highlighted) cell of TDBGrid2 stays in the Phone column and moves up
and down with the drag motion as depicted here.

• If you drop (release the left mouse button) on a row in TDBGrid2, the phone number from the
highlighted cell in TDBGrid1 will be copied to the phone number column of the row where the
drop occurs.
• If you start dragging from a column in TDBGrid1 other than the Phone column, the entire row in
TDBGrid1 is highlighted, indicating that the entire row of data is being dragged.
• As you drag over TDBGrid2, the current cell marquee (a solid border around the cell) disappears
as in the following figure.
 Tutorial 14 - OLE Drag-and-Drop · 61

• If you drop the data on TDBGrid2, a new record is created using the data from the current row of
TDBGrid1.
This concludes Tutorial 13.

Tutorial 14 - OLE Drag-and-Drop

In this tutorial, you will learn how to use the OLE drag-and-drop features of True DBGrid. Unlike the
Visual Basic drag-and-drop demonstrated in Tutorial 13 (page 56, )which invokes code as one control is
dragged or dropped over another, OLE drag-and-drop moves data from a source component to a target
component. These components can be controls on a Visual Basic form or standalone applications. For
example, you can select a range of text in Word 97 or Access 97, then drop it into a True DBGrid control
in your own application.
1. Start a new project.
2. Place a Data control (Data1), a True DBGrid control (TDBGrid1), and a TextBox control (Text1) on
the form (Form1) as shown in the following figure.
62 · Tutorials

3. Set the DatabaseName property of Data1 to TDBGDemo.MDB, and the RecordSource property to
Composer.
4. Set the DataSource property of TDBGrid1 to Data1.
5. Set the AllowAddNew and AllowDelete properties of TDBGrid1 to True (note that the default
value of AllowUpdate is True).
6. Set the MultiLine property of Text1 to True. Type several lines of text into the Text property of
Text1.
7. Set the OLEDragMode property of both TDBGrid1 and Text1 to 1 - Automatic, and the
OLEDropMode property of both controls to 2 - Automatic.
Run the program and observe the following:
• Select an arbitrary range of text in Text1. Move the mouse over the selected text, then hold down
the left mouse button and drag it to the current cell of TDBGrid1. When you start dragging, the
mouse pointer turns into a drag icon, indicating a move operation.

• As you drag over TDBGrid1, the mouse pointer turns into a “No drop allowed” symbol, since
True DBGrid only accepts data dropped into the current row or cell.

• As soon as you move the mouse over the current row, the mouse pointer turns into a drag icon,
indicating that TDBGrid1 is ready to accept data.
 Tutorial 15 - Creating a Grid with Fixed, Nonscrolling Columns · 63

• When you release the mouse button, the current cell of TDBGrid1 receives the text selection from
Text1, and the selected text is removed from Text1. If you want to copy the selection instead of
moving it, hold down the CTRL key while dragging. The mouse pointer will indicate that a copy
operation is in progress by changing its icon to the following symbol.

This feature enables you to transfer data between controls and applications that support OLE drag-and-
drop. If you have Word 97 or Access 97, feel free to try it with this project. To gain additional control over
the process, or to implement custom behavior, consider using the following events: OLECompleteDrag,
OLEDragDrop, OLEDragOver, OLEGiveFeedback, OLESetData, and OLEStartDrag.
This concludes Tutorial 14.

Tutorial 15 - Creating a Grid with Fixed, Nonscrolling Columns

Often, you would like to prevent one or more columns from scrolling horizontally so that they will
always be in view. The Splits collection of True DBGrid provides a generalized mechanism for defining
groups of adjacent columns, and can be used to implement any number of fixed, nonscrolling columns. In
this tutorial, you will learn how to write code to create a grid with two splits, and then "fix" a pair of
columns in the leftmost split.
1. Follow steps 1 through 5 of Tutorial 1 (page 27 )to create a project with a TDBGrid bound to a
Data control.
2. In the Form_Load event, place the following code to create an additional split and to fix columns
0 and 1 in the leftmost split:
Private Sub Form_Load()
' Before modifying the grid's properties, make sure the
' grid is initialized by refreshing the Data control.
Data1.Refresh

' Create an additional split:

Dim S As TrueDBGrid80.Split
Set S = TDBGrid1.Splits.Add(0)
' Hide all columns in the leftmost split, Splits(0),
' except for columns 0 and 1
Dim C As TrueDBGrid80.Column
Dim Cols As TrueDBGrid80.Columns
Set Cols = TDBGrid1.Splits(0).Columns
For Each C In Cols
C.Visible = False
Next C
Cols(0).Visible = True
Cols(1).Visible = True

' Configure Splits(0) to display exactly two columns,

' and disable resizing
With TDBGrid1.Splits(0)
.SizeMode = dbgNumberOfColumns
.Size = 2
.AllowSizing = False
End With
' Usually, if you fix columns 0 and 1 from scrolling
' in a split, you will want to make them invisible in
' other splits:
64 · Tutorials

Set Cols = TDBGrid1.Splits(1).Columns

Cols(0).Visible = False
Cols(1).Visible = False
' Turn off the record selectors in Split 1:
TDBGrid1.Splits(1).RecordSelectors = False
End Sub
Run the program and observe the following:
• TDBGrid displays data from the Data control as in Tutorial 1 (page 27.)
• The two columns (First and Last) in the leftmost split are fixed and cannot be scrolled. In fact,
there is no horizontal scroll bar present under the left split. A horizontal scroll bar appears under
the rightmost split, allowing users to scroll the columns in this split.

You can use splits to create fixed, nonscrolling columns anywhere within the grid—even in the middle!
You can also use splits to present different views of your data. For example, you can create splits which
scroll independently (in the vertical direction) so that users may compare records at the beginning of the
database with those at the end. For more information, see How to Use Splits (page 293).
This concludes Tutorial 15.

Tutorial 16 - Displaying Array Data in Unbound Mode

In this tutorial, you will learn how to use the unbound mode (DataMode property set to 1 - Unbound) of
True DBGrid to display an array of strings.
NOTE: This unbound mode has been retained for backward compatibility with DBGrid and earlier
versions of True DBGrid. ComponentOne recommends using unbound extended mode (Tutorial 17 (page
70)), application mode (Tutorial 18 (page 75)), or storage mode (Tutorial 19 (page 79)) instead. For
detailed instructions on how to use unbound mode 1, see Unbound Mode (page 219).
For simplicity, this tutorial does not cover updating, adding, or deleting records. However, the
UNBOUND1.VBP project provides a complete sample that you can use as a template for implementing
unbound mode 1. This project is located in the TUTORIAL\UNBOUND1 subdirectory of the True
DBGrid installation directory.
1. Start a new project.
2. Place a True DBGrid control (TDBGrid1) on the form (Form1).
 Tutorial 16 - Displaying Array Data in Unbound Mode · 65

3. Set the DataMode property of TDBGrid1 to 1 - Unbound (the default value of this property is 0 -
Bound).
Configuring the grid at design time
This example uses the grid to display an array with two columns. Since True DBGrid displays two
columns by default, you do not have to add or delete columns at design time.
4. Right-click TDBGrid1 to display its context menu.
5. Choose Properties… to display the Property Pages dialog. On the General property page, set the
AllowUpdate property to False so that data displayed in the grid will be read-only.
6. Select the Columns properties page by clicking the Columns tab. Set the Caption property of
Columns(00) and Columns(01) to Column 0 and Column 1, respectively.
Initializing the array data
First, create and initialize a two-dimensional array to hold the data to be displayed in the grid.
7. In the General section of Form1, insert the following declarations:
' General declarations
Option Explicit
' Special Note: Variables that store Row indices will be
' of data type Long (It is reasonable to assume there may
' be larger than 32,767 rows). Those storing Column
' indices will be of type Integer. (It is very unlikely
' there will be more than 32,767 columns.)
Dim MaxCol As Integer ' Number of columns
Dim MaxRow As Long ' Number of rows
Dim GridArray() As Variant ' Array to store the data
8. In the Form_Load event, initialize the elements of GridArray and set the ApproxCount property
of the grid accordingly. The ApproxCount property is optional, but setting this value will enable
the grid to position the vertical scroll bar accurately. If you want to initialize the current cell to a
specific location, the Form_Activate (Visual Basic) event is a good place to do it.
Private Sub Form_Load()
' Initialize the data array. Data must be ready
' before the grid is loaded. Form_Load or Main is a
' good place to initialize the data.

Dim I As Integer ' column index

Dim J As Long ' row index
Dim C As TrueDBGrid80.Column
Dim Col2 As TrueDBGrid80.Column
Dim Col3 As TrueDBGrid80.Column
' Use a 4 columns by 100 rows array as data source.
' Since user will be allowed to add data to the grid,
' the array may grow in size.
' This tutorial project assumes there are 3 columns in
' the grid for simplicity. If you wish to change this
' number, you will need to modify the code below to
' add the correct number of columns.
MaxCol = 4
' You can change MaxRow to show a different number of
' rows when the program loads. MaxRow must be >= 0.
MaxRow = 100
66 · Tutorials

If MaxRow > 0 Then

' If MaxRow = 0, then (MaxRow - 1) equals -1. This
' causes an error in the statement below, so we
' handle this special case in the Else clause.
ReDim GridArray(0 To MaxCol - 1, 0 To MaxRow - 1)
Else
ReDim GridArray(0 To MaxCol - 1, 0)
End If
For I = 0 To MaxCol - 1
For J = 0 To MaxRow - 1
GridArray(I, J) = "Row" + Str$(J) + ", Col" _
+ Str$(I)
Next J
Next I
' You can configure the grid either at design time or
' run time. Assuming you have not done this at
' design-time, the following code configures a grid
' with 4 columns. By default, the grid already has 2
' columns, so we just need to add 2 more (don't forget
' to make the new column visible). The existing
' columns are numbered 0 and 1, so we will add new
' columns at positions 2 and 3.
Set C = TDBGrid1.Columns.Add(2)
C.Visible = True
Set C = TDBGrid1.Columns.Add(3)
C.Visible = True
' For the sake of efficiency, we use Column objects
' to reference column properties instead of repeatedly
' going through the grid's Columns collection object.
Set Col2 = TDBGrid1.Columns(2)
Set Col3 = TDBGrid1.Columns(3)
' Set column heading text
Col2.Caption = "Column 2"
Col3.Caption = "Column 3"

' Inform the grid of how many rows are in the data set.
' This helps with scroll bar positioning.
TDBGrid1.ApproxCount = MaxRow
End Sub
Displaying data in the unbound grid
When using the ListBox control in Visual Basic, you store all of the data in the control using its AddItem
method. This storage method is neither adequate nor efficient when you have a large amount of data or
when the data source continuously changes.
Unlike the ListBox control, True DBGrid's unbound modes do not store your data. You manage the data
while the grid handles all display and end-user interactions. Whenever the grid needs to display more
rows of data, such as during vertical scrolling, it will fire the UnboundReadData event to ask for data
from your data source. The grid generally asks for only what it needs to display, but may cache some
data for efficiency considerations. You cannot predict when the grid will ask for data, nor can you assume
data will be requested in any particular order. Furthermore, since the grid does not store the data, any
data that has been requested once may be requested again.
9. Place the following code in the UnboundGetRelativeBookmark event of TDBGrid1. This event
provides bookmarks to the grid and also calibrates the vertical scroll bar:
Private Sub TDBGrid1_UnboundGetRelativeBookmark( _
 Tutorial 16 - Displaying Array Data in Unbound Mode · 67

StartLocation As Variant, ByVal Offset As Long, _

NewLocation As Variant, ApproximatePosition As Long)
' TDBGrid1 calls this routine each time it needs to
' reposition itself. StartLocation is a bookmark
' supplied by the grid to indicate the "current"
' position -- the row we are moving from. Offset is
' the number of rows we must move from StartLocation
' in order to arrive at the desired destination row.
' A positive offset means the desired record is after
' the StartLocation, and a negative offset means the
' desired record is before StartLocation.
' If StartLocation is NULL, then we are positioning
' from either BOF or EOF. Once we determine the
' correct index for StartLocation, we will simply add
' the offset to get the correct destination row.
' GetRelativeBookmark already does all of this, so we
' just call it here.
NewLocation = GetRelativeBookmark(StartLocation, Offset)
' If we are on a valid data row (i.e., not at BOF or
' EOF), then set the ApproximatePosition (the ordinal
' row number) to improve scroll bar accuracy. We can
' call IndexFromBookmark to do this.
If Not IsNull(NewLocation) Then
ApproximatePosition = IndexFromBookmark(NewLocation, 0)
End If
End Sub
10. Place the following code in the UnboundReadData event of TDBGrid1. This example shows how
data is provided to the grid via the RowBuffer object:
Private Sub TDBGrid1_UnboundReadData( _
ByVal RowBuf As TrueDBGrid80.RowBuffer, _
StartLocation As Variant, ByVal ReadPriorRows As Boolean)
' UnboundReadData is fired by an unbound grid whenever
' it requires data for display. This event will fire
' when the grid is first shown, when Refresh or ReBind
' is used, when the grid is scrolled, and after a
' record in the grid is modified and the user commits
' the change by moving off of the current row. The
' grid fetches data in "chunks", and the number of rows
' the grid is asking for is given by RowBuf.RowCount.
' RowBuf is the row buffer where you place the data and
' the bookmarks for the rows that the grid is requesting
' to display. It will also hold the number of rows that
' were successfully supplied to the grid.
' StartLocation is a bookmark which specifies the row
' before or after the desired data, depending on the
' value of ReadPriorRows. If we are reading rows after
' StartLocation (ReadPriorRows = False), then the first
' row of data the grid wants is the row after
' StartLocation, and if we are reading rows before
' StartLocation (ReadPriorRows = True) then the first
' row of data the grid wants is the row before
' StartLocation.
' ReadPriorRows is a boolean value indicating whether
' we are reading rows before (ReadPriorRows = True) or
' after (ReadPriorRows = False) StartLocation.
68 · Tutorials

Dim Bookmark As Variant

Dim I As Long, RelPos As Long
Dim J As Integer, RowsFetched As Integer
' Get a bookmark for the start location
Bookmark = StartLocation
If ReadPriorRows Then
RelPos = -1 ' Requesting data in rows prior to
' StartLocation
Else
RelPos = 1 ' Requesting data in rows after
' StartLocation
End If
RowsFetched = 0
For I = 0 To RowBuf.RowCount - 1
' Get the bookmark of the next available row
Bookmark = GetRelativeBookmark(Bookmark, RelPos)
' If the next row is BOF or EOF, then stop
' fetching and return any rows fetched up to this
' point.
If IsNull(Bookmark) Then Exit For

' Place the record data into the row buffer

For J = 0 To RowBuf.ColumnCount - 1
RowBuf.Value(I, J) = GetUserData(Bookmark, J)
Next J
' Set the bookmark for the row
RowBuf.Bookmark(I) = Bookmark
' Increment the count of fetched rows
RowsFetched = RowsFetched + 1
Next I

' Tell the grid how many rows we fetched

RowBuf.RowCount = RowsFetched
End Sub
11. The UnboundReadData event handler listed in the previous step calls the following support
functions to manage the array data and bookmarks: MakeBookmark, IndexFromBookmark,
GetRelativeBookmark, and GetUserData.
Private Function MakeBookmark(Index As Long) As Variant
' This support function is used only by the remaining
' support functions. It is not used directly by the
' unbound events. It is a good idea to create a
' MakeBookmark function such that all bookmarks can be
' created in the same way. Thus the method by which
' bookmarks are created is consistent and easy to
' modify. This function creates a bookmark when given
' an array row index.
' Since we have data stored in an array, we will just
' use the array index as our bookmark. We will convert
' it to a string first, using the CStr function.
MakeBookmark = CStr(Index)
End Function
Private Function IndexFromBookmark(Bookmark As Variant, _
ReadPriorRows As Boolean) As Long
 Tutorial 16 - Displaying Array Data in Unbound Mode · 69

' This support function is used only by the remaining

' support functions. It is not used directly by the
' unbound events.
' This function is the inverse of MakeBookmark. Given
' a bookmark, IndexFromBookmark returns the row index
' that the given bookmark refers to. If the given
' bookmark is Null, then it refers to BOF or EOF. In
' such a case, we need to use ReadPriorRows to
' distinguish between the two. If ReadPriorRows = True,
' the grid is requesting rows before the current
' location, so we must be at EOF, because no rows exist
' before BOF. Conversely, if ReadPriorRows = False,
' we must be at BOF.
Dim Index As Long
If IsNull(Bookmark) Then
If ReadPriorRows Then
' Bookmark refers to EOF. Since (MaxRow - 1)
' is the index of the last record, we can use
' an index of (MaxRow) to represent EOF.
IndexFromBookmark = MaxRow
Else
' Bookmark refers to BOF. Since 0 is the
' index of the first record, we can use an
' index of -1 to represent BOF.
IndexFromBookmark = -1
End If
Else
' Convert string to long integer
Index = Val(Bookmark)
' Check to see if the row index is valid:
' (0 <= Index < MaxRow).
' If not, set it to a large negative number to
' indicate that the bookmark is invalid.
If Index < 0 Or Index >= MaxRow Then Index = -9999
IndexFromBookmark = Index
End If
End Function
Private Function GetRelativeBookmark(Bookmark As Variant, _
RelPos As Long) As Variant
' GetRelativeBookmark is used to get a bookmark for a
' row that is a given number of rows away from the given
' row. This specific example will always use either -1
' or +1 for a relative position, since we will always be
' retrieving either the row previous to the current one,
' or the row following the current one.
' IndexFromBookmark expects a Bookmark and a Boolean
' value: this Boolean value is True if the next row to
' read is before the current one [in this case,
' (RelPos < 0) is True], or False if the next row to
' read is after the current one [(RelPos < 0) is False].
' This is necessary to distinguish between BOF and EOF
' in the IndexFromBookmark function if our bookmark is
' Null. Once we get the correct row index from
' IndexFromBookmark, we simply add RelPos to it to get
' the desired row index and create a bookmark using
' that index.
Dim Index As Long
70 · Tutorials

Index = IndexFromBookmark(Bookmark, RelPos < 0) + RelPos

If Index < 0 Or Index >= MaxRow Then
' Index refers to a row before the first or after
' the last, so just return Null.
GetRelativeBookmark = Null
Else
GetRelativeBookmark = MakeBookmark(Index)
End If
End Function
Private Function GetUserData(Bookmark As Variant, _
Col As Integer) As Variant
' In this example, GetUserData is called by
' UnboundReadData to ask the user what data should be
' displayed in a specific cell in the grid. The grid
' row the cell is in is the one referred to by the
' Bookmark parameter, and the column it is in it given
' by the Col parameter. GetUserData is called on a
' cell-by-cell basis.
Dim Index As Long
' Figure out which row the bookmark refers to
Index = IndexFromBookmark(Bookmark, False)
If Index < 0 Or Index >= MaxRow Or _
Col < 0 Or Col >= MaxCol Then
' Cell position is invalid, so just return null
' to indicate failure
GetUserData = Null
Else
GetUserData = GridArray(Col, Index)
End If
End Function
Run the program and observe the following:
• The grid displays the elements of GridArray and otherwise behaves as if it were bound to a Data
control.
This concludes Tutorial 16.

Tutorial 17 - Displaying Array Data in Unbound Extended Mode

In this tutorial, you will learn how to use the unbound extended mode (DataMode property set to 2 -
Unbound Extended) of True DBGrid to display an array of strings. As its name implies, the unbound
extended mode is an extension of the unbound mode introduced in Tutorial 16 (page 64. )Unbound mode
2 is both easier to use and more efficient than unbound mode 1. For detailed instructions on how to use
unbound mode 2, see Unbound Mode (page 219).
For simplicity, this tutorial does not cover updating, adding, or deleting records. However, the
UNBOUND2.VBP project provides a complete sample that you can use as a template for implementing
unbound mode 2. This project is located in the TUTORIAL\UNBOUND2 subdirectory of the True
DBGrid installation directory.
1. Start a new project.
2. Place a True DBGrid control (TDBGrid1) on the form (Form1).
3. Set the DataMode property of TDBGrid1 to 2 - Unbound Extended (the default value of this
property is 0 - Bound).
 Tutorial 17 - Displaying Array Data in Unbound Extended Mode · 71

Configuring the grid at design time

We shall configure the grid as in Tutorial 16 (page 64.)
4. Right-click TDBGrid1 to display its context menu.
5. Choose Properties… to display the Property Pages dialog. On the General property page, set the
AllowUpdate property to False so that data displayed in the grid will be read-only.
6. Select the Columns properties page by clicking the Columns tab. Set the Caption property of
Columns(00) and Columns(01) to Column 0 and Column 1, respectively.
Initializing the array data
First, create and initialize a two-dimensional array to hold the data to be displayed in the grid.
7. In the General section of Form1, insert the following declarations:
' General declarations
Option Explicit
' Use a 2 columns by 100 rows array as data source,
Const MaxCol = 2
Const MaxRow = 100
Dim GridArray(MaxCol, MaxRow) As Variant
8. In the Form_Load event, initialize the elements of GridArray and set the ApproxCount property
of the grid accordingly. The ApproxCount property is optional, but setting this value will enable
the grid to position the vertical scroll bar accurately. If you want to initialize the current cell to a
specific location, the Form_Activate (Visual Basic) event is a good place to do it.
Private Sub Form_Load()
' Initialize the data array. Data must be ready
' before the grid is loaded. Form_Load or Main is a
' good place to initialize the data.
Dim I As Integer, J As Long
For I = 0 To MaxCol - 1
For J = 0 To MaxRow - 1
GridArray(I, J) = "Row" + Str$(J) + ", Col" _
+ Str$(I)
Next J
Next I
' Inform the grid of how many rows are in the data set.
' This helps with scroll bar positioning.
TDBGrid1.ApproxCount = MaxRow
End Sub
Displaying data in the unbound grid
As explained in Tutorial 16 (page 64, )True DBGrid does not store your data in any of its unbound modes.
In unbound mode 2, whenever the grid needs to display more rows of data, it will fire the
UnboundReadDataEx event (instead of UnboundReadData) to ask for data from your data source.
9. Place the following code in the UnboundReadDataEx event of TDBGrid1. This example shows
how data and the row's ordinal position are provided to the grid via the RowBuffer object and
the ApproximatePosition arguments, respectively:
Private Sub TDBGrid1_UnboundReadDataEx( _
ByVal RowBuf As TrueDBGrid80.RowBuffer, _
StartLocation As Variant, ByVal Offset As Long, _
ApproximatePosition As Long)
' UnboundReadData is fired by an unbound grid whenever
' it requires data for display. This event will fire
72 · Tutorials

' when the grid is first shown, when Refresh or ReBind

' is used, when the grid is scrolled, and after a
' record in the grid is modified and the user commits
' the change by moving off of the current row. The
' grid fetches data in "chunks", and the number of rows
' the grid is asking for is given by RowBuf.RowCount.
' RowBuf is the row buffer where you place the data
' the bookmarks for the rows that the grid is
' requesting to display. It will also hold the number
' of rows that were successfully supplied to the grid.
' StartLocation is a bookmark which, together with
' Offset, specifies the row for the programmer to start
' transferring data. A StartLocation of Null indicates
' a request for data from BOF or EOF.
' Offset specifies the relative position (from
' StartLocation) of the row for the programmer to start
' transferring data. A positive number indicates a
' forward relative position while a negative number
' indicates a backward relative position. Regardless
' of whether the rows to be read are before or after
' StartLocation, rows are always fetched going forward
' (this is why there is no ReadPriorRows parameter to
' the procedure).
' If you page down on the grid, for instance, the new
' top row of the grid will have an index greater than
' the StartLocation (Offset > 0). If you page up on
' the grid, the new index is less than that of
' StartLocation, so Offset < 0. If StartLocation is
' a bookmark to row N, the grid always asks for row
' data in the following order:
' (N + Offset), (N + Offset + 1), (N + Offset + 2)...
' ApproximatePosition is a value you can set to indicate
' the ordinal position of (StartLocation + Offset).
' Setting this variable will enhance the ability of the
' grid to display its vertical scroll bar accurately.
' If the exact ordinal position of the new location is
' not known, you can set it to a reasonable,
' approximate value, or just ignore this parameter.
Dim ColIndex As Integer, J As Integer
Dim RowsFetched As Integer, I As Long
Dim NewPosition As Long, Bookmark As Variant
RowsFetched = 0
For I = 0 To RowBuf.RowCount - 1
' Get the bookmark of the next available row
Bookmark = GetRelativeBookmark(StartLocation, _
Offset + I)
' If the next row is BOF or EOF, then stop fetching
' and return any rows fetched up to this point.
If IsNull(Bookmark) Then Exit For
' Place the record data into the row buffer
For J = 0 To RowBuf.ColumnCount - 1
ColIndex = RowBuf.ColumnIndex(I, J)
RowBuf.Value(I, J) = GetUserData(Bookmark, _
ColIndex)
 Tutorial 17 - Displaying Array Data in Unbound Extended Mode · 73

Next J
' Set the bookmark for the row
RowBuf.Bookmark(I) = Bookmark
' Increment the count of fetched rows
RowsFetched = RowsFetched + 1
Next I
' Tell the grid how many rows were fetched
RowBuf.RowCount = RowsFetched
' Set the approximate scroll bar position. Only
' nonnegative values of IndexFromBookmark() are valid.
NewPosition = IndexFromBookmark(StartLocation, Offset)
If NewPosition >= 0 Then _
ApproximatePosition = NewPosition
End Sub
10. The UnboundReadDataEx event handler used in the previous step calls the following support
functions to manage the array data and bookmarks: MakeBookmark, IndexFromBookmark,
GetRelativeBookmark, and GetUserData.
Private Function MakeBookmark(Index As Long) As Variant
' This support function is used only by the remaining
' support functions. It is not used directly by the
' unbound events. It is a good idea to create a
' MakeBookmark function such that all bookmarks can be
' created in the same way. Thus the method by which
' bookmarks are created is consistent and easy to
' modify. This function creates a bookmark when given
' an array row index.
' Since we have data stored in an array, we will just
' use the array index as our bookmark. We will convert
' it to a string first, using the CStr function.
MakeBookmark = CStr(Index)
End Function
Private Function IndexFromBookmark(Bookmark As Variant, _
Offset As Long) As Long
' This support function is used only by the remaining
' support functions. It is not used directly by the
' unbound events.
' IndexFromBookmark computes the row index that
' corresponds to a row that is (Offset) rows from the
' row specified by the Bookmark parameter. For example,
' if Bookmark refers to the index 50 of the dataset
' array and Offset = -10, then IndexFromBookmark will
' return 50 + (-10), or 40. Thus to get the index of
' the row specified by the bookmark itself, call
' IndexFromBookmark with an Offset of 0. If the given
' Bookmark is Null, it refers to BOF or EOF. If
' Offset < 0, the grid is requesting rows before the
' row specified by Bookmark, and so we must be at EOF
' because prior rows do not exist for BOF. Conversely,
' if Offset > 0, we are at BOF.
Dim Index As Long
If IsNull(Bookmark) Then
If Offset < 0 Then
74 · Tutorials

' Bookmark refers to EOF. Since (MaxRow - 1)

' is the index of the last record, we can use
' an index of (MaxRow) to represent EOF.
Index = MaxRow + Offset
Else
' Bookmark refers to BOF. Since 0 is the index
' of the first record, we can use an index of
' -1 to represent BOF.
Index = -1 + Offset
End If
Else
' Convert string to long integer
Index = Val(Bookmark) + Offset
End If
' Check to see if the row index is valid:
' (0 <= Index < MaxRow).
' If not, set it to a large negative number to
' indicate that it is invalid.
If Index >= 0 And Index < MaxRow Then
IndexFromBookmark = Index
Else
IndexFromBookmark = -9999
End If
End Function
Private Function GetRelativeBookmark(Bookmark As Variant, _
Offset As Long) As Variant
' GetRelativeBookmark is used to get a bookmark for a
' row that is a specified number of rows away from the
' given row. Offset specifies the number of rows to
' move. A positive Offset indicates that the desired
' row is after the one referred to by Bookmark, and a
' negative Offset means it is before the one referred
' to by Bookmark.
Dim Index As Long
' Compute the row index for the desired row
Index = IndexFromBookmark(Bookmark, Offset)
If Index < 0 Or Index >= MaxRow Then
' Index refers to a row before the first or after
' the last, so just return Null.
GetRelativeBookmark = Null
Else
GetRelativeBookmark = MakeBookmark(Index)
End If
End Function
Private Function GetUserData(Bookmark As Variant, _
Col As Integer) As Variant
' In this example, GetUserData is called by
' UnboundReadData to ask the user what data should be
' displayed in a specific cell in the grid. The grid
' row the cell is in is the one referred to by the
' Bookmark parameter, and the column it is in it given
' by the Col parameter. GetUserData is called on a
' cell-by-cell basis.
Dim Index As Long
' Figure out which row the bookmark refers to
Index = IndexFromBookmark(Bookmark, 0)
 Tutorial 18 - Displaying Array Data in Unbound Application Mode · 75

If Index < 0 Or Index >= MaxRow Or _

Col < 0 Or Col >= MaxCol Then
' Cell position is invalid, so just return null to
' indicate failure
GetUserData = Null
Else
GetUserData = GridArray(Col, Index)
End If
End Function
Run the program and observe the following:
• The grid displays the elements of GridArray and otherwise behaves as if it were bound to a Data
control.
This concludes Tutorial 17.

Tutorial 18 - Displaying Array Data in Unbound Application Mode

In this tutorial, you will learn how to use the unbound application mode (DataMode property set to 3 -
Application) of True DBGrid to display an array of strings. When the data source is an array, application
mode is easier to use than either unbound mode (1) or unbound extended mode (2). In application mode,
the grid fetches data one cell at a time, and you must program the UnboundGetRelativeBookmark event
in order for the grid to obtain the bookmark of a row. For detailed instructions on how to use unbound
mode 3, see Application Mode (page 211).
For simplicity, this tutorial does not cover updating, adding, or deleting records. However, the
UNBOUND3.VBP project provides a complete sample that you can use as a template for implementing
application mode. This project is located in the TUTORIAL\UNBOUND3 subdirectory of the True
DBGrid installation directory.
1. Start a new project.
2. Place a True DBGrid control (TDBGrid1) on the form (Form1).
3. Set the DataMode property of TDBGrid1 to 3 - Application (the default value of this property is 0 -
Bound).
Configuring the grid at design time
We shall configure the grid as in Tutorial 16 (page 64.)
4. Right-click TDBGrid1 to display its context menu.
5. Choose Properties… to display the Property Pages dialog. On the General property page, set the
AllowUpdate property to False so that data displayed in the grid will be read-only.
6. Select the Columns properties page by clicking the Columns tab. Set the Caption property of
Columns(00) and Columns(01) to Column 0 and Column 1, respectively.
Initializing the array data
First, create and initialize a two-dimensional array to hold the data to be displayed in the grid.
7. In the General section of Form1, insert the following declarations:
' General declarations
Option Explicit
' Use a 2 columns by 100 rows array as data source,
Const MaxCol = 2
Const MaxRow = 100
76 · Tutorials

Dim GridArray(MaxCol, MaxRow) As Variant

8. In the Form_Load event, initialize the elements of GridArray and set the ApproxCount property
of the grid accordingly. The ApproxCount property is optional, but setting this value will enable
the grid to position the vertical scroll bar accurately. If you want to initialize the current cell to a
specific location, the Form_Activate (Visual Basic) event is a good place to do it.
Private Sub Form_Load()
' Initialize the data array. Data must be ready
' before the grid is loaded. Form_Load or Main is a
' good place to initialize the data.
Dim I As Integer, J As Long
For I = 0 To MaxCol - 1
For J = 0 To MaxRow - 1
GridArray(I, J) = "Row" + Str$(J) + ", Col" _
+ Str$(I)
Next J
Next I
' Inform the grid of how many rows are in the data set.
' This helps with scroll bar positioning.
TDBGrid1.ApproxCount = MaxRow
End Sub
Displaying data in the unbound grid
As explained in Tutorial 15 (page 63, )True DBGrid does not store your data in any of its unbound modes.
Whenever the grid needs to display data in a cell, it will fire the ClassicRead event to ask for data from
your data source. Unlike unbound modes 1 and 2, the ClassicRead event does not use the RowBuffer
object to transfer data several rows at a time. Instead, the ClassicRead event fetches data one cell at a
time. When using application mode, you must also program the UnboundGetRelativeBookmark event
in order for the grid to obtain the bookmark of a row.
9. Place the following code in the UnboundGetRelativeBookmark and the ClassicRead events of
TDBGrid1. These event handlers show how to provide bookmarks and data to the grid,
respectively:
Private Sub TDBGrid1_UnboundGetRelativeBookmark( _
StartLocation As Variant, ByVal Offset As Long, _
NewLocation As Variant, ApproximatePosition As Long)
' TDBGrid1 calls this routine each time it needs to
' reposition itself. StartLocation is a bookmark
' supplied by the grid to indicate the "current"
' position -- the row we are moving from. Offset is
' the number of rows we must move from StartLocation
' in order to arrive at the desired destination row.
' A positive offset means the desired record is after
' the StartLocation, and a negative offset means the
' desired record is before StartLocation.
' If StartLocation is NULL, then we are positioning
' from either BOF or EOF. Once we determine the
' correct index for StartLocation, we will simply add
' the offset to get the correct destination row.
' GetRelativeBookmark already does all of this, so we
' just call it here.
NewLocation = GetRelativeBookmark(StartLocation, Offset)
' If we are on a valid data row (i.e., not at BOF or
' EOF), then set the ApproximatePosition (the ordinal
' row number) to improve scroll bar accuracy. We can
' call IndexFromBookmark to do this.
 Tutorial 18 - Displaying Array Data in Unbound Application Mode · 77

If Not IsNull(NewLocation) Then

ApproximatePosition = IndexFromBookmark(NewLocation, 0)
End If
End Sub
Private Sub TDBGrid1_ClassicRead(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
' ClassicRead is analogous to the Fetch event of the
' TrueGrid Pro VBX control. When the grid needs data
' in DataMode 3, it fires a ClassicRead event for
' each visible cell on the grid to retrieve the data
' that will be shown there, so it fires on a
' cell-by-cell basis. The cell that this event is
' firing for is specified by the Bookmark (which
' tells which row to fetch the data from) and the
' Col parameter (which gives the column index). The
' only difference from the Fetch event of the VBX is
' that the row to fetch is specified by a Bookmark
' and not an integral row index. Thus, you must
' determine which row in your data source the bookmark.
' GetUserData uses the IndexFromBookmark function to
' do that.
' Assume that a function GetUserData(Bookmark, Col,
' Value) takes a row bookmark, a column index, and
' a variant which will hold the appropriate data to
' be fetched from the array or database. The function
' returns the fetched data in the Value parameter if
' the fetch is successful, otherwise, it returns Null.
Value = GetUserData(Bookmark, Col)
End Sub
10. The UnboundGetRelativeBookmark and the ClassicRead event handlers used in the previous
step call the following support functions to manage the array data and bookmarks:
MakeBookmark, IndexFromBookmark, GetRelativeBookmark, and GetUserData.
Private Function MakeBookmark(Index As Long) As Variant
' This support function is used only by the remaining
' support functions. It is not used directly by the
' unbound events. It is a good idea to create a
' MakeBookmark function such that all bookmarks can
' be created in the same way. Thus the method by
' which bookmarks are created is consistent and easy
' to modify. This function creates a bookmark when
' given an array row index.
' Since we have data stored in an array, we will just
' use the array index as our bookmark. We will convert
' it to a string first, using the Str$ function. Thus,
' if Index = 27, the Bookmark that is created is the
' string " 27". (Str$ always leaves a leading space
' for the sign of the number.)

MakeBookmark = Str$(Index)
End Function
Private Function IndexFromBookmark(Bookmark As Variant, _
Offset As Long) As Long
' This support function is used only by the remaining
' support functions. It is not used directly by the
' unbound events.
' IndexFromBookmark computes the row index that
78 · Tutorials

' corresponds to a row that is (Offset) rows from the

' row specified by the Bookmark parameter. For
' example, if Bookmark refers to the index 50 of the
' dataset array and Offset = -10, then
' IndexFromBookmark will return 50 + (-10), or 40.
' Thus to get the index of the row specified by the
' bookmark itself, call IndexFromBookmark with an
' Offset of 0. If the given Bookmark is Null, it
' refers to BOF or EOF. If Offset < 0, the grid is
' requesting rows before the row specified by
' Bookmark, and so we must be at EOF because prior
' rows do not exist for BOF. Conversely, if
' Offset > 0, we are at BOF.
Dim Index As Long
If IsNull(Bookmark) Then
If Offset < 0 Then
' Bookmark refers to EOF. Since (MaxRow - 1)
' is the index of the last record, we can use
' an index of (MaxRow) to represent EOF.
Index = MaxRow + Offset
Else
' Bookmark refers to BOF. Since 0 is the index
' of the first record, we can use an index of
' -1 to represent BOF.
Index = -1 + Offset
End If
Else
' Convert string to long integer
Index = Val(Bookmark) + Offset
End If
' Check to see if the row index is valid:
' (0 <= Index < MaxRow).
' If not, set it to a large negative number to
' indicate that it is invalid.
If Index >= 0 And Index < MaxRow Then
IndexFromBookmark = Index
Else
IndexFromBookmark = -9999
End If
End Function
Private Function GetRelativeBookmark(Bookmark As Variant, _
Offset As Long) As Variant
' GetRelativeBookmark is used to get a bookmark for
' a row that is a specified number of rows away from
' the given row. Offset specifies the number of rows
' to move. A positive Offset indicates that the
' desired row is after the one referred to by Bookmark,
' and a negative Offset means it is before the one
' referred to by Bookmark.
Dim Index As Long
' Compute the row index for the desired row
Index = IndexFromBookmark(Bookmark, Offset)
If Index < 0 Or Index >= MaxRow Then
' Index refers to a row before the first or
' after the last, so just return Null.
GetRelativeBookmark = Null
Else
GetRelativeBookmark = MakeBookmark(Index)
End If
 Tutorial 19 - Displaying Array Data in Unbound Storage Mode · 79

End Function
Private Function GetUserData(Bookmark As Variant, _
Col As Integer) As Variant
' In this example, GetUserData is called by
' UnboundReadData to ask the user what data should
' be displayed in a specific cell in the grid. The
' grid row the cell is in is the one referred to by
' the Bookmark parameter, and the column it is in it
' given by the Col parameter. GetUserData is called
' on a cell-by-cell basis.
Dim Index As Long
' Figure out which row the bookmark refers to
Index = IndexFromBookmark(Bookmark, 0)
If Index < 0 Or Index >= MaxRow Or Col < 0 Or _
Col >= MaxCol Then
' Cell position is invalid, so just return null
' to indicate failure
GetUserData = Null
Else
GetUserData = GridArray(Col, Index)
End If
End Function
Run the program and observe the following:
• The grid displays the elements of GridArray and otherwise behaves as if it were bound to a Data
control.
This concludes Tutorial 18.

Tutorial 19 - Displaying Array Data in Unbound Storage Mode

In this tutorial, you will learn how to use the unbound storage mode (DataMode property set to 4 - Storage)
of True DBGrid to display an array of strings. Unlike unbound (extended) and application modes, storage
mode does not fire data-gathering events. Instead, it uses an XArrayDB ActiveX object to store, access,
and maintain data.
In code, you create, redimension, and populate an XArrayDB object with your data just as you would a
Visual Basic array, then assign the XArrayDB object to the Array property of the grid. The data will then
be maintained and exchanged between the grid and the XArrayDB object automatically. There are no
unbound events to write, making this mode the easiest to use.
1. Start a new project.
2. Place a True DBGrid control (TDBGrid1) on the form (Form1).
3. Set the DataMode property of TDBGrid1 to 4 - Storage (the default value of this property is 0 -
Bound).
Configuring the grid at design time
We shall configure the grid to display four columns.
4. Right-click TDBGrid1 to display its context menu and choose Edit from the context menu. The
grid will enter its visual editing mode, enabling you to interactively change the grid's row and
column layout.
80 · Tutorials

5. By default, the grid contains two columns. We are going to create two more. Right-click
anywhere in the grid to display the visual editing menu. Choose the Append command to add a
new column at the end of the grid. Execute this command again to get a total of four columns.
6. Right-click TDBGrid1 to display its context menu.
7. Choose Properties… to display the Property Pages dialog. On the General property page, set the
AllowAddNew and AllowDelete properties to True. (Note that the AllowUpdate property is
True by default.)
8. Click the Columns tab to display a list of the available columns, designated as Columns(00)
through Columns(03). Expand the Columns(00) node and set its Caption property to Column 0.
Repeat the process for the remaining columns until the grid looks like this.

Adding XArrayDB to the project

Before writing the code, we need to add the ComponentOne XArrayDB Object to the project.
9. Select References… from the Project menu to display a list of available type library references.
Select the check box labeled ComponentOne XArrayDB Object (XADB8.OCX), then press the
OK button.
Initializing the array data
Next, create the XArrayDB object in code.
10. In the General section of Form1, insert the following declarations:
' General declarations
Option Explicit
Dim x As New XArrayDB
11. In the Form_Load event, ReDim the XArrayDB object to contain 100 rows and 4 columns. After
populating the XArrayDB object, assign it to the grid's Array property.
Private Sub Form_Load()
' Allocate space for 100 rows, 4 columns
x.ReDim 0, 99, 0, 3
Dim row As Long, col As Integer
' The LowerBound and UpperBound properties correspond
' to the LBound and UBound functions in Visual Basic.
' Hard-coded dimensions can be used instead, if known.
 Tutorial 20 - Sorting and Searching · 81

For row = x.LowerBound(1) To x.UpperBound(1)

For col = x.LowerBound(2) To x.UpperBound(2)
x(row, col) = "Row " & row & ", Col " & col
Next col
Next row
' Bind True DBGrid Control to this XArrayDB instance
Set TDBGrid1.Array = x
End Sub
Run the program and observe the following:
• The grid displays the data assigned to the XArrayDB object in code and appears as follows.

• Type a different value into any cell. When you click another row, the new data is saved to the
array.
• Select an entire row by clicking its record selector. Press the DEL key. The grid will remove the
record from the display (and from the array).
• Scroll down until the AddNew row appears. Enter any data into the cells. When you click a cell
in another row, the array is redimensioned to accommodate an extra row at the end, and the
newly added data is saved to that row.
This concludes Tutorial 19.

Tutorial 20 - Sorting and Searching

In this tutorial, you will learn how to use the sorting and searching features of the XArrayDB object. The
QuickSort method sorts a range of rows in an XArrayDB object according to one or more columns (up to
ten). The Find method searches for a specified value within a column of an XArrayDB object, starting at a
particular row
1. Start with a project created in Tutorial 19 (page 79.)
2. Place the following controls on the form (Form1) as shown in the following figure: two text box
controls (Text1 and Text2), a command button (Command1), and two labels (Label1 and Label2).
82 · Tutorials

Initializing the array data

Next, initialize the XArrayDB object so that it contains 100 rows and 4 columns of random integers.
3. Place the following code in the Form_Load event:
Private Sub Form_Load()
' Allocate space for 100 rows, 4 columns
x.ReDim 0, 99, 0, 3

Dim row As Long, col As Integer

' The LowerBound and UpperBound properties correspond
' to the LBound and UBound functions in Visual Basic.
' Hard-coded dimensions can be used instead, if known.
For row = x.LowerBound(1) To x.UpperBound(1)
For col = x.LowerBound(2) To x.UpperBound(2)
x(row, col) = CInt(99 * Rnd + 1)
Next col
Next row
' Bind True DBGrid Control to this XArrayDB instance
Set TDBGrid1.Array = x
' Enable footers
TDBGrid1.ColumnFooters = True
' Display headers and footers as buttons
Dim obcol As TrueDBGrid80.Column
For Each obcol In TDBGrid1.Columns
obcol.ButtonFooter = True
obcol.ButtonHeader = True
Next obcol
End Sub
4. Add the following code to Command1:
Private Sub Command1_Click()
Dim RowFound As Long
' Execute Find
RowFound = x.Find(x.LowerBound(1), CInt(Text2.Text), _
CInt(Text1.Text), _
XORDER_ASCEND, XCOMP_EQ, XTYPE_NUMBER)
 Tutorial 20 - Sorting and Searching · 83

' Successful Find will return a row number

' Set focus to the row and column
If RowFound >= 0 Then TDBGrid1.Bookmark = RowFound
TDBGrid1.col = CInt(Text2.Text)
TDBGrid1.SetFocus
End Sub
5. Add the following code to the HeadClick and FootClick events:
Private Sub TDBGrid1_HeadClick(ByVal ColIndex As Integer)
' Ascending sort
x.QuickSort x.LowerBound(1), x.UpperBound(1), ColIndex, _
XORDER_ASCEND, XTYPE_INTEGER
TDBGrid1.Refresh
End Sub
Private Sub TDBGrid1_FootClick(ByVal ColIndex As Integer)
' Descending sort
x.QuickSort x.LowerBound(1), x.UpperBound(1), ColIndex, _
XORDER_DESCEND, XTYPE_INTEGER
TDBGrid1.Refresh
End Sub
Run the program and observe the following:
• The grid displays the data assigned to the XArrayDB object in code and appears as follows.
(Since random numbers are used, the actual values may differ.)

• Clicking a column header sorts all of the rows in ascending order based on the data within the
associated column. Similarly, clicking a column footer sorts the rows in descending order.
• Type one of the visible values in the last column into the Find text box (54 in this example), 3 into
the In Column text box, then click the Find button. Since a matching value exists, the grid makes
the specified cell current.
84 · Tutorials

• Type a three-digit number into the Find text box, then click the Find button again. Since no
matching value exists, the current cell does not change.
This concludes Tutorial 20.

Tutorial 21 - Displaying Arbitrary Bitmaps

In this tutorial, you will learn how to use Style objects to display arbitrary bitmaps within grid cells. In
addition to font, color, and alignment settings, Style objects support both background and foreground
pictures. Background pictures can be centered, tiled, or stretched to fill the entire cell. Foreground
pictures can be positioned relative to the cell text, and can also be displayed using a transparent color.
1. Start a new project.
2. Place a True DBGrid control (TDBGrid1), a command button (Command1), and a TextBox control
(Text1) on the form (Form1)
3. Set the DataMode property of TDBGrid1 to 4 - Storage (the default value of this property is 0 -
Bound).
4. Set the AllowUpdate property to False.
5. Right-click TDBGrid1 to display its context menu and choose the Edit option to enter the grid's
visual editing mode. Place the mouse cursor over the row divider, and increase the row size to
about double the current height.
6. Right-click TDBGrid1 again to display its context menu and this time choose Properties… to
display the Property Pages dialog.
7. Select the Columns property page by clicking the Columns tab. Set the Caption property of
Columns(00) and Columns(01) to Picture and File Name, respectively.
8. Select the Splits tab and expand the Splits(00) object. Set the ExtendRightColumn property to
True.
9. Set the Caption property of Command1 to Display.
 Tutorial 21 - Displaying Arbitrary Bitmaps · 85

Adding XArrayDB to the project

As in Tutorial 19 (page 79, )we will use the XArrayDB object, therefore we need to add its reference to the
project.
10. Select References… from the Project menu to display a list of available type library references.
Select the check box labeled ComponentOne XArrayDB Object (XADB8.OCX), then press the
OK button.
11. Add the following declaration to the General section of Form1:
Dim x As New XArrayDB
12. Enter the following code in the Form_Load event:
Private Sub Form_Load()
' Initially we resize the XArrayDB
' to 0 rows and 2 columns
x.ReDim 0, -1, 0, 1
Set TDBGrid1.Array = x
' Enable FetchCellStyle Event
TDBGrid1.Columns(0).FetchStyle = dbgFetchCellStyleColumn
TDBGrid1.MarqueeStyle = dbgDottedRowBorder
End Sub
13. Add the following code to the Click event of Command1:
Private Sub Command1_Click()
Dim s As String
Dim i As Integer
x.ReDim 0, -1, 0, 1
i = 0
' Fill the XArrayDB object with all bitmap
' file names found in this directory
s = Dir(Text1.Text & "\*.bmp")
While s <> ""
If s <> "." And s <> ".." Then
x.ReDim 0, x.UpperBound(1) + 1, 0, 1
x(i, 1) = s
i = i + 1
End If
s = Dir
Wend
' Reinitialize the grid
TDBGrid1.Bookmark = Null
TDBGrid1.ReBind
End Sub
14. Enter the following code in the FetchCellStyle event:
Private Sub TDBGrid1_FetchCellStyle( _
ByVal Condition As Integer, ByVal Split As Integer, _
Bookmark As Variant, ByVal Col As Integer, _
ByVal CellStyle As TrueDBGrid80.StyleDisp)
Dim PathFileName As String
' Full Path file name of a picture
PathFileName = Text1.Text & "\" & _
TDBGrid1.Columns(1).CellText(Bookmark)
86 · Tutorials

' Load the picture

CellStyle.BackgroundPicture = LoadPicture(PathFileName)
End Sub
Run the program and observe the following:
• True DBGrid is initially displayed with no rows. In the text box, type the name of a directory
containing bitmap files (with a .bmp extension), then press the Display button. The grid will
display pictures in the first column and their filenames in the second.

• You have created a fully functional bitmap browser with just a few lines of code.
For more information, see Applying Pictures to Grid Elements (page 326).
This concludes Tutorial 21.

Tutorial 22 - Reusable Layouts

In True DBGrid, a layout comprises the complete set of properties that define the appearance and
behavior of a grid, its splits, and its columns. You can save a grid layout to a binary file, then reuse it in
other projects. At design time, you can store multiple layouts in a single file, then load them as needed in
code. You can even store a layout file on a remote computer and have True DBGrid download it
asynchronously, an ideal technique for initializing a grid on an HTML page.
In this tutorial, you will learn how to save and retrieve layouts at run time. If you have an Internet
connection, you can also retrieve a layout file from the APEX server.
1. Start with the project created in Tutorial 1 (page 27.)
2. Add three command buttons (Command1, Command2, Command3) to the form (Form1)
3. Set the Caption property of Command1, Command2, and Command3 to Retrieve Layout, Save
Layout, and Retrieve Component One Layout, respectively. Your form should now look like this.
 Tutorial 22 - Reusable Layouts · 87

4. Right-click TDBGrid1 to display its context menu.

5. Choose Properties… to display the Property Pages dialog. Select the Splits tab. Expand the
Splits(00) node and set the AllowColMove property to True.
6. Add the following code to the Click events of Command1, Command2 and Command3:
Private Sub Command1_Click()
On Error GoTo Err:
' Load the layout
TDBGrid1.LayoutName = "TestLayout"
TDBGrid1.LayoutFileName = App.Path & "\Tutor22.grx"
TDBGrid1.LoadLayout
Exit Sub
Err:
MsgBox Err.Description
End Sub
Private Sub Command2_Click()
' Save current layout
TDBGrid1.LayoutFileName = App.Path & "\Tutor22.grx"
TDBGrid1.Layouts.Add "TestLayout"
End Sub
Private Sub Command3_Click()
' Load layout from APEX
TDBGrid1.LayoutName = "APEX"

' Start the download

TDBGrid1.LayoutUrl = _
"ftp://ftp.apexsc.com/pub/files/tutor22.grx"
' Set the order of records (by Country)
Data1.RecordSource = _
"Select * From Composer Order By Country"
Data1.Refresh
End Sub
7. Place the following code in the LayoutReady event of TDBGrid1:
Private Sub TDBGrid1_LayoutReady()
' Load layout as soon as it is available
88 · Tutorials

TDBGrid1.LoadLayout
End Sub
Run the program and observe the following:
• As in Tutorial 1, True DBGrid retrieves the database schema information from the Data control
and automatically configures itself to display the data for all fields in the database table.
• Change the layout of the grid by modifying column widths and the row height. You can also
rearrange the column order. When you are finished, click the Save Layout button. End the
program and then restart it. The grid will display the default layout as before. Now, click the
Retrieve Layout button. The grid will display the layout that you saved previously.
• If your computer is connected to the Internet, click the Retrieve APEX Layout button. The grid
will be configured according to a layout file stored on the APEX server.
For more information, see Reusable Layouts (page 178).
This concludes Tutorial 22.

Tutorial 23 - Printing, Print Preview, and Export

In this tutorial, you will learn how to use the printing and exporting capabilities of True DBGrid.
1. Start with the project created in Tutorial 1 (page 27.)
2. Add two command buttons (Command1 and Command2) and a check box (Check1) to the form
(Form1)
3. Set the Caption property of Command1, Command2, and Check1 to Print Preview, Export HTML,
and Export Selected Rows, respectively. Your form should now look like this:

4. Enter the following code in the Form_Load event:

Private Sub Form_Load()
' Initialize the Data control
Data1.Refresh
' Allow user to change the column order
TDBGrid1.AllowColMove = True
 Tutorial 23 - Printing, Print Preview, and Export · 89

' Change the presentation of the grid

With TDBGrid1.Columns
.Item("Country").BackColor = vbCyan
.Item("Country").Font.Name = "Times New Roman"
.Item("Last").NumberFormat = ">"
.Item("Last").ForeColor = vbRed
End With
With TDBGrid1.HeadingStyle
.Font.Bold = True
.BackColor = vbBlue
.ForeColor = vbYellow
End With
End Sub
5. Add the following code to the Click events of Command1 and Command2:
Private Sub Command1_Click()
With TDBGrid1.PrintInfo
' Set the page header
.PageHeaderFont.Italic = True
.PageHeader = "Composers table"

' Column headers will be on every page

.RepeatColumnHeaders = True

' Display page numbers (centered)

.PageFooter = "\tPage: \p"
' Invoke Print Preview
.PrintPreview
End With
End Sub
Private Sub Command2_Click()
' Depending on the Check1.Value
' the grid will export all or just selected rows
TDBGrid1.ExportToFile App.Path & _
"\Tutor23.html", False, Check1.Value
End Sub
Run the program and observe the following:
• True DBGrid displays the data using the font and color changes specified in step 4.
90 · Tutorials

• Click the Print Preview button to display a separate application window similar to the following.
Note that the output mirrors the format of the grid.
 Tutorial 24 - Displaying Hierarchical Data · 91

• Press the PGDN key to view the next page of records. Note that this page also contains column
headers because the RepeatColumnHeaders property was set to True in code.
• Experiment with the View menu commands and the zoom factor combo box to preview the
output at different resolutions. When you are finished, close the preview window.
• Click the Export HTML button to create a file named TUTOR23.HTML in the TUTOR23
directory. Load this file into your browser and note that the generated HTML table mirrors the
format of the grid.
• Go back to Form1 and select one or more records in the grid. Check the box labeled Export
Selected Rows, then click the Export HTML button. Refresh your browser, and note that only the
selected rows appear in the table.

Tutorial 24 - Displaying Hierarchical Data

In this tutorial, you will learn how to use the DataView property of True DBGrid to display hierarchical
data. Hierarchical data generally refers to data that is stored in multiple relational tables, where a master
(or "parent") table is linked by keyed fields to detail (or "child") tables. The hierarchical display gives you
the ability to present the master data to your users, such that the related detail data can be viewed in the
same grid with a single mouse click.
NOTE: The DataView property is only supported by the OLE DB version of True DBGrid.
When the grid is bound to a master-detail data source, you can display related groups of hierarchical data
by using bands. A band is a virtual representation of a hierarchical recordset, not the data itself.
Therefore, hierarchical grids are read-only. A band is created for each level in a hierarchical recordset,
and may consist of entire tables or a just a few selected fields. At run time, users can expand and collapse
bands using a TreeView-like interface.
See Hierarchical Data Display (page 279) for more information.
For simplicity, this tutorial does not cover all of the different ways of binding to the various types of data
sources. For example, you can bind to a Data Environment created with the Visual Basic Data View
window. Another way is to create an ODBC Data Source. An ODBC Data Source is both a reference to a
database file and to a specific ODBC driver that is used to access the data in the database, and is one of
the easiest ways to specify the set of records you want to display in the hierarchical grid.
1. Create an ODBC Data Source. In Control Panel, double-click the ODBC icon. You may have 16-bit
and 32-bit ODBC Icons depending on what other software is installed on your system. (You will
want to choose the 32-bit icon in such a case.)
92 · Tutorials

2. This will display the ODBC Data Source Administrator. You can create ODBC Data Sources that
are visible to yourself only, to all users on the system, and so on. The list box in the center of the
dialog shows the Data Source Names for the data sources that have already been defined. In this
example, you will create a new User Data Source Name (DSN). Click the Add... button to add a
new User DSN as shown in the next figure.

3. Choose an ODBC Driver to use with your data source. The driver you choose should reflect the
type of database file you wish to access. The database used by the rest of this tutorial is a
 Tutorial 24 - Displaying Hierarchical Data · 93

Microsoft Access 7.0 database, so highlight the Microsoft Access Driver (*.mdb)
selection and choose Finish.

4. Choosing Finish will display the ODBC Microsoft Access Setup Dialog.
NOTE: The Microsoft Access ODBC driver is installed by a number of applications, including
Access, Visual Basic, Visual C++ 5.0 and others.

The next step is to select a database file to work with. Click on the Select... button to bring up a
file browse dialog. Locate and select the TDBGDemo.mdb database in the Tutorial subdirectory
where you installed True DBGrid. When creating your own data sources, you will browse for the
database file you wish to work with and select it.

Once you have done that, enter a name for this data source in the Data Source Name box. For this
example, the DSN must be called TDBGDemo, because that is the name used in the tutorial code,
so enter TDBGDemo in the Data Source Name box. When you are finished, choose OK to close
the dialog.
94 · Tutorials

5. Choose OK to close ODBC Administrator. This concludes the creation of the ODBC Data Source.
Once the ODBC Data Source is created, you can reuse it over and over again—you will not have
to repeat these steps to use this database in a different project. In order for the ODBC Data Source
to work in conjunction with the hierarchical grid, you must also identify the actual recordsets to
be displayed. This is done in code for this tutorial.

6. Start a new project.

7. From the Visual Basic Project menu, select Components, then check the boxes labeled
ComponentOne True DBGrid Pro 8.0 (OLEDB) and Microsoft ADO Control 6.0 (OLEDB).
8. Place an ADO Data control (Adodc1) and a True DBGrid control (TDBGrid1) on the form as
shown in the following figure.
 Tutorial 24 - Displaying Hierarchical Data · 95

9. Set the DataView property of TDBGrid1 to 1 – Hierarchical.

10. Add the following code to the Form_Load event of the form:
Private Sub Form_Load()
Dim strCn As String
Dim strSh As String
' Create a ConnectionString.
strCn = "Provider=MSDataShape.1;Data Source=TDBGDemo;Data
Provider=MSDASQL"

' Create a Shape command.

strSh = "SHAPE {SELECT First, Last, Country FROM `Composer`} AS
Composer " & _
"APPEND ({SELECT Last, Opus FROM `Opus`} AS Opus RELATE " & _
"Last TO Last) AS Opus"
' Assign the ConnectionString to an ADO Data Control's
' ConnectionString property, and the Shape command to the
' control's RecordSource property.
With Adodc1
.ConnectionString = strCn
.RecordSource = strSh
.Visible = False
End With
' Set the grid control's DataSource property to the ADO Data control.
Set TDBGrid1.DataSource = Adodc1
With TDBGrid1
.ExtendRightColumn = True
.Styles("Normal").WrapText = True
End With
End Sub
96 · Tutorials

Run the program and observe the following:

• True DBGrid displays the data in a hierarchical format. There are two recordsets, or Bands
displayed in the grid: Composer and Opus. The code includes a Shape command that establishes
the master-detail relationship between the two recordsets based on the Last field, and also selects
which fields to display. The first three columns, from Composer, are populated with data, the last
two columns, from Opus, are empty. An expand icon ("+") appears at the left of each record.

• Click an expand icon. The record expands, displaying the related data held in the Last and Opus
columns. The expand icon changes to a collapse icon ("–").

• Click on the expanded record's collapse icon. The detail fields collapse, and the collapse icon
changes back to an expand icon. The grid now looks as it did when it first opened.
 Tutorial 25 - Outlook-Style Grouping · 97

Tutorial 25 - Outlook-Style Grouping

In this tutorial, you will learn how to use the Outlook-Style Grouping feature.
The purpose of outlook-style grouping is to allow you to move grid columns into a new split for
enhanced data display capabilities. When in Group mode, a "grouping area" is added to the grid,
providing an intuitive interface for creating a columns group.
When DataView is set to 2 - Group, and AllowColMove is set to True, the grid will support the ability to
group columns into the grouping area. This action can be performed by users at run time by selecting a
column and dragging its header into the grouping area. This action can also be performed in code at run
time by invoking the Add method of the GroupColumns collection. Use the Remove method of the
GroupColumns collection at run time to remove a column from the grouping area.
See Outlook-Style Grouping (page 278) for more information.
NOTE: The DataView property is only supported by the OLE DB version of True DBGrid.
1. Start a new project.
2. From the Visual Basic Project menu, select Components, then check the boxes labeled
ComponentOne True DBGrid Pro 8.0 (OLEDB) and Microsoft ADO Data Control 6.0 (OLEDB).
3. Place an ADO Data control (Adodc1) and a True DBGrid control (TDBGrid1) on the form
(Form1.)
4. Display the custom property pages for Adodc1. Click the General tab and select the Use
Connection String option. Click Build. The "Microsoft OLE DB Provider for ODBC Drivers"
option should be highlighted. Click Next>>. Enter the datasource name (TDBGDEMO.MDB) in
the Use Data source name text box. You do not have to enter a user name or password. Test the
connection to make sure it works. Close the dialog window.
Click the OK button to close the property page.
5. Set the CommandType property to 2 - adCmdTable.
6. Set the RecordSource property to Composer.
7. Set the DataSource property of TDBGrid1 to Adodc1.
8. Set the AllowAddNew and AllowDelete properties of TDBGrid1 to True (note that the default
value of AllowUpdate is True).
9. Set the DataView property of TDBGrid1 to 2 - Group
10. Open the Property Pages dialog. Select the Splits property page by clicking the Splits tab.
Expand the Splits(00) object and set the AllowColMove property to True. Click the OK button at
the bottom of the property page dialog to accept the changes. You have now finished
configuring the grid. The grid should look like the one in the following figure.
98 · Tutorials

11. Add the following code to GroupColMove event of TDBGrid1:

Private Sub TDBGrid1_GroupColMove(ByVal Position As Integer, ByVal
ColIndex As Integer, Cancel As Integer)
Dim strSort As String
Dim Col As TrueOleDBGrid80.Column
' Loop through GroupColumns collection and construct
' the sort string for the Sort property of the Recordset
For Each Col In TDBGrid1.GroupColumns
If strSort <> vbNullString Then
strSort = strSort & ", "
End If
strSort = strSort & "[" & Col.DataField & "]"
Next Col
TDBGrid1.HoldFields
Adodc1.Recordset.Sort = strSort
End Sub
Run the program and observe the following:
• Select the "Country" column and drag its header to the column group area as in the following
picture.
 Tutorial 25 - Outlook-Style Grouping · 99

• Release the mouse button and note the change in the grid's appearance. The rows are now sorted
by the "Country" field. In addition, the grid will automatically group the same values in the
grouped column into one cell.

• Select the "Last" column and drag its header to the grouping area.
100 · Tutorials

• The grid's display should change as in the following picture:

• Note that this time the data is sorted by both columns. Primary sort is done on "Country" and
secondary sort on "Last" field. This order corresponds to the following SQL statement:
SELECT * FROM Composer ORDER BY Country, Last
• Experiment with different columns.

Tutorial 26 - Value Translation

In this tutorial, you will learn how to use the Value Translation feature. Using this feature, you can
connect a TDBG dropdown control to a table which contains a value and representation and the
dropdown will automatically map the representation to the value.
 Tutorial 26 - Value Translation · 101

1. Start a new project.

2. From the Visual Basic Project menu, select Components, then check the boxes labeled
ComponentOne True DBGrid Pro 8.0 (OLEDB) and Microsoft ADO Data Control (OLEDB).
3. Place two ADO Data controls, a True DBGrid control and a True DBGrid Dropdown control on
the form. The form should look similar to this:

4. Next we will connect Adodc1 to the TDBG8Demo database.

Display the custom property pages for Adodc1. Click the General tab and select the Use
Connection String option. Click Build. Choose the Microsoft Jet 4.0 OLE DB Provider option. Click
Next>>. Enter the datasource name by pressing the Ellipsis button (…) and locating the database
(TDBGDEMO.MDB). Test the connection to make sure it works. Press OK to close the dialog
window. Press the Apply button.

• Choose the Recordsource tab. Set the Command Type to 2 – adCmdTable and the Table or
Stored Procedure Name to Customers. Press the OK button to accept the selections and close
the properties page.
5. Next we will connect Adodc2 to the TDBG8Demo database using the same method we used in
the previous step. After testing the connection and pressing the Apply button, choose the
Recordsource tab. Set the Command Type to 2 – adCmdTable and the Table or Stored Procedure
Name to CustType. Press the OK button to accept the selections and close the properties page.
6. Set the TDBGrid1 DataSource to Adodc1 and TDBDropDown1 DataSource to Adodc2.
7. Retrieve the fields for TDBGrid1 by right clicking within the grid and choosing Retrieve Fields
from the context menu.
8. Retrieve the fields for TDBDropdown1 by right clicking within the grid and choosing Retrieve
Fields from the context menu. The form should be similar to this:
102 · Tutorials

9. Go to the TDBDropdown1 properties page and set DataField property to TypeID, the ListField
property to TypeDesc and the ValueTranslate property to True.
10. Go to the TDBGrid1 properties page and choose the Splits tab. Expand the Splits(00) tree, then
the Columns tree then the Columns(06) [CustType] tree. Set the Order property to 1, the
AutoCompletion property to True, the AutoDropdown property to True and the Width property
to 1300. Press Apply.
11. Choose the General tab in TDBGrid1 properties page. Expand the Columns tree then the
Columns(06) [CustType] tree. Set the DropDown property to TDBDropdown1. Press Ok to accept
the changes and close the property pages.
12. Go to the TDBDropdown1 properties. On the General tab, expand the Columns tree then the
Columns(00) [TypeID] tree. Set the Visible property to False. Press Ok to accept the changes and
close the property pages.
Run the program and observe the following:
 Tutorial 27 - Range Selection · 103

• TDBGrid’s Value Translation has mapped the customer type and the type description
dropdown with the customers table.

Tutorial 27 - Range Selection

In this tutorial, you will see how you can select cell ranges and perform “cut and paste” functions in True
DBGrid.
1. Start a new project.
2. From the Visual Basic Project menu, select Components, then check the boxes labeled
ComponentOne True DBGrid Pro 8.0 (OLEDB) and Microsoft ADO Data Control (OLEDB).
3. Place an ADO Data control, a True DBGrid control and a command button on the form.
4. Next we will connect Adodc1 to the TDBG8Demo database.
Display the custom property pages for Adodc1. Click the General tab and select the Use
Connection String option. Click Build. Choose the Microsoft Jet 4.0 OLE DB Provider option. Click
Next>>. Enter the datasource name by pressing the Ellipsis button (…) and locating the database
(TDBGDEMO.MDB). Test the connection to make sure it works. Press OK to close the dialog
window. Press the Apply button.

• Choose the Recordsource tab. Set the Command Type to 2 – adCmdTable and the Table or
Stored Procedure Name to Customers. Press the OK button to accept the selections and close
the properties page.
5. Set the TDBGrid1 DataSource to Adodc1.
6. Change the caption of Command1 to Copy.
7. Add the following code to Command1:
Private Sub Command1_Click()
Dim rs As ADODB.Recordset
Dim strTemp As String 'string to be copied onto clipboard
Dim Col As Integer, row As Variant
If TDBGrid1.SelRange Then
'You must format the string so it can be pasted directly
'into Excel (tab delimited)
Set rs = Adodc1.Recordset.Clone
For Each row In TDBGrid1.SelBookmarks
rs.Bookmark = row
For Col = TDBGrid1.SelStartCol To TDBGrid1.SelEndCol
strTemp = strTemp & rs(Col).Value & vbTab
Next Col
strTemp = strTemp & vbCrLf
Next row
Clipboard.Clear
Clipboard.SetText strTemp, vbCFText
MsgBox "Range of " & CStr(Abs(TDBGrid1.SelEndCol -
TDBGrid1.SelStartCol) + 1) _
& " x " & CStr(TDBGrid1.SelBookmarks.Count) & _
" cells have been copied to the clipboard in TAB delimited
format"
Else
104 · Tutorials

MsgBox "Please select a range of cells"

End If
End Sub
8. Go to the True DBGrid property pages and set the MultiSelect property to Extended.
9. Run the program.
10. Click and drag a group of cells approximately like the example below.

11. With the cells highlighted press the Copy button.

12. Open an Excel spreadsheet and paste the cells into Excel.
 Tutorial 28 - Transposed Views · 105

Tutorial 28 - Transposed Views

In this tutorial, you will learn how to modify the grid appearance by using the new features incorporated
into the DataView property. Utilizing the flexibility of True DBGrid you can present data in a variety of
formats.
1. Start a new project.
2. From the Visual Basic Project menu, select Components, then check the boxes labeled
ComponentOne True DBGrid Pro 8.0 (OLEDB) and Microsoft ADO Data Control (OLEDB).
3. Place an ADO Data control, a True DBGrid control and a ComboBox on the form.
4. Next we will connect Adodc1 to the TDBG8Demo database.
Display the custom property pages for Adodc1. Click the General tab and select the Use
Connection String option. Click Build. Choose the Microsoft Jet 4.0 OLE DB Provider option. Click
Next>>. Enter the datasource name by pressing the Ellipsis button (…) and locating the database
(TDBGDEMO.MDB). Test the connection to make sure it works. Press OK to close the dialog
window. Press the Apply button.

• Choose the Recordsource tab. Set the Command Type to 2 – adCmdTable and the Table or
Stored Procedure Name to Customers. Press the OK button to accept the selections and close
the properties page.
5. Set the TDBGrid1 DataSource to Adodc1.
6. Change the Name property of the combo box to cboDataView and the Text property to Data View.
7. Open the List property of the Combo Box and add the following items:
0 - Normal
1 - Hierarchical
2 - Group
3 - Form
4 - Inverted
8. Next, add the following code, which inserts the button header, prevents the user from selecting
the hierarchical view at run time, selects the data view, and adjusts the row height for a more
pleasing appearance.
Dim Col As TrueOleDBGrid80.Column
Private Sub Form_Load()
For Each Col In TDBGrid1.Columns
Col.ButtonHeader = True
Next Col
End Sub
Private Sub Form_Activate()
cboDataView.ListIndex = dbgNormalView
End Sub
Private Sub cboDataView_Click()
' Hierarchical View is not available at run time
If cboDataView.ListIndex = dbgHierarchicalView Then
MsgBox "Hierarchical view must be set at design time"
cboDataView.ListIndex = dbgNormalView
End If
TDBGrid1.DataView = cboDataView.ListIndex
If TDBGrid1.DataView = dbgFormView Then
106 · Tutorials

TDBGrid1.RowHeight = 315
ElseIf TDBGrid1.DataView = dbgInvertedView Then
TDBGrid1.RowHeight = 330
Else
TDBGrid1.RowHeight = 225
End If
TDBGrid1.SetFocus
End Sub
9. Next, add the following code, which facilitates sorting in Group mode, adds bitmaps, and adjusts
the appearance.
Private Sub TDBGrid1_GroupColMove(ByVal Position As Integer, ByVal
ColIndex As Integer, Cancel As Integer)
' This is executed in the Group view after a column is
' dragged to the grouping area
Dim s As String
For Each Col In TDBGrid1.GroupColumns
If s <> vbNullString Then s = s & ", "
' Construct the "WHERE" part of the SQL statement
' that will be passed to the Sort property of the recordset
' object
s = s & "[" & Col.DataField & "]"
With Col.HeadingStyle
' Add a picture to the column header
.ForegroundPicture = LoadPicture(App.Path &
"\bitmaps\SortUp.bmp")
.ForegroundPicturePosition = dbgFPRight
.TransparentForegroundPicture = True
End With
Next Col
' Change the split divider
If TDBGrid1.Splits.Count > 1 Then
TDBGrid1.Splits(1).DividerStyle = dbgDarkGrayLine
End If
TDBGrid1.HoldFields
' Apply the sorting
Adodc1.Recordset.Sort = s
End Sub
10. Run the program. It should look like this.
 Tutorial 28 - Transposed Views · 107

11. Set the combo to 1 – Hierarchical and you will receive this message box:

12. Change the combo box to 2 – Group. Drag the Company column header to the top section of the
grid header. Notice that the grid automatically groups the cells in relation to the new title.

13. Change the combo box to 3 – Form. Notice that the grid reconfigures the data into the form style.
108 · Tutorials

14. Change the combo box to 4 – Inverted. Notice that the grid automatically inverts the rows and
columns placing the user code across the top of the grid.

Tutorial 29 - Filter Bar

In this tutorial you will utilize the FilterBar property in True DBGrid. Using the Filter Bar feature of True
DBGrid, you can narrow the number of items in a given table by filtering the underlying recordset.
1. Start a new project.
2. From the Visual Basic Project menu, select Components, then check the boxes labeled
ComponentOne True DBGrid Pro 8.0 (OLEDB) and Microsoft ADO Data Control (OLEDB).
3. Place an ADO Data control, a True DBGrid control and a command button on the form.
4. Next we will connect Adodc1 to the TDBG8Demo database.
Display the custom property pages for Adodc1. Click the General tab and select the Use
Connection String option. Click Build. Choose the Microsoft Jet 4.0 OLE DB Provider option. Click
Next>>. Enter the datasource name by pressing the Ellipsis button (…) and locating the database
(TDBGDEMO.MDB). Test the connection to make sure it works. Press OK to close the dialog
window. Press the Apply button.

• Choose the Recordsource tab. Set the Command Type to 2 – adCmdTable and the Table or
Stored Procedure Name to Composer. Press the OK button to accept the selections and close
the properties page.
5. Set the TDBGrid1 DataSource to Adodc1.
6. Change the caption of Command1 to Clear Filter and change the Name to cmdClearFilter.
7. Open the TDBGrid property pages and select the Splits tab. Set the FilterBar property to True.
8. Add the following code to cmdClearFilter:
 Tutorial 29 - Filter Bar · 109

Dim col As TrueOleDBGrid80.Column

Dim cols As TrueOleDBGrid80.Columns
Private Sub cmdClearFilter_Click()
'Clears filter from grid
For Each col In TDBGrid1.Columns
col.FilterText = ""
Next col
Adodc1.Recordset.Filter = adFilterNone
End Sub
Private Sub TDBGrid1_FilterChange()
'Gets called when an action is performed on the filter bar
On Error GoTo errHandler
Set cols = TDBGrid1.Columns
Dim c As Integer
c = TDBGrid1.col
TDBGrid1.HoldFields
Adodc1.Recordset.Filter = getFilter()
TDBGrid1.col = c
TDBGrid1.EditActive = True
Exit Sub
errHandler:
MsgBox Err.Source & ":" & vbCrLf & Err.Description
Call cmdClearFilter_Click
End Sub
Private Function getFilter() As String
'Creates the SQL statement in adodc1.recordset.filter
'and only filters text currently. It must be modified to
'filter other data types.

Dim tmp As String

Dim n As Integer
For Each col In cols
If Trim(col.FilterText) <> "" Then
n = n + 1
If n > 1 Then
tmp = tmp & " AND "
End If
tmp = tmp & col.DataField & " LIKE '" & col.FilterText &
"*'"
End If
Next col
getFilter = tmp
End Function
9. Run the program. Your Form should look similar to this:
110 · Tutorials

10. Type B in the filter box located below Last header and type A in the filter box located below the
Country header. You will notice that TDBGrid filters the two columns alphabetically. You now
have a list of just the composers whose names start with B and who live in a country starting with
A.

11. Next, press the Clear Filter button and try typing in the filter box located below the Birth
column. You get an error message from the provider because the filter bar is set to filter only text.
To filter dates or any other type of data, you must alter the code.
 Tutorial 30 - Cell Bordering and Scroll Tips/Tracking · 111

Tutorial 30 - Cell Bordering and Scroll Tips/Tracking

In this tutorial you will utilize the Cell Border, Scroll Tips and Scroll Tracking features in True DBGrid.
The Cell Border feature allows you to manipulate border options at runtime, while the Scroll Tips and
Scroll Tracking features allow you to track the location of your scroll bar and give the user an
informational pop-up as the scroll bar moves.
1. Start a new project.
2. Based on the following illustration, place these three controls on the form: a True DBGrid control
(TDBGrid1), an ADO Data control (Adodc1), a Common Dialog control (Cdlg).

Next, below the ADO data control, place a control array of check boxes named chkBorderType (0-
3), where Top is 0, Left is 1, Bottom is 2 and Right is 3. Set the captions accordingly and set the
Alignment property of the Left check box to 1 - Right Justify.

To the right of the check boxes, place two combo boxes. Name the first one cboBorderAppearance
and set its Text property to Border Appearance. Name the second one cboBorderSize and set its Text
property to Border Size.

Add a command button named cmdColor and set its Caption to Border Color.

Finally, add a frame and place two check boxes (chkSTips and chkSTracking) inside it. Set the
Caption properties as shown in the illustration.

3. Next we will connect Adodc1 to the TDBG8Demo database:

• Display the custom property pages for Adodc1. Click the General tab and select the Use
Connection String option. Click Build. Choose the Microsoft Jet 4.0 OLE DB Provider option.
Click Next>>. Enter the datasource name by pressing the ellipsis button (…) and locating the
112 · Tutorials

database (TDBGDEMO.MDB). Test the connection to make sure it works. Press OK to close
the dialog window. Press the Apply button.
• Choose the Recordsource tab. Set the Command Type to 2 – adCmdTable and the Table or
Stored Procedure Name to Customers. Press the OK button to accept the selections and close
the properties page.
4. Set the TDBGrid1 DataSource to Adodc1.
5. Set the List property of cboBorderAppearance to:
Flat (Default)
3D Raised
3D Inset
3D Raised Bevel
3D Inset Bevel
With the following code:

Private Sub cboBorderAppearance_Click()

Call setStyle
End Sub
6. Set the List property of cboBorderSize to 0 through 10 and add the following code:
Private Sub cboBorderSize_Click()
Call setStyle
End Sub
7. Set the RowHeight property of TDBGrid1 to 400.
8. Add the following code to cmdColor:
Private Sub cmdColor_Click()
cdlg.ShowColor
Call setStyle
End Sub
9. Add the following code to chkSTracking:
Private Sub chkSTracking_Click()
TDBGrid1.ScrollTrack = chkSTracking.Value
End Sub
10. Add the following code to chkSTips:
Private Sub chkSTips_Click()
TDBGrid1.ScrollTips = chkSTips.Value
End Sub
11. Add the following code:
Option Explicit
Dim recset As ADODB.Recordset
Dim border As TrueOleDBGrid80.StyleBorderTypeConstants
Private Sub chkBorderType_Click(Index As Integer)
Dim chk As CheckBox
border = dbgBorderNone

For Each chk In chkBorderType

If chk.Value Then
Select Case chk.Index
Case 0:
border = border Or dbgBorderTop
 Tutorial 30 - Cell Bordering and Scroll Tips/Tracking · 113

Case 1:
border = border Or dbgBorderLeft
Case 2:
border = border Or dbgBorderBottom
Case 3:
border = border Or dbgBorderRight
End Select
End If
Next chk
Call setStyle
End Sub
Private Sub Form_Load()
'Recordset for use with scroll tips/tracking
Set recset = Adodc1.Recordset.Clone
cdlg.Color = vbGreen
cboBorderAppearance.ListIndex = 3
cboBorderSize.ListIndex = 5
End Sub
Private Sub setStyle()
cmdColor.BackColor = cdlg.Color
With TDBGrid1.Columns(TDBGrid1.Col).Style
.BorderSize = IIf(cboBorderSize.ListIndex < 0, 0,
cboBorderSize.ListIndex)
.BorderColor = cdlg.Color
.BorderType = border
.BorderAppearance = IIf(cboBorderAppearance.ListIndex < 0, 0,
cboBorderAppearance.ListIndex)
End With
End Sub

Private Sub TDBGrid1_FetchScrollTips(ByVal SplitIndex As Integer, ByVal

ColIndex As Integer, _
Bookmark As Variant, ByVal ScrollBar As
TrueOleDBGrid80.ScrollBarsConstants, _
ScrollTip As String, ByVal TipStyle As TrueOleDBGrid80.StyleDisp)
' Gets called when scrolling occurs.
' Set the ScrollTip depending on which
' scroll bar was moved
Select Case ScrollBar
Case dbgVertical:
recset.Bookmark = Bookmark
ScrollTip = "Record: " & CStr(recset.AbsolutePosition) & " of "
& CStr(recset.RecordCount) & vbCrLf & _
"Company: " & recset("Company").Value & vbCrLf & _
"UserCode: " & recset("UserCode").Value
Case dbgHorizontal:
ScrollTip = TDBGrid1.Columns(ColIndex).Caption
End Select
TipStyle.ForeColor = vbBlue
End Sub
12. Run the program and you should have a form that looks like this:
114 · Tutorials

• Notice how you can now manipulate border options at run-time by using the check boxes
and drop down menus.

• Click on the Scroll Tips and Scroll Tracking check boxes. Notice how information is displayed
as you scroll through the table using the scroll bar.
 Tutorial 30 - Cell Bordering and Scroll Tips/Tracking · 115

Congratulations, you have successfully completed all 30 tutorials!

 True DBGrid Objects and Collections · 117

Object Model
True DBGrid was developed using the latest ActiveX and data binding technologies. The True DBGrid
control and its programmable components are all ActiveX objects designed according to Microsoft
specifications. If you are already familiar with the Visual Basic object and collection models, you will
have no problem using True DBGrid.
If you are new to Visual Basic, please read Working with Objects and Collections (page 123), which
illustrates how to manipulate True DBGrid objects in code. Although individual objects are designed to
perform different tasks, the techniques used to manipulate them are the same. Once you have mastered
these common programming constructs, using Visual Basic and ActiveX controls will be quite easy and
intuitive.
Regardless of your experience level, please read the following section, as it provides a thumbnail sketch
of all True DBGrid objects and collections.

True DBGrid Objects and Collections

True DBGrid provides a rich set of properties, methods, and events that enable you to develop
sophisticated database applications. The organization imposed by True DBGrid's object model makes it
easier to work with such a large feature set.
Objects and collections that refer to visual entities, such as columns, can be customized at design time or
run time. Objects and collections that refer to abstract entities, such as arrays and bookmarks, are only
available in code at run time.
When you add True DBGrid to a Visual Basic project, the following controls are added to the toolbox:
TDBGrid True DBGrid ActiveX control.
TDBDropDown True DBDropDown ActiveX control.
The type library for True DBGrid also contains definitions for the following objects:
Column Represents a column of data within a grid or split.
DataObject Transfers data between OLE drag sources and drop targets.
PrintInfo Encapsulates page setup and print job settings.
RowBuffer Transfers data to and from row-based unbound mode events.
Split Represents a group of adjacent columns that scroll as a unit.
Style Encapsulates font, color, picture, and formatting information.
ValueItem Allowable input value for a column, with optional translation.
A collection is an object used to group similar data items, such as bookmarks, or visual objects, such as
grid columns. In general, a group of similar items in True DBGrid is implemented as a collection. Since a
collection is an object, you can manipulate it in code just as you would any other object. The type library
for True DBGrid contains definitions for the following collections:
Columns Contains zero or more Column objects in a grid or split.
Errors Contains zero or more Error objects associated with a grid.
GroupColumns Contains zero or more Column objects in the grouping area.
118 · Object Model

Layouts Contains zero or more named grid layouts.

PrintInfos Contains one or more PrintInfo objects in a grid.
SelBookmarks Contains zero or more selected row bookmarks.
Splits Contains one or more Split objects in a grid.
Styles Contains built-in and user-defined Style objects for a grid.
ValueItems Contains zero or more ValueItem objects for a column.
NOTE: The Errors and GroupColumns collections are available only in the OLE DB grid, and are not
available in the legacy (ICursor) version.
When using True DBGrid's storage mode (DataMode 4), you also need to add a reference to the
ComponentOne XArrayDB Object to your project. This is not a control, but a reference that defines a
single nongraphical object:
XArrayDB Variant array used as a data source in storage mode.
The following sections provide a brief overview of True DBGrid's objects and collections.

TDBGrid Control
The TDBGrid control is the primary object of True DBGrid. Using its Columns collection, you can create,
access, and modify the Column objects that define the mappings between the grid's physical columns
and the underlying database fields. Using its Splits collection, you can divide the grid into multiple
vertical panes to provide different views of the same data source.
Whether you use the legacy grid (TDBG8.OCX) or the OLE DB grid (TODG8.OCX), the control's class
name appears in the Object Browser as TDBGrid.
The DataMode property determines whether the grid connects to a bound data source, fires unbound or
application mode events to retrieve data, or operates in storage mode. In bound mode, the DataSource
and DataMember properties specify the source database table or query. In storage mode, you can set the
Array property in code to use an independent XArrayDB object as a data source.
See Also
Design Time Interaction (page 129)
Run Time Interaction (page 181)
Bound Mode (page 195)
Storage Mode (page 205)
Application Mode (page 211)
Unbound Mode (page 219)
Reference Topics
TDBGrid Control Properties (page 347)
TDBGrid Control Methods (page 351)
TDBGrid Control Events (page 352)

TDBDropDown Control
The TDBDropDown control, which is a subset of the TDBGrid control, is used as a multicolumn drop-
down list box for a grid column. You cannot use it as a standalone control.
 Column Object, Columns Collection · 119

At design time, you can place a TDBDropDown control on a Visual Basic form just as you would a
TDBGrid control. However, the drop-down control will be invisible at run time unless it is attached to a
Column object of a TDBGrid control.
To use the drop-down control, set the DropDown property of a grid column to the name of a
TDBDropDown control at either design time or run time. At run time, when the user clicks the in-cell
button for that column, the TDBDropDown control will appear below the grid's current cell. If the user
selects an item from the drop-down control, the grid's current cell is updated. The TDBDropDown
control also supports incremental search.
See Also
TDBDropDown at Design Time (page 179)
Using the TDBDropDown Control (page 342)
Reference Topics
TDBDropDown Control Properties (page 573)
TDBDropDown Control Methods (page 575)
TDBDropDown Control Events (page 576)

Column Object, Columns Collection

Each column within a TDBGrid control, TDBDropDown control, or Split object is represented by a
Column object. When a grid or drop-down control is bound to a database, each Column object is usually
associated with a database field, although True DBGrid also supports unbound columns in bound mode.
When a control is first created, it contains two Column objects by default.
The TDBGrid control, the TDBDropDown control, and the Split object all maintain a Columns
collection to hold and manipulate Column objects. This collection is accessed using the Columns
property.
See Also
Configuring Columns at Run Time (page 20)
Reference Topics
Column Object Properties (page 355)
Column Object Methods (page 357)

DataObject Object, DataObjectFiles Collection

The DataObject object is a placeholder for data being transferred between source and target components.
It mirrors the IDataObject interface, which is the protocol used for OLE drag-and-drop and clipboard
operations.
The TDBGrid control supplies an argument of type DataObject when it fires the following events:
OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.
The DataObjectFiles collection is not supported by True DBGrid. However, it is defined in the type
library because it is referenced by the DataObject object.
See Also
Tutorial 14 (page 61)
120 · Object Model

Reference Topics
DataObject Object Properties (page 357)
DataObject Object Methods (page 357)

Error Object, Errors Collection

OLE DB data sources can generate more than one error in response to a single failure. Simple providers
generate a single error object, but more advanced ones can generate more than one object. This is because
a provider can consist of several components and each component may have something to say about the
error.
The first (main) error object is generated when an error condition first occurs in one of the provider's
components. This is the original source of the error, which is usually used to describe the error. Then
components that called it can add their own description of the error. In most cases, only the original
(deepest in call stack) error matters, but sometimes users need to examine the whole set (collection) of
generated errors. For example, the MS OLE DB provider for SQL Server generates multiple error objects
in response to a single failure.
TDBGrid's Error event only shows one error, the original (main) one. This would not be a problem if the
user would always have access to the ADO Errors collection in the data source. However, ADO fills its
Errors collection only in response to direct calls to ADO methods. For example, the Errors collection will
be filled for a failed Recordset.Update call, but it won't be filled on a failed update initiated by the
grid.
For this reason, the TDBGrid control (OLE DB version only) maintains its own collection of Error objects
to hold information about errors caused by interaction with the grid's OLE DB data source. This collection
is accessed using the Errors property.
Reference Topics
Error Object Properties (page 357)
Errors Collection Properties (page 358)
Errors Collection Methods (page 358)

GroupColumns Collection
When the DataView property is set to 2 - Group, a grouping area is created above the grid; columns may
be added to this area to form a group, creating a new split in the grid. Each column that is placed into the
group becomes a member of the GroupColumns collection, while remaining a member of the Columns
collection. If the column is removed from the GroupColumns collection, it is returned to the grid; it is not
deleted.
The TDBGrid control (OLE DB version only) maintains a GroupColumns collection to hold and
manipulate grouped columns. This collection is accessed using the GroupColumns property.
See Also
Outlook-Style Grouping (page 278)
Reference Topics
GroupColumns Collection Properties (page 358)
GroupColumns Collection Methods (page 358)
 Layouts Collection · 121

Layouts Collection
In True DBGrid, the term layout refers to the complete set of persistent properties for a TDBGrid or
TDBDropDown control, including its design-time collections. You can store one or more grid layouts in
a binary file, then recall them later. You can even take advantage of this feature in code to enable your
end users to save their layout preferences.
The Layouts collection facilitates switching between multiple named layouts at either design time or run
time. Both the TDBGrid and TDBDropDown controls support this collection.
See Also
Reusable Layouts (page 178)
Reference Topics
Layouts Collection Properties (page 358)
Layouts Collection Methods (page 358)

PrintInfo Object, PrintInfos Collection

The PrintInfo object is used to specify page layout and print job characteristics such as the name of the
output device, margin settings, page headers and footers, and the number of copies to print. When a
TDBGrid control is first created, its PrintInfos collection contains a single PrintInfo object representing
the system default printer.
The PrintInfo property of a TDBGrid control returns the default member of its PrintInfos collection.
Through this default member, you can access the PageSetup, PrintData, and PrintPreview methods in
code.
The PrintInfos collection is persistent, which means that you can define multiple print layouts at design
time, then recall them in code at run time.
Reference Topics
PrintInfo Object Properties (page 665)
PrintInfo Object Methods (page 666)

RowBuffer Object
The RowBuffer object is only used when the DataMode property is set to 1 - Unbound or 2 - Unbound
Extended. It exists only to transfer data to and from the grid in the row-based unbound mode events. You
cannot create a standalone RowBuffer object.
See Also
Unbound Mode (page 219)
Reference Topics
RowBuffer Object Properties (page 358)

SelBookmarks Collection
When the user selects and highlights one or more rows of a TDBGrid control at run time, the bookmarks
of the selected rows are stored in the SelBookmarks collection. In code, you can use its Count property
and Item method to determine which rows are selected. You can also select and deselect records
122 · Object Model

programmatically using its Add and Remove methods. This collection is accessed using the
SelBookmarks property.
See Also
Selecting and Highlighting Records (page 240)
Reference Topics
SelBookmarks Collection Properties (page 359)
SelBookmarks Collection Methods (page 359)

Split Object, Splits Collection

True DBGrid supports Excel-like splits that divide the grid into vertical panes to provide users with
different views of the data source. Each split is represented by a Split object and contains a group of
adjacent columns that scroll as a unit.
When a TDBGrid control is created, it contains one Split object by default. Many of the properties of the
Split object also apply to the TDBGrid control as a whole, so you do not need to concern yourself with
splits until you actually need to use them, such as when creating fixed, nonscrolling columns.
The TDBGrid control maintains a Splits collection to hold and manipulate Split objects. A grid has one
split by default, but may contain multiple splits. This collection is accessed using the Splits property.
See Also
How to Use Splits (page 293)
Reference Topics
Split Object Properties (page 359)
Split Object Methods (page 360)
Splits Collection Properties (page 361)
Splits Collection Methods (page 361)

Style Object, Styles Collection

Style objects encapsulate font, color, picture, and formatting information for a TDBGrid,
TDBDropDown, Split, or Column object. The Style object is a very flexible and powerful tool that
provides Excel- and Word-like formatting capabilities for controlling the appearance of the grid's display.
When a TDBGrid or TDBDropDown control is created, it contains ten built-in styles. You can modify
the built-in styles or add your own styles at either design time or run time. Both controls also support
several optional events that use Style objects to convey formatting information on a per-cell or per-row
basis.
The TDBGrid and TDBDropDown controls store all built-in and user-defined Style objects in the Styles
collection. You can access the members of this collection by name at run time, then apply them to a grid,
column, or split in order to control the appearance of the object in question. This collection is accessed
using the Styles property.
See Also
How to Use Styles (page 307)
 ValueItem Object, ValueItems Collection · 123

Reference Topics
Style Object Properties (page 361)
Style Object Methods (page 361)
Styles Collection Properties (page 361)
Styles Collection Methods (page 361)

ValueItem Object, ValueItems Collection

A ValueItem object is used to simplify data access for the user. It specifies an allowable input value for a
given Column object, and can also be used to translate raw data values into alternate text or graphics for
display. For example, you may want to display Balance Due and Paid in Full instead of the numeric data
values 0 and 1.
Each Column object within a TDBGrid or TDBDropDown control stores these items, if specified, in a
ValueItems collection, which is accessed using the ValueItems property.
See Also
Automatic Data Translation with ValueItems (page 265)
Automatic Data Translation with TDBDropdown (page 343)
Reference Topics
ValueItem Object Properties (page 362)
ValueItems Collection Properties (page 362)
ValueItems Collection Methods (page 362)

XArrayDB Object
The XArrayDB object implements a two-dimensional array of arbitrary variants. XArrayDB objects
automatically shift their contents when rows (or columns) are inserted or deleted. You can use the Find
and QuickSort methods to perform searching and sorting without having to iterate over the array
elements yourself.
Unlike the RowBuffer object, you can create one or more standalone XArrayDB objects in code. You can
even use XArrayDB outside the context of True DBGrid, as it is packaged as a separate file, XADB8.OCX,
which is not dependent upon any of the grid .OCX files.
The XArrayDB object is used as a data source for a TDBGrid or TDBDropDown control in storage
mode, which corresponds to a DataMode property setting of 4 - Storage. To connect an XArrayDB object
to a storage mode control, set the control's Array property.
See Also
Storage Mode (page 205)
Reference Topics
XArrayDB Object Properties (page 689)
XArrayDB Object Methods (page 689)

Working with Objects and Collections

This section describes how to work with objects and collections in Visual Basic code, with an emphasis on
efficiency. Although the concepts are illustrated with True DBGrid objects and collections, you can apply
the same fundamentals to all Visual Basic objects and collections.
124 · Object Model

A TDBGrid object is created when you place a True DBGrid control on a Visual Basic form. TDBGrid
objects created in Visual Basic will have default names of TDBGrid1, TDBGrid2, and so forth. You can
change the control name in the Visual Basic Properties window at design time. You can also change the
control's properties using the property pages at design time and Visual Basic code at run time.
A TDBGrid object has the following collections: Splits, Columns, SelBookmarks, Styles, Layouts, and
PrintInfos. By default, the Splits collection contains one Split object, and the Columns collection
contains two Column objects. The Styles collection contains ten default Style objects: Normal, Heading,
Footing, Selected, Caption, HighlightRow, EvenRow, OddRow, RecordSelector, and FilterBar. The PrintInfos
collection contains one PrintInfo object for accessing the system default printer. The SelBookmarks and
Layouts collections are initially empty.
You can reference an object in a collection using its zero-based index. For example, the default Split
object in a grid has an index value of 0. You can read or set the Split object's properties as follows:
' Read a Split object property
variable = TDBGrid1.Splits(0).Property
' Set a Split object property
TDBGrid1.Splits(0).Property = variable
You can create a reference to an object in a collection using the collection's Item method. The following
code creates a reference to a grid's default Split object:
' Declare Split0 as a Split object
Dim Split0 As TrueDBGrid80.Split
' Set Split0 to reference the first Split in the collection
Set Split0 = TDBGrid1.Splits.Item(0)
Note the use of the type library qualifier TrueDBGrid80 in the preceding example. Using the type
library qualifier is recommended in order to resolve potential naming conflicts with other controls. For
example, if you use another control in the same project that also defines an object named Split, the
TrueDBGrid80 type library qualifier is required, as is the type library qualifier for the other control.
NOTE: If you are using the OLE DB version of True DBGrid, the type library qualifier is
TrueOleDBGrid80 instead of TrueDBGrid60. The object names are the same.
Since the Item method is implicit for collections, you can omit it:
' Declare Split0 as a Split object
Dim Split0 As TrueDBGrid80.Split
' Set Split0 to reference the first Split in the collection
Set Split0 = TDBGrid1.Splits(0)
You can now use Split0 to read or set the Split object's properties or to execute its methods:
variable = Split0.Property ' Read a Split object property
Split0.Property = variable ' Set a Split object property
Split0.Method arg1, arg2, ... ' Execute a Split object method
Very often, you need to read and set more than one of an object's properties. For example:
' Read a Split object's properties
variable1 = TDBGrid1.Splits(0).Property1
variable2 = TDBGrid1.Splits(0).Property2

' Set a Split object's properties

TDBGrid1.Splits(0).Property1 = variable1
TDBGrid1.Splits(0).Property2 = variable2
 Working with Objects and Collections · 125

This code is very inefficient because each time the object TDBGrid1.Splits(0) is accessed, Visual Basic
creates a reference to the object and then discards it after the statement is completed. It is more efficient to
create a single reference to the object up front and use it repeatedly:
' Declare Split0 as a Split
Dim Split0 As TrueDBGrid80.Split
' Set Split0 to reference the first Split in the collection
Set Split0 = TDBGrid1.Splits(0)
' Read a Split object's properties
variable1 = Split0.Property1
variable2 = Split0.Property2
' Set a Split object's properties
Split0.Property1 = variable1
Split0.Property2 = variable2
This code is much more efficient and also easier to read. If your Visual Basic application accesses
collection objects frequently, you can improve the performance of your code significantly by adhering to
these guidelines.
Similarly, you can apply this technique to other objects and collections of True DBGrid, and of Visual
Basic in general. Of particular importance to the grid are the Column object and Columns collection:
' Declare Cols as a Columns collection object, then set it to
' reference TDBGrid1's Columns collection object.
Dim Cols As TrueDBGrid80.Columns
Set Cols = TDBGrid1.Columns
' Declare Col0 as a Column object, then set it to reference the
' first Column object in the collection.
Dim Col0 As Column
Set Col0 = Cols(0)

' Read and set the Column object's Property1

variable1 = Col0.Property1
Col0.Property1 = variable1
' Execute the Column object's Method1 (declared as a Sub)
Col0.Method1 arg1, arg2, ...
' Execute the Column object's Method2 (declared as a Function)
variable2 = Col0.Method2(arg1)
Visual Basic also provides an efficient With...End With statement for setting multiple properties of an
object without explicitly assigning it to a variable. For example, the following code sets multiple
properties of the first column of a grid (recall that collections are zero-based):
With TDBGrid1.Columns(0)
.Property1 = variable1
.Property2 = variable2
End With
Some collections allow you to reference their members by name. For example, you can reference a
Column object using either its index, the name of the database field the column is associated with, or the
column's heading caption. Thus, the following statements are equivalent:
' Declare Col0 as a Column object
Dim Col0 As TrueDBGrid80.Column
' Reference by numeric index
Set Col0 = TDBGrid1.Columns.Item(0)
126 · Object Model

' Reference by numeric index (Item method is implicit)

Set Col0 = TDBGrid1.Columns(0)
' Reference by database field name
Set Col0 = TDBGrid1.Columns("LAST")
' Reference by column header text (Caption property)
Set Col0 = TDBGrid1.Columns("Last Name")
A True DBGrid Style object can also be referenced by name:
' Declare S as a Style object
Dim S As TrueDBGrid80.Style
' Set S to the grid's built-in Normal style
Set S = TDBGrid1.Styles("Normal")
' Set S to the programmer-defined style MyStyle
Set S = TDBGrid1.Styles("MyStyle")
To create and add an object to a collection, use the collection's Add method. For example, you can create
more splits in the grid by adding new Split objects to the Splits collection:
' Create a Split object with index 0
Dim S As TrueDBGrid80.Split
Set S = TDBGrid1.Splits.Add(0)
This code adds a Split object with index 0 to the Splits collection of TDBGrid1. The original Split object
now has an index of 1. Alternatively, you can create a Split object with index 1:
' Create a Split object with index 1
Dim S As TrueDBGrid80.Split
Set S = TDBGrid1.Splits.Add(1)
Note that the Add method of the Splits collection is used like a function, with its arguments (here, the
split index) enclosed in parentheses. Also, since the Add method always returns a reference to the Split
object that was just created, you must precede the assignment statement with the Visual Basic Set
keyword.
However, not all collections define their Add method to return a value. If a collection does nothing more
than maintain a list of the arguments passed to its Add method, then there is no need for it to return the
same item that was just added. In True DBGrid, the Layouts, SelBookmarks, and ValueItems collections
are designed this way. For example, you can use the following code to select the current record in a
TDBGrid control:
TDBGrid1.SelBookmarks.Add TDBGrid1.Bookmark
Since the SelBookmarks collection manages a list of variants corresponding to selected grid rows, its Add
method does not return a value, and no assignment statement is needed. This example could also be
coded as:
With TDBGrid1
.SelBookmarks.Add .Bookmark
End With
Regardless of how a collection implements the Add method, the syntax for removing items is the same.
To remove an existing item from a collection, use the Remove method:
' Remove the Split object with index 1
TDBGrid1.Splits.Remove 1
After this statement is executed, all splits with collection indexes greater than 1 will be shifted down by 1
to fill the place of the removed split. Note that the Remove method is called like a subroutine—its
argument is not enclosed in parentheses.
 Working with Objects and Collections · 127

You can determine the number of objects in a collection using the collection's Count property:
' Set a variable equal to the number of Splits in TDBGrid1
variable = TDBGrid1.Splits.Count
You can also iterate through all objects in a collection using the Count property as in the following
example, which prints the Caption string of each Column object in a grid:
For n = 0 To TDBGrid1.Columns.Count - 1
Debug.Print TDBGrid1.Columns(n).Caption
Next n
The Count property is also useful for appending and removing columns:
' Determine how many columns there are
Dim NumCols As Integer
NumCols = TDBGrid1.Columns.Count
' Append a column to the end of the Columns collection
Dim C As TrueDBGrid80.Column
Set C = TDBGrid1.Columns.Add(NumCols)
' Make the new column visible, since columns created
' at run time are invisible by default
TDBGrid1.Columns(NumCols).Visible = True
' The following loop removes all columns from the grid
While TDBGrid1.Columns.Count
TDBGrid1.Columns.Remove 0
Wend
Visual Basic also provides an efficient For Each...Next statement that you can use to iterate through
the objects in a collection without using the Count property:
Dim C As TrueDBGrid80.Column
For Each C In TDBGrid1.Columns
Debug.Print C.Caption
Next S
In fact, using the For Each...Next statement is the preferred way to iterate through the objects in a
collection.
 Context Menu · 129

Design Time Interaction

You can easily configure True DBGrid at design time using its context menu, visual editing mode,
property pages, and reusable layout facility. These features enable you to see the grid's run-time
appearance at design time and eliminate the need to write customization code for most applications.
The following sections describe how to use True DBGrid's design-time environment to configure the
TDBGrid control. Most of the following material also applies to the TDBDropDown control since it is a
subset of TDBGrid. Specific differences between the two controls are discussed at the end of this chapter.

Context Menu
Right-click anywhere on the grid to display the True DBGrid context menu, which is a superset of the
context menu that Visual Basic provides for all ActiveX controls.

The first eight commands are controlled by Visual Basic; the last four commands are controlled by True
DBGrid. The context menu commands operate as follows.

Cut, Copy, Paste, Delete

These commands are identical to those on the Visual Basic Edit menu. Cut (CTRL+X) moves the grid from
the Visual Basic form to the Clipboard. Copy (CTRL+C) moves a copy of the grid to the Clipboard while
leaving the grid on the form intact. Paste (CTRL+V) copies the grid from the Clipboard to the form. Delete
(the DEL key) removes the grid but does not move it to the Clipboard. You can undo the Delete command
by selecting Undo (CTRL+Z) from the Visual Basic Edit menu.

Bring To Front, Send To Back

These commands control the z-order of the grid relative to the other objects on the Visual Basic form.
Bring To Front (CTRL+J) places the grid in front of other objects; Send To Back (CTRL+K) places it behind
130 · Design Time Interaction

other objects. These commands are also available from the Visual Basic Edit menu. The Zorder (Visual
Basic) method can be used to change the z-order of controls at run time.

View Code
This command displays the grid's code window, which enables you to view and edit the grid's event
handling code.

Align to Grid
This command automatically aligns the outer edges of the grid control to the design-time grid lines on the
form.

Edit
This command switches to True DBGrid's visual editing mode, in which you can interactively change the
grid's column layout and row height. Within visual editing mode, you can right-click anywhere on the
grid to display a different context menu called the visual editing menu. Using the visual edit menu, you
can manipulate individual columns and splits directly on the surface of the grid. For convenience, the
visual editing menu also contains some of the context menu commands. For details, see Visual Editing
Mode (page 130).

Properties…
This command displays the grid's property pages, which enable you to customize the layout and
appearance of the grid at design time. You can also display the property pages by selecting (Custom)
from the Visual Basic Properties window. For details, see Property Page Overview (page 135).

Retrieve Fields
This command automatically configures the grid's columns according to the schema information
obtained from the Data control's Recordset. If you have already changed the grid's default layout, True
DBGrid will ask for confirmation before discarding your changes. By default, the grid will use the
database field names, or SQL aliases, as the column headings. If all of the columns do not fit in the visible
portion of the grid, a horizontal scroll bar will appear. The scroll bar is usable only when the grid is in
visual editing mode as described in the next section.

Clear Fields
This command clears all column layouts and field names. Use this command to force a bound grid to use
automatic layouts at run time.

Visual Editing Mode

To enter True DBGrid's visual editing mode, right-click anywhere on the grid to display the context
menu, then click Edit. The appearance of the grid does not change; however, when you move the mouse
over the column headers, column dividers, or row dividers, the mouse pointer changes to indicate that
the object can be selected or resized.
To exit visual editing mode, select another control or click anywhere on the form outside the grid. The
next time you right-click the grid, the context menu will appear, not the visual editing menu.
You can use visual editing mode to interactively perform any of the following tasks:
• Create and delete columns and splits.
 Visual Editing Mode · 131

• Move and resize columns within the grid.

• Move columns to and from the Clipboard.
• Adjust the grid's row height.
• Save the current grid layout to a file.
• Load and remove grid layouts stored in a file.
The following sections provide step-by-step instructions for using visual editing mode.

Sizing columns and rows

If necessary, use the horizontal scroll bar to bring the desired column into view. Move the pointer over a
column divider in the column header area. The pointer will become a horizontal double arrow.

Simply drag the divider left or right to adjust the width of the corresponding column. Dragging the
divider all the way to the left has the same effect as setting the column's Visible property to False. To
redisplay an invisible column, move the pointer over the preceding column divider until it changes to a
horizontal right arrow.

Drag the divider to the right to make the column visible and adjust its width.
To adjust the height of all grid rows, move the pointer over a row divider in the record selector column.
The pointer will become a vertical double arrow.

Drag the divider up or down to adjust the row height. All rows will be adjusted to the same height; you
cannot have different heights for individual rows.

Creating and sizing splits

If the horizontal scroll bar is visible, and the AllowSizing property of the leftmost split is True, the grid
displays a split box immediately to the left of the horizontal scroll bar.

To clone the current split, point to the split box. The pointer will change to a double vertical bar with a
down arrow.

Drag the pointer to the right to display and move a pair of dividing lines that will mark the right edge of
the new split.
132 · Design Time Interaction

The leftmost split box is always used to create a new split. If other split boxes are present, you can use
them to reposition the split dividers. Point to the split box you want to move. The pointer will change to a
double vertical bar with horizontal arrows.

Drag the dividers left or right to adjust the widths of the adjacent splits. As with columns, you can drag
the dividers all the way to the left to hide a split. However, since splits do not have a Visible property,
hiding a split in this manner actually deletes it.
If the horizontal scroll bar is not visible, or the AllowSizing property of the leftmost split is False, you can
still create a new split with the Split command on the visual editing menu.

Selecting and highlighting columns

In order to move or delete columns in visual editing mode, you need to select them first.
To select and highlight an individual column, simply click the column header. If one or more columns are
already selected, they will be deselected. To select multiple columns, use one of the following methods:
• Select a column by clicking its header. Then hold the SHIFT key and click another column's
header. All of the columns between the first selected column and the current one (inclusive) will
be selected.
• Press the mouse button and drag within the column header area to extend the selection until all
desired columns are highlighted.
Note that you can only select multiple columns if they are adjacent.
To deselect all selected columns, click a cell in the grid's display area.

Moving selected columns

To move the selected columns as a unit to a different location, press the mouse button within the header
area of any selected column. The pointer will change to an arrow with a small box at its lower right
corner.

The divider at the left edge of the column being pointed to will be enlarged and highlighted. Drag the
divider to the desired location and release the mouse button to move the selected columns immediately
to the left of the divider. The moved columns remain selected.
If you drag the divider to a position within the currently selected range, no movement occurs. If a column
is not selected, you cannot move it.

Using the visual editing menu

While the grid is in visual editing mode, right-click anywhere on the grid to display the visual editing
menu. The visual editing menu contains several commands that are also present in the grid's context
 Visual Editing Mode · 133

menu. However, while the context menu operates on the grid as a whole, the visual editing menu is used
to manipulate the grid's columns and splits.

When you right-click a column to display the visual editing menu, the column you are pointing to
becomes the current column. This enables you to quickly execute commands that depend on the current
column, such as Cut and Insert.
Some commands, such as Copy and Delete, can operate on multiple selected columns. Follow the
procedures described earlier for selecting columns, then choose the desired command from the visual
editing menu.
For convenience, the visual editing menu also contains some of the commands from the grid's context
menu. The visual editing menu commands operate as follows.

Cut, Copy, Paste, Delete

These commands are similar to their context menu counterparts except that they apply to a column, or
selected columns, not to the entire grid. Using the Cut, Copy, and Paste commands, you can move
columns to the Clipboard and paste them to another grid, or within the same grid. The ability to copy
columns to the Clipboard provides an easy way to set up grid columns, since all of the properties that
define a column are copied as a unit. You can set the properties for multiple columns, copy them to the
Clipboard, then paste them to a grid on another form.
Cut moves the selected columns from the grid to the Clipboard. Copy moves a copy of the selected
columns to the Clipboard while leaving the grid intact. If there are selected columns, then Cut and Copy
operate on the entire selection. If there are no selected columns, then these commands operate on the
current column only.
The Paste command is available only after a Cut or Copy command has been performed. If there are
selected columns, then Paste replaces the selection with the Clipboard contents. If there are no selected
columns, then Paste inserts the Clipboard contents to the left of the current column. In either case, the
newly pasted columns are selected.
134 · Design Time Interaction

Delete removes columns without saving them to the Clipboard. To prevent accidental deletions, the
Delete command is available only when one or more columns are selected.

Insert
This command creates and inserts a new column to the left of the current column.

Append
This command creates and adds a new column to the right of the rightmost column in the grid.

Split
This command creates and inserts a new split to the left of the current split. You can then use the Splits
and Layout property pages to configure the splits and the columns they contain.

Remove
This command removes the current split, that is, the split where you clicked to display the visual editing
menu.

Properties…
This command is identical to the context menu command with the same name. It displays the grid's
property pages, which enable you to customize the grid's layout and appearance.

Retrieve Fields
This command is identical to the context menu command with the same name. It automatically
configures the grid columns according to the schema information from the Data control's Recordset (Data
control).

Clear Fields
This command is identical to the context menu command with the same name. All field and column
layout properties set in the grid are cleared.

Load Layout
This command loads the grid layout whose name is given by the LayoutName property from the binary
layout storage file specified in the LayoutFileName property. A layout comprises all persistent property
settings for the entire grid, not just its columns and splits. This command is unavailable if either of the
aforementioned properties have not been set.

Save Layout
This command saves the current grid layout using the name specified in the LayoutName property to the
binary layout storage file specified in the LayoutFileName property. This command is unavailable if
either of these properties have not been set.

Remove Layout
This command removes the grid layout whose name is given by the LayoutName property from the
binary layout storage file specified by the LayoutFileName property. This command is unavailable if
either of these properties have not been set.
 Property Page Overview · 135

Property Page Overview

True DBGrid Pro 8.0 introduces a new tree view property page interface that adds object browsing
features to the standard property page model. Properties are grouped and displayed using tree controls
that fully outline the object models of TDBGrid or TDBDropDown, enabling you to set almost all
properties at design time with minimal typing. This new property tree model, which is used in all
property pages except Values, easily accommodates the ever-increasing set of properties supported by
the grid and its collection objects.

When you select an item in the property tree, a brief description of the selected property appears below
the tree itself, and the controls displayed to the right of the tree change to match the data type and current
value of the selected property. For example, if you select a boolean property such as AllowAddNew, the
page displays True and False option buttons and selects the appropriate one. If you select a string
property such as Caption, the page displays an edit control and fills it with the caption string, if any.
Property trees also provide a context menu for navigating the object hierarchy, accessing context-sensitive
help, and copying values from one property to another. You can also use the context menu to apply the
value of a column or split property to all other members within the collection.

Working with property pages

Select Properties… from the grid's context menu to display the property page dialog. You can also
display the property pages by selecting (Custom) from the Visual Basic Properties window. To accept the
changes made on any page, click the OK button at the bottom of the property page dialog. Click Cancel
to discard any changes. The property page dialog will be closed after you click OK or Cancel.
136 · Design Time Interaction

You can also click the Apply button to commit your changes without closing the dialog. Any changes you
have made will be reflected in the grid immediately. You can continue to make additional changes after
clicking Apply. Note that selecting a different tab implicitly applies any changes made to the current tab.
Use the Help button to display the online help for the current property page.

Working with property trees

With the exception of the Values page, all property pages use property trees to depict the object model of
the grid or one of its collections. Property trees are similar to the list of folders displayed in the left pane
of Windows Explorer. Just as folders preceded by a plus sign contain other folders, property tree nodes
preceded by a plus sign represent sub-objects with their own set of editable properties. To expand a sub-
object node and view its properties, click the adjacent plus sign or double-click the node's name or icon.
The following illustration shows the General property tree for a grid with its CaptionStyle property
expanded.

When a property tree node is expanded, the plus sign changes to a minus sign. To collapse an expanded
node, click the minus sign or double-click the node's name or icon.
Property trees use the following icons to help you identify properties and objects more readily:
A collection object or a member of a collection.
A string, number, color, font, or picture property.
An enumerated property.
A boolean property with a value of True.
A boolean property with a value of False.

Changing values in property trees

To change the value of a property, first select it in the property tree using the mouse or the navigation
keys on the numeric keypad. Depending upon the data type of the selected property, the input controls
displayed to the right of the tree change accordingly. After entering or selecting the new value, you can
apply it to the grid by clicking the OK or Apply button, selecting a different tab within the property page
dialog, or selecting a different item within the property tree.
 Property Page Overview · 137

If you change one or more property values by selecting a different item within the property tree, you can
use the Cancel button to restore the previous values. However, if you use the OK or Apply button, or
select a different tab, then the changes are committed to the grid and the Cancel button will not restore
the previous values.
The input controls displayed to the right of the property tree vary according to the data type and
semantics of the selected property. A brief description of each input control set follows.

Boolean properties

To change the value of a boolean property, select the desired option button. You can also toggle the value
of a boolean property by double-clicking its name (or icon) within the property tree. Alternatively, you
can use the property tree context menu to change the value of a boolean property without selecting a
different property in the tree.

String properties

To change the value of a string property, type the desired text into the edit control. You can also use the
edit control's context menu to paste text from the Clipboard.

String selection properties

Some string properties, such as NumberFormat, support both text entry and selection from a predefined
list. In this case, you can type the desired text into the edit control or select the desired item in the list.
You can also use the edit control's context menu to paste text from the Clipboard.
Note that the list of predefined items may be empty. For example, if you have not set the grid's
DataSource property, then selecting the DataField property of a Column object will not display any field
names.
138 · Design Time Interaction

Numeric properties

To change the value of a numeric property (that is, one whose data type is Integer, Long, Single, or
Double), type the desired text into the edit control. You can also use the edit control's context menu to
paste text from the Clipboard.
The edit control accepts all characters, even letters and punctuation marks. However, invalid values will
be rejected when you attempt to commit the change, and an error message will be displayed. Note that
you can enter hexadecimal values with the &H prefix. For example, typing &HFF specifies a value of 255.

Enumerated properties

To change the value of an enumerated property such as MousePointer, select the desired item in the list.
You can also use the property tree context menu to change the value of an enumerated property without
selecting a different property in the tree.

Font properties

For font properties, the input controls are similar to the stock Font property page used in many ActiveX
controls. The Sample Text area enables you to preview different fonts, sizes, and effects before updating
the selected property.
 Property Page Overview · 139

Color properties

For color properties, the input controls are similar to the stock Color property page used in many ActiveX
controls. Use the Color Set combo to switch between system and standard color lists; use the Edit
Custom Color button to define additional colors that do not appear in either list.

Picture properties

For picture properties, the input controls are similar to the stock Picture property page used in many
ActiveX controls. Use the Browse button to specify an image filename; use the Clear button to remove the
current image.
140 · Design Time Interaction

Style properties

To change the named style associated with a Style object property, select the desired item in the list.
Unlike enumerated properties, style properties do not appear in the property tree context menu. Select
the item labeled (None) to sever an association with a named style. Use the Reset button to force an
anonymous style to discard any specialized attributes.
When setting the Parent property of a style on the Style Factory property page, the (None) item and Reset
button are not available.

Layout properties

When you select the LayoutFileName or LayoutName properties in the General property tree, the input
controls shown in the preceding illustration are displayed. To specify a layout filename, use the Browse
button or type directly into the adjacent edit control. To enter a new layout name, type directly into the
second edit control. To choose an existing layout name, select an item from the adjacent list.

Understanding the object model

True DBGrid supports a rich object model that reflects the organization of its visual components.
Therefore, in order to customize a grid's appearance and behavior, you need to know how property trees
are used to represent this component hierarchy. In particular, you need to understand the distinction
between global and split-specific properties.
 Property Page Overview · 141

A split is similar to the split window features of products such as Microsoft Excel and Word. You can use
splits to present your data in multiple vertical panes. These vertical panes, or splits, can display data in
different colors and fonts. They can scroll as a unit or individually, and they can display different sets of
columns or the same set. You can also use splits to prevent one or more columns from scrolling. By
default, a grid contains a single split comprising all of its columns.

Splits in property trees

In the grid's General property tree, splits are represented by numbered Split objects contained within the
Splits property, as shown in the following figures. In the first tree, the Splits property is expanded to
reveal the default split, labeled Splits(00). In the second tree, the default split is expanded to reveal its
design-time properties, listed alphabetically beginning with AllowColMove.

The number enclosed in parentheses (00) represents the index of the default split within the Splits
collection. The extra leading zero is there so that property tree nodes sort properly if there are more than
ten items in a collection. Although this is unlikely for splits, it is common to have more than ten columns.
142 · Design Time Interaction

As a convenience, you can use the Splits property page to access the members of the Splits collection
directly. The nodes displayed in the Splits property tree are identical to the nodes that appear when you
expand the Splits property within the General tree.
Note that most of the split properties are not present at the root level of the General property tree. For
example, you cannot set the AlternatingRowStyle property without expanding a Split object, because
the value of this property can vary from split to split. The term split-specific is used to describe such
properties, since they apply to individual splits rather than the grid as a whole.
Conversely, the term global is used to describe properties that apply to the grid as a whole, such as
DataMode and BorderStyle. Global properties are accessible through the General property page or the
Visual Basic Properties window. The latter also shows extender properties specific to the Visual Basic
environment, such as Align and Tag.

Columns in property trees

The distinction between split-specific and global properties also extends to the Columns collection that
represents columns of data within the grid. As a rule of thumb, properties that govern display
characteristics or end-user interaction tend to be split-specific, while properties that govern database
access are global.
In the grid's General property tree, global column properties are represented by numbered Column
objects contained within the Columns property, as shown in the following figures. In the first tree, the
Columns property is expanded to reveal the default columns, labeled Columns(00) and Columns(01).
In the second tree, the first default column is expanded to reveal its design-time properties, listed
alphabetically beginning with ButtonPicture.
 Property Page Overview · 143

As a convenience, you can use the Columns property page to access the global properties of the members
of the Columns collection directly. The nodes displayed in the Columns property tree are identical to the
nodes that appear when you expand the Columns property within the General tree.
Each member of the Splits collection also exposes a Columns property, as shown in the next pair of
figures. In the first tree, the Columns property of the default split is expanded to reveal the same default
columns. In the second tree, the first default column is expanded to reveal its design-time properties,
listed alphabetically beginning with Alignment.
144 · Design Time Interaction

Note the difference between this set of column properties and the set listed in the preceding pair of
figures. The properties in this set are split-specific, since their values can vary from split to split. For
example, you can create a fixed, nonscrolling column by setting its Visible property to True in the
leftmost split and False in all others.
See TDBGrid Property Pages (page 147) or TDBDropDown Property Pages (page 171) if you are unsure
where a given property is located.

Using the property tree context menu

Right-click any node to display the property tree context menu, which enables you to navigate the object
hierarchy, access context-sensitive help, and copy values from one property to another. You can also use
the context menu to apply the value of a column or split property to all other members within the
collection.
 Property Page Overview · 145

In this illustration, the context menu is opened on the selected property node. However, if you right-click
a node that is not selected, the context menu is opened on that node, and neither the selection nor the
input control set to the right of the property tree are changed. In other words, left-clicking changes the
selection; right-clicking does not.
The context menu may contain some or all of the following commands, depending upon the data type of
the property that was clicked and the state of the property tree itself.

Help
This command displays the online help for the target property or object (that is, the node that was right-
clicked). It is unavailable for nodes that represent collection members.

Copy
This command copies the current value of the target property into an internal buffer (not the Clipboard),
overwriting the previous contents of the buffer. It is especially useful for copying complex values such as
fonts or colors. This command is not displayed for object nodes unless the node represents a named style
property.

Paste
This command sets the value of the target property equal to the value stored in the internal buffer used
by the Copy command. If the target node is also the selected node, then the stored value is used to set the
input controls to the right of the property tree, but the grid itself is not updated until you commit the
change. If the target node is not the selected node, then the stored value is applied to the grid
immediately.
146 · Design Time Interaction

This command is unavailable if the internal buffer is empty. It is not displayed for object nodes unless the
node represents a named style property.

Selected
This command scrolls the selected node into view. It is not displayed if the selected node is currently
visible within the property tree.

Set All collection-name

This command applies the value of the selected property to all sibling objects within the collection. The
input controls to the right of the property tree determine which value is used, even if the value has not
yet been committed to the grid itself. For example, if the WrapText property is selected for the fourth
column of the second split, and the True option button is selected, then this command is displayed in the
context menu as Set All Columns, and executing it sets the WrapText property of all columns in the
second split to True.
This command is only displayed if the parent of the selected node is a member of a collection, and the
target node is also the selected node. It is unavailable if the collection in question contains only one
member.

Next
This command navigates to the next object in the current collection. If the target node is the selected node,
then this command selects the next occurrence of the target property or object and scrolls it into view. If
the target node is not the selected node, then the next occurrence of the target property or object is
scrolled into view but is not selected.
This command is only displayed if the parent of the target node is a member of a collection. It is
unavailable if the parent node represents the last object of the collection.

Previous
This command navigates to the previous object in the current collection. If the target node is the selected
node, then this command selects the previous occurrence of the target property or object and scrolls it
into view. If the target node is not the selected node, then the previous occurrence of the target property
or object is scrolled into view but is not selected.
This command is only displayed if the parent of the target node is a member of a collection. It is
unavailable if the parent node represents the first object of the collection.

True, False
For boolean properties, these commands set the value of the target property. If the target node is also the
selected node, then the selected command is used to set the appropriate option button to the right of the
property tree, but the grid itself is not updated until you commit the change. If the target node is not the
selected node, then the selected command is applied to the grid immediately.

Enumerated values
For enumerated properties, the context menu also contains a command for each enumerated value. When
selected, these commands set the value of the target property. If the target node is also the selected node,
then the selected command is used to select the appropriate list item to the right of the property tree, but
the grid itself is not updated until you commit the change. If the target node is not the selected node, then
the selected command is applied to the grid immediately.
 TDBGrid Property Pages · 147

TDBGrid Property Pages

The TDBGrid control supports the following property pages. With the exception of the Values page, all
of them use the property tree model described earlier in this chapter.
General This page contains all grid properties and displays the full object model. It is a
superset of the Columns and Splits pages, as it provides access to grid properties in
addition to those of the Columns and Splits collections.
Columns This page contains the properties of the grid's Column objects. It provides a shortcut
to the contents of the Columns property node on the General page. Only column
properties that are global to all splits appear on this page.
Splits This page contains the properties of the grid's Split objects. It provides a shortcut to
the contents of the Splits property node on the General page. This page also
provides access to split-specific properties of Column objects.
Style Factory This page enables you to create and modify named styles that can be applied to the
various style properties of the grid and its constituent objects.
Print Info This page manages a collection of PrintInfo objects, which encapsulate page setup
and print job settings.
Values This page defines alternate text or graphics for underlying data values, as well as
special data presentation and user interaction settings, such as built-in combo boxes
and radio buttons.

General property page

The General property page defines the grid's data access mode, database related permissions, navigation
key behavior, and overall display characteristics. These are global properties that apply to the grid as a
whole (that is, the TDBGrid object). You can also use this page to specify a grid layout file containing one
or more named layouts.
148 · Design Time Interaction

General properties by alphabet

The following TDBGrid control properties are available on the General property page:
AllowAddNew Enables interactive record addition
AllowArrows Enables use of arrow keys for grid navigation
AllowDelete Enables interactive record deletion
AllowUpdate Enables interactive record updating
AnimateWindow Controls the object's animation style
AnimateWindowClose Controls the animation effect when the object is closed
AnimateWindowDirection Controls the direction of the animation effect
AnimateWindowTime Controls the duration of the animation effect
Appearance Controls 3-D display of headings, caption, record selectors
BackColor Sets/returns the background color
BorderStyle Sets/returns style for grid border
Caption Sets/returns grid caption text
CaptionStyle Controls the caption style for a grid
CellTips Enables pop-up cell tip window when the cursor is idle
CellTipsDelay Sets/returns idle time for cell tip window
CellTipsWidth Sets/returns width of cell tip window
ChildGrid Sets the child grid control when using master/detail
ColumnFooters Turns column footings on or off
ColumnHeaders Turns column headings on or off
Columns Contains a collection of True DBGrid columns
DataMember Sets/returns a data member offered by an OLE DB provider
DataMode Specifies bound or unbound mode
DataView Returns or sets how the grid will display master-detail recordsets
DeadAreaBackColor Sets/returns the background color of the control's dead area
DefColWidth Specifies column width for auto-created columns
DirectionAfterEnter Specifies the position of the next cell after enter
EditBackColor Sets/returns the editor background color
EditDropDown Controls whether a drop-down window is used for editing
EditForeColor Sets/returns the editor foreground color
EditorStyle Controls the editor style for a grid
EmptyRows Enables empty rows in an under populated grid
Enabled Enables or disables user interaction
EvenRowStyle Controls the row style for even-numbered rows
ExposeCellMode Controls behavior of clicked rightmost visible cell
FilterBarStyle Returns the style object that controls the FilterBar cell appearance
 TDBGrid Property Pages · 149

Font Specifies the overall font for a grid

FooterBackColor Sets/returns the footing background color
FooterFont Specifies the footing font for a grid
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a grid
FootLines Number of lines allocated for footing text
ForeColor Sets/returns the foreground color
GroupByCaption Sets/returns the text displayed in the grouping area when no
groupings are defined
HeadBackColor Sets/returns the heading background color
HeadFont Specifies the heading and caption font for a grid
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a grid
HeadLines Number of lines allocated for heading text
HighlightRowStyle Controls the marquee style when set to Highlight Row
InactiveBackColor Sets/returns the inactive heading background color
InactiveForeColor Sets/returns the inactive heading foreground color
InactiveStyle Controls the inactive heading style for a grid
InsertMode Sets/returns the insertion mode for the grid's editor
LayoutFileName Sets/returns the name of a file containing grid layouts
LayoutName Sets/returns the name of the current grid layout
LayoutURL Sets/returns the URL used for downloading grid layouts
MarqueeUnique Restricts display of marquee to current split
MaxRows Sets/returns maximum number of rows in control
MouseIcon Sets/returns a custom mouse icon
MousePointer Sets/returns the mouse pointer type
MultipleLines Controls whether individual records span multiple lines
MultiSelect Sets/returns the type of selection allowed in the grid
OddRowStyle Controls the row style for odd-numbered rows
OLEDragMode Controls whether a grid handles OLE drag operations
OLEDropMode Controls whether a grid handles OLE drop operations
PictureAddNewRow Sets/returns the record selector bitmap for the AddNew row
PictureCurrentRow Sets/returns the record selector bitmap for the current row
PictureModifiedRow Sets/returns the record selector bitmap for modified rows
PictureFilterBar Sets/returns the bitmap used in the record selector column
PictureFooterRow Sets/returns the record selector bitmap for the footer row
PictureHeaderRow Sets/returns the record selector bitmap for the header row
150 · Design Time Interaction

PictureModifiedRow Sets/returns the record selector bitmap for modified rows

PictureStandardRow Sets/returns the record selector bitmap for standard rows
PrintInfos Contains a collection of printer information objects
RecordSelectorStyle Returns the style object that controls the appearance of
RecordSelectors
RightToLeft When True, applies right to left text functionality
RowDividerColor Controls the row divider color
RowDividerStyle Selects style of row divider lines
RowHeight Specifies height of all grid rows
RowSubDividerColor Controls the row subdivider color
ScrollTips Determines whether the grid displays a pop-up window
ScrollTrack Scrollbar thumb causes the grid display to update
SelectedBackColor Sets/returns the selected row background color
SelectedForeColor Sets/returns the selected row foreground color
SelectedStyle Controls the selected row and column style for a grid
Splits Contains a collection of True DBGrid splits
Style Controls the normal style for a grid
TabAcrossSplits Allows tab and arrow keys to cross split boundaries
TabAction Defines the behavior of the tab key
TransparentRowPictures True if record selector pictures use a transparent color
ViewColumnCaptionWidth Width of the Column caption in Form or Inverted DataView
ViewColumnWidth Width of the Column in Form or Inverted DataView
WrapCellPointer Defines behavior of tab and arrow keys at row boundaries

General properties by category

Appearance properties
AnimateWindow Controls the object's animation style
AnimateWindowClose Controls the animation effect when the object is closed
AnimateWindowDirection Controls the direction of the animation effect
AnimateWindowTime Controls the duration of the animation effect
Appearance Controls 3-D display of headings, caption, record selectors
BorderStyle Sets/returns style for grid border
Caption Sets/returns grid caption text
ColumnFooters Turns column footings on or off
ColumnHeaders Turns column headings on or off
DefColWidth Specifies column width for auto-created columns
EmptyRows Enables empty rows in an underpopulated grid
 TDBGrid Property Pages · 151

FootLines Number of lines allocated for footing text

HeadLines Number of lines allocated for heading text
MultipleLines Controls whether individual records span multiple lines
PictureAddNewRow Sets/returns the record selector bitmap for the AddNew row
PictureCurrentRow Sets/returns the record selector bitmap for the current row
PictureModifiedRow Sets/returns the record selector bitmap for modified rows
PictureFilterBar Sets/returns the bitmap used in the record selector column
PictureFooterRow Sets/returns the record selector bitmap for the footer row
PictureHeaderRow Sets/returns the record selector bitmap for the header row
PictureModifiedRow Sets/returns the record selector bitmap for modified rows
PictureStandardRow Sets/returns the record selector bitmap for standard rows
PrintInfos Contains a collection of printer information objects
RowDividerStyle Selects style of row divider lines
RowDividerColor Controls the row divider color
RowHeight Specifies height of all grid rows
RowSubDividerColor Controls the row subdivider color
TransparentRowPictures True if record selector pictures use a transparent color
ViewColumnCaptionWidth Width of the Column caption in Form or Inverted DataView
ViewColumnWidth Width of the Column in Form or Inverted DataView

Behavior properties
AllowAddNew Enables interactive record addition
AllowArrows Enables use of arrow keys for grid navigation
AllowDelete Enables interactive record deletion
AllowUpdate Enables interactive record updating
CellTips Enables pop-up cell tip window when the cursor is idle
CellTipsDelay Sets/returns idle time for cell tip window
CellTipsWidth Sets/returns width of cell tip window
ChildGrid Sets the child grid control when using master/detail
DirectionAfterEnter Specifies the position of the next cell after enter
EditDropDown Controls whether a drop-down window is used for editing
Enabled Enables or disables user interaction
ExposeCellMode Controls behavior of clicked rightmost visible cell
InsertMode Sets/returns the insertion mode for the grid's editor
MarqueeUnique Restricts display of marquee to current split
MouseIcon Sets/returns a custom mouse icon
152 · Design Time Interaction

MousePointer Sets/returns the mouse pointer type

MultiSelect Sets/returns the type of selection allowed in the grid
OLEDragMode Controls whether a grid handles OLE drag operations
OLEDropMode Controls whether a grid handles OLE drop operations
RightToLeft When True, applies right to left text functionality
ScrollTips Determines whether the grid displays a pop-up window
ScrollTrack Scrollbar thumb causes the grid display to update
TabAcrossSplits Allows tab and arrow keys to cross split boundaries
TabAction Defines the behavior of the tab key
WrapCellPointer Defines behavior of tab and arrow keys at row boundaries

Color properties
BackColor Sets/returns the background color
DeadAreaBackColor Sets/returns the background color of the control's dead area
EditBackColor Sets/returns the editor background color
EditForeColor Sets/returns the editor foreground color
FooterBackColor Sets/returns the footing background color
FooterForeColor Sets/returns the footing foreground color
ForeColor Sets/returns the foreground color
HeadBackColor Sets/returns the heading background color
HeadForeColor Sets/returns the heading foreground color
InactiveBackColor Sets/returns the inactive heading background color
InactiveForeColor Sets/returns the inactive heading foreground color
SelectedBackColor Sets/returns the selected row background color
SelectedForeColor Sets/returns the selected row foreground color

Data properties
AllowAddNew Enables interactive record addition
AllowDelete Enables interactive record deletion
AllowUpdate Enables interactive record updating
DataMember Sets/returns a data member offered by an OLE DB provider
DataMode Specifies bound or unbound mode
MaxRows Sets/returns maximum number of rows in control

Font properties
Font Specifies the overall font for a grid
 TDBGrid Property Pages · 153

FooterFont Specifies the footing font for a grid

HeadFont Specifies the heading and caption font for a grid

Layout properties
LayoutFileName Sets/returns the name of a file containing grid layouts
LayoutName Sets/returns the name of the current grid layout
LayoutURL Sets/returns the URL used for downloading grid layouts

Style properties
CaptionStyle Controls the caption style for a grid
EditorStyle Controls the editor style for a grid
EvenRowStyle Controls the row style for even-numbered rows
FilterBarStyle Returns the style object that controls the FilterBar cell appearance
FooterStyle Controls the footing style for a grid
HeadingStyle Controls the heading style for a grid
HighlightRowStyle Controls the marquee style when set to Highlight Row
InactiveStyle Controls the inactive heading style for a grid
OddRowStyle Controls the row style for odd-numbered rows
RecordSelectorStyle Returns the style object that controls the appearance of
RecordSelectors
SelectedStyle Controls the selected row and column style for a grid
Style Controls the normal style for a grid

Columns property page

The splits of a grid provide users with different views of the same data source. Therefore, corresponding
columns in different splits must be bound to the same data fields. A few other column properties are
global to all splits as well. The Columns property page provides a shortcut to the Columns collection of
the General property page. It is used to set global Column object properties that cannot vary from one
split to another.
154 · Design Time Interaction

NOTE: The Columns property page is used to edit existing columns, not create or delete them. Use the
Retrieve Fields command on the context menu to derive a column layout from a bound data source. For
information on how to create your own custom column layout, see Visual Editing Mode (page 130.)

Column properties by alphabet

The following Column object properties are available on the Columns property page of the TDBGrid
control:
ButtonPicture Sets/returns the bitmap used for the in-cell button
Caption Sets/returns column heading text
ConvertEmptyCell Specifies if empty cells are saved as empty strings or Null values
DataField Data table field name for a column
DataWidth Maximum number of characters available for column input
DefaultValue Default value for new column data
DropDown Sets the TDBDropDown control for a column
EditMask Input mask string for a column
EditMaskRight Controls whether the edit mask is applied from right to left
EditMaskUpdate Controls whether masked data is used for updates
ExternalEditor Sets the ActiveX input control for a column
FilterButtonPicture Sets/returns the bitmap for the in-cell button in the current filter
FilterText Sets/returns the data associated with the value of the filter
FooterText Column footing text
 TDBGrid Property Pages · 155

NumberFormat Data formatting string for a column

Column properties by category

Appearance properties
ButtonPicture Sets/returns the bitmap used for the in-cell button
Caption Sets/returns column heading text
FilterButtonPicture Sets/returns the bitmap for the in-cell button in the current filter
FilterText Sets/returns the data associated with the value of the filter
FooterText Column footing text

Behavior properties
DropDown Sets the TDBDropDown control for a column
EditMask Input mask string for a column
EditMaskRight Controls whether the edit mask is applied from right to left
EditMaskUpdate Controls whether masked data is used for updates
ExternalEditor Sets the ActiveX input control for a column

Data properties
DataField Data table field name for a column
DataWidth Maximum number of characters available for column input
DefaultValue Default value for new column data
NumberFormat Data formatting string for a column

Splits property page

The Splits property page defines the appearance and behavior of the splits in the grid. The grid has one
split by default, so even if you do not create a grid with multiple splits, you may still need to set
properties on this page in order to configure the grid's behavior. This page provides a shortcut to the
Splits collection of the General property page.
156 · Design Time Interaction

NOTE: The Splits property page is used to edit existing splits, not create or delete them. For information
on how to create splits at design time, see Visual Editing Mode (page 130.)

Split properties by alphabet

The following Split object properties are available on the Splits property page of the TDBGrid control:
AllowColMove Enables interactive column movement
AllowColSelect Enables interactive column selection
AllowFocus Allows cells within a split to receive focus
AllowRowSelect Enables interactive row selection
AllowRowSizing Enables interactive row resizing
AllowSizing Enables interactive resizing for a split
AlternatingRowStyle Controls whether even/odd row styles are applied to a split
AnchorRightColumn Controls horizontal scrolling when the last column is visible
BackColor Sets/returns the background color
Caption Sets/returns split caption text
CaptionStyle Controls the caption style for a split
Columns Returns a collection of column objects for a split
DividerColor Controls the divider color of a split or column divider
DividerStyle Divider style for right split border
EditBackColor Sets/returns the editor background color
 TDBGrid Property Pages · 157

EditForeColor Sets/returns the editor foreground color

EditorStyle Controls the editor style for a split
EvenRowStyle Controls the row style for even-numbered rows
ExtendRightColumn Sets/returns extended right column for a split
FetchRowStyle Controls whether the FetchRowStyle event will be fired
FilterBar Activates the FilterBar
FilterBarStyle Controls the filter bar style for a split
Font Specifies the overall font for a split
FooterBackColor Sets/returns the footing background color
FooterFont Sets/returns the footing font for a split
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a split
ForeColor Sets/returns the foreground color
HeadBackColor Sets/returns the heading background color
HeadFont Specifies the heading font for a split
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a split
HighlightRowStyle Controls the marquee style when set to Highlight Row
InactiveBackColor Sets/returns the inactive heading background color
InactiveForeColor Sets/returns the inactive heading foreground color
InactiveStyle Controls the inactive heading style for a split
Locked True if data entry is prohibited for a split
MarqueeStyle Sets/returns marquee style for a split
OddRowStyle Controls the row style for odd-numbered rows
PartialRightColumn True if rightmost column can be clipped to edge of split
RecordSelectors Shows/hides selection panel at left border
RecordSelectorWidth Sets/returns the record selector width
ScrollBars Sets/returns scroll bar style for a split
ScrollGroup Used to synchronize vertical scrolling between splits
SelectedBackColor Sets/returns the selected row background color
SelectedForeColor Sets/returns the selected row foreground color
SelectedStyle Controls the selected row and column style for an object
Size Sets/returns split width according to SizeMode
SizeMode Controls whether a split is scalable or fixed size
SpringMode Sets/returns how columns size when the split is resized
Style Controls the normal style for an object
158 · Design Time Interaction

Split properties by category

Appearance properties
AlternatingRowStyle Controls whether even/odd row styles are applied to a split
AnchorRightColumn Controls horizontal scrolling when the last column is visible
Caption Sets/returns split caption text
DividerStyle Divider style for right split border
ExtendRightColumn Sets/returns extended right column for a split
FetchRowStyle Controls whether the FetchRowStyle event will be fired
MarqueeStyle Sets/returns marquee style for a split
PartialRightColumn True if rightmost column can be clipped to edge of split
RecordSelectors Shows/hides selection panel at left border
RecordSelectorWidth Sets/returns the record selector width
Size Sets/returns split width according to SizeMode
SizeMode Controls whether a split is scalable or fixed size

Behavior properties
AllowColMove Enables interactive column movement
AllowColSelect Enables interactive column selection
AllowFocus Allows cells within a split to receive focus
AllowRowSelect Enables interactive row selection
AllowRowSizing Enables interactive row resizing
AllowSizing Enables interactive resizing for a split
AnchorRightColumn Controls horizontal scrolling when the last column is visible
ExtendRightColumn Sets/returns extended right column for a split
FilterBar Activates the FilterBar
FilterBarStyle Controls the filter bar style for a split
Locked True if data entry is prohibited for a split
PartialRightColumn True if rightmost column can be clipped to edge of split
RecordSelectors Shows/hides selection panel at left border
ScrollBars Sets/returns scroll bar style for a split
ScrollGroup Used to synchronize vertical scrolling between splits
SpringMode Sets/returns how columns size when the split is resized

Color properties
BackColor Sets/returns the background color
DividerColor Controls the divider color of a split or column divider
 TDBGrid Property Pages · 159

EditBackColor Sets/returns the editor background color

EditForeColor Sets/returns the editor foreground color
FooterBackColor Sets/returns the footing background color
FooterForeColor Sets/returns the footing foreground color
ForeColor Sets/returns the foreground color
HeadBackColor Sets/returns the heading background color
HeadForeColor Sets/returns the heading foreground color
InactiveBackColor Sets/returns the inactive heading background color
InactiveForeColor Sets/returns the inactive heading foreground color
SelectedBackColor Sets/returns the selected row background color
SelectedForeColor Sets/returns the selected row foreground color

Font properties
Font Specifies the overall font for a split
FooterFont Sets/returns the footing font for a split
HeadFont Specifies the heading font for a split

Style properties
AlternatingRowStyle Controls whether even/odd row styles are applied to a split
CaptionStyle Controls the caption style for a split
EditorStyle Controls the editor style for a split
EvenRowStyle Controls the row style for even-numbered rows
FooterStyle Controls the footing style for a split
HeadingStyle Controls the heading style for a split
HighlightRowStyle Controls the marquee style when set to Highlight Row
InactiveStyle Controls the inactive heading style for a split
OddRowStyle Controls the row style for odd-numbered rows
SelectedStyle Controls the selected row and column style for an object
Style Controls the normal style for an object

Split-specific Column properties by alphabet

The following Column object properties are available on the Splits property page of the TDBGrid
control. To access individual columns, expand the Columns property node.
Alignment Specifies horizontal text alignment
AllowFocus Controls whether a column can receive focus
AllowSizing Enables interactive resizing for a column
AutoCompletion If True, the dropdown auto fills with the matched entry
160 · Design Time Interaction

AutoDropDown True if a drop-down control opens when a character is typed

BackColor Sets/returns the background color
Button Controls whether a button appears within the current cell
ButtonAlways Controls when an in-cell button is displayed
ButtonFooter Controls whether a column footer acts like a standard button
ButtonHeader Controls whether a column header acts like a standard button
ButtonText Controls whether a cell is rendered as a button
Columns Returns a collection of column objects for a split
DividerColor Controls the divider color of a split or column divider
DividerStyle Divider style for right column border or left edge of a split
DropDownList Controls whether a TDBDropDown control acts like a list
EditBackColor Sets/returns the editor background color
EditForeColor Sets/returns the editor foreground color
EditorStyle Controls the editor style for a column
FetchStyle Controls whether the FetchCellStyle event fires for a column
FilterButton If True, displays a button in the current filter cell
Font Specifies the overall font for a column
FooterAlignment Specifies column footing alignment
FooterBackColor Sets/returns the footing background color
FooterDivider Controls display of dividing line in column footer
FooterFont Specifies the footing font for a column
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a column
ForeColor Sets/returns the foreground color
HeadAlignment Specifies column heading alignment
HeadBackColor Sets/returns the heading background color
HeaderDivider Controls display of dividing line in column header
HeadFont Specifies the heading font for a column
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a column
Locked True if data entry is prohibited for a column
Merge True if a column merges adjacent rows of like-valued cells
MinWidth Sets/returns the column can resize when in SpringMode
Order Sets/returns the display position of a column
OwnerDraw Controls whether the OwnerDrawCell event fires for a column
Style Controls the normal style for a column
Visible Shows/hides a column
 TDBGrid Property Pages · 161

Width Sets/returns column width in container coordinates

WrapText True if cell text is word wrapped

Split-specific Column properties by category

Appearance properties
Alignment Specifies horizontal text alignment
Button Controls whether a button appears within the current cell
ButtonAlways Controls when an in-cell button is displayed
ButtonText Controls whether a cell is rendered as a button
DividerStyle Divider style for right column border
FetchStyle Controls whether the FetchCellStyle event fires for a column
FilterButton If True, displays a button in the current filter cell
FooterAlignment Specifies column footing alignment
FooterDivider Controls display of dividing line in column footer
HeadAlignment Specifies column heading alignment
HeaderDivider Controls display of dividing line in column header
Merge True if a column merges adjacent rows of like-valued cells
Order Sets/returns the display position of a column
OwnerDraw Controls whether the OwnerDrawCell event fires for a column
Visible Shows/hides a column
Width Sets/returns column width in container coordinates
WrapText True if cell text is word wrapped

Behavior properties
AllowFocus Controls whether a column can receive focus
AllowSizing Enables interactive resizing for a column
AutoCompletion If True, the dropdown auto fills with the matched entry
AutoDropDown True if a drop-down control opens when a character is typed
Button Controls whether a button appears within the current cell
ButtonFooter Controls whether a column footer acts like a standard button
ButtonHeader Controls whether a column header acts like a standard button
ButtonText Controls whether a cell is rendered as a button
DropDownList Controls whether a TDBDropDown control acts like a list
Locked True if data entry is prohibited for a column
MinWidth Sets/returns the column can resize when in SpringMode
162 · Design Time Interaction

Color properties
BackColor Sets/returns the background color
DividerColor Controls the divider color of a split or column divider
EditBackColor Sets/returns the editor background color
EditForeColor Sets/returns the editor foreground color
FooterBackColor Sets/returns the footing background color
FooterForeColor Sets/returns the footing foreground color
ForeColor Sets/returns the foreground color
HeadBackColor Sets/returns the heading background color
HeadForeColor Sets/returns the heading foreground color

Font properties
Font Specifies the overall font for a column
FooterFont Specifies the footing font for a column
HeadFont Specifies the heading font for a column

Style properties
DividerStyle Divider style for right column border or left edge of a split
EditorStyle Controls the editor style for a column
FooterStyle Controls the footing style for a column
HeadingStyle Controls the heading style for a column
Style Controls the normal style for a column

Style Factory property page

Use the Style Factory property page to create, modify, and delete named styles that can be applied to a
TDBGrid or TDBDropDown control and its constituent objects. By default, each control contains ten
built-in styles: Normal, Heading, Footing, Selected, Caption, HighlightRow, EvenRow, OddRow, RecordSelector,
and FilterBar.
 TDBGrid Property Pages · 163

Using the Style Factory property page

When you select a root-level Style object in the Style Factory property tree, the input controls shown in
the preceding illustration are displayed, enabling you to add new styles, remove existing styles, and
preview sample formatting.

New Style Name

This edit control specifies the name of the style to be added. It corresponds to the style's Name property.
164 · Design Time Interaction

New
This command button attempts to create a new style using the name specified in the New Style Name
edit control. An error message will be displayed if you do not specify a unique name.
Note that newly created styles automatically inherit their attributes from the selected style in the property
tree. If you want a new style to inherit its attributes from a different named style, you can expand its
property tree node and change the value of its Parent property.

Reset
This command button resets the selected style so that it inherits all of its font, color, and formatting
attributes from its parent, if any. For styles with no parent, the Reset button causes the selected style to
revert to its original settings.

Remove
This command button deletes the selected style and removes it from the Styles collection. You can
remove any style, even if it is a built-in style, and even if other styles inherit from it. If you remove a style
that is a parent of another style, the child style subsumes any characteristics that the parent specialized,
but the child's own settings take precedence.

Sample
This static area displays sample text that shows how a grid cell will appear when the selected style is
applied. Whenever you change a font, color, or alignment setting, you can select the affected style object
in the property tree to view an updated sample area, enabling you to see the results of the change before
committing it with either the OK or Apply button.

Style properties by alphabet

The following Style object properties are available on the Style Factory property page of the TDBGrid
and TDBDropDown controls:
Alignment Specifies the horizontal text alignment
BackColor Controls the background color
BackgroundPicture Sets/returns a style's background picture
BackgroundPictureDrawMode Controls how a style's background picture is displayed
BorderAppearance Controls the appearance (3D effects) of the cell
borders
BorderColor Specifies the color for the border
BorderSize Specifies the size of cell border
BorderType Controls which, if any, cell borders are displayed
EllipsisText When True, displays an ellipsis (…) at the end of cell
text
Font Specifies typeface, size, and other text characteristics
ForeColor Controls the foreground color
ForegroundPicture Sets/returns a style's foreground picture
ForegroundPicturePosition Controls how a style's foreground picture is positioned
 TDBGrid Property Pages · 165

Locked Disallows in-cell editing when true

Parent Sets/returns the object from which a style inherits
TransparentForegroundPicture True if the foreground picture uses a transparent color
VerticalAlignment Specifies vertical text alignment
WrapText Word wraps cell text when true

Style properties by category

Appearance properties
Alignment Specifies the horizontal text alignment
BorderAppearance Controls the appearance (3D effects) of the cell borders
BorderSize Specifies the size of cell border
BorderType Controls which, if any, cell borders are displayed
EllipsisText When True, displays an ellipsis (…) at the end of cell
text
VerticalAlignment Specifies vertical text alignment
WrapText Word wraps cell text when true

Behavior properties
Locked Disallows in-cell editing when true
Parent Sets/returns the object from which a style inherits

Color properties
BackColor Controls the background color
BorderColor Specifies the color for the border
ForeColor Controls the foreground color

Font properties
Font Specifies typeface, size, and other text characteristics

Picture properties
BackgroundPicture
BackgroundPictureDrawMode
ForegroundPicture
ForegroundPicturePosition
TransparentForegroundPicture
Sets/returns a style's background picture
Controls how a style's background picture is displayed
Sets/returns a style's foreground picture
Controls how a style's foreground picture is positioned
True if the foreground picture uses a transparent color
166 · Design Time Interaction

Print Info property page

Use the Print Info property page to create, modify, and delete named PrintInfo objects specifying page
layout and print job characteristics such as page headers and footers and the number of copies to print.
When a TDBGrid control is first created, its PrintInfos collection contains a single PrintInfo object
representing the system default printer.

Using the Print Info property page

When you select a root-level PrintInfo object in the Print Info property tree, the input controls shown in
the preceding illustration are displayed, enabling you to add new members to the PrintInfos collection or
remove existing members.
 TDBGrid Property Pages · 167

New PrintInfo
This edit control specifies the name of the object to be added. This is not the name of the output device,
but a collection index corresponding to the Name property.

New
This command button attempts to create a new PrintInfo object using the name specified in the New
PrintInfo edit control. An error message will be displayed if you do not specify a unique name.

Remove
This command button deletes the selected PrintInfo object and removes it from the PrintInfos collection.
However, if you remove the last member of the collection, the grid automatically creates a new one
named DefaultPrintInfo.

PrintInfo properties by alphabet

The following PrintInfo object properties are available on the Print Info property page of the TDBGrid
control:
Collate Sets/returns whether printed output should be collated
Default Sets/returns default PrintInfo status
Draft Sets/returns whether output should be rendered faster at the
cost of lower quality
Name Index into the PrintInfos collection
NeedTotalPageCount Sets/returns whether total page count is required for owner
drawn page header or footer
NoClipping Sets/returns whether printed text is clipped to cell boundaries
NumberOfCopies Sets/returns the number of copies to print
PageFooter Sets/returns the page footer for a PrintInfo object
PageFooterFont Sets/returns the page footer font for a PrintInfo object
PageFooterHeight Sets/returns height of owner drawn page footer
PageFooterOwnerDraw Sets/returns whether page header is owner drawn
PageHeader Sets/returns the page header for a PrintInfo object
PageHeaderFont Sets/returns the page header font for a PrintInfo object
PageHeaderHeight Sets/returns height of owner drawn page header
PageHeaderOwnerDraw Sets/returns whether page header is owner drawn
PreviewAllowFileOps Sets/returns whether file load/save are allowed in preview
PreviewCaption Sets/returns the print preview window caption
PreviewInitHeight Sets/returns print preview window's initial height
PreviewInitPosX Sets/returns print preview window's initial X position
PreviewInitPosY Sets/returns print preview window's initial Y position
PreviewInitScreenFill sets/returns print preview window's initial screen fill
PreviewInitWidth Sets/returns print preview window's initial width
168 · Design Time Interaction

PreviewInitZoom Sets/returns print preview window's initial zoom factor

PreviewMaximize
PreviewPageOf
RepeatColumnFooters
RepeatColumnHeaders
RepeatGridHeader
RepeatSplitHeaders
VariableRowHeight
Controls whether the PrintPreview window is initially
maximized when shown
Controls the PrintPreview window display of "Page x of y"
Sets/returns whether column footers should appear on each
page
Sets/returns whether column headers should appear on each
page
Sets/returns whether the grid caption should appear on each
page
Sets/returns whether split captions should appear on each
page
Sets/returns whether row height can vary to fully print each cell

Values property page

The Values property page defines alternate text or graphics for underlying data values, as well as special
data presentation and user interaction settings, such as built-in combo boxes and radio buttons.

Using the Values property page

Unlike the other property pages, the Values property page does not use the tree view model. Instead, it
provides a set of controls for specifying the properties of the ValueItems collection associated with each
Column object, and a translation table for populating the collection with ValueItem members. The
Values property page contains the following controls:
 TDBGrid Property Pages · 169

Column
Use this combo box to select the column to be modified. Like the properties in the Columns property
page, the ValueItems collection of a Column object is global, which means that it cannot vary from one
split to another.

Translate
This check box determines whether data will be translated before it is displayed in the column. It
corresponds to the Translate property of the ValueItems collection, which defaults to False. Note that the
DisplayValue column of the translation table is only visible when this box is checked.

AnnotatePicture
This check box determines whether both text and graphics can be displayed in the same cell. It
corresponds to the AnnotatePicture property of the ValueItems collection, which defaults to False.

Validate
This check box determines whether end users can enter only data that is defined in the translation table. If
checked, data not defined in the translation table will not be accepted by the column. This corresponds to
the Validate property of the ValueItems collection, which defaults to False.

CycleOnClick
If checked, end users can click on the cell to cycle through the data items defined in the translation table.
This control corresponds to the CycleOnClick property of the ValueItems collection, which defaults to
False.

Presentation
This combo box controls whether value items are displayed as a set of radio buttons, a dropdown combo
box, check boxes, or text. It corresponds to the Presentation property of the ValueItems collection, which
defaults to 0 - Normal (normal text display).

MaxComboItems
If the built-in combo box is used for display (Presentation is set to 2 - Combo Box or 3 - Sorted Combo Box),
this edit control defines the maximum number of items that can be displayed in the combo box. It
corresponds to the MaxComboItems property of the ValueItems collection, which defaults to 5.

Value (first column of translation table)

Entries in this column match the underlying data value stored in the database. For translation purposes,
this value must match the string representation of the underlying data, which is used internally by the
grid. Depending on how the data source converts numbers to strings, there may be an extra space, for a
possible minus sign, at the beginning of the string representation. Therefore, you may need to pad entries
in this column with a single space. This column corresponds to the Value property of the ValueItem
object.

DisplayValue (second column of translation table)

Entries in this column contain the translated display value, if desired. For example, to display 1 as Yes,
enter 1 in the Value column, and Yes in the DisplayValue column. This column corresponds to the
170 · Design Time Interaction

DisplayValue property of the ValueItem object. Note that the DisplayValue column is only visible when
the Translate box is checked.

Append
This command button adds a new blank row to the end of the translation table for entering additional
data values. The new row becomes the current row.

Insert
This command button inserts a new row above the current row of the translation table for entering
additional data values. The new row becomes the current row.

Remove
This command button deletes the current row from the translation table.

Picture
Use this button to open a bitmap file selection dialog. Locate the bitmap you want to display, then press
the OK button in the dialog to load the bitmap into the DisplayValue column.

Record Selectors (translation table)

Select a row in the translation table to specify a default value to display whenever a data value not
present in the ValueItems collection is encountered. The index of the selected row corresponds to the
DefaultItem property of the ValueItems collection.

ValueItems properties
The following ValueItems collection properties are available on the Values property page of the
TDBGrid control:
AnnotatePicture True to show both underlying data and display value graphics
CycleOnClick True to cycle through value items on click
DefaultItem Index of default value item, or -1 if no default
MaxComboItems Maximum number of items shown in a drop-down combo
Presentation Specifies how value items are displayed
Translate True to translate data values to display values
Validate True to auto-validate input values

ValueItem properties
The following ValueItem object properties are available on the Values property page of the TDBGrid
control:
DisplayValue Sets/returns displayed text or graphics
Value Sets/returns untranslated data value
 TDBDropDown Property Pages · 171

TDBDropDown Property Pages

The TDBDropDown control supports the following property pages. With the exception of the Values
page, all of them use the property tree model described earlier in this chapter.
General This page contains all control properties and displays the full object model. It
is a superset of the Columns page, as it provides access to grid properties in
addition to those of the Columns collection.
Columns This page contains the properties of the control's Column objects. It provides
a shortcut to the contents of the Columns property node on the General
page. Since the TDBDropDown control does not support splits, all properties
of the Column object appear on this page.
Style Factory This page enables you to create and modify named styles that can be applied
to the various style properties of the control and its columns.
Values This page defines alternate text or graphics for underlying data values.

General property page (TDBDropDown)

The General property page defines the control's data access mode, user interaction permissions,
navigation key behavior, and overall display characteristics. These are global properties that apply to the
control as a whole (that is, the TDBDropDown object). You can also use this page to specify a layout file
containing one or more named layouts.
Since this control does not support multiple splits, it does not have a Splits collection or a Splits property
page. Therefore, properties that still make sense for a single-split control, such as ScrollBars, were moved
to this page.
172 · Design Time Interaction

General properties by alphabet (TDBDropDown)

The following TDBDropDown control properties are available on the General property page:
AllowColMove Enables interactive column movement
AllowColSelect Enables interactive column selection
AllowRowSizing Enables interactive row resizing
AlternatingRowStyle Controls whether even/odd row styles are applied
AnchorRightColumn Controls horizontal scrolling when the last column is visible
Appearance Controls 3-D display of column headings
BackColor Sets/returns the background color
BorderStyle Sets/returns style for drop-down border
ColumnFooters Turns column footings on or off
ColumnHeaders Turns column headings on or off
Columns Contains a collection of drop-down columns
DataField Drop-down column used to update associated grid column
DataMember Sets/returns a data member offered by an OLE DB provider
DataMode Specifies bound or unbound mode
DeadAreaBackColor Sets/returns the background color of the control's dead area
DefColWidth Specifies column width for auto-created columns
EmptyRows Enables empty rows in an underpopulated drop-down
Enabled Enables or disables user interaction
EvenRowStyle Controls the row style for even-numbered rows
ExtendRightColumn True if rightmost column extends to edge of split
FetchRowStyle Controls whether the FetchRowStyle event will be fired
Font Specifies the overall font for a drop-down
FooterBackColor Sets/returns the footing background color
FooterFont Specifies the footing font for a drop-down
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a drop-down
FootLines Number of lines allocated for footing text
ForeColor Sets/returns the foreground color
HeadBackColor Sets/returns the heading background color
HeadFont Specifies the heading font for a drop-down
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a drop-down
HeadLines Number of lines allocated for heading text
HighlightRowStyle Controls the marquee style when set to Highlight Row
IntegralHeight Controls whether partial rows are displayed
 TDBDropDown Property Pages · 173

LayoutFileName Sets/returns the name of a file containing drop-down layouts

LayoutName Sets/returns the name of the current drop-down layout
LayoutURL Sets/returns the URL used for downloading drop-down layouts
ListField Sets/returns the name of the incremental search column
OddRowStyle Controls the row style for odd-numbered rows
RightToLeft When True, applies right to left text functionality
RowDividerColor Controls the row divider color
PartialRightColumn True if rightmost column can be clipped to edge of split
RowDividerStyle Selects style of row divider lines
RowHeight Specifies height of all drop-down rows
RowSubDividerColor Controls the row subdivider color
RowTracking When True, cursor position determines current selected row
ScrollBars Sets/returns scroll bar style for the drop-down
ScrollTips Determines whether the grid displays a pop-up window
ScrollTrack Scrollbar thumb causes the grid display to update
Style Controls the normal style for a drop-down
ValueTranslate Determines if a grid column performs automatic value translation

General properties by category (TDBDropDown)

Appearance properties
AlternatingRowStyle Controls whether even/odd row styles are applied
AnchorRightColumn Controls horizontal scrolling when the last column is visible
Appearance Controls 3-D display of column headings
BorderStyle Sets/returns style for drop-down border
ColumnFooters Turns column footings on or off
ColumnHeaders Turns column headings on or off
DefColWidth Specifies column width for auto-created columns
EmptyRows Enables empty rows in an underpopulated drop-down
ExtendRightColumn True if rightmost column extends to edge of split
FootLines Number of lines allocated for footing text
HeadLines Number of lines allocated for heading text
IntegralHeight Controls whether partial rows are displayed
PartialRightColumn True if rightmost column can be clipped to edge of split
RowDividerStyle Selects style of row divider lines
RowHeight Specifies height of all drop-down rows
174 · Design Time Interaction

Behavior properties
AllowColMove Enables interactive column movement
AllowColSelect Enables interactive column selection
AllowRowSizing Enables interactive row resizing
Enabled Enables or disables user interaction
ExtendRightColumn True if rightmost column extends to edge of split
FetchRowStyle Controls whether the FetchRowStyle event will be fired
PartialRightColumn True if rightmost column can be clipped to edge of split
RightToLeft When True, applies right to left text functionality
RowTracking When True, cursor position determines current selected row
ScrollBars Sets/returns scroll bar style for the drop-down
ScrollTips Determines whether the grid displays a pop-up window
ScrollTrack Scrollbar thumb causes the grid display to update
ValueTranslate Determines if a grid column performs automatic value translation

Color properties
BackColor Sets/returns the background color
DeadAreaBackColor Sets/returns the background color of the control's dead area
FooterBackColor Sets/returns the footing background color
FooterForeColor Sets/returns the footing foreground color
ForeColor Sets/returns the foreground color
HeadBackColor Sets/returns the heading background color
HeadForeColor Sets/returns the heading foreground color
RowDividerColor Controls the row divider color
RowSubDividerColor Controls the row subdivider color

Data properties
DataField Drop-down column used to update associated grid column
DataMember Sets/returns a data member offered by an OLE DB provider
DataMode Specifies bound or unbound mode
ListField Sets/returns the name of the incremental search column

Font properties
Font Specifies the overall font for a drop-down
FooterFont Specifies the footing font for a drop-down
HeadFont Specifies the heading font for a drop-down
 TDBDropDown Property Pages · 175

Layout properties
LayoutFileName Sets/returns the name of a file containing drop-down layouts
LayoutName Sets/returns the name of the current drop-down layout
LayoutURL Sets/returns the URL used for downloading drop-down layouts

Style properties
AlternatingRowStyle Controls whether even/odd row styles are applied
EvenRowStyle Controls the row style for even-numbered rows
FooterStyle Controls the footing style for a drop-down
HeadingStyle Controls the heading style for a drop-down
HighlightRowStyle Controls the marquee style when set to Highlight Row
OddRowStyle Controls the row style for odd-numbered rows
Style Controls the normal style for a drop-down

Columns property page (TDBDropDown)

The Columns property page provides a shortcut to the Columns collection of the General property page.
Since the TDBDropDown control does not have a Splits collection or a Splits property page, all Column
object properties are global, and all are accessible from this page.
176 · Design Time Interaction

Column properties by alphabet (TDBDropDown)

The following Column object properties are available on the Columns property page of the
TDBDropDown control:
Alignment Specifies horizontal text alignment
AllowSizing Enables interactive resizing for a column
BackColor Sets/returns the background color
Caption Sets/returns column heading text
ConvertEmptyCell Specifies if empty cells are saved as empty strings or Null values
DataField Data table field name for a column
DataWidth Maximum number of characters available for column input
DefaultValue Default value for new column data
DividerColor Controls the divider color of a split or column divider
DividerStyle Divider style for right column border
FetchStyle Controls whether the FetchCellStyle event fires for a column
Font Specifies the overall font for a column
FooterAlignment Specifies column footing alignment
FooterBackColor Sets/returns the footing background color
FooterDivider Controls display of dividing line in column footer
FooterFont Specifies the footing font for a column
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a column
FooterText Column footing text
ForeColor Sets/returns the foreground color
HeadAlignment Specifies column heading alignment
HeadBackColor Sets/returns the heading background color
HeaderDivider Controls display of dividing line in column header
HeadFont Specifies the heading font for a column
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a column
MinWidth Sets/returns the minimum width a column can resize to when in
spring mode
NumberFormat Data formatting string for a column
Style Controls the normal style for a column
Visible Shows/hides a column
Width Sets/returns column width in container coordinates
WrapText True if cell text is word wrapped
 TDBDropDown Property Pages · 177

Column properties by category (TDBDropDown)

Appearance properties
Alignment Specifies horizontal text alignment
Caption Sets/returns column heading text
DividerStyle Divider style for right column border
FetchStyle Controls whether the FetchCellStyle event fires for a column
FooterAlignment Specifies column footing alignment
FooterDivider Controls display of dividing line in column footer
FooterText Column footing text
HeadAlignment Specifies column heading alignment
HeaderDivider Controls display of dividing line in column header
Visible Shows/hides a column
Width Sets/returns column width in container coordinates
WrapText True if cell text is word wrapped

Behavior properties
AllowSizing Enables interactive resizing for a column
ConvertEmptyCell Specifies if empty cells are saved as empty strings or Null values
MinWidth Sets/returns the minimum width a column can resize to when in
spring mode

Color properties
BackColor Sets/returns the background color
DividerColor Controls the divider color of a split or column divider
FooterBackColor Sets/returns the footing background color
FooterForeColor Sets/returns the footing foreground color
ForeColor Sets/returns the foreground color
HeadBackColor Sets/returns the heading background color
HeadForeColor Sets/returns the heading foreground color

Data properties
DataField Data table field name for a column
DataWidth Maximum number of characters available for column input
DefaultValue Default value for new column data
NumberFormat Data formatting string for a column
178 · Design Time Interaction

Font properties
Font Specifies the overall font for a column
FooterFont Specifies the footing font for a column
HeadFont Specifies the heading font for a column

Style properties
FooterStyle Controls the footing style for a column
HeadingStyle Controls the heading style for a column
Style Controls the normal style for a column

Style Factory property page (TDBDropDown)

The Style Factory property page of the TDBDropDown control is identical to its TDBGrid counterpart.
For more information, see Style Factory property page (page 162.)

Values property page (TDBDropDown)

The Values property page of the TDBDropDown control is similar to its TDBGrid counterpart.
However, since the TDBDropDown control is used for selection, not editing, the following ValueItems
collection properties are not supported:
CycleOnClick True to cycle through value items on click
MaxComboItems Maximum number of items shown in a drop-down combo
Presentation Specifies how value items are displayed
Validate True to auto-validate input values
For more information, see Values property page (page 168.)

Reusable Layouts
True DBGrid provides a reusable layout facility that enables you to store one or more grid layouts in a
binary file, then recall them as needed at design time or run time. With this feature, you can:
• Create repositories of grid layouts that you can reuse in future projects.
• Reduce the number of grids on a form by associating multiple layouts with a single grid control.
• Change the layout at run time with very little coding.
• Save end-user layout preferences to a file, then reload them the next time the application is run.
• Initialize a grid on an HTML page by downloading a layout file asynchronously.
At design time, use the LayoutFileName and LayoutName properties to specify the current layout. Then,
use the appropriate visual editing menu commands to load, save, or remove the current layout.
At run time, use the LayoutName property and LoadLayout method to restore a layout from the file
specified by the LayoutFileName property. To add a new layout to the current layout file, or replace an
existing layout in the file, use the Add method of the Layouts collection. To remove a layout from the
current layout file, use the Remove method of the Layouts collection.
 TDBDropDown at Design Time · 179

If you use a TDBGrid or TDBDropDown control on an HTML page, you can set the LayoutURL
property to initiate asynchronous downloading of a layout file from an HTTP server. When the grid has
finished downloading the file, it will fire the LayoutReady event. Your script code should handle this
event by using the LayoutName property and LoadLayout method to restore a particular layout.

Saving the current layout

To save a grid layout to a file at design time, do the following:
1. Configure the grid to your liking as you normally would.
2. In the General property page or Visual Basic Properties window, set the LayoutFileName
property to the name of a layout file. If the file does not exist, you will be asked if you want to
create it.
3. In the General property page or Visual Basic Properties window, set the LayoutName property to
the string that you will use to identify the layout.
4. From the visual editing menu, choose the Save Layout command. This is analogous to calling the
Add method of the Layouts collection, which uses the current value of the LayoutFileName
property at run time.

Loading a saved layout

To load a grid layout from a file at design time, do the following:
1. In the General property page or Visual Basic Properties window, set the LayoutFileName
property to the name of an existing layout file.
2. In the General property page or Visual Basic Properties window, set the LayoutName property to
the string that identifies the layout to be loaded.
3. From the visual editing menu, choose the Load Layout command. This is analogous to calling the
LoadLayout method, which uses the current values of the LayoutName and LayoutFileName
properties at run time.

Removing a saved layout

To remove a grid layout from a file at design time, do the following:
1. In the General property page or Visual Basic Properties window, set the LayoutFileName
property to the name of an existing layout file.
2. In the General property page or Visual Basic Properties window, set the LayoutName property to
the string that identifies the layout to be removed.
3. From the visual editing menu, choose the Remove Layout command. This is analogous to calling
the Remove method of the Layouts collection, which uses the current value of the
LayoutFileName property at run time.

TDBDropDown at Design Time

Since the TDBDropDown control is a subset of TDBGrid, the two controls have many properties in
common and are similar to work with at design time. There are two major differences, however, due to
the reduced functionality and user interface of TDBDropDown.
180 · Design Time Interaction

First, TDBDropDown does not support multiple splits. Therefore, it does not have a Splits collection,
which means that:
• There is no Splits property page. Properties that still make sense for a single-split control, such as
ScrollBars, were moved to the General property page.
• The visual editing menu commands Split and Remove were removed.
• You cannot create a new split interactively in visual editing mode.
Second, TDBDropDown does not support cell editing. Therefore, the following features are no longer
accessible from the property pages:
• In-cell buttons.
• Some ValueItems properties, such as CycleOnClick and Validate.
• User permission properties, such as AllowAddNew, AllowDelete, and AllowUpdate.
 Navigation and Scrolling · 181

Run Time Interaction

This chapter describes how users of your application interact with True DBGrid at run time. You can give
your users the ability to perform any or all of the following:
• Navigate within the grid using the mouse or keyboard.
• Select rows or columns.
• Add, update, and delete records.
• Configure the grid's layout.
In the following sections, the properties and events associated with a particular user action are noted
where applicable.

Navigation and Scrolling

The following sections describe the grid's default navigation and scrolling behavior. You always have
complete control over the behavior of the TAB and arrow keys as well as the position of the current cell
when a row or split boundary is reached.

Mouse navigation
When the user clicks a non-current cell, the grid fires the BeforeRowColChange event. Unless you cancel
this event, the clicked cell becomes current and the grid subsequently fires the RowColChange event
after any pending update operations have completed. The only exceptions to this are:
• If the user clicks a cell in a column or split that has the AllowFocus property set to False, and the
cell belongs to the current row, then the current cell does not change.
• If the user clicks a cell in a column or split that has the AllowFocus property set to False, and the
cell does not belong to the current row, then the current row changes, but the column with the
focus retains it.
• If the current cell has been modified, and the BeforeColUpdate event is canceled, then the
current cell does not change.
• If the current row has been modified, and the user clicks a cell in a different row, and the
BeforeUpdate event is canceled, then the current cell does not change.
The user can also use the mouse to manipulate the grid's scroll bars, bringing cells that lie outside the
grid's display area into view. The vertical scroll bar governs rows; the horizontal scroll bar governs
columns. The ScrollBars property controls which scroll bars are displayed, if any.
Scrolling always occurs in discrete cell units; the user cannot scroll on a per-pixel basis in either direction.
Note that the scroll bars do not change the current cell. Therefore, the current cell may not always be
visible.
To respond to vertical scrolling operations in code, use the FirstRowChange event. To respond to
horizontal scrolling operations in code, use the LeftColChange event.
182 · Run Time Interaction

Clicking the rightmost column

The grid always displays the leftmost column (the first visible column) in its entirety. The rightmost
column, however, is usually clipped. The behavior of the last partially visible column when clicked by the
user is controlled by the grid's ExposeCellMode property.
The default value for the ExposeCellMode property is 0 - Scroll On Select. If the user clicks the rightmost
column when it is partially visible, the grid will scroll to the left to display this column in its entirety. This
may be less desirable for users who commonly click on the grid to begin editing, as the grid will always
shift to the left when the user clicks on a partially visible rightmost column.
If ExposeCellMode is set to 1 - Scroll On Edit, the grid will not scroll when the rightmost visible column is
clicked. However, if the user attempts to edit the cell, then the grid will scroll to the left to display the
column in its entirety. This is how Microsoft Excel works and is probably the most familiar setting to
users.
If ExposeCellMode is set to 2 - Never Scroll, the grid will not scroll to make the rightmost column visible,
even if the user subsequently attempts to edit the cell. Note that editing may be difficult if only a small
portion of the column is visible. The chief reason to use this setting is if you know there will always be
enough space available for editing (or if you disallow editing) and you never want the grid to shift
accidentally.
Note that the ExposeCellMode property controls the behavior of the rightmost visible column only when
the user clicks it with the mouse. If the rightmost column becomes visible by code (setting the grid's Col
property) or by keyboard navigation, then the grid will always scroll to make it totally visible.

IntelliMouse support
True DBGrid responds to Microsoft IntelliMouse activity as follows:
• If the user turns the wheel, the grid scrolls vertically by one row for each click of the wheel.
• If the user holds down the SHIFT key while turning the wheel, the grid scrolls vertically by one
page for each click of the wheel.
• If a horizontal scroll bar is present, and the user holds down the CTRL key while turning the
wheel, the grid scrolls horizontally by one column for each click of the wheel. If there is no
vertical scroll bar, the user need not hold down the CTRL key.
• If the user holds down the SHIFT key while performing a horizontal scrolling operation, the grid
scrolls horizontally by one page for each click of the wheel.
In summary:
• Vertical scrolling takes precedence over horizontal scrolling, unless overridden with the CTRL
key.
• The default scrolling increment is one row (or column), unless overridden with the SHIFT key, in
which case the grid scrolls by one page.

Keyboard navigation
By default, the user can navigate the grid with the arrow keys, the ENTER key, the TAB key, the PGUP and
PGDN keys, and the HOME and END keys.
UP/DOWN ARROWS These keys move the current cell to adjacent rows.
LEFT/RIGHT ARROWS If the AllowArrows property is True (the default), these keys move the
current cell to adjacent columns.
 Navigation and Scrolling · 183

If the AllowArrows property is False, then these keys move focus from
control to control and cannot be used to move between cells.
ENTER By default, the ENTER key behaves in the same manner as the RIGHT ARROW
key, by moving the current cell from left to right along the adjacent columns.
The behavior for the ENTER key can be modified by using the
DirectionAfterEnter property.
TAB If the TabAction property is 0 - Control Navigation (the default), the TAB key
moves focus to the next control on the form, as determined by the tab order.
If the TabAction property is 1 - Column Navigation or 2 - Grid Navigation, the
TAB key moves the current cell to the next column, while SHIFT + TAB moves
to the previous column. The differences between column and grid navigation
are discussed in the next section.
PGUP, PGDN These keys scroll the grid up or down an entire page at a time. Unlike the
vertical scroll bar, the PGUP and PGDN keys change the current row by the
number of visible rows in the grid's display. When paging up, the current row
becomes the first row in the display area. When paging down, the current row
becomes the last row in the display area, including the AddNew row. The
current column does not change.
HOME, END These keys move the current cell to the first or last column. If necessary, the
grid will scroll horizontally so that the current cell becomes visible. The
current row does not change. If the current cell is being edited, HOME and
END move the insertion point to the beginning or end of the cell's text.

Navigation at row boundaries

At row boundaries, namely the first and last column, grid navigation depends on the WrapCellPointer
property. The following explanation assumes that the AllowArrows property is True, and that the
TabAction property is set to either 1 - Column Navigation or 2 - Grid Navigation.
LEFT/RIGHT ARROWS If the WrapCellPointer property is True, the current cell wraps across row
boundaries. If the current cell is in the last column, the RIGHT ARROW key
moves it to the first column of the next row. If the current cell is in the first
column, the LEFT ARROW key moves it to the last column of the previous row.
If the WrapCellPointer property is False (the default), these keys cannot
move the current cell at row boundaries.
TAB If the TabAction property is 1 - Column Navigation, the cell pointer does not
wrap to an adjacent row, and the WrapCellPointer property is ignored. If the
current cell is in the last column, TAB moves focus to the next control in the
tab order. If the current cell is in the first column, SHIFT+TAB moves focus to
the previous control in the tab order.
If the TabAction property is 2 - Grid Navigation and WrapCellPointer is
True, TAB and SHIFT+TAB move the current cell to the next or previous row.
The current cell will not cross row boundaries if WrapCellPointer is False.

Navigation at split boundaries

At split boundaries, grid navigation depends on the TabAcrossSplits property as follows:
LEFT/RIGHT ARROWS If the TabAcrossSplits property is True, these keys move the current cell
across split boundaries to the next or previous split.
If the TabAcrossSplits property is False (the default), the behavior of these
keys at split boundaries will be the same as their behavior at row boundaries.
184 · Run Time Interaction

Note that a split's AllowFocus property must be True in order for these keys
to move the current cell to that split.
TAB The TAB and SHIFT+TAB keys honor TabAcrossSplits as previously
described for the arrow keys.

Restricting cell navigation

You can always use the BeforeRowColChange event to prevent the user from moving to a different cell,
regardless of whether the current cell is modified. Set the Cancel argument to True to keep another cell
from becoming current.
If the current cell has been modified, you can use the BeforeColUpdate event to examine its value before
moving to another grid cell. If the value entered is invalid, you can set the Cancel argument to True to
prevent the current cell from changing, and optionally beep or display an error message for the user. The
BeforeColUpdate event provides a flexible way to validate user input and restrict cell navigation.
Private Sub TDBGrid1_BeforeColUpdate( _
ByVal ColIndex As Integer, _
OldValue As Variant, _
Cancel As Integer)
Dim CharCode As Integer
If ColIndex = 1 Then
' Data in Column 1 must start with upper case
CharCode = Asc(TDBGrid1.Columns(1).Text)
If CharCode > 64 And CharCode < 91 Then Exit Sub
' Display warning message for user
MsgBox "Last name must start with upper case"
' Data validation fails, prohibit user from moving to
' another cell
Cancel = True
End If
End Sub

Selection and Movement

The following sections describe how users can select columns, move selected columns, and select rows.
You can always restrict any or all of these operations at design time or in code.

Selecting columns
If the AllowColSelect property is True, the user can select an individual column or a range of columns
with the mouse. Nonadjacent column selections are not supported.
When the user points to the header of an unselected column, the mouse pointer changes to a down arrow
to indicate that the column can be selected.
 Selection and Movement · 185

When the user clicks a column header, that column is selected and highlighted, and any columns or rows
that were previously selected are deselected.

There are two ways for the user to select a range of columns:
1. After selecting the first column in the range by clicking its header, the user can select the last
column in the range by holding down the SHIFT key and clicking another column header. If
necessary, the horizontal scroll bar can be used to bring additional columns into view.
2. Alternatively, the user can hold and drag the mouse pointer within the column headers to select
multiple columns.
The SelStartCol and SelEndCol properties will be adjusted to reflect the columns selected by the user.
You can prevent a column selection from occurring at run time by setting the Cancel argument to True in
the grid's SelChange event.

Moving columns
If the AllowColMove property is True, the user can move previously selected columns as a unit to a
different location by pressing the mouse button within the header area of any selected column. The
pointer will change to an arrow with a column header box on its tip, a small box at its lower right corner,
and a position marker consisting of two red triangles will appear at the left edge of the column being
pointed to and highlighted.
186 · Run Time Interaction

The user specifies the desired location of the selected columns by dragging position marker, which
changes position as the mouse pointer crosses the right edge of a column.

The user completes the operation by releasing the mouse button, which moves the selected columns
immediately to the left of the position marker. The moved columns remain selected.

If the user drags the marker to a position within the currently selected range, no movement occurs.
Columns that are not selected cannot be moved interactively.
When a move occurs, the Order property is adjusted for all affected columns. You can always rearrange
columns in code by modifying the Order property yourself.
You can prevent interactive column movement from occurring at run time by setting the Cancel argument
to True in the ColMove event.
 Selection and Movement · 187

Selecting rows
If the AllowRowSelect and RecordSelectors properties are both True, the user can select records with the
mouse. When the user points to a button within the record selector column, the mouse pointer changes to
a right arrow to indicate that record selection is enabled.

If enabled, record selection behavior is determined by the MultiSelect property. By default, this property
is set to 1 - Simple, and the user can select one or more records with the mouse. When the user clicks the
record selector for a row, that row is selected and highlighted, and any rows or columns that were
previously selected are deselected. The newly selected row also becomes the current row.

However, unlike column selections, nonadjacent row selections are supported. If the user holds down the
CTRL key while making the selection, the current row does not change, and any previously selected rows
remain selected. This technique also enables the user to select multiple rows, one at a time. Since selected
rows do not have to be adjacent, the user can also operate the vertical scroll bar to bring other rows into
view if desired.
The user can also select a range of contiguous rows by clicking the record selector of the first row in the
range, then holding down the SHIFT key and clicking the record selector of the last row in the range. If
necessary, the vertical scroll bar can be used to bring additional rows into view.
If MultiSelect is set to 2 - Extended, the default behavior is supported, but the user can also select records
with the following key combinations: SHIFT + UP ARROW, SHIFT + DOWN ARROW, SHIFT + PGUP, and SHIFT
+ PGDN. NOTE: When 2 - Extended is chosen, the user will not be able to select a single cell, instead the
entire corresponding row will be selected.
If MultiSelect is set to 0 - None, multiple selection is disabled but single selection is permitted. When the
user clicks a record selector, the current selection is cleared and the clicked row is selected and
highlighted. However, the CTRL and SHIFT keys are ignored, and the user can only select one row at a
time.
188 · Run Time Interaction

If the value of MultiSelect is set to 0 or 1, the user can deselect all rows by clicking a data cell or selecting
columns. Clicking the record selector of a selected row does not deselect it.
The SelBookmarks collection will always be updated to reflect which rows are currently selected by the
user. You can always select one or more rows in code by adding bookmarks to the SelBookmarks
collection, even if MultiSelect is 0 - None. Similarly, you can deselect rows by removing bookmarks from
this collection.
You can prevent a row selection from occurring at run time by setting the Cancel argument to True in the
grid's SelChange event.

Sizing and Splitting

The following sections describe how users can resize rows, columns, and splits. You can always restrict
any or all of these operations at design time or in code.

Sizing rows
If the AllowRowSizing property is True, the user can change the row height at run time. When the user
points to a row divider in the record selector column, the pointer changes to a vertical double arrow,
which the user can drag to adjust the height of all rows.

Dragging the pointer upward makes the rows smaller; dragging it downward makes the rows larger. All
rows in the grid will be resized to the same height; it is not possible to resize individual rows. If the grid
does not display the record selector column (that is, the RecordSelectors property is False), users cannot
interactively change the row height.
The RowHeight property of the grid will be adjusted when the user completes the resize operation.
You can prevent row resizing from occurring at run time by setting the Cancel argument to True in the
RowResize event. You can always change the RowHeight of the grid in code, even if AllowRowSizing is
False or you cancel the RowResize event.

Sizing columns
If the AllowSizing property is True for a column, the user can adjust the width of the column
individually at run time. When the user points to the divider at the right edge of a column's header, the
pointer changes to a horizontal double arrow, which the user can drag to resize the column in question.
 Sizing and Splitting · 189

Dragging the pointer to the left makes the column smaller; dragging it to the right makes the column
larger. The column's Width property will be adjusted when the user completes the resize operation.
If the grid does not display column headers (that is, the ColumnHeaders property is False), the horizontal
double arrow will appear when the pointer is over the column divider within the grid's data area.
If the user drags the pointer all the way to the left, the column retains its original Width property setting,
but its Visible property is set to False. To make the column visible again, the user can point to the right
side of the divider of the column that preceded it. The pointer turns into a vertical bar with a right arrow.

Dragging the pointer to the right establishes a new column width and sets the column's Visible property
back to True.
Another way to resize columns is to use the AutoSize method, which allows you to specify auto-sizing
for a specific Column object in code. When a column is auto-sized, its width is adjusted to fit the longest
visible field in that column. Longer records that are not displayed in a visible row when AutoSize is
invoked do not participate in the width calculations. Furthermore, if the specified column is either hidden
or scrolled out of view, a trappable error occurs.
You can prevent column resizing from occurring at run time by setting the Cancel argument to True in the
ColResize event. You can always change the width of a column in code, even if AllowSizing is False for
that column.

Sizing splits
If the AllowSizing property is True for a split, the user can reposition its split bar. If the split is the
leftmost sizable split of the grid, the user can also create a new split. For details, see Creating and sizing
splits (page 131).
190 · Run Time Interaction

Database Operations
The editing, deleting, and adding permissions granted to the user at run time are controlled by the
AllowUpdate, AllowDelete, and AllowAddNew properties. The default values of these properties are:
AllowUpdate = True
AllowDelete = False
AllowAddNew = False
Note that these properties only control user interaction with the grid at run time. They do not control
whether database operations can be performed by the Data control or other bound controls, or by your
application code.

Editing data
True DBGrid's AllowUpdate property must be True in order for the user to edit data in the grid. The
default value is True.
If the user moves to a cell and starts typing, the cell's data will be replaced by what is typed.
Alternatively, clicking within the current cell will put the grid into edit mode (its EditActive property
becomes True), enabling the user to modify the cell's data.
While editing, the LEFT ARROW and RIGHT ARROW keys move the insertion point within the cell. If the
insertion point is at the beginning or end of the cell's text, the LEFT ARROW and RIGHT ARROW keys will
terminate editing by moving to the adjacent cell. The UP ARROW and DOWN ARROW keys terminate
editing by moving the current cell to the row above or below the current one. The user can also end
editing without moving the current cell by pressing the ENTER key.
When one or more cells in a row have been modified, a pencil icon will appear in the record selector
column to indicate that data in the row has been changed. The pencil icon does not mean that the grid's
EditActive property is True; it means that the grid's DataChanged property is True. To cancel the changes
made to the current cell, the user can press the ESC key. In fact, before moving to another row, the user
can revisit any column within the current row and press the ESC key to restore the cell to its original
value. If the user repeats this procedure for all modified cells in the row, the pencil icon in the record
selector will disappear.
Moving to another row by clicking it, using the UP ARROW or DOWN ARROW keys, or by clicking the
navigation buttons of the Data control will update the modified record to the database. If the update is
successful, the pencil icon will disappear. If no grid columns have been modified, no update will occur
when changing rows.

Adding a new record

True DBGrid's AllowAddNew property must be True in order for the user to add new records to the grid
interactively. The default value is False.
If the AllowAddNew property is True, an empty AddNew row, marked by an asterisk in the record
selector column, will be displayed after the last record. The user can initiate an add operation by
navigating to the AddNew row, either by clicking it or by using the DOWN ARROW key, then typing new
data. The first character typed will cause the grid to insert a blank row before the AddNew row. The
newly inserted blank row becomes the current row, and the grid fires the OnAddNew event.
At this point, the new row exists only in the grid—it does not have a bookmark, and it does not yet
represent a physical database record. The new row is added to the underlying data source when the user
navigates to another data row or the AddNew row.
 Drag-and-Drop Behavior · 191

Deleting a record
True DBGrid's AllowDelete property must be True in order for the user to delete records through the
grid. The default value is False.
To delete a record, the user selects the row to be deleted by clicking its record selector, then pressing the
DEL key. Only one record can be deleted at a time. The user cannot select multiple records and press the
DEL key to delete them all.
NOTE: In order for the record to be deleted, the grid must have focus so it can receive the DEL key.
Clicking the grid's record selector column does not set focus to the grid. However, if you always want the
grid to receive focus when the user clicks the record selector column, set focus to the grid in the grid's
SelChange event:
Private Sub TDBGrid1_SelChange(Cancel As Integer)
TDBGrid1.SetFocus
End Sub

Drag-and-Drop Behavior
Typically, implementing a drag-and-drop interface using a grid is a painstaking task, since you normally
want to drag data from a particular cell or row to another. Visual Basic's drag-and-drop facilities work
with entire controls, but do not provide features for detecting which element of a control is involved.
True DBGrid has a special event, DragCell, designed to simplify the initiation of a drag operation.
DragCell is called whenever the user attempts to drag data from a cell to another location; your code can
respond accordingly. DragCell informs you of the split index, row bookmark, and column index of the
cell being dragged. Typically, you will save the information so that it is available when the drag-and-
drop operation terminates. At design time, be sure to change the grid's DragIcon (Visual Basic) property
to a meaningful icon, since the default behavior is to drag an outline of the grid.
NOTE: The DragCell event will not fire for the current cell when the grid's MarqueeStyle property is set
to the default value of 6 - Floating Editor. This is because the floating editor processes mouse events itself,
as it must handle insertion point movement and text selection. For more information, see Highlighting
the Current Row or Cell (page 254).
For example, assume that you want to be able to drag a row of data elsewhere. The following code in the
DragCell event handler starts the drag-and-drop operation:
Private Sub TDBGrid1_DragCell(ByVal SplitIndex As Integer, _
RowBookmark As Variant, ByVal ColIndex As Integer)
' Set the current cell to the one being dragged
TDBGrid1.Col = ColIndex
TDBGrid1.Bookmark = RowBookmark
' Set up drag operation, such as creating visual effects by
' highlighting the cell or row being dragged.
' Use VB manual drag support (put TDBGrid1 into drag mode)
TDBGrid1.Drag vbBeginDrag
End Sub
Note that the Col and Bookmark properties of the grid are set to reflect the cell that was dragged. Once
this event is completed, Visual Basic takes over the drag operation (see the Visual Basic documentation
for the Drag method). Place code in the DragDrop event of the destination to perform the actions related
to the drop.
192 · Run Time Interaction

If the destination of a drag operation is another True DBGrid control, and you want to drop data into a
row or cell, you need to consider the following:
• You may want to provide feedback for the user about which row or cell will be the target of the
drop.
• You may want to respond to the DragDrop (Visual Basic) event by actually entering the data
into the target cell or row.
• The limitations of your data source may preclude some operations. For example, you cannot
insert a row into the middle of a recordset or resultset—you can only modify existing records or
append new ones. However, if your grid is populated from an array in unbound mode, you can
insert a new row into the array.
Often, the difficulty with implementing such operations on grids is that, given the mouse location, it is
difficult to find out which cell, row, or column you are about to drop into. True DBGrid solves this
problem by providing the SplitContaining, ColContaining, and RowContaining methods, which
translate mouse coordinates into a grid location. You can also use the PointAt method to detect whether
the drop position is over a data cell or a static element such as a caption bar or record selector.
Suppose that you want to provide feedback to the user about which cell is under the mouse pointer. The
easiest way to do this is in the DragOver (Visual Basic) event, which fires as the mouse moves over the
destination grid. Here's how you would set the current cell pointer so that it tracks the dragging object:
Private Sub TDBGrid2_DragOver(Source As Control, _
X As Single, Y As Single, State As Integer)
' Set current cell to "track" the dragging object
Dim overCol As Integer
Dim overRow As Long
overCol = TDBGrid2.ColContaining(X)
overRow = TDBGrid2.RowContaining(Y)
If overCol >= 0 Then TDBGrid2.Col = overCol
If overRow >= 0 Then TDBGrid2.Row = overRow
End Sub
When the drop occurs [detected in the DragDrop (Visual Basic) event], you can move the appropriate
data into the destination grid, or perform whatever action you want the drop to trigger. For example, you
can copy the contents of the dragged cell (which was made current in the DragCell example presented
earlier) to the current cell in the destination grid:
Private Sub TDBGrid2_DragDrop(Source As Control, _
X As Single, Y As Single)
TDBGrid2.Columns(TDBGrid2.Col).Value = _
TDBGrid1.Columns(TDBGrid1.Col).Value
End Sub
You should also perform some clean-up when the drag-and-drop operation fails or the user completes
the drop outside the boundaries of the destination control. Tutorial 13 (page 56) demonstrates how to
implement a drag-and-drop interface from one grid to another.
True DBGrid also supports OLE drag-and-drop as demonstrated in Tutorial 14 (page 61).
 Additional User Interaction Features · 193

Additional User Interaction Features

True DBGrid provides additional data presentation and manipulation functionality that you can expose
to your users at run time. For more information, please see the following topics:
Context-sensitive Help with CellTips (page 274)
Scroll Tracking and ScrollTips (page 276)
Hierarchical Data Display (page 279)
Dropdown Hierarchical Data Display (page 281)
Filtering Data in Recordsets (page 288)
Outlook-Style Grouping (page 278)
 Binding True DBGrid to a Data Source · 195

Bound Mode
The easiest way to use True DBGrid is in bound mode, in which it communicates directly with an intrinsic
or external data source control to retrieve and update data. Visual Basic 6.0 provides a variety of data
sources that work with True DBGrid in this fashion:
• The built-in Data control, which is included in the standard toolbox. This control uses the
Microsoft Jet engine to access data.
• The Remote Data Control (RDC), which provides access to data stored in a remote ODBC data
source.
• The ADO Data Control, which uses ActiveX Data Objects (ADO) to establish connections
between bound controls and data providers written to the OLE DB specification.
• The Data Environment, which provides a design-time interface for building ADO objects that are
created and consumed by bound controls at run time.
You can also use any other data control that adheres to the Microsoft data binding specifications, such as
Microsoft's Tabular Data Control (TDC).
To use bound mode, set the DataMode property of the grid to 0 - Bound at design time, then set the
DataSource property of the grid to reference an available data source. This can be an intrinsic or external
data control on the same Visual Basic form, or a project-wide data source such as the Data Environment.
You do not need to fully configure the data source at design time since True DBGrid automatically
responds to changes in the data source at run time. Therefore, you can defer specifying a database table
or query until the application is running.

Binding True DBGrid to a Data Source

True DBGrid includes two separate grid controls, one for legacy (ICursor) data sources such as the Visual
Basic built-in Data control, and one for OLE DB-compliant data sources such as the ADO Data Control. In
Visual Basic, you will need to use the correct grid depending upon the type of data source used, as the
following table illustrates.

Binding to an ICursor data source

To associate a True DBGrid control (TDBG8.OCX) with a Visual Basic Data control, set the DataSource
property of the grid to the name of a Data control on the same form. This is all that is required to make
True DBGrid fully aware of the database in your application.
196 · Bound Mode

Once such a link exists, True DBGrid and the Data control automatically notify and respond to all
operations performed by the other, simplifying your application development:
• Once the grid has been associated with a Data control, you can retrieve the field layout of the
database at design time and use the property pages to customize the appearance of the grid. For
more information, see Design Time Interaction (page 129).
• When you run your application, True DBGrid will automatically respond by displaying the
contents of the Recordset defined by the Data control's RecordSource property. Data will be fully
available at run time, and can be edited as well.
True DBGrid will automatically update its display to reflect any changes made to the Data control.
However, True DBGrid waits until the system is idle before performing such display updates, since your
program may need to perform other actions before the display is synchronized.
NOTE: The DataSource property cannot be set at run time, and can only be set at design time within the
Visual Basic Properties window.

Binding to an OLE DB data source

To associate a True DBGrid control (TODG8.OCX) with an OLE DB data source, set the DataSource
property of the grid to the name of an available data source. If necessary, set the DataMember property
to the name of a table or query exposed by the data source. At design time, these properties can only be
set in the Visual Basic Properties window.
Unlike the legacy control (TDBG8.OCX), the OLE DB version of True DBGrid supports assignment to the
DataSource property at run time. The following code sample demonstrates how to bind the grid to a
Data Environment command:
With TDBGrid1
Set .DataSource = DataEnvironment1
.DataMember = "Command1"
End With
The most widely used form of binding a grid to a data source at run time is to assign an ADO recordset to
the DataSource property:
Dim RS As New ADODB.Recordset
RS.Open ...
TDBGrid1.DataSource = RS
NOTE: If you are binding True DBGrid to an ADO recordset in an HTML page, you may need to set the
BookmarkType property before passing grid bookmarks to its data source. For more information, see the
documentation for the BookmarkType property and DataSourceChanged event.

Visual Basic Data Control Considerations

This section gives an overview of how True DBGrid interacts with the built-in Data control of Visual
Basic. Generally speaking, True DBGrid responds to external data controls in a similar manner; however,
the terminology and programming interface used in this section is specific to Visual Basic's intrinsic Data
control.

How True DBGrid reacts to Recordset changes

When you bind a grid to a Data control, you are actually linking the grid to the underlying Recordset
object, which is managed by the Data control. The Recordset object can be accessed directly using the
Recordset property of the Data control:
 Visual Basic Data Control Considerations · 197

Data1.Recordset.MoveFirst
This statement positions the record pointer to the first record in the Recordset.
You need not worry about keeping the grid synchronized with changes made to the Recordset, as this
happens automatically. Modifying the Recordset is the preferred way to effect changes to the grid's
display.
Here is how the grid responds to various operations performed on the Recordset associated with the
Data control:
Positioning The grid's current row will change in response to a successful invocation of any of
the following Recordset control methods: Seek, Move, MoveFirst, MoveLast,
MoveNext, MovePrevious, FindFirst, FindLast, FindNext, and FindPrevious.
If necessary, the grid will scroll to make the current row visible. The grid optimizes
its response to these messages. For example, if your code performs a MoveFirst
followed by 20 consecutive MoveNext calls, the grid will position only once, to the
21st row. Consult the Visual Basic Help for more information on the Recordset
object's methods.
Update The Recordset object's Update method causes the grid to write any changed
data to the database. The update may be canceled in the Data control's Validate
event. After the database is updated, the grid will clear the pencil icon in the
record selector column.
Delete True DBGrid reacts to the Recordset object's Delete method by removing the
current row from the grid display. However, the Delete method does not change
the current record, therefore the Bookmark property of both the grid and the
Recordset still refers to the record that was just deleted. At this point, there is no
current row in the grid, and its Row property returns -1.
Requery This method causes the grid to refetch and redisplay all data. Any modifications
made to the grid's current row that have not been updated to the database will be
lost. After the Requery method is executed, the current cell will be the leftmost
visible column of the first record, which will be displayed at the upper left corner of
the grid.

Interactions between True DBGrid and the Data control

The Data control's First, Last, Next, and Previous buttons can be used to navigate through the grid or any
other bound control. When a Data control button is clicked, the new current row is indicated in the record
selector column of the grid:
• The First and Last buttons have the same effect as the MoveFirst and MoveLast methods of the
Recordset. The grid will position to the first or last row.
• The Next and Previous buttons have the same effect as the MoveNext and MovePrevious
methods of the Recordset. The grid will move forward or backward by one row.
If grid data has been edited, moving the record pointer using the Data control will automatically trigger
an update to the database.
The grid responds to the Data control's Refresh, UpdateRecord, and UpdateControls methods as
follows:
Refresh The grid refetches and redisplays all data. Any modifications made to the grid's
current row that have not been updated to the database will be lost. After the
refresh, the current cell will be the leftmost visible column of the first record,
which will be displayed at the upper left corner of the grid.
198 · Bound Mode

UpdateRecord If data in the current row has changed, the modified data in the grid will be written
to the database without firing the Data control's Validate event. The pencil icon in
the record selector column will disappear. The current cell and the grid display
are not changed.
UpdateControls Any modifications made to the grid's current row that have not been updated to
the database will be discarded and data will be refreshed from the database. The
current cell and the grid display are not changed. This method can be used to
cancel an AddNew or Edit operation.

Using True DBGrid with a Data control on a different form

Using the Data control's Recordset property, you can effectively bind True DBGrid or any other bound
control on one form to a Data control on another form. Strictly speaking, you cannot directly bind a grid to
a Data control on another form. For example, assume you have a grid on Form2 and you would like it to
display data from the Recordset of Data1, which is on Form1. You need to first bind the grid to a Data
control (Data2) on Form2. Form2.Data2 is not connected to a database. Instead, the Recordset of
Form2.Data2 is set to the Recordset of Form1.Data1:
Form2.Data2.DatabaseName = Form1.Data1.DatabaseName
Set Form2.Data2.Recordset = Form1.Data1.Recordset
The grid on Form2 will work as if it were directly bound to Form1.Data1. When you move or update
records through Form1.Data1, the grid on Form2 will respond accordingly. Conversely, if you move or
update records in the grid, all controls on Form1 that are bound to Form1.Data1 will respond.

Using True DBGrid to display SQL query results

True DBGrid can automatically configure itself to changes in the data control's Recordset. This feature is
very useful for displaying the results of ad-hoc SQL queries. If the grid does not have a layout defined, it
will detect any change in the Data control's Recordset and display the new query result set
automatically—no code is necessary to tell the grid what to do. You can create very powerful user
interfaces using these automatic features of the grid. Tutorial 2 (page 29) describes this feature in detail
and also illustrates a few interesting and useful SQL statements.

Unbound Columns
Normally, True DBGrid automatically displays data from bound database fields. However, you may
need to augment the set of fields present in your layouts with columns derived from database fields, or
columns which are unrelated (or only loosely related) to database information. For example, if your
database contains a Balance field, you may instead want to display two columns, Credit and Debit, to show
positive and negative numbers separately. Or, you may want to look up data in another database, or
convert field data to some other form, such as mapping numeric codes to textual descriptions.
To accomplish such tasks you can use unbound columns. The term unbound column refers to a column
that is part of a bound grid, but is not tied directly to a database field. A bound grid has its DataMode
property set to 0 - Bound, and its DataSource property set to a valid data source as described in Binding
True DBGrid to a Data Source (page 195. )Unbound columns are not used in any of the unbound modes.
Columns that do not have the DataField property set (that is, the DataField property is equal to an empty
string), but do have the column Caption property set are considered unbound columns. The grid will
request data for these columns through the UnboundColumnFetch event.
Columns with their DataField property set will be bound to the underlying Recordset if the DataField
property is the same as one of the fields of the Recordset.
 Unbound Columns · 199

Columns with their DataField property set to a value that is not in the Recordset are ignored for the
purposes of fetching data. Similarly, columns that have no value for both the DataField and Caption
properties set are also ignored. Values entered into the grid for these columns will not be cached by the
grid, and will therefore disappear when the row is scrolled out of view.

Creating unbound columns

The first step in using an unbound column is creating the column itself. This may be done at design time
by choosing either the Append or Insert command from the grid's visual editing menu. At run time,
unbound columns may be added using the Add method of the Columns collection. The column must be
given a name by setting its Caption property. At design time, this is done using the Columns property
page. At run time, the Caption property of the appropriate Column object is set. When these actions are
performed at run time, new columns are not considered as unbound columns until the grid's ReBind
method is executed.
NOTE: If you attempt to insert an unbound column in code, you may need to use the HoldFields method
to ensure that the column appears at the desired position within the grid:
Dim Col As TrueDBGrid80.Column

With TDBGrid1
Set Col = .Columns.Add(1)
Col.Visible = True
Col.Caption = "Unbound"
.HoldFields
.ReBind
End With
When the grid needs to display the value of an unbound column, it fires the UnboundColumnFetch
event. This event supplies the user with a bookmark and a column index as the means of identifying the
grid cell being requested. The third argument to the event is a Variant which by default is Null, but can be
changed to any desired value, and will be used to fill the contents of the cell specified by the given
bookmark and column index.
Private Sub TDBGrid1_UnboundColumnFetch(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
When Recordset data is retrieved through the data control, the data is cached by the grid to allow smooth
scrolling operations and rapid display. As a result, many rows must be fetched at one time so that they
are readily available for display. Internally, the grid uses a Recordset clone when it requests data, thus
allowing data to be retrieved without changing the current row of the bound Recordset managed by the
Data control. Why is this important? The reason is that UnboundColumnFetch may need to fetch data
unrelated to the current row position.
For example, suppose a row is being edited and the user scrolls the grid vertically or horizontally. To
update the display, the grid will need to fetch the new data that is scrolled into view for all rows and
columns on the face of the grid. However, changing the current row would cause an unwanted update to
occur. For this reason, the grid will not allow the current row of the grid or Recordset to be changed
during the UnboundColumnFetch event, even through implicit means such as the FindFirst method of
the Recordset. Similarly, other Recordset operations are prohibited as well during the course of this
event.
Given these restrictions, how do you obtain Recordset data in order to set the values of the unbound
column? There are several ways, all of which involve the use of a Recordset clone.
200 · Bound Mode

Implementing unbound columns using Recordset clones

The simplest way to gather the data from other columns is to clone the Recordset, move to the specified
bookmark, and get the data from the clone, as in the following example:
Private Sub TDBGrid1_UnboundColumnFetch(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
Dim myclone As Recordset
Set myclone = Data1.Recordset.Clone()
myclone.Bookmark = Bookmark
Value = myclone.Fields(Col)
End Sub
Although this example is functional, it would be more efficient to make the clone a global object, as it
would no longer be necessary for Visual Basic to create it with each call to the event. A good place to do
this is in the Form_Load event, which fires before the grid is displayed:
Dim ucfClone As Recordset ' Global UnboundColumnFetch clone

Private Sub Form_Load()

Data1.Refresh ' Make sure the recordset is created first
Set ucfClone = Data1.Recordset.Clone()
End Sub
Private Sub TDBGrid1_UnboundColumnFetch(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
ucfClone.Bookmark = Bookmark
Value = ucfClone.Fields(Col)
End Sub
You can speed things up even more by using a Field object, creating it from the clone's Fields collection.
This is faster because Visual Basic does not need to locate the correct field each time the event is called:
Dim ucfClone As Recordset ' Global UnboundColumnFetch clone
Dim ucfField As Field ' Global UnboundColumnFetch field
Private Sub Form_Load()
Data1.Refresh
Set ucfClone = Data1.Recordset.Clone()
Set ucfField = ucfClone.Fields(1)
End Sub
Private Sub TDBGrid1_UnboundColumnFetch(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
ucfClone.Bookmark = Bookmark
Value = ucfField
End Sub
After the ucfField object is initialized in Form_Load, it will always contain the data in Field 1 of the
current row of the clone. If the underlying database field allows null values, you should test the Field
object first before assigning its data to the Value argument:
Private Sub TDBGrid1_UnboundColumnFetch(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
ucfClone.Bookmark = Bookmark
If Not IsNull(ucfField) Then Value = ucfField
End Sub
 Unbound Columns · 201

Using Field objects is an elegant approach. Not only is it more efficient, but it frees you from keeping
track of collection indexes throughout your code. For example, given a Rectangle table containing Length
and Width fields, the following code implements an unbound column that uses Field objects to calculate
the area:
Dim ucfClone As Recordset ' Global UnboundColumnFetch clone
Dim ucfLength As Field
Dim ucfWidth As Field
Private Sub Form_Load()
Data1.Refresh
Set ucfClone = Data1.Recordset.Clone()
Set ucfLength = ucfClone.Fields("Length")
Set ucfWidth = ucfClone.Fields("Width")
End Sub
Private Sub TDBGrid1_UnboundColumnFetch(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
ucfClone.Bookmark = Bookmark
Value = ucfLength * ucfWidth ' Calculate "Area" column
End Sub

Implementing unbound columns using cell access methods

Using Recordset clones is the preferred way to handle the UnboundColumnFetch event. However, if the
grid is bound to a data control that does not support clones, such as the Microsoft Remote Data Control
(RDC), you can derive cell values using the Column object methods CellText and CellValue.
Private Sub TDBGrid1_UnboundColumnFetch(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
Value = TDBGrid1.Columns(1).CellText(Bookmark)
End Sub
Note that these methods are not as efficient as using your own clone. This is because they always create a
new clone (internal to the grid), get the value, then destroy the clone. However, at times using CellText
or CellValue may be preferable for the sake of simplicity.
Using a global clone can become complicated when the data control is refreshed frequently. Refreshing
the data control rebuilds the Recordset, meaning that the data control's bookmarks are no longer the
same as the bookmarks of the clone. Thus, re-cloning and re-establishing the field variables is necessary,
or else the clone will continue to access the data of the old Recordset. As this may be a cumbersome
process, you may find that the simplicity of CellText and CellValue is a workable alternative.
Finally, please note that CellText and CellValue cannot be used to retrieve the values of other unbound
columns within the context of the UnboundColumnFetch event. Attempts to do so will always return an
empty string (CellText) or Null (CellValue). The grid has been designed this way to avoid infinite
recursions of UnboundColumnFetch events when two unbound columns reference one another.

Implementing multiple unbound columns

So far, our examples have demonstrated the UnboundColumnFetch event using only a single unbound
column. Suppose you want to have more than one? Since the UnboundColumnFetch is fired for each
unbound column of each row, only one column value may be set at a time, and each column must be
identified for the value to be properly determined. The second UnboundColumnFetch argument, Col, is
used to identify the column of the grid for which the value is required.
202 · Bound Mode

Returning to the Rectangle example, the following code also displays the perimeter of the rectangle in
addition to its area:
Dim ucfClone As Recordset ' Global UnboundColumnFetch clone
Dim ucfLength As Field
Dim ucfWidth As Field
Private Sub Form_Load()
Data1.Refresh
Set ucfClone = Data1.Recordset.Clone()
Set ucfLength = ucfClone.Fields("Length")
Set ucfWidth = ucfClone.Fields("Width")
End Sub
Private Sub TDBGrid1_UnboundColumnFetch(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
ucfClone.Bookmark = Bookmark
Select Case TDBGrid1.Columns(Col).Caption
Case "Area"
' Calculate "Area" column of grid
Value = ucfLength * ucfWidth
Case "Perimeter"
' Calculate "Perimeter" column of grid
Value = 2 * (ucfLength + ucfWidth)
End Select
End Sub
Please note the use of the column captions to identify the actual column for which the value is to be set.
The Caption property (instead of the index number) is sometimes necessary to identify the proper
column. If columns are added or removed at run time, each column's index number could change,
resulting in different values of Col for the Area column. Since the caption text is much less ambiguous
than the column number, code is easier to read, more reliable, and self-adjusting to column layout
changes.

Updating unbound columns

In most cases, you will want unbound columns to be read-only, as the values are derived from other data
in the grid. In these cases, you should set the Locked property of the column to True.
If Locked is False and updates are allowed, the user can edit the values of an unbound column, even if the
underlying Recordset is not updatable. However, if the underlying Recordset is not updatable, the
unbound column's Locked property will automatically be set to True at runtime, regardless of the design
time setting in the property pages. Therefore, for editing to be allowed, you must set the unbound
column object's Locked property to False at run time using code.
If editing of an unbound column occurs, the row will be marked as dirty (a pencil icon will be shown in
the record selector column) and the update sequence will be performed as usual. However, the grid does
not know what to do with the modified data, since there is no database field in which to store it.
Therefore, you must put code in the BeforeUpdate and AfterUpdate events (or BeforeInsert and
AfterInsert for AddNew operations) to properly store the edited values. These values may be stored in
any manner desired, including another database table.
BeforeUpdate can be used to cancel the update operation. Therefore, if the unbound column is to be used
in cooperation with another database, the update of the unbound column should be performed in
BeforeUpdate. If the operation fails, then the event should be canceled. However, if the operation
succeeds, then the bound update should be allowed to proceed. The bound update may then fail, hence
any database actions associated with unbound columns would best be handled on a transactional basis.
 Unbound Columns · 203

If the bound update succeeds, the AfterUpdate event is fired, and the unbound column transaction
should be committed. If the bound update fails, the unbound column transaction should be rolled back in
either the grid's or the Data control's Error event, or within a trappable error handler, depending on how
the update was initiated. If transactions are not available, then you must store the original unbound
column values prior to the update, then perform another update to restore these values should the bound
update fail.

Editing unbound columns

Another technique for updating an unbound column is to use the AfterColUpdate event to adjust the
value of other (bound) columns. For example, imagine a pair of columns for Debit and Credit, as shown in
this portion of a grid display:

Assume that there is no database field for these, but that they are unbound columns which derive their
value from a single Balance column, which is either positive or negative. From the user's perspective, it
would be desirable to edit these values directly; from your perspective, it would be desirable to have the
grid update the dependent Balance column automatically.
True DBGrid makes such tasks easy. Here's the code you would put in the grid's AfterColUpdate event
to cause either column to change the Balance column when updated:
Private Sub TDBGrid1_AfterColUpdate(ByVal ColIndex As Integer)
Dim Cols As Columns
Set Cols = TDBGrid1.Columns
Select Case Cols(ColIndex).Caption
Case "Debit"
Cols("Balance").Value = -Cols(ColIndex).Value
Case "Credit"
Cols("Balance").Value = Cols(ColIndex).Value
End Select
End Sub
Notice that, when updating these columns, the code actually changes the value of the Balance column,
which is both bound and invisible.
 When to Use Storage Mode · 205

Storage Mode
True DBGrid supports an array-based unbound mode, or storage mode, that does not rely upon the Visual
Basic Data control or any other data provider that follows the Microsoft data binding specifications.
Instead, storage mode uses a ComponentOne XArrayDB object as a data source. XArrayDB, which is
included with True DBGrid Pro 8.0, is packaged as a separate file, XADB8.OCX. You must distribute this
file along with your application if you use storage mode.
To use storage mode, set the DataMode property of the grid to 4 - Storage at design time. In code,
redimension and populate an XArrayDB object with your data just as you would a Visual Basic array,
then assign the XArrayDB object to the Array property of the grid. The data will then be maintained and
exchanged between the grid and the XArrayDB object automatically. There are no unbound events to
write, making this mode the easiest to use.
Storage mode was created to deliver ease of use without sacrificing the power and flexibility that you
expect from True DBGrid. When using this mode, the index of the first dimension of the XArrayDB object
serves as a bookmark to uniquely identify rows. This means that all of the grid's bookmark-related
properties, methods, and events (Bookmark, FirstRow, GetBookmark, FetchCellStyle, and others) work
the same in storage mode as in any other DataMode, either bound or unbound.

When to Use Storage Mode

If you need to display and manipulate two-dimensional array data, either one of the following DataMode
settings is ideally suited to the task:
3 - Application, which fires events on a cell-by-cell basis,
4 - Storage, which communicates directly with an XArrayDB object.
The choice of which one to use depends upon the life cycle of your application. If you are adding True
DBGrid to a mature application that already manages intrinsic Visual Basic arrays, application mode is
recommended, since you can easily wrap the ClassicRead and ClassicWrite events around existing data
structures. If you are writing a new application from scratch, storage mode is recommended, since it is
easier to use and provides sorting and searching capabilities via the QuickSort and Find methods of
XArrayDB.

Using the XArrayDB Object

XArrayDB is an ActiveX object designed as a drop-in replacement for Visual Basic variant arrays. The
XArrayDB object, which can be used outside the scope of True DBGrid, is functionally similar to a
standard array but provides additional flexibility. For example, data is automatically preserved when
rows (or columns) are inserted or deleted.
Once created, an XArrayDB object is assigned to a TDBGrid or TDBDropDown control via the grid's
Array property (usually in the Form_Load event). You can create as many XArrayDB objects as you
want, then attach them to one or more grids as needed.
206 · Storage Mode

Adding XArrayDB to a Visual Basic project

From the Project menu in Visual Basic, select References… to display a list of available type library
references. Select the check box labeled ComponentOne XArrayDB Object (XADB8.OCX), then press the
OK button.

Creating an XArrayDB object

XArrayDB has no design-time interface or persistent properties. All XArrayDB operations are performed
in code at run time.
To create an XArrayDB object at the start of an application, add the following line to the general
declarations section of a form:
Dim MyArray As New XArrayDB
To declare an XArrayDB object variable without creating it, omit the New keyword. Use the Set
statement to create the XArrayDB object in code:
Dim MyArray As XArrayDB
Set MyArray = New XArrayDB

Redimensioning an XArrayDB object

Before an XArrayDB object can be used, you must define its dimensions in code with the ReDim method,
which is similar to its counterpart in Visual Basic. For example, the following line of code sets up a two-
dimensional array with 20 rows (indexed from 1 to 20) and 4 columns (indexed from 0 to 3):
MyArray.ReDim 1, 20, 0, 3
You can use the Count property to determine the number of elements in a given dimension:
Debug.Print MyArray.Count(1) ' prints 20
Debug.Print MyArray.Count(2) ' prints 4
Note that the index passed to the Count property is one-based. To determine the valid indexes for a given
dimension, you can use the LowerBound and UpperBound properties:
Debug.Print MyArray.LowerBound(1) ' prints 1
Debug.Print MyArray.UpperBound(1) ' prints 20
Debug.Print MyArray.LowerBound(2) ' prints 0
Debug.Print MyArray.UpperBound(2) ' prints 3
When an XArrayDB object is connected to a TDBGrid or TDBDropDown control, its first dimension
always specifies the row index from the grid's perspective. Or, to put it another way, the set of allowable
bookmarks ranges from LowerBound(1) to UpperBound(1).
Likewise, the second dimension of an XArrayDB object always specifies the column index from the grid's
perspective. Or, to put it another way, the grid addresses data columns in the XArrayDB object using
indexes that range from LowerBound(2) to UpperBound(2). Therefore, if your application
manipulates columns in code, it is a good idea to make the second XArrayDB dimension zero-based
instead of one-based. That way, you can use the same indexes to refer to both grid columns and
XArrayDB columns.

Populating an XArrayDB object

To set or retrieve an element of an XArrayDB object, use the Value property:
MyArray.Value(x, y) = "A string"
s$ = MyArray.Value(x, y)
 Interactions between True DBGrid and XArrayDB · 207

Since the Value property is the default property for XArrayDB, the preceding statements can be
shortened to:
MyArray(x, y) = "A string"
s$ = MyArray(x, y)

Attaching an XArrayDB object to a True DBGrid control

Since XArrayDB objects can only exist at run time, you must write code to associate them with a
TDBGrid or TDBDropDown control. This is done by setting the Array property:
TDBGrid1.Array = MyArray
Once this association is made, the grid will store a reference to the XArrayDB object and query it as
needed to determine the contents of individual cells. When the Array property is set, the grid also
determines the number of rows (the first dimension) in an XArrayDB object and calibrates the vertical
scroll bar accordingly.
However, the grid will never adjust its column layout to match the number of columns (the second
dimension) in an XArrayDB object. As with other unbound data modes, you must define the column
layout yourself at design time, run time, or a combination of both. At run time, you can use the following
code to clear the existing columns from a grid, then create a new one for each XArrayDB column:
Dim C As TrueDBGrid80.Column
With TDBGrid1.Columns
While .Count > 0
.Remove 0
Wend
While .Count < MyArray.Count(2)
Set C = .Add(0)
C.Visible = True
Wend
End With
Note that newly created columns are invisible by default, so you must explicitly set their Visible
property to True.

Interactions between True DBGrid and XArrayDB

Add, update, and delete operations performed through True DBGrid's user interface or its properties and
methods are automatically reflected in the attached XArrayDB object. For example, if the following code
is executed:
With TDBGrid1
.Text = "New value"
.Update
End With
then the current cell of the grid and the corresponding element of the associated XArrayDB object are
automatically updated, and the following expression will be True (assuming that the second array
dimension is zero-based):
MyArray(TDBGrid1.Bookmark, TDBGrid1.Col) = "New value"
However, the reverse is not true. If you insert or delete XArrayDB rows or columns directly in code, or
even change the value of a single element, the grid does not receive any notifications from the XArrayDB.
Therefore, you must either Refresh, ReBind, or ReOpen the grid in order to update the display.
You can follow two rules of thumb to ensure that the display is updated properly:
208 · Storage Mode

1. If you insert or delete XArrayDB columns or rows in code, you are changing the structure of the
underlying data source. Therefore, you should invoke the grid's ReBind or ReOpen method.
2. If you change the value of one or more array elements in code, you are changing the underlying
data source without altering its structure. Therefore, you should invoke the grid's Refresh
method.

Updating XArrayDB elements

With the XArrayDB object, you always have instant access to all "records" in your "database," so you can
update cells in different rows directly without having to move the current record pointer, initiate edit
mode, modify one or more cells, then update the changed record. For this reason, it is usually more
convenient to make changes to XArrayDB directly, then use the grid's Refresh method to update the
display.
However, if you have modified only a single row or column, it is not necessary to refresh the entire grid;
you can use the RefetchRow or RefetchCol methods to update only the modified cells within the grid's
display. Likewise, if you have modified only a single cell, you can use the RefetchCell method of the
corresponding Column object.
NOTE: Take care to use the correct method when updating a row, column, or cell. The Refetch***
methods force the grid to request cell data from the associated XArrayDB object. The Refresh*** methods
repaint the affected areas of the display using (unmodified) data from the grid's cache.
It is important to note that when you change one or more elements in an XArrayDB object, you must
refresh either the affected cells or the entire grid, otherwise the display will not reflect the correct data.
Consider the following example, which implements a command button that clears the contents of the
current grid row, then sets focus to the grid:
Private Sub Command1_Click()
Dim row As Long, col As Integer
With TDBGrid1
row = .Bookmark
With MyArray
For col = .LowerBound(2) To .UpperBound(2)
.Value(row, col) = ""
Next col
End With
.RefetchRow
.SetFocus
End With
End Sub
Note that the Bookmark property of the grid is used as a row index for the XArrayDB object. The loop
that clears the current row also uses the LowerBound and UpperBound properties to iterate over the
columns (second dimension) of the array. This technique will work with any XArrayDB object, although
you can substitute integer constants if the array bounds are known in advance.
After the array elements are cleared, the grid's RefetchRow method is invoked, causing all unmodified
cells in the current row to be repainted as empty. Since no arguments are passed to the RefetchRow
method, the grid requests data for the current row.

Inserting and removing XArrayDB rows

When inserting or deleting rows, you must ReBind the grid afterwards, since it does not receive any
notifications from the XArrayDB object. Note that a grid Refresh is not sufficient in this case, since the
dimensions of the XArrayDB object have been changed.
 Storage Mode Examples · 209

The following example implements a command button that inserts a new row before the current grid
row, then sets focus to the grid:
Private Sub Command1_Click()
With TDBGrid1
MyArray.InsertRows .Bookmark
.ReBind
.SetFocus
End With
End Sub
The InsertRows method requires a row index argument that specifies the position of the new row. This
method also accepts an optional second argument that specifies the number of rows to insert. If omitted,
this argument defaults to 1.
When a new row is inserted, all subsequent rows are shifted to make room for it. That is, if you insert a
row at index position 6, the former row 6 becomes row 7, the former row 7 becomes row 8, and so forth.
To add one or more rows to the end of an XArrayDB object, use the AppendRows method. This method
accepts one optional argument that specifies the number of rows to append. If omitted, this argument
defaults to 1.
To delete the current row, you could use the DeleteRows method of XArrayDB, then ReBind the grid.
However, the Delete method of the grid provides a more direct way of accomplishing the same task.
NOTE: For backward compatibility, the Insert and Delete methods of the original XArray object were
retained in XArrayDB.

Inserting and removing XArrayDB columns

The InsertColumns and DeleteColumns methods are analogous to InsertRows and DeleteRows. Both
methods require a column index argument and accept an optional second argument that defaults to 1.
When you insert or delete XArrayDB columns, the grid will not automatically insert or delete its own
columns. You must write code to do this, as in the following example, which implements a command
button that inserts a new column before the current one:
Private Sub Command1_Click()
Dim C As TrueDBGrid80.Column
With TDBGrid1
MyArray.InsertColumns .Col
Set C = .Columns.Add(.Col)
C.Visible = True
.ReBind
.SetFocus
End With
End Sub
Note the use of the grid's ReBind method rather than the Refresh method. This is necessary because the
addition or deletion of a column constitutes a change in the underlying database structure as opposed to
a change in data values.

Storage Mode Examples

For an example of how to use True DBGrid in storage mode (DataMode 4) using an XArrayDB object as
the data source, see Tutorial 19 (page 79) or examine the UNBOUND4.VBP sample, which can be found
in the TUTORIAL\UNBOUND4 subdirectory of the True DBGrid installation directory. Tutorial 20 (page
81) demonstrates the searching and sorting features of XArrayDB.
 When to Use Application Mode · 211

Application Mode
True DBGrid supports a cell-based unbound mode, or application mode, that does not rely upon either the
Visual Basic Data control or the ComponentOne XArrayDB object. Instead, application mode fires events
whenever the grid needs to retrieve or update the value of an individual cell. Your application is in total
control of the data; no intermediate objects are involved.
To use application mode, set the DataMode property of the grid to 3 - Application at design time. In code,
write handlers for the ClassicRead and UnboundGetRelativeBookmark events. If users of your
application need the ability to add, update, and delete records, you will have to write handlers for the
ClassicAdd, ClassicWrite, and ClassicDelete events as well.
Application mode was modeled after the Fetch [TrueGrid Pro (VBX)] and Update [TrueGrid Pro (VBX)]
events of Component One's TrueGrid Pro (VBX) product. However, unlike TrueGrid Pro, which
identifies rows with absolute row numbers, True DBGrid identifies rows with bookmarks. This subtle
change provides uniformity across data access modes, and ensures that all of the grid's bookmark-related
properties, methods, and events (Bookmark, FirstRow, GetBookmark, FetchCellStyle, and others) work
the same in application mode as in any other DataMode, either bound or unbound.

When to Use Application Mode

If you do not want to use a bound data source control to populate the grid, either one of the following
DataMode settings is ideally suited to the task:
2 - Unbound Extended, which fetches multiple rows in a single event,
3 - Application, which fires events on a cell-by-cell basis,
The choice comes down to efficiency versus ease of implementation. If you are concerned about
efficiency, and would like to minimize the number of events that fire, you should consider using
DataMode 2 - Unbound Extended. Mode 2 is also recommended when using database APIs that support
multiple-row fetches, such as ODBC.
If you are migrating from DBGrid and find DataMode 1 - Unbound difficult to use, you should consider
switching to application mode, as it provides the same benefits, but is much easier to implement.
If your data source is a two-dimensional array, you should use DataMode 4 - Storage, as it was
specifically designed for this purpose.
If you are familiar with the Fetch and Update callback events of TrueGrid Pro (TRUEGRID.VBX), then
application mode is recommended, as the style of coding is very similar. In fact, the "classic" events are so
named because they were patterned after the callback mode events of TrueGrid Pro.

How Application Mode Works

When True DBGrid runs in application mode, it is not connected to a data control. Instead, your
application must supply and maintain the data, while the grid handles all user interaction and data
display. For example, when a user covers the grid with another window, then uncovers it later, the grid is
completely responsible for repainting the exposed area. Your application does not need to deal with any
low-level display operations.
212 · Application Mode

With the grid in control of low-level display, you need to concentrate solely on maintaining your data.
The grid fires the ClassicRead event as needed to determine the value of individual cells. It is up to your
application to provide the requested value on demand. Similarly, when the user repositions the scroll
box, the grid may need to determine the bookmark of a row that has yet to be displayed. In this case, it
fires the UnboundGetRelativeBookmark event, and your application needs to respond accordingly.
In this respect, programming True DBGrid in application mode is very similar to writing the event-
handling code for a Visual Basic form. You cannot predict when the user will click a button or select an
item from a combo box, so your application must be prepared to handle these events at all times.
Similarly, you cannot predict when the grid will request the value of a particular cell, or provide a new
value to be written to the underlying data source. Therefore, the code that handles application mode
events such as ClassicRead and UnboundGetRelativeBookmark should be written so that it performs as
little work as possible.
The grid generally limits its data requests to visible cells, although it may also cache other rows in
anticipation of paging and scrolling operations. You cannot predict when the grid will ask for data, nor
can you assume that data will be requested in any particular order. Furthermore, since the grid does not
permanently store the data, data that has been requested once from your application may be requested
again.
Compare this event-driven approach with the storage mode used by the intrinsic ListBox control of
Visual Basic, which is populated by repeated calls to its AddItem method at run time. Although this
storage mode is convenient for small datasets, it is neither adequate nor efficient when there is a large
volume of data or when the data source changes dynamically.
When running in application mode, True DBGrid translates user interactions into events that enable you
to keep your data source synchronized. For example, when the user updates a cell, then attempts to move
to another row, the grid fires the ClassicWrite event. If the cell was modified as part of a pending
AddNew operation, the grid fires the ClassicAdd event instead. If the user deletes an entire row through
the grid's user interface, your application receives notification through the ClassicDelete event.
Conversely, if your application code manipulates the data source directly, you need to tell the grid to
update its display by using either the Refresh or ReBind method.
To summarize, True DBGrid's application mode is a useful tool for dealing with dynamic data. Since it
has no inherent storage capability, the grid handles frequently changing data fluidly and easily. A
common use of application mode is to provide an interface for viewing and updating the contents of a
Visual Basic array. Application mode can also be used with proprietary database formats not supported
by the Visual Basic Data control.

Application Mode Bookmarks

In application mode, a bookmark is a variant supplied by your application and used by the grid as a
means of uniquely identifying a row of data to be displayed or modified.
Just as your application provides, stores, and maintains the data for the unbound grid, you must deal
similarly with the bookmarks. The bookmarks themselves must be supplied by your code in the
UnboundGetRelativeBookmark, ClassicRead, and ClassicAdd events as variant data. You are free to
use whatever you choose for the purpose of identifying a row, but keep in mind that the bookmarks must
be unique for each row. In general, you will also want to be able to search for the associated record
quickly when given a bookmark. Three common examples of what to use for bookmarks are:
1. If you use the unbound grid with a proprietary database, you can use the values of a unique key
field as bookmarks. That way, when given a bookmark, you can search and retrieve the
associated record quickly.
 Application Mode Bookmarks · 213

2. If the database you use supports unique row IDs or record numbers, these can be conveniently
used as bookmarks.
3. If you use the grid to display an array, the array's row index is an obvious choice for bookmarks.
Bookmarks cannot exceed 255 characters in length. Since Visual Basic 5.0 uses 2 bytes per character, this
means that string bookmarks cannot exceed 127 characters.
True DBGrid's application mode supports string, integral, and floating point bookmarks. All other data
types must be converted to strings before they are passed to the grid as variant bookmarks.
Since True DBGrid and Visual Basic differ in their treatment of bookmarks, some restrictions apply when
manipulating them in code, as discussed in the following sections.

Bookmarks in True DBGrid

True DBGrid treats bookmarks as packets of binary information that cannot be interpreted. To the grid, a
bookmark is a piece of data containing a specific number of bytes (ASCII codes) in a specific order. Thus,
pieces of different lengths, or pieces with different bytes, are considered different bookmarks. For
example, if the grid were to compare the following string bookmarks:
bmk1 = "1"
bmk2 = " 1"
bmk3 = "01"
it would consider each bookmark to be different from the others, although they could be considered
equivalent numerically. Similarly, a 2-byte integer and a 4-byte integer would also be considered
different, even if both contained the same numeric value.

Bookmarks in Visual Basic

Visual Basic, on the other hand, treats bookmarks as true variants. That is, they are quantities that can be
converted from one form to another without loss of equality, unless they are both in the form of a string.
In addition, bookmarks are often passed in Visual Basic as byte arrays, both by the grid and by the Data
control.
In Visual Basic, two bookmarks should not be compared for equality unless they are first converted to
strings. This rule holds true regardless of whether the bookmark comes from a grid (bound or unbound)
or from a Data control.
Another important consideration regarding bookmarks is their length. You should take care to ensure
that all bookmarks in your application are created in the same way. For example, the Visual Basic
functions Format$ and Str$ do not generate the same string, even if they are passed the same numeric
value. The Str$ function always generates a leading space character for the sign of the numeric value, while
Format$ does not:
Str$(1) = " 1"
Format$(1) = "1"
Remember that since these strings are of different length, they constitute different bookmarks.
To avoid difficulties of this nature, we suggest writing a single Visual Basic function, like the
MakeBookmark function used in the unbound tutorial projects, and use it consistently whenever a
bookmark must be generated.
214 · Application Mode

Application Mode Events

In application mode, there are five events that may fire, depending upon end-user permission settings
and run-time interactions. You must write handlers for these two events:
UnboundGetRelativeBookmark Fired when the control needs to retrieve a bookmark.
ClassicRead Fired when the control requires unbound data for display.
The following three events are optional:
ClassicWrite Fired when an unbound row needs to be modified. Required if
AllowUpdate is True.
ClassicAdd Fired when a new row is added to the unbound dataset.
Required if AllowAddNew is True.
ClassicDelete Fired when an unbound row needs to be deleted. Required if
AllowDelete is True.

Handling the UnboundGetRelativeBookmark event in mode 3

You must always provide a handler for the UnboundGetRelativeBookmark event in application mode.
True DBGrid fires this event whenever it needs to determine the bookmark that identifies a row given a
starting bookmark and a long integer offset. The starting bookmark may be Null, which denotes BOF if
the offset is positive, EOF if the offset is negative. The offset may be positive to denote forward
movement, or negative to denote backward movement. The syntax for this event is as follows:
Private Sub TDBGrid1_UnboundGetRelativeBookmark( _
StartLocation As Variant, ByVal Offset As Long, _
NewLocation As Variant, ApproximatePosition As Long)
StartLocation is a bookmark which, together with Offset, specifies the row to be returned in NewLocation.
Offset specifies the relative position (from StartLocation) of the row to be returned in NewLocation. A
positive number indicates a forward relative position while a negative number indicates a backward
relative position.
NewLocation is a variable which receives the bookmark of the row which is specified by StartLocation plus
Offset. If the row specified is beyond the first or the last row (or beyond BOF or EOF), then NewLocation
should be set to Null.
ApproximatePosition is a variable which receives the ordinal position of NewLocation. Setting this variable
will enhance the ability of the grid to display its vertical scroll bar accurately. If the exact ordinal position
of NewLocation is not known, you can set it to a reasonable, approximate value, or just ignore it altogether.
Before returning from the UnboundGetRelativeBookmark event, you must set NewLocation to a valid
bookmark. For example, if Offset is 1 (or -1), then you must return in NewLocation the bookmark of the
row that follows (or precedes) StartLocation. However, if the requested row is beyond the first or last row,
then you should return Null in NewLocation to inform the grid of BOF/EOF conditions.
Similarly, a StartLocation of Null indicates a request for a row from BOF or EOF. For example, if
StartLocation is Null and Offset is 2 (or -2), then you must return in NewLocation the bookmark of the
second (or second to last) row. The following code template provides the basis for a typical
implementation of the UnboundGetRelativeBookmark event:
If IsNull(StartLocation) Then
If Offset < 0 Then
' StartLocation indicates EOF, because the grid is
' requesting data in rows prior to the StartLocation,
' and prior rows only exist for EOF.
 Application Mode Events · 215

' There are no rows prior to BOF.

Else
' StartLocation indicates BOF, because the grid is
' requesting data in rows after the StartLocation,
' and rows after only exist for BOF.
' There are no rows after EOF.
End If
Else
' StartLocation is an actual bookmark passed to the grid
' via one of the unbound events. It is up to the VB
' programmer to ensure the bookmark is valid, and to take
' the appropriate action if it is not.
End If
The UnboundGetRelativeBookmark event is also used to improve performance in DataMode 1 -
Unbound. For more information, see Unbound Mode (page 219).

Handling the ClassicRead event in mode 3

In application mode, the grid uses the UnboundGetRelativeBookmark event to determine the bookmark
of the row it is about to display. To determine the contents of an individual cell, the grid passes a known
bookmark and a column index to the ClassicRead event, which has the following syntax:
Private Sub TDBGrid1_ClassicRead(Bookmark As Variant, _
ByVal Col As Integer, Value As Variant)
Bookmark is a bookmark which specifies the row of the desired data.
Col is a value which specifies the column index of data to be retrieved.
Value is a variable used to return the data corresponding to the cell location identified by Bookmark and
Col.
Before returning from this event, you must set Value to the actual data, or else the grid will display an
empty cell. Note that Value need not contain a string. It can also hold numeric, boolean, or date data, and
the grid will convert it to a string automatically, just as it does with such data types in bound mode.

Handling the ClassicWrite event in mode 3

If the AllowUpdate property of the grid is True, and the user has edited data in one or more cells of the
current row, then moving to another row will trigger an update. The grid will then fire the ClassicWrite
event once for each updated cell, which enables you to apply the changed value to the underlying data
stored and maintained by your application. The syntax of this event is as follows:
Private Sub TDBGrid1_ClassicWrite(Bookmark as Variant, _
ByVal Col as Integer, Value As Variant)
Bookmark is a bookmark which specifies the row that needs to be updated.
Col is a value which specifies the column index of data that has been modified.
Value is the data that corresponds to the cell location identified by Bookmark and Col.
Before returning from this event, you must update the underlying data source with Value. If, for some
reason, the update cannot be completed, you can set the Bookmark argument to Null in order to force the
grid to maintain the previous value of the current cell.

Handling the ClassicAdd event in mode 3

If the AllowAddNew and AllowUpdate properties of the grid are True, then users can add new records
to the grid, and you must implement the ClassicAdd event. The syntax of this event is as follows:
216 · Application Mode

Private Sub TDBGrid1_ClassicAdd(NewRowBookmark As Variant, _

ByVal Col As Integer, Value As Variant)
NewRowBookmark is a variable which receives the bookmark for the newly added row. Initially, the
NewRowBookmark argument is Null. However, before returning from this event, you must set it to a
bookmark that uniquely identifies the newly added row. If you do not set the value of NewRowBookmark,
the add operation will fail and the grid will not allow its current row to change.
Col is a value which specifies the column index of data that has been added.
Value is the data that corresponds to the newly added cell.
Before returning from this event, you must update the underlying data source with Value and set the
NewRowBookmark argument to the bookmark of the newly added row. If, for some reason, the add cannot
be completed, you can set NewRowBookmark to Null in order to force the grid to cancel the AddNew
operation initiated by the user.
Note that the ClassicAdd event will fire once for each modified cell in the new row. This does not pose a
problem if the underlying data source permits you to add blank records. However, if this is not the case,
and you are using unique key field values as bookmarks, you cannot assume that the event will fire for
the key field column first. Since you must still supply a valid bookmark (even if you don't know what it is
yet), you can set NewRowBookmark to a special key that will never refer to a real record. Then, when the
ClassicAdd event fires for the key field column (and subsequent columns), you can return the actual
bookmark. The grid will use the last bookmark it receives and discard the special key that you supplied
earlier.

Handling the ClassicDelete event in mode 3

If the AllowDelete property of the grid is True, then the user can delete rows from the grid, and you must
implement the ClassicDelete event:
Private Sub TDBGrid1_ClassicDelete(Bookmark As Variant)
When fired, the Bookmark argument specifies the row being deleted. If the deletion fails, you should set
the Bookmark argument to Null before returning from the event. Note that following execution of the
ClassicDelete event, the grid is automatically refreshed.

Application Mode Programming Considerations

When the user updates, adds, or deletes data through the grid's user interface, the grid fires the
ClassicWrite, ClassicAdd, or ClassicDelete event so that your application can take the appropriate
action. Conversely, when you modify the underlying data source in code, you need to notify the grid so
that it can update its display to synchronize with your data.

Refreshing the display in mode 3

You can refresh the display with the grid's Refresh and ReBind methods, which work in the same
manner as documented for bound mode. When these methods are called, the grid will discard its current
display and call the ClassicRead event to retrieve new data.
Please note that during a ReBind operation, the grid attempts to maintain the current record position.
Therefore, if the current record does not exist after the ReBind operation, it is up to you to position the
grid to a valid record afterwards. Or, you can avoid potential problems by reinitializing the grid before
performing the ReBind.
 Application Mode Example · 217

Reinitializing the grid in mode 3

Setting the grid's Bookmark property equal to Null before issuing the grid's ReBind or Refresh method
will cause the UnboundGetRelativeBookmark event to fire with a Null StartLocation just as if the grid
were first being displayed:
TDBGrid1.Bookmark = Null
TDBGrid1.ReBind

Updating and deleting rows in mode 3

In application mode, or in any other mode, you can update a row in code and force the ClassicWrite (or
ClassicAdd) event to fire by applying the grid's Update method:
TDBGrid1.Update
Similarly, you can delete a row in code and force the ClassicDelete event to fire by applying the grid's
Delete method:
TDBGrid1.Delete

Application Mode Example

For an example of how to use True DBGrid in application mode (DataMode 3) using a Visual Basic array
as the data source, see Tutorial 18 (page 75) or examine the UNBOUND3.VBP sample, which can be
found in the TUTORIAL\UNBOUND3 subdirectory of the True DBGrid installation directory.
 When to Use Unbound Mode · 219

Unbound Mode
True DBGrid supports a row-based unbound mode that does not rely upon either the Visual Basic Data
control or the ComponentOne XArrayDB object. Instead, unbound mode events fire whenever the grid
needs to retrieve a group of adjacent rows or update, add, or delete an individual row. Unlike application
mode, an intermediate RowBuffer object serves as the liaison between the grid and your data source.
There are actually two row-based unbound modes: DataMode 1 - Unbound, is the original unbound mode
of DBGrid; DataMode 2 - Unbound Extended, uses a slightly different event syntax that simplifies coding
and is more efficient. Therefore, if you are writing a new application, you should use mode 2. Mode 1 is
included for backward compatibility with DBGrid.
To use the newer row-based unbound mode, set the DataMode property of the grid to 2 - Unbound
Extended at design time. In code, write a handler for the UnboundReadDataEx event. If users of your
application need the ability to add, update, and delete records, you will have to write handlers for the
UnboundAddData, UnboundWriteData, and UnboundDeleteRow events as well.
If you are converting an application that uses DataMode 1, you can improve its performance
dramatically by writing a handler for the UnboundGetRelativeBookmark event.
Regardless of whether you use mode 1 or 2, all of the grid's bookmark-related properties, methods, and
events (Bookmark, FirstRow, GetBookmark, FetchCellStyle, and others) work the same in the row-
based unbound modes as they do in any other DataMode, either bound or unbound.

When to Use Unbound Mode

The row-based unbound modes were designed to provide a workable interface between database APIs
and the grid. Therefore, if you simply need to display and manipulate two-dimensional array data, the
row-based unbound modes can be cumbersome to work with, and either one of the following DataMode
settings would be a better choice:
3 - Application, which fires events on a cell-by-cell basis,
4 - Storage, which communicates directly with an XArrayDB object.
Modes 3 and 4 are specifically intended for an array-based data source, whereas the row-based modes 1
and 2 are more generalized and will work well with any data source.
If you are working with a database instead of an array, the choice comes down to efficiency versus ease of
implementation. If you are concerned about efficiency, and would like to minimize the number of events
that fire, you should consider using DataMode 2 - Unbound Extended. Mode 2 is also recommended when
using database APIs that support multiple-row fetches, such as ODBC. You can also use mode 2 to
bypass the overhead associated with an external bound control. For example, instead of binding to a
Remote Data Control (RDC), you can use the Remote Data Objects (RDO) in unbound mode 2 to populate
the grid with data from an rdoResultSet object.
Mode 3 is easier to implement than mode 2, but it can be less efficient because events fire on a per-cell
rather than a per-row basis. If speed and efficiency are your primary concerns, mode 2 is preferred over
mode 3.
If your application uses an unbound DBGrid, you should consider switching to mode 2, as it is more
efficient. However, if you do not want to revise existing UnboundReadData handlers, you can achieve
similar performance improvements in mode 1 by implementing the optional
220 · Unbound Mode

UnboundGetRelativeBookmark event, which the grid fires whenever it needs to determine the
bookmark of a row given a starting position and an integral offset. Even if you do not implement this
event, your existing application will continue to function properly.
If you are familiar with the Fetch and Update callback events of TrueGrid Pro (TRUEGRID.VBX), then
mode 3 is recommended, as the style of coding is very similar. In fact, the "classic" events of application
mode are so named because they were patterned after the callback mode events of TrueGrid Pro.

How Unbound Mode Works

When True DBGrid runs in unbound mode, it is not connected to a data control. Instead, your application
must supply and maintain the data, while the grid handles all user interaction and data display. For
example, when a user covers the grid with another window, then uncovers it later, the grid is completely
responsible for repainting the exposed area. Your application does not need to deal with any low-level
display operations.
With the grid in control of low-level display, you need to concentrate solely on maintaining your data. In
DataMode 1 - Unbound, the grid fires the UnboundReadData event whenever it needs to fetch a row of
data. It is up to your application to fill the RowBuffer object, passed as an event parameter, with the
requested values on demand. Similarly, when the user repositions the scroll box, the grid may need to
determine the bookmark of a row that has yet to be displayed. In this case, it fires the
UnboundGetRelativeBookmark event, and your application needs to respond accordingly.
In DataMode 2 - Unbound Extended, the grid fires the UnboundReadDataEx event, which combines the
functionality of UnboundReadData and UnboundGetRelativeBookmark. When the grid first loads, it
fires the UnboundReadDataEx event to retrieve the bookmark (but not the data) for the first row. If your
event handler provides a bookmark, the grid fires UnboundReadDataEx again, this time to fetch the
actual data in a block of ten rows. This process continues until the grid has enough data to fill its display
or your event handler informs the grid that the end of the dataset has been reached. As the user scrolls
through the grid, the UnboundReadDataEx event is fired as needed to obtain bookmarks and data.
In this respect, programming True DBGrid in unbound mode is very similar to writing the event-
handling code for a Visual Basic form. You cannot predict when the user will click a button or select an
item from a combo box, so your application must be prepared to handle these events at all times.
Similarly, you cannot predict when the grid will request a particular data row, or provide a new value to
be written to the underlying data source. Therefore, the code that handles unbound mode events such as
UnboundReadData and UnboundWriteData should be written so that it performs as little work as
possible.
The grid generally limits its data requests to visible cells, although it may also cache other rows in
anticipation of paging and scrolling operations. You cannot predict when the grid will ask for data, nor
can you assume that data will be requested in any particular order. Furthermore, since the grid does not
permanently store the data, data that has been requested once from your application may be requested
again. Thus, you must provide and maintain your own data storage, as the grid will not do this for you.
Compare this event-driven approach with the storage mode used by the intrinsic ListBox control of
Visual Basic, which is populated by repeated calls to its AddItem method at run time. Although this
storage mode is convenient for small datasets, it is neither adequate nor efficient when there is a large
volume of data or when the data source changes dynamically.
When running in unbound mode, True DBGrid translates user interactions into events that enable you to
keep your data source synchronized. For example, when the user updates a cell, then attempts to move to
another row, the grid fires the UnboundWriteData event. If the cell was modified as part of a pending
AddNew operation, the grid fires the UnboundAddData event instead. If the user deletes an entire row
 Unbound Mode Bookmarks · 221

through the grid's user interface, your application receives notification through the UnboundDeleteRow
event.
Conversely, if your application code manipulates the data source directly, the grid will not know that the
underlying data has changed, so you need to tell the grid to update its display by using either the
Refresh or ReBind method.
To summarize, True DBGrid's unbound mode is a useful tool for communicating with third-party
database APIs or avoiding the overhead associated with bound data controls. Although it is not as easy to
implement as application mode, unbound mode can provide significant gains in performance, especially
when there are many columns.

Unbound Mode Bookmarks

In unbound mode, as in application mode, a bookmark is a variant supplied by your application and
used by the grid as a means of uniquely identifying a row of data to be displayed or modified.
Just as your application must provide, store, and maintain the data for the unbound grid, you must deal
similarly with the bookmarks. The bookmarks themselves must be supplied by your code as variant data
in the following events:
• UnboundGetRelativeBookmark, UnboundReadData, and UnboundAddData (for DataMode 1
- Unbound)
• UnboundReadDataEx and UnboundAddData (for DataMode 2 - Unbound Extended)
You are free to use whatever you choose for the purpose of identifying a row, but keep in mind that the
bookmarks must be unique for each row. In general, you will also want to be able to search for the
associated record quickly when given a bookmark. That is, when the grid gives you a bookmark, asking
for information about a particular row in your dataset, you should be able to locate the row the grid is
asking for quickly. An important concept to remember is that whatever you supply to the grid as a
bookmark for a particular row, that is how the grid will refer to that row later on. Three common
examples of what to use for bookmarks are:
1. If you use the unbound grid with a proprietary database, you can use the values of a unique key
field as bookmarks. That way, when given a bookmark, you can search and retrieve the
associated record quickly.
2. If the database you use supports unique row IDs or record numbers, these can be conveniently
used as bookmarks.
3. If you use the grid to display an array, the array's row index is an obvious choice for bookmarks.
Bookmarks cannot exceed 255 characters in length. Since Visual Basic 5.0 uses 2 bytes per character, this
means that string bookmarks cannot exceed 127 characters.
True DBGrid's unbound modes support string, integral, and floating point bookmarks. All other data
types must be converted to strings before they are passed to the grid as variant bookmarks.
Since True DBGrid and Visual Basic differ in their treatment of bookmarks, some restrictions apply when
manipulating them in code. For more information, see Application Mode Bookmarks (page 212).

Using the RowBuffer Object

The RowBuffer is a programmable object used to exchange data between the grid and your data source
via the unbound grid events. The RowBuffer object is passed into the unbound grid event handlers as an
222 · Unbound Mode

argument. In fact, the RowBuffer object can only exist within the scope of the unbound events; you
cannot create a new one in code as you would a Column or Split object. Here is a thumbnail sketch of the
properties of the RowBuffer object:

RowCount property
RowCount is a long integer that specifies the maximum number of rows that can be processed in an
unbound event (read, write, or add). If the value of this property exceeds the number of rows that can be
processed, such as when an end-of-file condition is detected, then your event handling code should
change this property to reflect the actual number of rows processed.
RowBuffer.RowCount = Long

ColumnCount property
ColumnCount is an integer that specifies the number of columns that the unbound event should process.
This property is read-only, and no attempt should be made to change it. The unbound event should
process all columns requested.
Integer = RowBuffer.ColumnCount

ColumnName property
ColumnName is a string array that specifies the name of the grid column corresponding to a row buffer
index. This property is read-only.
String = RowBuffer.ColumnName(ColIndex)
' where ColIndex = 0 to ColumnCount - 1

Bookmark property
Bookmark is a variant array used to specify unique row bookmarks when the RowBuffer is used to fetch
data during an unbound read event.
RowBuffer.Bookmark(RowIndex) = Variant
' where RowIndex = 0 to RowCount - 1

Value property
Value is a variant array used to specify the data value associated with a RowBuffer row and column.
RowBuffer.Value(RowIndex, ColIndex) = Variant
' where RowIndex = 0 to RowCount - 1
' and ColIndex = 0 to ColumnCount - 1

ColumnIndex property
ColumnIndex is a variant array used to specify a grid column index associated with a RowBuffer row
and column. This property is read-only. You can use it in the UnboundReadDataEx event to identify
which data columns are being requested.
Col = RowBuffer.ColumnIndex(RowIndex, ColIndex)
' where RowIndex = 0 to RowCount - 1
' and ColIndex = 0 to ColumnCount - 1
 Unbound Mode Events · 223

Unbound Mode Events

In DataMode 1 - Unbound, the grid fires one event when it needs to determine a relative bookmark,
another when it needs to fetch data rows. The first event is optional and can be implemented to improve
performance; the second event is mandatory:
UnboundGetRelativeBookmark Fired when the control needs to retrieve a bookmark.
UnboundReadData Fired when the control requires unbound data for display.
In DataMode 2 - Unbound Extended, the grid fires a single event to acquire both data and relative
bookmarks. This event is mandatory:
UnboundReadDataEx Fired when the control needs to retrieve a bookmark or
requires unbound data for display.
In modes 1 and 2, the following three events are optional, depending upon end-user permission settings:
UnboundWriteData Fired when the current row of the grid has been modified and
the user commits the changes by leaving the row. This event is
your notification that the user wants to modify a row in the
unbound dataset. It is also fired when the grid's Update method
is executed in code. Required if AllowUpdate is True.
UnboundAddData Fired when the user types data into the grid's AddNew row and
commits the changes by leaving the row. This event is your
notification that the user wants to add a new row to the
unbound dataset. Required if AllowAddNew is True.
UnboundDeleteRow Fired when the user deletes the current grid row by clicking its
record selector and pressing the DEL key. This event is your
notification that the user wants to delete a row from the
unbound dataset. It is also fired when the grid's Delete method
is executed in code. Required if AllowDelete is True.

Handling the UnboundReadData event in mode 1

The UnboundReadData event is fired only if the DataMode property is set to 1 - Unbound. This event is
retained only for backward compatibility with DBGrid and earlier versions of True DBGrid. If you are
writing a new unbound mode application, DataMode 2 - Unbound Extended is recommended, since it is
more efficient and easier to use.
The UnboundReadData event is fired whenever the grid requires data for display. Its syntax is as
follows:
Private Sub TDBGrid1_UnboundReadData( _
ByVal RowBuf As RowBuffer, _
StartLocation As Variant, _
ReadPriorRows As Boolean)
When this event is fired, the properties of the RowBuf argument are set as follows:
• RowCount specifies the number of rows of data requested from your data source.
• ColumnCount specifies the number of columns of data requested from your data source.
• The ColumnName array contains the names of the grid columns corresponding to the columns in
RowBuf.
• The Bookmark and Value arrays contain all Null values.
224 · Unbound Mode

StartLocation is a bookmark that specifies the row before or after the desired data, depending on the value
of the ReadPriorRows argument.
ReadPriorRows indicates the direction in which the grid is requesting the data. If False, you should provide
data in the forward direction, starting with the row immediately after the row specified by StartLocation.
If True, you should provide data in the backward direction, starting with the row immediately before the
row specified by StartLocation.
Before returning from the UnboundReadData event, you are expected to fill the Bookmark property
array with unique row identifiers, and the Value property array with the actual data:
Dim RowIndex As Long
Dim ColIndex As Integer
With RowBuf
For RowIndex = 0 To .RowCount - 1
.Bookmark(RowIndex) = Variant Bookmark
For ColIndex = 0 To .ColumnCount - 1
.Value(RowIndex, ColIndex) = Variant Data
Next ColIndex
Next RowIndex
End With
For example, if the grid specifies a StartLocation bookmark indicating the 46th row, the ReadPriorRows
argument is False, and the row buffer's RowCount property is 10, then the grid is asking for the records
following the 46th row, and your UnboundReadData event handler should populate the row buffer's
Value array as follows:
RowBuf.Value(0, ColIndex) = Data for row 47
RowBuf.Value(1, ColIndex) = Data for row 48
RowBuf.Value(2, ColIndex) = Data for row 49
...
RowBuf.Value(9, ColIndex) = Data for row 56
However, if ReadPriorRows is False, then the grid is asking for the records preceding the 46th row, and a
different set of values must be returned:
RowBuf.Value(0, ColIndex) = Data for row 45
RowBuf.Value(1, ColIndex) = Data for row 44
RowBuf.Value(2, ColIndex) = Data for row 43
...
RowBuf.Value(9, ColIndex) = Data for row 36
If you reach the beginning or end of the data, and have fewer than RowCount rows to provide, then you
should fill the row buffer with the data you can provide, and change the RowCount property to the
actual number of rows provided, which may be zero.
For example, if your dataset contains 50 records, the grid specifies a StartLocation bookmark indicating the
46th row, the ReadPriorRows argument is False, and the row buffer's RowCount property is 10, then your
UnboundReadData event handler should populate the row buffer's Value array as follows:
RowBuf.Value(0, ColIndex) = Data for row 47
RowBuf.Value(1, ColIndex) = Data for row 48
RowBuf.Value(2, ColIndex) = Data for row 49
RowBuf.Value(3, ColIndex) = Data for row 50

RowBuf.RowCount = 4 ' Since only 4 rows were processed

At first glance, StartLocation and ReadPriorRows may seem unnecessarily cumbersome. However, they
communicate the row boundaries to the grid simply and directly. The grid only caches a portion of the
data, and it is with these two arguments that it can navigate from one bookmark to the next.
 Unbound Mode Events · 225

For example, suppose there are 100 rows of data, the current row is 75, and the grid is asked to move to
row 3 using a previously obtained bookmark. The following sequence demonstrates what might happen
in this situation:
1. The grid receives a bookmark for row 3. Since the data for this row is not in the grid's cache, the
grid requests the data using the UnboundReadData event, which is called with the following
parameters:
RowBuf.RowCount = 10
RowBuf.ColumnCount = Number of columns
StartLocation = Bookmark for row 3
ReadPriorRows = False
2. The event code responds as follows:
RowBuf.Value(0, ColIndex) = Data for row 4
RowBuf.Value(1, ColIndex) = Data for row 5
...
RowBuf.Value(9, ColIndex) = Data for row 13
RowBuf.RowCount = 10 ' Since all 10 rows were processed
3. The UnboundReadData event is called again, this time with:
RowBuf.RowCount = 10
RowBuf.ColumnCount = Number of columns
StartLocation = Bookmark for row 4
ReadPriorRows = True
4. The event code responds as follows:
RowBuf.Value(0, ColIndex) = Data for row 3
RowBuf.Value(1, ColIndex) = Data for row 2
RowBuf.Value(2, ColIndex) = Data for row 1

RowBuf.RowCount = 3 ' Since only 3 rows were processed

Note that after fetching row 1, the event code stops setting values since there is no more data available in
the indicated direction from the starting bookmark. Also, RowBuf.RowCount is set to 3, since only 3
rows could be read before the beginning of the dataset was encountered. At this point, additional
UnboundReadData events may be fired to obtain the data necessary to complete the display.
The preceding example demonstrates how the same event interface is called upon to handle both BOF
and EOF conditions. When one of these special cases is encountered, the event handler simply exits the
loop used to fill the row buffer and reports the number of rows actually processed in the RowCount
property.
A StartLocation of Null indicates a request for BOF or EOF. Whether it indicates BOF or EOF depends
upon the value of ReadPriorRows:
If IsNull(StartLocation) Then
If ReadPriorRows Then
' StartLocation indicates EOF, because the grid is
' requesting data in rows prior to the StartLocation,
' and prior rows only exist for EOF.
' There are no rows prior to BOF.
Else
' StartLocation indicates BOF, because the grid is
' requesting data in rows after the StartLocation,
' and rows after only exist for BOF.
' There are no rows after EOF.
End If
Else
' StartLocation is an actual bookmark passed to the grid
226 · Unbound Mode

' in the RowBuffer, an event argument (UnboundAddData), or

' the setting of a grid bookmark. You must ensure that
' the bookmark is valid, and take the appropriate action
' if it is not.
End If
NOTE: You cannot make any assumptions about when the grid will request data, or how many times it
will request the same data. In short, it is the grid's responsibility to display the data properly, while the
task of storing and maintaining the data falls to you. This division of labor frees you from worrying about
when or how to display data in the grid.

Handling the UnboundGetRelativeBookmark event in mode 1

This event is mandatory when the DataMode property is set to 3 - Application, but optional when it is set
to 1 - Unbound. It is not used at all when the DataMode property is set to 2 - Unbound Extended.
In DataMode 1, this event is used in conjunction with the UnboundReadData event when the grid needs
to obtain positional information about your underlying data. If you are converting an existing project that
uses DBGrid or an earlier version of True DBGrid, you can add a handler for this event to dramatically
improve the grid's performance. However, if you choose to ignore this event, your project will continue
to function properly. The syntax for this event is as follows:
Private Sub TDBGrid1_UnboundGetRelativeBookmark( _
StartLocation As Variant, _
ByVal Offset As Long, _
NewLocation As Variant, _
ApproximatePosition As Long)
For more information on the UnboundGetRelativeBookmark event, see Application Mode (page 211).

Handling the UnboundReadDataEx event in mode 2

The UnboundReadDataEx event is used when the DataMode property is set to 2 - Unbound Extended, and
is fired by the grid whenever it requires one of the following:
• A bookmark for a specific row.
• Data for display.
The syntax of the UnboundReadDataEx event is as follows:
Private Sub TDBGrid1_UnboundReadDataEx( _
ByVal RowBuf As RowBuffer, _
StartLocation As Variant, _
ByVal Offset As Long, _
ApproximatePosition As Long)
When this event is fired, the properties of the RowBuf argument are set as follows:
• RowCount specifies the number of rows of data requested from your data source.
• ColumnCount specifies the number of columns of data requested from your data source.
• The ColumnName array contains the names of the grid columns corresponding to the columns in
RowBuf.
• The ColumnIndex array contains the indexes of the grid columns corresponding to the columns
in RowBuf.
• The Bookmark and Value arrays contain all Null values.
 Unbound Mode Events · 227

You can examine the RowCount and ColumnCount properties to determine whether the grid is
requesting a bookmark or data. If RowCount is 1 and ColumnCount is 0, the grid is asking for a
bookmark only; if ColumnCount is nonzero, the grid is asking for RowCount rows of data (and the
corresponding bookmarks).
StartLocation is a bookmark which, together with Offset, specifies the first row of data to be transferred to
RowBuf.
Offset specifies the relative position (from StartLocation) of the first row of data to be transferred. A
positive number indicates a forward relative position; a negative number indicates a backward relative
position. Regardless of whether Offset is positive or negative, you should always return rows to the grid
in the forward direction.
ApproximatePosition is a variable which optionally receives the ordinal position of the first row of data to
be transferred. Setting this variable will enhance the ability of the grid to display its vertical scroll bar
accurately. If the exact ordinal position of the row is not known, you can set it to a reasonable,
approximate value, or just ignore this parameter.
Before returning from the UnboundReadDataEx event, you are expected to fill the Bookmark array of
RowBuf with unique row identifiers, and the Value array with the actual data, if requested. For example,
if Offset is 1 (or -1), then you must fill in RowBuf starting from the row that follows (or precedes)
StartLocation:
Dim RowIndex As Long
Dim ColIndex As Integer, Col As Integer
With RowBuf
For RowIndex = 0 To .RowCount - 1
.Bookmark(RowIndex) = Variant Bookmark
For ColIndex = 0 To .ColumnCount - 1
Col = .ColumnIndex(RowIndex, ColIndex)
.Value(RowIndex, ColIndex) = Variant Data for Col
Next ColIndex
Next RowIndex
End With
Note that there is a subtle difference between this example and the one presented in the earlier discussion
of the UnboundReadData event of mode 1. When programming the UnboundReadDataEx event, you
must fill in the Value array with column data according to the ColumnIndex array of the RowBuffer
object, since it is possible that the column indexes of the grid and the row buffer no longer match.
The grid generally asks for data according to the number of columns and the order of the columns as
displayed on the grid. For example, if your data source has 20 columns, and the grid needs to display the
first 5 columns on the screen, then the UnboundReadDataEx event will be called with ColumnCount
equal to 5 and the ColumnIndex array equal to (0, 1, 2, 3, 4). However, if the user moves column 4
between column 0 and column 1, then the next UnboundReadDataEx event will be called with
ColumnCount equal to 5 and the ColumnIndex property array equal to (0, 4, 1, 2, 3). Therefore, you must
account for the new column order, as given by the ColumnIndex property, when filling the Value array.
Another important distinction between the two row-based unbound modes is that in mode 2,
UnboundReadDataEx will not fetch data for columns whose Visible property is False, and may not fetch
data for columns that are not physically displayed or have been scrolled out of view, even if their Visible
property is True. In mode 1, however, UnboundReadData will always fetch data for all columns, even if
they are not shown on the screen or have their Visible property set to False. This is one of the reasons
why mode 2 generally outperforms mode 1.
When the grid first loads, it needs to determine if there is any data to display. It does this by firing the
UnboundReadDataEx event to retrieve the bookmark (but not the data) for the first row. If your event
228 · Unbound Mode

handler provides a bookmark, the grid fires UnboundReadDataEx again, this time to fetch the actual
data in a block of ten rows. This process continues until the grid has enough data to fill its display or your
event handler informs the grid that the end of the dataset has been reached.
For example, if the grid specifies a StartLocation bookmark indicating the 46th row, the Offset argument is
3, and the row buffer's RowCount property is 10, then your UnboundReadDataEx event handler should
populate the row buffer's Value array as follows:
RowBuf.Value(0, ColIndex) = Data for row 49
RowBuf.Value(1, ColIndex) = Data for row 50
RowBuf.Value(2, ColIndex) = Data for row 51
...
RowBuf.Value(9, ColIndex) = Data for row 58
However, if Offset is -3, a different set of values must be returned:
RowBuf.Value(0, ColIndex) = Data for row 43
RowBuf.Value(1, ColIndex) = Data for row 44
RowBuf.Value(2, ColIndex) = Data for row 45
...
RowBuf.Value(9, ColIndex) = Data for row 52
Note that you should always populate the Value array in the forward direction, regardless of whether
Offset is positive or negative. This differs from the UnboundReadData event of mode 1, in which rows
must be returned in reverse order if ReadPriorRows is True.
If you reach the beginning or end of the data, and have fewer than RowCount rows to provide, then you
should fill the row buffer with the data you can provide, and change the RowCount property to the
actual number of rows provided, which may be zero.
For example, if your dataset contains 50 records, the grid specifies a StartLocation bookmark indicating the
46th row, the Offset argument is 1, and the row buffer's RowCount property is 10, then your
UnboundReadDataEx event handler should populate the row buffer's Value array as follows:
RowBuf.Value(0, ColIndex) = Data for row 47
RowBuf.Value(1, ColIndex) = Data for row 48
RowBuf.Value(2, ColIndex) = Data for row 49
RowBuf.Value(3, ColIndex) = Data for row 50
RowBuf.RowCount = 4 ' Since only 4 rows were processed
Since the value of RowCount was changed from 10 to 4, and Offset is positive, the grid determines that it
has reached the end of your data and stops firing UnboundReadDataEx with a positive Offset.
When the user scrolls vertically, the grid computes the position of the new topmost visible row and fires
UnboundReadDataEx to obtain a bookmark for that row. For example, if the user hits the PGUP key, the
grid might fire UnboundReadDataEx with a StartLocation representing row 90 and Offset equal to -20. In
this case, the grid is effectively asking for a bookmark for row 70. Once the grid has the bookmark it
needs, it will fire UnboundReadDataEx again to fetch the data to be displayed.
At times, the arguments passed to UnboundReadDataEx may seem peculiar. For example, if StartLocation
specifies row 2 and Offset equals -10, the grid is effectively asking for a bookmark for row -8, and you
should set RowCount to 0 and exit the event. Although it may seem unnecessary for the grid to request
the bookmark of a row that does not exist, such behavior is normal, for this is how the grid determines
the boundaries of your data source. Also, since the grid is designed to work with multiuser data sources,
it is very conservative about boundary conditions. As long as you respond to UnboundReadDataEx
consistently and correctly, the grid will detect BOF and EOF conditions as fluidly as it does in bound
mode.
 Unbound Mode Events · 229

A StartLocation of Null indicates a request for data from BOF or EOF. For example, if StartLocation is Null
and Offset is 2 (or -2), then you should retrieve data starting from the second (or second to last) row:
If IsNull(StartLocation) Then
If Offset < 0 Then
' StartLocation indicates EOF, because the grid is
' requesting data in rows prior to the StartLocation,
' and prior rows only exist for EOF.
' There are no rows prior to BOF.
Else
' StartLocation indicates BOF, because the grid is
' requesting data in rows after the StartLocation,
' and rows after only exist for BOF.
' There are no rows after EOF.
End If
Else
' StartLocation is an actual bookmark passed to the grid
' in the RowBuffer, an event argument (UnboundAddData), or
' the setting of a grid bookmark. You must ensure that
' the bookmark is valid, and take the appropriate action
' if it is not.
End If
NOTE: You cannot make any assumptions about when the grid will request data, or how many times it
will request the same data. In short, it is the grid's responsibility to display the data properly, while the
task of storing and maintaining the data falls to you. This division of labor frees you from worrying about
when or how to display data in the grid.

UnboundReadDataEx event examples

The following examples assume a dataset containing 100 rows, numbered 0 to 99. Thus, when calculating
bookmark positions, a negative row number denotes BOF, and a row number greater than or equal to 100
denotes EOF.
Example 1:
RowBuf.RowCount = 1
RowBuf.ColumnCount = 0
StartLocation = Bookmark for row 8
Offset = -1
In this example, 1 row and 0 columns are being requested, so the event handler must supply a bookmark
only. Since Offset is -1, the grid is asking for the row before row 8, and the event handler should respond
as follows:
RowBuf.Bookmark(0) = Bookmark for row 7
RowBuf.RowCount = 1
ApproximatePosition = 7
Example 2:
RowBuf.RowCount = 10
RowBuf.ColumnCount = 5
StartLocation = Bookmark for row 80
Offset = 15
In this example, the grid is asking for 10 rows of data starting with row 95 (80 + 15). Thus, the grid wants
data from rows 95 to 104, in ascending order. However, rows 100 to 104 do not exist in the dataset, so the
event handler returns as many rows as it can:
RowBuf.Bookmark(0) = Bookmark for row 95
RowBuf.Value(0, ColIndex) = Data for row 95
...
230 · Unbound Mode

RowBuf.Bookmark(4) = Bookmark for row 99

RowBuf.Value(4, ColIndex) = Data for row 99
RowBuf.RowCount = 5
ApproximatePosition = 95
Example 3:
RowBuf.RowCount = 10
RowBuf.ColumnCount = 2
StartLocation = Null
Offset = -13
In this example, the grid is asking for 10 rows of data. Since StartLocation is Null, and since Offset is
negative, the grid wants data starting at 13 rows before EOF. Since the last valid row is 99, row 100
denotes EOF, and the first requested row is 87 (100 - 13). Thus, the grid wants data from rows 87 to 96, in
ascending order, and the event handler should respond as follows:
RowBuf.Bookmark(0) = Bookmark for row 87
RowBuf.Value(0, ColIndex) = Data for row 87
...
RowBuf.Bookmark(9) = Bookmark for row 96
RowBuf.Value(9, ColIndex) = Data for row 96
RowBuf.RowCount = 10
ApproximatePosition = 87
Example 4:
RowBuf.RowCount = 1
RowBuf.ColumnCount = 0
StartLocation = Null
Offset = 1
In this example, the grid is asking for a bookmark, since 1 row and 0 columns are being requested. Since
StartLocation is Null and Offset is positive, the request is relative to BOF. Since Offset is 1, the bookmark
requested is that of the first row of the dataset. This example corresponds to the initial firing of
UnboundReadDataEx when the grid is first loaded, and the event handler should respond as follows:
RowBuf.Bookmark(0) = Bookmark for row 0
RowBuf.RowCount = 1
ApproximatePosition = 0
Example 5:
RowBuf.RowCount = 1
RowBuf.ColumnCount = 0
StartLocation = Bookmark for row 6
Offset = -15
In this example, the grid is asking for a bookmark, but the row requested (6 - 15 = -9) does not exist, since
the first valid data row is 0. In this case, the event handler should respond as follows:
RowBuf.RowCount = 0
Exit Sub
This is also the correct response when there are no records in the dataset.

Handling the UnboundWriteData event in modes 1 and 2

This event applies to both DataMode 1 - Unbound and 2 - Unbound Extended.
If the AllowUpdate property of the grid is True, and the user has edited data in one or more cells of the
current row, then moving to another row will trigger an update. The grid will then fire the
UnboundWriteData event, which allows you to use the changed values, passed via a RowBuffer object,
to update the data you are responsible for storing and maintaining. The syntax of this event is as follows:
 Unbound Mode Events · 231

Private Sub TDBGrid1_UnboundWriteData( _

ByVal RowBuf As RowBuffer, WriteLocation As Variant)
When this event is fired, the properties of the RowBuf argument are set as follows:
• RowCount is 1, since only one row can be updated at a time.
• ColumnCount specifies the number of columns of data in the Value array. This will always
reflect the total number of columns in the grid's Columns collection and not just those that are
visible on the screen. This ensures that data in invisible columns, which may have been modified
by other event handlers such as AfterColUpdate, are also updated to the underlying data source.
• The ColumnName array contains the names of the grid columns corresponding to the columns in
RowBuf.
• The Bookmark array is not used, since WriteLocation specifies the row being updated.
• The Value array contains a single row of data. Entries which are Null have not been changed.
Entries which are not Null reflect the user's changes.
WriteLocation is a bookmark that specifies the exact row that needs to be updated. This differs from the
StartLocation argument in the UnboundReadData event, which specifies the row before or after the desired
data, depending on the value of the ReadPriorRows argument.
The following code sample demonstrates how to determine which cells were modified by the user:
For ColIndex = 0 To RowBuf.ColumnCount - 1
If IsNull(RowBuf.Value(0, ColIndex)) Then
' Cell not modified by the user
Else
' RowBuf.Value(0, ColIndex) contains updated value
End If
Next ColIndex
The RowCount property is always set to 1 for this event, but you should change it to 0 if the update
cannot be completed, such as when the underlying database reports an error. The contents of the current
cell will be maintained if RowCount is set to zero.
NOTE: You can force the UnboundWriteData event to occur in code with the grid's Update method. This
technique is particularly valuable when the unbound dataset contains a single row and AllowAddNew is
False, since there is no way for the user to trigger the update by moving to another row in this case.

Handling the UnboundAddData event in modes 1 and 2

This event applies to both DataMode 1 - Unbound and 2 - Unbound Extended.
If the AllowAddNew and AllowUpdate properties of the grid are True, then users can add new records
to the grid, and you must implement the UnboundAddData event. The syntax of this event is as follows:
Private Sub TDBGrid1_UnboundAddData( _
ByVal RowBuf As RowBuffer, NewRowBookmark As Variant)
As with the UnboundWriteData event, data from the new row is passed via a RowBuffer object. When
this event is fired, the properties of the RowBuf argument are set as follows:
• RowCount is 1, since only one row can be added at a time.
• ColumnCount specifies the number of columns of data in the Value array.
• The ColumnName array contains the names of the grid columns corresponding to the columns in
RowBuf.
232 · Unbound Mode

• The Bookmark array is not used, since the new row does not yet have a valid bookmark.
• The Value array contains a single row of data. Entries which are Null have not been specified by
the user. Entries which are not Null reflect the user's additions.
The NewRowBookmark argument is initially Null. However, before returning from this event, you must set
it to a bookmark that uniquely identifies the newly added row. If you do not set the value of
NewRowBookmark, the add operation will fail and the grid will not allow its current row to change.

Handling the UnboundDeleteRow event in modes 1 and 2

This event applies to both DataMode 1 - Unbound and 2 - Unbound Extended.
If the AllowDelete property of the grid is True, then users can delete rows from the grid, and you must
implement the UnboundDeleteRow event. The syntax of this event is as follows:
Private Sub TDBGrid1_UnboundDeleteRow(Bookmark As Variant)
This is the simplest of all the unbound grid events. When fired, the Bookmark argument specifies the row
being deleted. If the deletion fails, you should set the Bookmark argument to Null before returning from
the event. Note that following execution of the UnboundDeleteRow event, the grid is automatically
refreshed.

Unbound Mode Programming Considerations

When the user updates, adds, or deletes data through the grid's user interface, the grid fires the
UnboundWriteData, UnboundAddData, or UnboundDeleteRow event so that your application can take
the appropriate action. Conversely, when you modify the underlying data source in code, you need to
notify the grid so that it can update its display to synchronize with your data.

Refreshing the display in mode 1

In the original DBGrid, the Refresh and ReBind methods behaved differently in bound and unbound
modes. For backward compatibility, these differences were preserved in True DBGrid when the
DataMode property is set to 1 - Unbound.
When a grid Refresh occurs, the grid refetches and redisplays all data by firing the UnboundReadData
event. After the refresh, the current cell is the first column of the first record, which is displayed at the
upper left corner of the grid. Any changed data will be lost.
When a grid ReBind occurs, the grid refetches data by firing the UnboundReadData event, but it
maintains any changed data within the current row. When redisplaying data, the grid attempts to
preserve the same current cell and top row, if possible.

Refreshing the display in mode 2

In DataMode 2 - Unbound Extended, the grid's Refresh and ReBind methods work in the same manner as
documented for bound mode. When these methods are called, the grid will discard its current display
and call the UnboundReadDataEx event to retrieve new data.
Please note that during a ReBind operation, the grid attempts to maintain the current record position.
Therefore, if the current record does not exist after the ReBind operation, it is up to you to position the
grid to a valid record afterwards. Or, you can avoid potential problems by reinitializing the grid before
performing the ReBind.
 Unbound Mode Programming Considerations · 233

Reinitializing the grid in modes 1 and 2

In DataMode 1 - Unbound, setting the grid's Bookmark property to Null before calling the grid's Refresh
or ReBind method will cause the UnboundGetRelativeBookmark and UnboundReadData events to fire
with a StartLocation of Null just as if the grid were first being displayed:
TDBGrid1.Bookmark = Null
TDBGrid1.ReBind
Similarly, in DataMode 2 - Unbound Extended, setting the grid's Bookmark property to Null before calling
the grid's Refresh or ReBind method will cause the UnboundReadDataEx event to fire with a
StartLocation of Null just as if the grid were first being displayed:

Updating and deleting rows in modes 1 and 2

In unbound mode, you can update a row in code and force the UnboundWriteData event to fire by
calling the grid's Update method:
TDBGrid1.Update
Similarly, you can delete a row in code and force the UnboundDeleteRow event to fire by calling the
grid's Delete method:
TDBGrid1.Delete

Adding rows in modes 1 and 2

True DBGrid does not provide an AddNew method to complement Update and Delete since it cannot
anticipate the requirements of the underlying data source. However, you can use the ApproxCount
property and ReOpen method to resynchronize the grid after adding one or more rows in code.
The following example assumes that the data source is a two-dimensional array. It allocates storage space
for a new row, informs the grid that the total number of rows has changed, then calls the grid's ReOpen
method to force the grid to refetch data and position to the newly added row:
' General declarations
Dim MaxRow As Long
Dim MaxCol As Integer
Dim MyArray() As String
' Assume that MyArray is one-based
MaxRow = MaxRow + 1
ReDim Preserve MyArray(1 To MaxRow, 1 To MaxCol)
' Update the number of rows
TDBGrid1.ApproxCount = MaxRow
' ReOpen the data source and make MaxRow the current row
TDBGrid1.ReOpen MaxRow

Calibrating the vertical scroll bar in modes 1 and 2

When the grid displays a vertical scroll bar, the scroll box indicates the ordinal positions of the records
being displayed, and users expect to be able to drag the scroll box to quickly locate the desired records.
In order for the scroll box to function properly, both the total number of rows and the ordinal position of
the first displayed row must be known, or at least approximated. Unfortunately, one or both of these
quantities are often unavailable to the grid, especially in unbound modes.
Since data is supplied and maintained by the application code, the grid does not generally know the total
number of rows in the data source. Also, when the grid is instructed to position to a particular record, as
234 · Unbound Mode

in an assignment to its Bookmark property, the grid does not generally know the ordinal position of the
assigned bookmark, which may have been obtained through a find or seek operation.
Unless you compensate for these unknowns, the vertical scroll bar may behave unpredictably. To avoid
this, you need to supply the grid with the total number of rows in the data source (or an approximate
total), and the ordinal position of the first displayed row (or an approximate position).
To provide the total row count, you can set the grid's ApproxCount property:
TDBGrid1.ApproxCount = TotalRows ' Set approximate row count
To provide the ordinal position of the first displayed row in DataMode 1 - Unbound, write a handler for
the UnboundGetRelativeBookmark event.
To provide the ordinal position of the first displayed row in DataMode 2 - Unbound Extended, set the
ApproximatePosition argument within the handler for the UnboundReadDataEx event.

Unbound Mode Examples

For an example of how to use True DBGrid in unbound mode (DataMode 1) using a Visual Basic array as
the data source, see Tutorial 16 (page 64) or examine the UNBOUND1.VBP sample, which can be found
in the TUTORIAL\UNBOUND1 subdirectory of the True DBGrid installation directory.
For an example of how to use True DBGrid in unbound extended mode (DataMode 2) using a Visual
Basic array as the data source, see Tutorial 17 (page 70) or examine the UNBOUND2.VBP sample, which
can be found in the TUTORIAL\UNBOUND2 subdirectory of the True DBGrid installation directory.
 Changing the Current Record Position · 235

Database Programming Techniques

As Tutorial 1 (page 27) demonstrates, no code is necessary to create a fully functional database browser
and editor using True DBGrid. However, in order to build more sophisticated applications, you can use
the techniques outlined in this chapter. Except where noted, these techniques apply to all DataMode
property settings.
If you haven't already, please read Understanding Bookmarks (page 23), as the remainder of this chapter
presupposes knowledge of bookmarks.
NOTE: The terminology and code samples used in this chapter are specific to Visual Basic's intrinsic Data
control. However, you can generally apply similar techniques to other data source controls as well.

Changing the Current Record Position

True DBGrid enables you to manipulate the current record position directly in either bound or unbound
modes. To do so, you can use the Bookmark property or one of the navigation methods.

Using the Bookmark property

When you set the Bookmark property to a valid value in code, the row associated with that value
becomes the current row, and the grid adjusts its display to bring the new current row into view if
necessary.

Using the navigation methods

When the grid is bound to a Data control, you can manipulate the underlying Recordset using Data
control properties and methods such as EOF, MoveFirst, and MoveNext. However, if you decide later on
to switch to an unbound data source, these properties and methods will be unavailable.
True DBGrid solves this problem by providing properties and methods that mimic those supported by
Recordset objects. These properties and methods work the same for all DataMode settings, thus
eliminating the need to write separate implementations for bound and unbound modes.
MoveFirst Moves the current record to the first record available.
MoveLast Moves the current record to the last record available.
MoveNext Moves the current record to the next record available.
MovePrevious Moves the current record to the previous record available.
MoveRelative Moves the current record according to a specified offset and optional
bookmark.
Only the MoveRelative method accepts arguments (a long integer offset and an optional variant
bookmark). A positive offset indicates forward movement; a negative offset indicates backward
movement. If the bookmark argument is omitted, the current row's bookmark is used. Thus, the
following statements are all equivalent:
TDBGrid1.MoveRelative -1, TDBGrid1.Bookmark
TDBGrid1.MoveRelative -1
TDBGrid1.MovePrevious
236 · Database Programming Techniques

Detecting BOF and EOF conditions

In addition to the record navigation methods, True DBGrid provides BOF and EOF properties for
determining beginning and end of file conditions. For example, the following loop iterates through all
available records in any data mode:
With TDBGrid1
.MoveFirst
While Not .EOF
' Process current record
.MoveNext
Wend
End With
NOTE: This example is provided for illustration purposes only. In a real application, iterating through
the entire grid would produce a flurry of screen activity, and is therefore not recommended. Such
operations are best performed on the underlying data source, or better yet, a Recordset clone if one is
available.

Accessing and Manipulating Cell Data

In order to access and manipulate cell data, you need to use the Columns collection, which contains zero
or more Column objects. For more information, see Configuring Columns at Run Time (page 20).

Reading and writing cell data within the current record

You can read and write cell data within the current row by using the Column object's Text and Value
properties. (The CellText and CellValue methods are used to read values from other, non-current rows.)
To examine cell data in the current row:
CurrentText$ = TDBGrid1.Columns(ColIndex).Text
CurrentValue = TDBGrid1.Columns(ColIndex).Value
The Text and Value properties return the current contents of the specified column in the current row.
Note that the contents may have been edited by the user. The Text property returns a formatted string
(according to the column's NumberFormat property) exactly as it appears in the cell. The Value property
returns the unformatted cell data as a string variant.
To change cell contents in the current row:
TDBGrid1.Columns(ColIndex).Text = NewText$
TDBGrid1.Columns(ColIndex).Value = NewValue
Since the Value property accepts a variant, you can supply the new data using any appropriate data type.
For example, you can write a null value to the database by setting Value to Null in the BeforeUpdate
event. You do not need to format NewText$ or NewValue, since the grid will perform the appropriate
formatting before displaying the data.

Reading cell data from non-current records

You can read cell data from non-current rows by using the Column object's CellText and CellValue
methods. Note that you can only read data from non-current rows; you cannot update them. (The Text
and Value properties are used to read and write values within the current row.)
To examine cell data in any row, where bkm is the bookmark of the desired row:
RowText$ = TDBGrid1.Columns(ColIndex).CellText(bkm)
RowValue = TDBGrid1.Columns(ColIndex).CellValue(bkm)
 Validating Cell Data · 237

The CellText method returns a formatted string (according to the column's NumberFormat property)
exactly as it appears in the cell. The CellValue method returns the unformatted cell data as a string
variant.

Retrieving a bookmark relative to the current record

To retrieve a bookmark relative to the current record, use the grid's GetBookmark method, which accepts
an integer offset that specifies the number of records after the current record if positive, or before the
current record if negative:
Dim Bmk As Variant
Bmk = TDBGrid1.GetBookmark(0) ' Current row
Bmk = TDBGrid1.GetBookmark(1) ' Next row
Bmk = TDBGrid1.GetBookmark(-1) ' Previous row
Bmk = TDBGrid1.GetBookmark(4) ' Fourth row after current row
Note that the record referred to by the GetBookmark method need not be visible on the screen.

Retrieving a bookmark relative to a displayed row

To retrieve a bookmark relative to a row that is currently displayed, use the RowBookmark method,
which accepts an integer offset that specifies a zero-based row number ranging from 0 to VisibleRows -
1:
Dim Bmk As Variant
With TDBGrid1
Bmk = .RowBookmark(0) ' First displayed row
Bmk = .RowBookmark(1) ' Second displayed row
Bmk = .RowBookmark(.VisibleRows - 1) ' Last displayed row
End With
Note that unlike the GetBookmark method, the RowBookmark method only returns bookmarks for
visible rows.

Validating Cell Data

If the grid's AllowUpdate property is True, your users will be able to modify the underlying data
interactively through the grid's user interface. To prevent users from updating the database with invalid
entries, you can write data validation code that works on a per-cell or per-row basis. To validate
individual cells, use the BeforeColUpdate event. To validate entire rows, use the BeforeUpdate event.
For certain kinds of data, such as dates and phone numbers, you can use the EditMask property to
specify an input template that filters out illegal characters as they are typed. Even if you use True
DBGrid's built-in input masking features, you may still want to write data validation code. For example,
the user may enter a phone number that is syntactically legal, but contains a bogus area code. Since the
grid knows nothing about area codes, you would have to write a handler for either BeforeColUpdate or
BeforeUpdate in order to prevent the invalid number from being written to the underlying data source.

Validating end-user data entries

When finished making changes to a cell, the user can terminate editing by pressing the ENTER key,
moving to another cell using the arrow keys, or clicking another cell with the mouse. If the user stays in
the same row, data is not updated to the database. At the end of each cell editing session, you have the
opportunity to reject or change the user's modifications in the BeforeColUpdate event:
Private Sub TDBGrid1_BeforeColUpdate( _
ByVal ColIndex As Integer, _
OldValue As Variant, Cancel As Integer)
238 · Database Programming Techniques

ColIndex is the index of the column just edited. OldValue is the value of the cell before any changes were
made to it. It is possible to edit a cell many times before updating to the database, but OldValue will be the
same for all the updating sessions.
You generally use BeforeColUpdate to validate data entered by the user before leaving the cell. You can
examine or change the edited data using the Column object's Text and Value properties. In any data
mode, you can compare the changes to the original cell data using the OldValue argument. In bound
mode only, you can also examine the field value of the data control:
Data1.Recordset.Fields(ColIndex).Value
Note that this expression assumes that the grid's columns match the members of the Fields collection of
the Data control's Recordset. This assumption holds true if you are using the grid's automatic layout
feature. However, if you have defined your own layout, then you should reference the Fields collection
by name:
Data1.Recordset.Fields("FieldName").Value
Note the similarity between the Column object and Columns collection and the Field object and the
Fields collection. You can access the members of either collection by numeric index or name, whichever is
more convenient.
You can cancel the update by setting Cancel to True in the BeforeColUpdate event. If canceled, the grid
will restore the cell to its value before the current editing session. The restored value may not be the same
as OldValue if the user has edited the cell multiple times. The cell movement will be canceled and the
current cell remains in place.
If the update is not canceled, the AfterColUpdate event will fire:
Private Sub TDBGrid1_AfterColUpdate(ByVal ColIndex As Integer)
and the current cell moves to a new location if appropriate. The current cell does not change if the user
has left editing by pressing the ENTER key. Note that unless the cell is moved to another row, the user has
only changed the visible data in the grid; no change will be made to the database. Before the change has
been updated to the database, the user can always restore the cell to OldValue by pressing the ESC key.
For more information, see Database Operations (page 190).
The following example prevents the user from leaving the current cell if the value entered is an empty
string. Although your first inclination may be to display a message box for the user in BeforeColUpdate,
this will not work as expected because the message box will cause the BeforeColUpdate event to fire
again before it is finished, resulting in an endless series of message boxes. The solution is to post a
message to the grid using the PostMsg method, then show the message box in the handler for the
PostEvent event, which will not fire until the BeforeColUpdate event has finished.
Private Sub TDBGrid1_BeforeColUpdate( _
ByVal ColIndex As Integer, _
OldValue As Variant, Cancel As Integer)
If TDBGrid1.Text = "" Then
' Schedule the PostEvent event
TDBGrid1.PostMsg 1
' The following line is used to keep the cell blank
' (remove it to restore the old cell value)
OldValue = ""
' Cancel the update and keep focus on this cell
Cancel = True
End If
End Sub
 Validating Cell Data · 239

Private Sub TDBGrid1_PostEvent(ByVal MsgId As Integer)

' 1 is the argument to PostMsg in BeforeColUpdate
If MsgId = 1 Then MsgBox "Cells may not be empty"
End Sub

Validating data before updating to the database

Any changes made to the current row are updated to the database when the user moves to another row
or when your code executes the Edit and Update methods on the Data control's Recordset:
Data1.Recordset.Edit
Data1.Recordset.Update
Before any changes are made to the database, the Data control's Validate event will fire, followed by True
DBGrid's BeforeUpdate event. Either of these events can be used to cancel the update to the database by
setting the Cancel argument to True.
Private Sub TDBGrid1_BeforeUpdate(Cancel As Integer)
If the update succeeds, the grid's AfterUpdate event will fire:
Private Sub TDBGrid1_AfterUpdate()
and the current cell moves to a new location when appropriate.
You can use similar True DBGrid events to validate the data before adding or deleting a row from the
database:
Private Sub TDBGrid1_BeforeInsert(Cancel As Integer)
Private Sub TDBGrid1_AfterInsert()
Private Sub TDBGrid1_BeforeDelete(Cancel As Integer)
Private Sub TDBGrid1_AfterDelete()
Alternatively, you can use the Data control's Validate event to accept or reject the changes to the
database. Internally, True DBGrid uses bookmarks to navigate through the database. Thus, when a Data
control's Validate event is fired in response to a row change in the grid, the Action argument will be
vbDataActionBookmark, which indicates that the Bookmark property of the underlying Recordset has
changed. You can cancel the movement by setting the Action argument to zero. In this case, the grid will
keep the original row current, rather than changing to the newly selected row. The Save argument will be
True if data in a bound control has changed and is about to be written to the database. If you set the Save
argument to False, any user edits will remain, and the user will need to correct the data before continuing.
This is how invalid data is typically handled. See the Visual Basic Help for more details on using the Data
control's Validate event.
The following example demonstrates how to use the BeforeUpdate event to validate an entire row of
data. Whenever the user attempts to update the current row, a message box is displayed, asking the user
if the record should be saved. If the user chooses Yes, the update proceeds. If the user chooses No, the
update is canceled, and the grid's current row does not change.
Dim UpdateFlag As Boolean
Private Sub TDBGrid1_BeforeUpdate(Cancel As Integer)
Dim MsgText As String, MsgCaption As String
Dim Response As Integer, MsgBoxType As Integer
MsgText = "Do you want to save this record?"
MsgBoxType = vbYesNo + vbQuestion
MsgCaption = "Confirm Update"

Response = MsgBox(MsgText, MsgBoxType, MsgCaption)

240 · Database Programming Techniques

If Response = vbNo Then

Cancel = True
UpdateFlag = True
End If
End Sub
Private Sub TDBGrid1_Error(ByVal DataError As Integer, _
Response As Integer)
If UpdateFlag Then ' Error triggered in BeforeUpdate
Response = 0 ' Don't display default message
UpdateFlag = False ' Clear flag for next update
End If
End Sub
Unlike the BeforeColUpdate event, displaying a message box in the BeforeUpdate event does not cause
recursion problems.
The Error event is included in this example because it will fire as a result of the update being canceled.
The boolean variable UpdateFlag is used to suppress the default error message for the BeforeUpdate
case but not for other kinds of errors. For more information, see Handling Database Errors (page 243).

Selecting and Highlighting Records

At run time, the user can select and highlight one or more records by clicking the record selector of the
desired row. You can achieve the same effect in code by manipulating the grid's SelBookmarks
collection, which maintains a list of bookmarks corresponding to the selected rows.
Like all other collections in True DBGrid, the SelBookmarks collection supports Add, Item, and Remove
methods and a Count property. For example, to select the grid's current row, use the Add method:
TDBGrid1.SelBookmarks.Add TDBGrid1.Bookmark
After the Add method executes, the collection's Count property is incremented. You can use the Add
method repeatedly to select and highlight additional rows. This is analogous to the user holding down
the CTRL key while clicking a record selector.
To deselect a single record, use the Remove method, which takes a collection index, not a bookmark:
TDBGrid1.SelBookmarks.Remove 0
After the Remove method executes, the collection's Count property is decremented. If more than one
record is selected, the previous example will only remove the first selected record; that is, the one that
was added to the collection first, regardless of its position on the screen. To deselect all records, you need
to write a loop like the following:
With TDBGrid1.SelBookmarks
While .Count > 0
.Remove 0
Wend
End With
Tutorial 5 (page 37) demonstrates how to use the SelBookmarks collection to select records that satisfy
specific criteria.
 Updating and Deleting the Current Record · 241

Updating and Deleting the Current Record

If the user finishes making changes to a cell, but stays in the same row, data is not updated to the
database. You can force the row to be updated by applying the Update method of the grid. This method
works for any DataMode setting:
TDBGrid1.Update
For a bound grid (ICursor) (DataMode property set to 0 - Bound), you can also force an update using the
Update method of the Data control's Recordset:
Data1.Recordset.Edit
Data1.Recordset.Update
Similarly, for a bound OLE DB grid (bound to an ADODC control):
Adodc1.Recordset.Update
And if bound to an ADO recordset directly:
Recordset.Update
You can delete the current row in any data mode using the grid's Delete method:
TDBGrid1.Delete
NOTE: When an OLE DB grid is bound to a data source for which batch updates are in effect (such as an
ADO Recordset whose LockType property is set to adLockBatchOptimistic), the grid must not update the
current record. In most cases, the grid can derive this information even though it is not part of the OLE
DB specification. For the rare cases in which the grid cannot determine whether batch updates are in
effect, you can set the BatchUpdates property in code to override the grid's default behavior.
To prevent updates from occurring when the user moves off a modified row, set BatchUpdates to True.
To enable updates on a per-row basis, set BatchUpdates to False.

Refreshing the Display

True DBGrid defers screen updates until they are needed by waiting until Windows enters an idle loop.
This generally occurs when your code stops executing and the system is waiting for user input. You can
simulate an idle loop in code by calling the Visual Basic function DoEvents, which causes all pending
events to be processed.
In most cases, you need not be concerned with the grid's display operations and can concentrate on
writing code that works directly with the database. However, if the structure of your data source
changes, or you need to temporarily keep the grid from responding to database events, you can use the
Refresh, ReBind, or ReOpen methods. If you are not using DataMode 1 - Unbound, these methods
behave as follows:

Refresh This method simply forces the grid to repaint, and no database access occurs. The
grid maintains all modified data in the current row, and the current cell position is
unchanged.
ReBind This method causes the grid to disconnect from and then reconnect to its data
source. The grid rebinds all columns and refetches all data. Any data changed by the
user (but not yet updated to the database) will be lost. The grid maintains the current
row but not the current column. When data is redisplayed, the leftmost visible column
becomes current, and the current row becomes the first row in the grid (unless all
records are visible).
242 · Database Programming Techniques

ReOpen This method is typically used following a Close method to reconnect the grid to its
data source. The grid is repopulated and the current row is positioned to the row
identified by an optional bookmark argument. If no bookmark is specified, then the
current row reflects the current row of the data source.
If you need to refresh a single column or row instead of the entire grid, you can use the RefreshCol or
RefreshRow methods instead of Refresh. To refresh an individual grid cell, use the RefreshCell method
of the desired Column object.
To maintain backward compatibility with the original unbound mode of DBGrid, the Refresh and
ReBind methods behave as follows when the DataMode property is set to 1 - Unbound:
Refresh The grid refetches and redisplays all data by firing the UnboundReadData event.
Any data changed by the user (but not yet updated to the database) will be lost. The
grid maintains the current row but not the current column. When data is redisplayed,
the leftmost visible column becomes current, and the current row becomes the first
row in the grid (unless all records are visible).
ReBind The grid refetches data by firing the UnboundReadData event, but it maintains any
data changed by the user within the current row. When data is redisplayed, the
current cell position and the grid display are unchanged.

Refetching Data from the Data Source

Normally, you need not be concerned with the mechanics of data retrieval. True DBGrid retrieves data
automatically as needed, in blocks of ten rows, and only gathers data for visible columns. However, in
some cases, you can improve performance by fetching only the data for a single (changed) row, column,
or cell using one of the following methods:
RefetchRow Given a bookmark, this TDBGrid control method repopulates the specified row from
the data source.
RefetchCol Given a column index, this TDBGrid control method repopulates the specified
column from the data source.
RefetchCell Given a bookmark, this Column object method repopulates the specified cell from
the data source.
These methods repaint the affected cells, firing all events necessary for redisplay. However, they do not
force the data source control to refresh its own data from the underlying database. You must use data
control methods or options to accomplish this.

Coordinating with Other Controls

You can link multiple True DBGrid controls using the RowColChange event to trigger related actions.
Whenever the grid's current cell changes, the RowColChange event is fired, indicating that a new row
and/or column has become current. RowColChange is triggered in the following cases:
• The user clicks on a new row and/or column in the grid.
• The current cell is changed by code. This includes changing the grid's Bookmark, Col, or Row
properties and changing the current record through the Recordset.
• Data in the grid is refreshed.
• The user moves the record pointer using the navigation buttons on the Data control associated
with the grid.
 Handling Database Errors · 243

For example, you can use the RowColChange event to update the display of a status bar that provides
additional information or instructions as the user navigates from column to column. By providing the
user with clues during the data entry process, you can make your program more intuitive.
Private Sub TDBGrid1_RowColChange(LastRow As Variant, _
ByVal LastCol As Integer)
' TDBGrid1.Col has the new current column index
' Display help string in Label1
Select Case TDBGrid1.Col
Case 0
Label1.Caption = "Customer's credit card number"
Case 1
Label1.Caption = "Five-digit order number"
Case 2
Label1.Caption = "Total cost in US dollars"
End Select
End Sub
The RowColChange event is also a convenient place to coordinate activities with other controls or
databases. Tutorial 3 (page 32) provides an example of how you can use the RowColChange event to
implement master-detail relationships using two True DBGrid controls.

Handling Database Errors

True DBGrid processes errors in a manner consistent with other custom controls, generating both
trappable errors and error events. Trappable errors are reported whenever an error is generated by a
Visual Basic command or statement. Error events are fired whenever an error is generated by a user
action and there is no identifiable line of Visual Basic code causing the error.
When you develop error handling procedures, there are two key points to always keep in mind:
1. The source of the operation which ultimately results in an error.
2. The source of the actual error.

Trapping errors
Trapping an error is the first step in handling an error. As an example, suppose there is a grid bound to a
Data control, displaying a Recordset with a numeric field. Suppose also that a user enters non-numeric
data in the grid column associated with the numeric field. When an attempt is made to change rows, the
Data control automatically initiates the update process and tries to store the non-numeric data, resulting
in an error.
How is this error to be handled? Will the error appear as a trappable error, or in an error event? The
answer lies with the first key point given. The error will be reported by the control or code which initiates
the row change (the source of the operation which ultimately leads to the error), since it is the row change
operation which cannot be completed.
How many ways can you initiate the row change operation, and how is each trapped? Here are some
examples:
1. Click a command button which performs a Recordset move operation. In this case, the row
change operation is initiated by a line of Visual Basic code, and the error will be reported as a
trappable error, which is handled with the On Error statement.
2. Click a button of the data control. In this case, there is no identifiable line of Visual Basic code
which can be trapped, so the error will be reported in an error event. Because the row change is
initiated by the data control, the data control's Error event will be fired.
244 · Database Programming Techniques

3. Click any non-current row of True DBGrid. As in example 2, there is no identifiable line of Visual
Basic code which can be trapped, so once again the error is reported in an error event. However,
in this case, the row change is initiated by True DBGrid, so the error is reported in the grid's Error
event.
4. Press the down arrow key. As in example 3, the error is reported in the grid's Error event for the
same reasons.
5. Press the down arrow key, but perform a row change operation in the KeyDown event of the
grid using a bookmark or Recordset move operation. In this case, the row change event is
initiated by the code in the KeyDown event, and the error is trapped through the On Error
statement.

Processing trapped errors

After trapping a reported error, the task remains to process the error appropriately within the context of
your program. This requires analyzing the error code and error text to determine the problem and, of
course, deciding what to do about it.
In many cases, you will find that simply reporting the error to the user is the most appropriate. When an
error is trapped through an error event, reporting the error can be handled automatically by not coding
the error event at all. By default, a message box is displayed indicating the error. Additional details of
generalized Error events can be obtained from the Visual Basic help file.
Trappable errors, which originate from Visual Basic code, will result in program termination unless the
On Error statement is used to set up an error handler. Appropriate messages for the errors can usually
be obtained from the Visual Basic Error function, but sometimes require inspection of the object in which
the original error occurred. This will be discussed later.
When it becomes necessary to do more than display an error message, the second key point (the source of
the actual error) must be considered. In the example presented earlier, where non-numeric data is placed
in a numeric field, the error "Data type conversion error" is usually issued. This error does not originate
from the grid, or even the Data control. It comes from the database engine—DAO in the case of an Access
database.
Database errors usually result in a cascade of errors, each a direct result of the other. In our example, the
first error encountered is the "Data conversion error" generated by the database engine when attempting
to update the numeric field. As a result, a general failure error occurs from the row update. The row
update error causes the row change operation to fail, also with a general error code. This cascade of errors
makes the problem difficult to analyze, since only the general error of the row change failure is reported
to the grid from the data control, and finally passed on to your Visual Basic program as the trappable
error code or the DataError argument of the grid's Error event. In order to discern the true nature of the
problem, it is necessary to inspect the source of the original error—the Errors collection of the database
engine. This collection object is discussed fully in the Visual Basic help file.
To simplify handling of errors in the grid's Error event, True DBGrid supports an ErrorText property.
This property is read-only, and is available only during the execution of the Error event. It returns the
error message string associated with the underlying data source error that ultimately caused the grid's
Error event to fire.

Errors caused by cancellation

There are times when the source of an error is difficult to determine. The most common case of this is an
error which reports "Action canceled by an associated object." In most cases, this will be the result of a
database operation which has not been completed because a bound control has denied permission for the
 Postponing Illegal Operations in Grid Events · 245

operation to complete. Commonly, this will be the result of a canceled event. For example, suppose the
grid's BeforeUpdate event is canceled. The cancellation is reported to the Data control, which simply
reports the cancellation back to the grid. The Data control does not have knowledge of the reason for
cancellation; it only knows that it has occurred. Therefore, it issues the generic "Action canceled by an
associated object" message. In this case, since the cancellation is performed by your code. It is your
responsibility to display an informative error message and cancel the default error message generated by
the Data control.

Postponing Illegal Operations in Grid Events

During most of the grid events, database and other system operations are still pending, and certain
operations are not allowed within these grid events. To circumvent such limitations, you can use the
PostMsg method in conjunction with the PostEvent event to postpone operations which are illegal within
the grid events. If the PostMsg method is called, the grid will fire the PostEvent event with the MsgId of
the corresponding PostMsg invocation after all pending operations are completed. You can then safely
perform all desired operations in the PostEvent event.
For example, suppose it is necessary to keep the rows of a Recordset in sorted order based upon a
particular column, say Column 2. Whenever a cell in Column 2 is edited, or a new row is added, it is then
necessary to Refresh the Data control so the new data will be placed in the correct order in the Recordset.
A reasonable approach to this problem is to include a flag variable to determine that a Refresh is needed
in the grid's BeforeUpdate event:
Dim refreshNeeded As Boolean ' Global flag variable
Private Sub Form_Load()
refreshNeeded = False ' Initialize flag variable
End Sub

Private Sub TDBGrid1_BeforeUpdate(Cancel As Integer)

refreshNeeded = TDBGrid1.Columns(2).DataChanged Or _
(TDBGrid1.AddNewMode = dbgAddNewPending)
End Sub
A convenient place to perform the Data control Refresh is within the grid's AfterUpdate event. However,
it is not possible to perform the Refresh method within the AfterUpdate event because database
operations are still pending, and the Refresh method will fail. Instead of performing the Refresh, you can
call the PostMsg method with an arbitrary numeric argument (1, in the following example) in the
AfterUpdate event. After all pending database operations are completed, the grid will fire the PostEvent
event. You can then check for the numeric argument and perform the Refresh operation safely:
Private Sub TDBGrid1_AfterUpdate()
If refreshNeeded Then
refreshNeeded = False ' Reset flag variable
TDBGrid1.PostMsg 1 ' Post a message with MsgId = 1
End If
End Sub
Private Sub TDBGrid1_PostEvent(ByVal MsgId As Integer)
Select Case MsgId
Case 0
Exit Sub
Case 1
Data1.Refresh
Case 2
' Process other postponed operations
End Select
End Sub
246 · Database Programming Techniques

The PostMsg and PostEvent combination in the preceding example postpones the Refresh until the
PostEvent event—after all pending database operations have completed.
If the PostMsg argument is zero, the grid will fire the PostEvent event with an argument of zero, but all
other pending posted events will be discarded. Since refreshing the Data control makes all other posted
events irrelevant anyway, the preceding example can be simplified as follows:
Private Sub TDBGrid1_AfterUpdate()
If refreshNeeded Then
refreshNeeded = False ' Reset flag variable
TDBGrid1.PostMsg 0 ' Post a message with Id = 0
End If
End Sub
Private Sub TDBGrid1_PostEvent(ByVal MsgId As Integer)
Select Case MsgId
Case 0
Data1.Refresh
Case 1
' Process other postponed operations
End Select
End Sub
When the PostMsg method is called with a numeric argument, the grid uses the Windows API function
PostMessage to place a message in the Windows message queue. The numeric argument is passed along
with it. When the grid retrieves the posted Windows message, it fires the PostEvent event with the
numeric argument of the corresponding PostMsg method.
Please note that execution of the Visual Basic DoEvents function will cause the Windows message queue
to be processed, thus causing execution of the PostEvent events before the DoEvents returns.
 Captions, Headers, and Footers · 247

Customizing the Grid's Appearance

This chapter explains how to configure the non-interactive elements of True DBGrid's display, such as
captions, headers, footers, record selectors, and dividing lines.

Captions, Headers, and Footers

You can affix a title to a grid, column, or split by setting the Caption property of the appropriate object.
TDBGrid1.Caption = "Grid Caption"
TDBGrid1.Columns(0).Caption = "Column 0 Caption"
TDBGrid1.Splits(0).Caption = "Split 0 Caption"

Column and grid captions

For Column objects, the Caption property specifies the text that appears in each column's header area.

If you are using True DBGrid in bound mode with an automatic layout, the column captions are set
automatically at run time. At design time, you can use the Retrieve Fields context menu item to initialize
the grid layout according to the current RecordSource setting for the Data control to which the grid is
bound.
You can also set column captions at design time using the Columns property page, or at run time by
manipulating the Columns collection in code. For more information, see Configuring Columns at Run
Time (page 20).
The Caption property also applies to the TDBGrid control itself, which lets you provide a descriptive
header for the entire grid.

By default, True DBGrid displays headings for each column, even if you never set the Caption property
of an individual column explicitly. However, you can hide all column headings by setting the
ColumnHeaders property to False.
248 · Customizing the Grid's Appearance

Column footers
Just as the ColumnHeaders property controls the display of column captions, the ColumnFooters
property controls the display of the column footer row. Column footers, which are similar in appearance
to column headers, are always displayed at the bottom of the grid, even if it is underpopulated.

For each Column object, the FooterText property determines the text that is displayed within the footer
row. You can set the footer text at design time using the Columns property page, or at run time by
manipulating the Columns collection in code, as in the following example:
TDBGrid1.Columns(0).FooterText = "Footer0"
TDBGrid1.Columns(1).FooterText = "Footer1"
Unlike the Caption property, the FooterText property is not set automatically from a bound data source,
so you will have to set it yourself.

Multiple-line headers and footers

The HeadLines property controls the height of the column headers. By default, it is set to 1, which means
that the column headers occupy a single row. If you need to display more than one line of text in a
column header, you can increase the HeadLines property to accommodate additional lines, as in the
following example:
With TDBGrid1
.HeadLines = 2
.Columns(0).Caption = "First line" + vbCr + "Second line"
End With
Note the use of the Visual Basic constant vbCr to specify a line break within the caption text. After this
code executes, the first column's caption will contain two lines of text, and the second column's caption
will be centered vertically.

Similarly, you can set the FootLines property to control the height of column footers, and use the vbCr
constant to specify a line break when setting the FooterText property of a column.
 Three-dimensional versus Flat Display · 249

NOTE: The HeadLines property only affects column headers; it has no effect on grid or split captions,
which can only occupy a single row.

Split captions
Split objects can also have their own captions. For a grid with one split, a split caption can serve as a
second grid caption.

However, split captions are best used in grids with at least two splits, as they are ideal for categorizing
groups of columns for end users.

Three-dimensional versus Flat Display

True DBGrid supports a standard, "flat" control appearance, the more attractive three-dimensional
appearance used by many controls and a third that combines the flat appearance with the 3D.. By default,
the grid's Appearance property is set so that the 3-D look is used. However, this property only controls
whether 3-D effects are used to draw the grid's border, caption bars, column headings and footings, and
the record selector column. It does not affect the grid's data cells or row and column dividers.
When Appearance is set to 1 - 3D, the grid looks like this.
250 · Customizing the Grid's Appearance

When Appearance is set to 2 – 3D Track, the grid looks like this.

Note that the initial grid has the same in appearance as the 0 – Flat. As the mouse moves over any control
element, the appearance of that element takes on a 3D look.
When Appearance is set to 0 - Flat, the grid looks like this.

To achieve a 3-D appearance for the entire grid, including its interior, set the following properties at
either design time or run time:
• On the General property page, set the RowDividerStyle property to 4 - Inset. Or, in code:
TDBGrid1.RowDividerStyle = dbgInset
• On the Splits property page, set the DividerStyle property to 4 - Inset for all members of the
Columns collection of each split. Do not confuse this with the DividerStyle property of the Split
object itself. Or, in code:
Dim C As TrueDBGrid80.Column
For Each C In TDBGrid1.Columns
C.DividerStyle = dbgInset
Next
• On the General property page, set the BackColor property to gray. Or, in code:
TDBGrid1.BackColor = &HC0C0C0
 Borders and Dividing Lines · 251

The resulting grid will look something like this.

Note that changing the RowDividerStyle property from 2 - Dark gray line to 4 - Inset consumes an extra
vertical pixel in each data row, resulting in fewer visible rows.
You can experiment to achieve different 3-D effects using other color combinations and divider styles, as
explained in the next section.

Borders and Dividing Lines

The RowDividerStyle and DividerStyle properties enable you to choose different horizontal and vertical
lines and their colors. Note that RowDividerStyle is a TDBGrid object property and DividerStyle is both
a Column and Split object property. The allowable values for both properties are as follows:
0 - No dividers
1 - Black line
2 - Dark gray line
3 - Raised
4 - Inset
5 - ForeColor
6 - Light gray line
7 - Custom Color
8 - Double Line
For example, setting the RowDividerStyle property to 0 - No dividers eliminates the dividing lines
between rows and enables you to cram a bit more data into the available area.
252 · Customizing the Grid's Appearance

For Column objects, you can set the DividerStyle property to 0 - No dividers, and the HeaderDivider
property to False. This enables you to visually group related columns, as shown in the following figure.

For Split objects, setting the DividerStyle property only affects the display of the border drawn at the left
edge of the split; it does not change the appearance of column dividers within the split. For example, if a
grid has two splits, you can set the DividerStyle property of the rightmost split to 1 - Black line to de-
emphasize the thick border that the grid normally draws to indicate split boundaries.

NOTE: Prior to version 6.0, Split objects did not have a DividerStyle property, and the grid always
displayed the divider as a thick black line. The setting 0 - No dividers refers to this default behavior; it does
not eliminate the divider.

Unpopulated Regions
Depending upon the number of rows and columns in the data source, a portion of the grid's interior may
not contain data cells. However, you can eliminate these "dead zones" using the ExtendRightColumn
and EmptyRows properties. Change the color of the dead areas by using the DeadAreaBackColor
property.

The rightmost column

As the grid scrolls horizontally until the last column is totally visible, there is usually a blank area
between the last column and the right border of the grid.
 Unpopulated Regions · 253

The color of this blank area depends on the setting of your system's 3D Objects color (or Button Face
color), which is usually gray. You can eliminate this blank area with the ExtendRightColumn property.
The default value of this property is False, but if you set it to True, then the last column will extend its
width to the right edge of the grid.

Unused data rows

If the data source contains fewer rows than the grid can display, the area below the AddNew row (or the
last data row, if AllowAddNew is False) is left blank.

The color of this blank area depends on the setting of your system's 3D Objects color (or Button Face
color), which is usually gray. You can eliminate this blank area with the EmptyRows property. The
default value of this property is False, but if you set it to True, then the grid will display empty rows
below the last usable data row.
254 · Customizing the Grid's Appearance

Note that the empty rows cannot receive focus.

You can set both the EmptyRows and ExtendRightColumn properties to True to ensure that no blank
areas appear within the interior of the grid.

Highlighting the Current Row or Cell

The term marquee refers to the highlighted area which represents the current grid cell or row. The
MarqueeStyle property can be set to seven possible presentations, illustrated as follows.

MarqueeStyle 0 - Dotted Cell Border

The current cell is highlighted by a dotted border.

MarqueeStyle 1 - Solid Cell Border

This is a more distinctive form of cell highlighting, often useful when a different background color is used
(since the dotted rectangle is often difficult to spot).
 Highlighting the Current Row or Cell · 255

MarqueeStyle 2 - Highlight Cell

This style inverts the current cell completely, making it very visible. Values of the EditBackColor and
EditForeColor properties should be chosen carefully to make a pleasing effect if your grid is editable.

MarqueeStyle 3 - Highlight Row

The entire row will be highlighted, but it won't be possible to tell which cell is the current cell in the row.
To change highlight colors, you can edit the built-in HighlightRow style on the Style Factory property
page. This style is most useful when the grid is not editable and your users would view the data one
record at a time.

MarqueeStyle 4 - Highlight Row, Raise Cell

This value should only be used if 3-D lines are used in the grid, since cell highlighting is accomplished
using a "raised" appearance for the current cell.
256 · Customizing the Grid's Appearance

MarqueeStyle 5 - No Marquee
This setting will make the marquee disappear completely. Often this setting is useful for cases where the
current row is irrelevant, or where you don't want to draw the user's attention to the grid until necessary.

MarqueeStyle 6 - Floating Editor

This is the default marquee style of the grid. The cell text (the actual text only, not the entire cell) is
highlighted and there is a blinking text cursor (caret) at the end of the text.

The color of the highlight is your system's highlight color. The floating editor style simulates the look and
feel of the Microsoft Access datasheet. The blinking text cursor indicates that the cell is edit-ready, hence
the name floating editor for this marquee style. Since no other marquee style places the cell in a similar
edit-ready mode, the behavior of the grid with the floating editor is sometimes different from the other
marquee styles. The following list summarizes the differences when the MarqueeStyle property is set to
6 - Floating Editor:
1. The following properties are ignored by the floating editor: EditBackColor, EditDropDown,
EditForeColor, EditorStyle, and MarqueeUnique.
2. When using the AddCellStyle and AddRegexCellStyle methods with the floating editor, the
grid ignores the current cell bit (dbgCurrentCell) and highlighted row bit (dbgMarqueeRow)
of the Condition argument. For more details, see Applying Styles to Cells (page 321).
3. The floating editor will not be displayed in a cell with radio buttons or a picture, as described in
Automatic Data Translation with ValueItems (page 265). A dotted cell marquee will be used
instead. The floating editor highlight will return when the current cell is changed to one with
normal text display.
4. The CycleOnClick property (applies to ValueItems collection) has no effect when the
MarqueeStyle property is set to 6 - Floating Editor.
5. The drag-and-drop features described in Drag-and-Drop Behavior (page 191) will not work as
well as they do with other marquee styles. Users will not be able to begin dragging a cell to
trigger the DragCell event unless they manage to grab the narrow region between the floating
editor and either column divider. This is because the floating editor is itself a control and is
preventing the grid cell from detecting the drag.
 Row Height and Multiple-line Displays · 257

6. The DblClick event of the TDBGrid control does not fire when the user double-clicks a non-
current cell within the grid. This is because the first click is used by the floating editor to begin
editing, placing the cell into edit mode at the character on which the click occurred. Double-
clicking the current cell of the grid fires the DblClick event normally, however.

MarqueeStyle 7 - Dotted Row Border

This setting highlights the entire row with a dotted rectangle. You can use this setting instead of 3 -
Highlight Row if you prefer a more subdued highlight.

Row Height and Multiple-line Displays

The RowHeight property controls the height of all grid rows. The MultipleLines property controls
whether a single row can span multiple lines.

Adjusting the height of all grid rows

You can configure the row height interactively at design time by placing the grid in its visual editing
mode or by changing the grid's RowHeight property on the General property page. At run time, the user
can adjust the row height interactively if AllowRowSizing is True. For more information, see Run Time
Interaction (page 181).
The RowHeight property is expressed in units of the container's coordinate system. However, a setting of
0 causes the grid to readjust its display so that each row occupies a single line of text in the current font.
Therefore, you can use the following code to adjust the row height to display exactly three lines of text:
TDBGrid1.RowHeight = 0
TDBGrid1.RowHeight = 3 * TDBGrid1.RowHeight
This technique is particularly effective when displaying multiple-line memo fields, as in this example.

Note that the Description column must have its WrapText property set to True; otherwise, the memo field
display will be truncated after the first line.
258 · Customizing the Grid's Appearance

Enabling wordwrap in cells

By default, a grid cell displays a single line of text, truncated at the cell's right boundary. You can display
multiple lines of text in a cell by increasing the grid's RowHeight property and setting the WrapText
property of the desired columns to True. If WrapText is True (the default is False), a line break occurs
before words that would otherwise be partially displayed in a cell. The cell contents will continue to
display on the next line, assuming that the grid's row height accommodates multiple lines.
You can use the following loop to enable wordwrap for all grid columns:
Dim C As TrueDBGrid80.Column
For Each C In TDBGrid1.Columns
C.WrapText = True
Next
Or, at design time, you can set WrapText to True in one column, then use the Set All Columns command
on the property tree context menu to apply that value to all columns.

Displaying a single record on multiple lines

Normally, a record is displayed in a single row in the grid. If the grid is not wide enough to display all of
the columns in the record, a horizontal scroll bar automatically appears to enable users to scroll columns
in and out of view. For discussion purposes, we shall distinguish between the following:
• A line in a grid is a single physical row of cells displayed in the grid. Do not confuse this with a
line of text inside a grid cell; depending upon the settings of the RowHeight and WrapText
properties, data in a grid cell may be displayed in multiple lines of text.
• A row in a grid is used to display a single record. A row may contain multiple lines or multiple
physical rows.
The MultipleLines property of the grid controls how records are displayed. The default value is 0 -
Disabled, which means that a single record or row cannot span multiple lines. If necessary, the end user
can operate the horizontal scroll bar to view all of the columns within a row. This is how the grid
normally displays data.
However, if the MultipleLines property is set to 1 - Variable or 2 - Fixed, then a single record may span
multiple lines. This feature enables the end user to view simultaneously all of the columns (fields) of a
record within the width of the grid without scrolling horizontally, as in the following figure:

When the MultipleLines property is set to a value other than 0 - Disabled, the horizontal scroll bar will be
hidden (if one is present), and the grid will automatically span or wrap the columns to multiple lines so
that all columns will be visible within the width of the grid. If the resulting column layout is not to your
 Alternating Row Colors · 259

liking, you can adjust it at either design time or run time by changing the widths and orders of the
columns.
The difference between the settings 1 - Variable and 2 - Fixed comes into play when the width of a column
or the grid itself is changed. The former setting readjusts column breaks if necessary; the latter setting
preserves existing column breaks.
NOTE: At design time, if the ScrollBars property is set to 4 - Automatic, and the MultipleLines property
is enabled, a vertical scroll bar appears even though no data is displayed. This is done so that you can
take the width of the scroll bar into account when adjusting columns at design time.

Implications of multiple-line mode

Existing row-related properties, methods, and events fit well with the earlier definitions of records, rows,
and lines (with two exceptions to be described later). For example:
• The VisibleRows property returns the number of visible rows or records displayed on the grid—
not the number of visible lines. If a row spans 2 lines, and the VisibleRows property is 5, then
there are 10 visible lines displayed on the grid.
• The RowTop method accepts a row number argument ranging from 0 to VisibleRows - 1. If a
row spans 2 lines, then RowTop(2) returns the position of the top of the third displayed row (that
is, the fifth displayed line).
• The RowResize event will be fired whenever a row is resized by the user at run time. In fact, at
the record selector column, only row divider boundaries are displayed; thus, the user can only
resize rows, not lines.
Other row-related properties, methods, and events can be interpreted similarly. There are two exceptions:
1. The first is the RowHeight property. The RowHeight property returns the height of a cell or a
line, not the height of a row. Changing this property would break users' existing code, so we
decided to keep this property the same.
2. The second is more of a limitation than an exception. Currently the dividers between rows and
lines are the same. When you change the RowDividerStyle property, all dividers between rows
and lines change to the same style. That is, you cannot have different dividers for rows and for
lines.

Alternating Row Colors

You can often improve the readability of the display by alternating the background colors of adjacent
rows. When you set the AlternatingRowStyle property to True, the grid displays odd-numbered rows
(the first displayed row is 1) using the built-in style OddRow, and even-numbered rows using the built-in
style EvenRow.
260 · Customizing the Grid's Appearance

Tutorial 12 (page 54) demonstrates how to change the default alternating colors at design time.

Horizontal and Vertical Alignment

Use the Alignment property of the Column object to control the horizontal placement of cell text within a
column. The allowable values for this property are as follows:
0 - Left
1 - Right
2 - Center
3 - General
The setting 3 - General, which is the default for data cells, indicates that the alignment should be based
upon the underlying data type. For example, strings are left-aligned, while numbers are right-aligned.
Use the VerticalAlignment member of the Style property to control the vertical placement of text within
the cells of a grid, split, or column. The allowable values for this property are as follows:
0 - Top
1 - Bottom
2 - Vertical Center
For data cells, the default value is 0 - Top. For static grid elements such as caption bars, column headers,
and column footers, the default value is 2 - Vertical Center. See the section Named style defaults (page 308)
to learn how the default values are derived.
The following grid depicts all possible combinations of the Alignment and VerticalAlignment properties
(the general setting is omitted because it is ultimately rendered as left, right, or center).

The Alignment and VerticalAlignment properties are tightly integrated with the concept of styles. For
more information, see How to Use Styles (page 307).
 Window Animation · 261

Window Animation
You can enhance the behavior of TDBGrid control's built-in combo box, the TDBDropDown control, and
the CellTips window with animation properties.
For a TDBGrid control, the AnimateWindow property controls the style of animation when the user
opens and closes its drop-down combo (either a built-in combo box or a separate TDBDropDown
control). To enable animation, set the AnimateWindow property to a value other than 0 - NoAnimate.
The AnimateWindow property also controls the animation effects of the CellTips window when the
AnimateWindow property has been set to a value other than 0 - No animation.
Use the AnimateWindowTime property to control the duration of the animation, the
AnimateWindowDirection property to control the direction of the animation effect, and the
AnimateWindowClose property for additional control over the behavior of the animation when closing
the drop-down combo or cell tips.
NOTE: These properties have a system requirement of Windows 98 or NT 5.0, or higher.
 Text Formatting · 263

Data Presentation Techniques

This chapter explains how to display cell data in a variety of textual and graphical formats. To learn how
to customize the behavior of cell editing in True DBGrid, see Cell Editing Techniques (page 333).

Text Formatting
In many cases, the raw numeric data that True DBGrid receives from its data source is not suitable for
end-user display. For example, date fields may need to be converted to a specific international format;
currency fields may contain too many insignificant digits after the decimal point. Therefore, True DBGrid
provides access to the intrinsic formatting of Visual Basic on a per-column basis by means of the
NumberFormat property.
For cases where Visual Basic's formatting is inadequate, or for other development environments such as
Visual C++, True DBGrid provides an event, FormatText, that enables your application to override the
default formatting on a per-column basis.

Using Visual Basic's built-in formatting

True DBGrid supports a variety of data formatting options through the Column object's NumberFormat
property, which provides the same functionality as Visual Basic's Format$ function. For example, to
display all date values within a column according to the form 26-Apr-97, you would use the Medium Date
setting:
TDBGrid1.Columns("HireDate").NumberFormat = "Medium Date"
Note that if you change the NumberFormat property of a column at run time, you do not need to refresh
the display, as True DBGrid handles this automatically.
At design time, you can set the NumberFormat property using the Columns property page. For numeric
data, the following predefined options are available:
Standard Display number with thousands separator, at least one digit to the left and two
digits to the right of the decimal separator.
General Number Display number as is, with no thousand separators.
Currency Display number with thousand separator, if appropriate; display two digits to the
right of the decimal separator. Note that output is based on system locale
settings.
Percent Display number multiplied by 100 with a percent sign (%) appended to the right;
always display two digits to the right of the decimal separator.
Fixed Display at least one digit to the left and two digits to the right of the decimal
separator.
Scientific Use standard scientific notation.
Yes/No Display No if number is 0; otherwise, display Yes.
True/False Display False if number is 0; otherwise, display True.
On/Off Display Off if number is 0; otherwise, display On.
0% Display number multiplied by 100, then rounded to the nearest integer, with a
percent sign (%) appended to the right.
264 · Data Presentation Techniques

0.00% Same as Percent.

For date and time data, the following predefined options are available:
General Date Display a date and/or time. For real numbers, display a date and time (for
example, 4/3/93 05:34 PM); if there is no fractional part, display only a date (for
example, 4/3/93); if there is no integer part, display only a time (for example,
05:34 PM). Date display is determined by your system settings.
Long Date Display a date using your system's long date format.
Medium Date Display a date using the medium date format appropriate for the language
version of Visual Basic.
Short Date Display a date using your system's short date format.
Long Time Display a time using your system's long time format: includes hours, minutes,
seconds.
Medium Time Display a time in 12-hour format using hours and minutes and the AM/PM
designator.
Short Time Display a time using the 24-hour format (for example, 17:45).

Input validation with built-in formatting

It is important to note that the NumberFormat property affects only the display of data in the grid. Unless
you also specify a value for the EditMask property, True DBGrid does not enforce an input template, and
the user is free to type anything into the formatted cell. When moving to another cell, the grid will
reasonably interpret the user's input value, update to the database (if necessary), and redisplay the data
according to the NumberFormat setting.
For example, if Medium Date formatting is in effect for a column, a date of Saturday, April 25, 1998, 12:00:00
AM will be displayed as 25-Apr-98 with the day of the week and time ignored. If a user enters July and
moves to another row, the grid cannot reasonably interpret the input date value and a trappable error
will occur. If the user enters oct 5 or 10/5, the grid will interpret the entered date as October 5, 1998 (that is,
the current year is assumed). If the database update is successful, the entered date will be redisplayed as
05-Oct-98, since Medium Date formatting is in effect.

Formatting with an input mask

Since it is common for the input and display formats to be the same, the NumberFormat property has an
Edit Mask option (note the space between words). If you select this option, then the EditMask property
setting will be used for both data input and display. However, the input and display formats need not be
the same, so you are free to select a NumberFormat option that differs from the EditMask property.
For example, the following code applies a phone number template to a column for both display and
editing:
With TDBGrid1.Columns("Phone")
.EditMask = "(###) ###-####"
.NumberFormat = "Edit Mask"
End With
For more information on how to specify a data input mask, see Input Masking (page 337).

Formatting with a custom event handler

On occasion, you may find that the Visual Basic formatting options do not suit your particular needs. Or,
you may be using True DBGrid in a development environment that does not support Visual Basic
 Automatic Data Translation with ValueItems · 265

formatting, such as Visual C++. In these cases, the FormatText Event option can be specified for the
NumberFormat property. Choosing this option for a column will cause the FormatText event to fire each
time data is about to be displayed in that column. The event allows you to reformat, translate, indent, or
do anything you want to the data just prior to display:
Private Sub TDBGrid1_FormatText(ByVal ColIndex As Integer, _
Value As Variant, Bookmark As Variant)
ColIndex contains the column number of the grid to be reformatted. Value contains the current value of the
data and also serves as a placeholder for the formatted display value. For example, suppose the first
column contains numeric values from 1 to 30, and you wish to display the data as Roman numerals:
Private Sub TDBGrid1_FormatText(ByVal ColIndex As Integer, _
Value As Variant, Bookmark As Variant)

Dim result As String

If ColIndex = 0 Then
' Determine how many X's
While Value >= 10
result = result & "X"
Value = Value - 10
Wend
' Append "digits" 1-9
Select Case Value
Case 1
result = result & "I"
Case 2
result = result & "II"
Case 3
result = result & "III"
Case 4
result = result & "IV"
Case 5
result = result & "V"
Case 6
result = result & "VI"
Case 7
result = result & "VII"
Case 8
result = result & "VIII"
Case 9
result = result & "IX"
End Select
' Change the actual format
Value = result
End If
End Sub
Since the FormatText event is not restricted to a particular development environment, you can always
use it to gain full control over the textual content of any value displayed in the grid.

Automatic Data Translation with ValueItems

Although you can use the FormatText event to map data values into more descriptive display values,
True DBGrid also provides a mechanism for performing such data translations automatically without
code. Through the use of the ValueItems collection, you can specify alternate text or even pictures to be
displayed in place of the underlying data values.
266 · Data Presentation Techniques

This feature is ideally suited for displaying numeric codes or cryptic abbreviations in a form that makes
sense to end users. For example, country codes can be rendered as proper names or even as pictures of
their respective flags. Or, the numbers 0, 1, and 2 may be displayed as Yes, No, and Maybe. Either the
actual values (0, 1, 2) or the translated values (Yes, No, Maybe) may be displayed as radio buttons in a
cell or in a drop-down combo box.

What are ValueItems?

A ValueItem object describes the association between an underlying data value and its visual
representation. It supports only two properties: Value, the underlying data value, and DisplayValue, its
visual representation. Both properties are of type Variant.
A ValueItems collection contains zero or more ValueItem objects. Each Column object owns one
ValueItems collection, which is initially empty.
At design time, the Values property page can be used to build the ValueItems collection for a column.
Tutorial 7 (page 42) and Tutorial 10 (page 49) provide step-by-step instructions for using the Values
property page.
At run time, you can manipulate the ValueItems collection as you would any other True DBGrid or
Visual Basic collection.

Specifying text-to-text translations

Consider the following example, in which the Country field is represented by a short character code.

To display the character codes as proper names, you can use the column's ValueItems collection to
specify automatic data translations. At design time, this is done with the Values property page.
 Automatic Data Translation with ValueItems · 267

The Values property page enables you to specify data translations on a per-column basis. To construct a
list of data translations for an individual column, do the following:
1. Use the Column combo box to select the column for which automatic data translation is to be
performed.
2. Select the Translate check box. This enables automatic data translation and causes the
DisplayValue column to appear in the property page grid. If the Translate check box is not
selected, you will only be able to enter items in the Value column of the property page grid.
3. Enter as many Value/DisplayValue pairs as necessary. Use the Append or Insert buttons to
cause a new data entry row to appear.
4. Select OK or Apply to commit the changes.
When the program is run, Country field values that match an item in the Value column appear as the
corresponding DisplayValue entry. For example, CAN becomes Canada, UK becomes United Kingdom,
and so forth.

Note that the underlying database is not affected; only the presentation of the data value is different. The
same effect can be achieved in code as follows:
Dim Item As New TrueDBGrid80.ValueItem

With TDBGrid1.Columns("Country").ValueItems
Item.Value = "CAN"
268 · Data Presentation Techniques

Item.DisplayValue = "Canada"
.Add Item
Item.Value = "UK"
Item.DisplayValue = "United Kingdom"
.Add Item
Item.Value = "USA"
Item.DisplayValue = "United States"
.Add Item
Item.Value = "JPN"
Item.DisplayValue = "Japan"
.Add Item
Item.Value = "AUS"
Item.DisplayValue = "Australia"
.Add Item
.Translate = True
End With

Specifying text-to-picture translations

The same techniques used to specify text-to-text translations can also be used for text-to-picture
translations. Within the Values property page, instead of typing a string into the DisplayValue column,
you can use the Picture button to select a bitmap to be used for data translations.

To make the Picture button available, move the current cell marquee to the DisplayValue column. Note
that the Translate check box must also be selected. Depending upon the height of the bitmaps, you may
need to increase the value of the RowHeight property on the General property page. If you do so, you
may also want to change the VerticalAlignment member of the grid's Style property to 2 - Vertical Center.
This ensures that the bitmaps (as well as textual data in other columns) are centered vertically within grid
cells instead of being anchored at the top.
When the program is run, Country field values that match an item in the Value column appear as the
corresponding DisplayValue picture.
 Automatic Data Translation with ValueItems · 269

As with textual translations, the underlying database is not affected; only the presentation of the data
value is different. The same effect can be achieved in code as follows:
Dim Item As New TrueDBGrid80.ValueItem

With TDBGrid1.Columns("Country").ValueItems
Item.Value = "CAN"
Item.DisplayValue = LoadPicture("canada.bmp")
.Add Item
Item.Value = "UK"
Item.DisplayValue = LoadPicture("uk.bmp")
.Add Item
Item.Value = "USA"
Item.DisplayValue = LoadPicture("usa.bmp")
.Add Item
Item.Value = "JPN"
Item.DisplayValue = LoadPicture("japan.bmp")
.Add Item
Item.Value = "AUS"
Item.DisplayValue = LoadPicture("australia.bmp")
.Add Item
.Translate = True
End With

Displaying both text and pictures in a cell

Once you have configured the ValueItems collection to perform text-to-picture translations for a column,
you can cause both the Value string and the DisplayValue bitmap to appear within the same cell by
selecting the AnnotatePicture check box on the Values property page. Or, in code:
With TDBGrid1.Columns("Country").ValueItems
.AnnotatePicture = True
End With
The horizontal placement of the bitmap with respect to the cell text is determined by the Alignment and
ForegroundPicturePosition properties of the column's Style object. In the following example, Alignment
is set to 3 - General. Since the Country column represents a string field, the cell text is left-aligned.
However, since the ForegroundPicturePosition property is set to the default value of 0 - Left, the bitmap
is placed at the left edge of the cell, and the cell text is left-aligned in the remaining space.
270 · Data Presentation Techniques

However, if you change the ForegroundPicturePosition property to 1 - Right, then the cell text is left-
aligned as usual, but the bitmap is right-aligned.

To place the cell text below the bitmap while centering both items, set the Alignment property to 2 -
Center and the ForegroundPicturePosition property to 4 - Top of Text.

NOTE: For an illustration of all possible combinations of the Alignment and ForegroundPicturePosition
properties, see Displaying foreground pictures (page 329).
When editing, the editor uses all space available in the text portion of the cell. When the Presentation
property of the ValueItems collection is set to one of the combo box options, the bitmap will not change
until editing is completed.
Note that in the preceding examples, the text is displayed as it is stored in the database without
formatting. But what if you want to display both a picture and formatted text? Since the ValueItem object
 Automatic Data Translation with ValueItems · 271

can only accommodate one translation, you cannot accomplish this with ValueItems alone. However,
you can use the FormatText event to translate the text, then use the ValueItems collection to associate the
translated text (not the underlying data value) with a picture:
TDBGrid1.Columns("Country").NumberFormat = "FormatText Event"
In this example, the NumberFormat property is set to a special value that causes the FormatText event to
fire:
Private Sub TDBGrid1_FormatText(ByVal ColIndex As Integer, _
Value As Variant, Bookmark As Variant)
Select Case Value
Case "CAN"
Value = "Canada"
Case "UK"
Value = "United Kingdom"
Case "USA"
Value = "United States"
Case "JPN"
Value = "Japan"
Case "AUS"
Value = "Australia"
End Select
End Sub
Since the FormatText event now translates the country codes stored in the database into actual names for
display, the Value property of each member of the ValueItems collection must be changed accordingly.
The following figure depicts the updated Values property page (only the entries in the Value column are
different).

Assuming that the Alignment and ForegroundPicturePosition properties are set as in the previous
example, the end result is that the underlying data is displayed as both descriptive text and a picture.
272 · Data Presentation Techniques

NOTE: DisplayValue pictures are ideally suited for translating status codes or other fields where the
number of allowable values is relatively small. If you need a more generalized picture display mechanism
than the ValueItems collection offers, you can use the ForegroundPicture property in conjunction with
the FetchCellStyle event to display arbitrary pictures on a per-cell basis. For more information, see
Displaying foreground pictures (page 329).

Displaying boolean values as check boxes

You can also use the ValueItems collection to represent boolean values as in-cell check boxes. Prior to
version 6.0, you had to define two ValueItem objects (representing the underlying values 0 and -1) and
assign an appropriate DisplayValue picture to each one. However, in version 6.0, you can achieve the
same effect without defining any ValueItem objects—just set the Presentation property to 4 - Check Box.
 Automatic Data Translation with ValueItems · 273

Note that you do not need to select the Translate check box to enable automatic data translation; nor do
you need to select the CycleOnClick check box to enable end users to toggle the value of a cell by clicking
it. The following figure shows a typical check box display.

NOTE: If you want to use different check box bitmaps, you can still define a two-state ValueItems
collection as described earlier. Set the Presentation property to 0 - Normal, and set the Translate and
CycleOnClick properties to True.

Displaying allowable values as radio buttons

If the number of allowable values for a column is relatively small, you may want to consider a radio
button presentation. At design time, go to the Values property page and set the Presentation property to
1 - Radio Button. Or, in code:
With TDBGrid1.Columns("Country").ValueItems
.Presentation = dbgRadioButton
End With
If necessary, adjust the Width property of the column and the RowHeight property of the grid to
accommodate all of the items.

For a given cell, if the underlying data does not match any of the available values, none of the radio
buttons will be selected for that cell. However, you can provide a default ValueItem object that will be
selected instead.
274 · Data Presentation Techniques

In this example, the last ValueItem has an empty Value property so that any cells where Country = ""
will be displayed as Other. Also note that the entire last row in the property page grid is selected. This
was done to mark the last ValueItem as the default, which means that Country fields that do not match
any of the items will also be displayed as Other.
Selecting a row in the Values property page is equivalent to setting the DefaultItem property of the
ValueItems collection at run time:
With TDBGrid1.Columns("Country").ValueItems
.DefaultItem = 5
End With
In this example, 5 is the zero-based index of the default item.

Context-sensitive Help with CellTips

In many Windows applications, when the user points to a toolbar button and leaves the mouse at rest for
a short time, a ToolTip window appears with the name of the associated command. You can provide
similar context-sensitive help for your users with the CellTips property of True DBGrid.
The CellTips property determines whether the grid displays a pop-up text window when the cursor is
idle. By default, this property is set to 0 - None, and cell tips are not displayed.
If the CellTips property is set to either 1 - Anchored or 2 - Floating, the FetchCellTips event will be fired
whenever the grid has focus and the cursor is idle over a grid cell, record selector, column header,
column footer, split header, or grid caption. The event will not fire if the cursor is over the scroll bars.
The setting 1 - Anchored aligns the cell tip window with either the left or right edge of the cell. The left
edge is favored, but the right edge will be used if necessary in order to display as much text as possible.
 Context-sensitive Help with CellTips · 275

The setting 2 - Floating displays the cell tip window below the cursor, if possible.

If you do not provide a handler for the FetchCellTips event, and the cursor is over a grid cell, the default
behavior is to display a text box containing the cell's contents (up to 256 characters). This enables the user
to peruse the contents of a cell even if it is not big enough to be displayed in its entirety. You can also
program the FetchCellTips event to override the default cell text display in order to provide users with
context-sensitive help.
A common application of the FetchCellTips event is to display the contents of an invisible column that
provides additional information about the row being pointed to, as in the following example:
' General Declarations
Dim DescCol As TrueDBGrid80.Column
Private Sub Form_Load()
Set DescCol = TDBGrid1.Columns("Description")
End Sub
Private Sub TDBGrid1_FetchCellTips( _
ByVal SplitIndex As Integer, _
ByVal ColIndex As Integer, _
ByVal RowIndex As Long, _
CellTip As String, _
ByVal FullyDisplayed As Boolean, _
ByVal TipStyle As TrueDBGrid80.StyleDisp)
CellTip = DescCol.CellText(TDBGrid1.RowBookmark(RowIndex))
End Sub
You can use the CellTipsDelay property to control the amount of time that must elapse before the cell tip
window is displayed.
You can use the CellTipsWidth property to control the width of the cell tip window.
You can use the AnimateWindow property for additional control over the behavior of the cell tip
window as it opens and closes. The AnimateWindowTime property controls how long it takes for the
276 · Data Presentation Techniques

cell tip window to open and close, the AnimateWindowDirection property controls the direction in
which the cell tip window opens, and the AnimateWindowClose property controls the way the animated
cell tip window closes.
See Window Animation (page 261) for more information.

Scroll Tracking and ScrollTips

If the ScrollTrack property is set to True, moving the scrollbar thumb causes vertical scrolling of the
grid's display. By default, this property is False, and no scrolling occurs until the thumb is released.
If the ScrollTips property is set to True, moving the scrollbar thumb causes the FetchScrollTips event to
fire. You can use this event to track the position of the scroll bar on a record by record basis. You can also
use this event to present the user with useful information relating to the current record or recordset.
When used in tandem, the ScrollTrack and ScrollTips properties provide users with visual feedback
when scrolling through large recordsets.

Data-sensitive Cell Merging

If the underlying grid data is sorted, you may be able to improve the readability of the display by
grouping adjacent like-valued cells within the sorted column(s). The Merge property of the Column
object controls whether its data cells are grouped in this manner to form a single non-editable cell. By
default, this property is False, and each physical row within a column displays a data value, if any.
Consider the following grid, which is sorted on the Country field.
 Data-sensitive Cell Merging · 277

If data-sensitive cell merging is enabled for the Country column at run time, then its cells are grouped
according to their contents:
TDBGrid1.Columns("Country").Merge = True
Executing this statement produces the following display. Note that when the current cell is in the
Country column, the marquee spans all like-valued rows and takes on the appearance of a dotted
rectangle, regardless of the setting of the MarqueeStyle property. The behavior of the marquee in other
columns is not affected, however.

If you have specified a design-time layout, you can achieve the same effect by setting the Merge property
of the desired Column object within the Splits property page.
If the Merge property is True for a column, then none of its data cells can be edited, even if all rows
contain unique values. The only exception to this is the AddNew row. However, once the new row is
added to the underlying database, then its data will also be uneditable within the merged column(s).
You can use the Alignment and VerticalAlignment properties of the column's Style object to center the
data within the merged cell, as in the following figure.

On the Splits property page, you can access these properties by expanding the Style property node at the
same level of the tree as the Merge property. Or, in code:
With TDBGrid1.Columns("Country").Style
278 · Data Presentation Techniques

.Alignment = dbgCenter
.VerticalAlignment = dbgVertCenter
End With
NOTE: Merged cells are not restricted to displaying text. You can also display bitmaps within merged
cells by populating the ValueItems collection as described earlier in Specifying text-to-picture
translations (page 268. )The section Applying Pictures to Grid Elements (page 326) describes a more
flexible method for displaying in-cell graphics using Style objects.

Outlook-Style Grouping
The OLE DB version of True DBGrid includes a feature called "Outlook-Style Grouping." The purpose of
this feature is to allow users to dynamically configure fixed, nonscrolling columns on the left side of the
grid as in Microsoft Outlook. When in Group mode, a "grouping area" is added to the top of the grid,
providing an intuitive interface for specifying column groups. In code, this feature is supported by the
GroupColumns collection, which contains the columns that have been moved to the grouping area; it is
similar to the Columns collection.
The grouping area is created when DataView is set to 2 - Group. When AllowColMove is set to True, the
grid will support the ability to move one or more columns into this area. Users can do this by selecting a
single column and dragging its header into the grouping area. This action can also be performed in code
at run time by invoking the Add method of the GroupColumns collection. When a column is first added
to the grouping area, a new split is created on the left side of the grid. Similarly, when the last column is
removed from the grouping area, the (now empty) split is deleted.
When a column is added to the grouping area, either in code or by user interaction, its Merge property is
implicitly set to True. Therefore, if adjacent fields are identical in a grouped column, those fields are
rendered as a single non-editable cell, as shown in the following illustration.

It is important to note that the act of moving columns to or from the grouping area does not sort the
underlying data source; it simply provides a convenient way to manipulate a split containing
nonscrolling columns. Therefore, if you want a grouped column to appear in sorted order, you must sort
it explicitly in code. Typically, this is done in the GroupColMove event, which is fired before a column is
moved to or from the grouping area. You can also use the GroupHeadClick event, which is fired when a
column header is clicked within the grouping area.
 Hierarchical Data Display · 279

To manipulate the grouping area in code, use the GroupColumns property to access the collection of
grouped columns. Like the Columns collection, the GroupColumns collection supports Add, Item, and
Remove methods, as well as a Count property. However, since the GroupColumns collection serves as a
placeholder for existing grid columns, the semantics of its Add and Remove methods are different.
The Add method moves an existing column to the grouping area; it does not create a new column in the
grid. Similarly, the Remove method removes a column from the grouping area and returns it to its
original position within the grid; it does not delete the column altogether. Also, the Remove method
implicitly restores the previous value of the Merge property of the affected column.
Use the GroupByCaption property to add descriptive or directional text to the grouping area, which will
be displayed when no columns are present there.
See Tutorial 25 (page 97) Outlook-Style Grouping for more information.

Hierarchical Data Display

The OLE DB version of True DBGrid now supports the ability to display hierarchical data. Hierarchical
data generally refers to data that is stored in multiple relational tables, where a master (or "parent") table
is linked by keyed fields to detail (or "child") tables. The hierarchical display gives you the ability to
present the master data to your users, such that the related detail data can be viewed in the same grid
with a single mouse click.
When the grid is bound to a master-detail data source, you can display related groups of hierarchical data
by using bands. A band is a virtual representation of a hierarchical recordset, not the data itself. A band is
created for each level in a hierarchical recordset, and may consist of entire tables or a just a few selected
fields. At run time, users can expand and collapse bands using a TreeView-like interface.
To use this feature, the DataMode property must be set to 0 – Bound, and the DataView property must be
set to 1 – Hierarchical. The grid control must be bound to a hierarchical recordset. One way to do this is to
use the DataSource property and/or the DataMember property (if you are binding to a Data
Environment created with the Visual Basic Data View window). Another way is to create an ODBC Data
Source, as described in Tutorial 24 (page 91).
The following example illustrates the hierarchical relationships in a master-detail data source named
DataEnvironment1. There are three recordsets, or Bands in this example. Customers is the master band
(Band 0), whose fields will be displayed in the grid first. Relationships between Customers and Orders
(Band 1), and between Orders and Order_Details (Band 2) enable you to create a nested display of
detailed data for your users to expand and collapse as needed. Each Customers record is joined to the
Orders records by a relation defined on the CustomerID fields. Orders are joined to the Order_Detail data
by a relation defined on the OrderID fields.
Note that the Customers and Orders recordsets contain more fields than the ones shown; an SQL
statement was used to select the fields of interest.
280 · Data Presentation Techniques

At run time, the grid displays read-only data. The next figure illustrates the initial display of
DataEnvironment1. The data from the master recordset (Customers) is displayed first, and the fields from
the detail recordset bands appear to the right. The detail recordset fields initially contain no data,
however. An expand icon ("+") at the left edge of a record indicates the presence of hierarchical data.
Note that in this example, only one record, CustomerID FISSA, has no detail records.

When the user clicks an expand icon, it changes to a collapse icon ("–") and the next band (Orders)
expands to show the detail records for the clicked row. Note that the Customer ID field of the Orders
table also contains expand icons, which indicate the presence of an additional hierarchical level as shown
in the next figure. Users can expand each Orders record to display the detailed order information held in
Order_Details. The grid can therefore display detailed order information for each customer in a single
view.
 Dropdown Hierarchical Data Display · 281

In this example, if a user clicks the collapse icon in the CustomerID field (CONSH), the records held in
the Order_Details fields collapse (OrderID, ProductID, etc.), and are no longer visible. Also, the collapse
icon changes back to an expand icon. However, if the user clicks the collapse icon in the ContactName
field (Elizabeth Brown) first, the fields in the Order as well as the Order_Details band collapse, and the
grid will look the same as it did when it was first displayed.
NOTE: If the DataView property is set to its default value of 0 – Normal, the grid will only display flat
files; it will not support a hierarchical view. Even if the data source is a hierarchical recordset, the grid
will only display data from the master table. It will be necessary to distribute xadb8.ocx if you are setting
the True DBGrid’s DataView property to hierarchical.
The DataView property must be set at design time; you cannot change it at run time.
The following methods are provided for manipulating hierarchical grid displays:
GetBand Returns the band for a specified column index
CollapseBand Collapses all rows for the specified band
ExpandBand Expands all rows for the specified band
RowExpanded Returns True if the current row is expanded within the specified band
If the number of recordset levels in a master-detail data source is not known in advance, you can examine
the Bands property in code. Allowable band numbers range from 0 to Bands-1.
The following events enable your application to respond to hierarchical view operation initiated by the
user:
Collapse Fired when a band is collapsed by a user
Expand Fired when a band is expanded by a user

Dropdown Hierarchical Data Display

True DBGrid allows you to create a master/child relationship between data sources in such a way that
the child data records are available from within the master table with a click of the mouse. By simply
using the ChildGrid property to connect two grid controls and one line of code, you can create a fully
editable dropdown child that appears within the master table.
282 · Data Presentation Techniques

To do this, start by placing two Microsoft ADO Data Controls (ADODC) and two True DBGrid controls
(OLE) on a blank form.
Display the custom property pages for Adodc1. Click the General tab and select the Use Connection
String option. Click Build. Choose the Microsoft Jet 4.0 OLE DB Provider option. Click Next>>. Enter the
datasource name (C:\Program Files\ComponentOne Studio\Common\TDBG8DEMO.MDB) by pressing
the Ellipsis button (…) and locating the database. Test the connection to make sure it works. Press OK to
close the dialog window. Press the Apply button.
Choose the Recordsource tab. Set the Command Type to 2 – adCmdTable and the Table or Stored
Procedure Name to Composer. Press the OK button to accept the selections and close the properties page.
Set the DataSource property for TDBGrid1 to Adodc1. Right click on TDBGrid1 and choose Retrieve Fields
from the context menu.
Display the custom property pages for Adodc2. Click the General tab and select the Use Connection
String option. Click Build. Choose the Microsoft Jet 4.0 OLE DB Provider option. Click Next>>. Enter the
datasource name (C:\Program Files\ComponentOne Studio\Common\TDBG8DEMO.MDB) by pressing
the Ellipsis button (…) and locating the database. Test the connection to make sure it works. Press OK to
close the dialog window. Press the Apply button.
Choose the Recordsource tab. Set the Command Type to 2 – adCmdTable and the Table or Stored
Procedure Name to Opus. Press the OK button to accept the selections and close the properties page.
Set the DataSource property for TDBGrid2 to Adodc2. Right click on TDBGrid2 and choose Retrieve Fields
from the context menu.
Create the master/child relationship by entering TDBGrid2 into the ChildGrid property textbox of
TDBGrid1.
Next, open the Split tab of the TDBGrid2 property pages and change the ExtendRightColumn property
to True. We are doing this so that the right most column on TDBGrid2 extends to the end of the control
area. At this point, your form should look something like this:
 Dropdown Hierarchical Data Display · 283

The final step in constructing our program, is to insert the following code which will match the Last fields
in both the Composers and Opus tables:
Private Sub TDBGrid1_BeforeOpen(Cancel As Integer)
Adodc2.Recordset.Filter = "Last='" & _
Adodc1.Recordset("Last").Value & "'"
End Sub
Run the program and notice that TDBGrid2 is rendered invisible and there is an expand icon (“+”)
beside the left most cell in each row. As you can see, our master table, contains a list of composers
including vital statistics. Note, that as you scroll right, the expand icon remains in the left most cell at all
times.

By left clicking on any of the expand icons, our child table appears in a dropdown. In this case, the
dropdown lists the written works of the specific composer that you expanded.

NOTE: Though we created the example using code, it is also possible to perform the same functions by
using the VB Data Environment and parent/child commands.
The ChildGrid property and BeforeOpen event can be used in any data mode; they are not restricted to
OLE DB data sources. To create a hierarchical display automatically when bound to an OLE DB data
284 · Data Presentation Techniques

source, you can set the DataMode property to 1 - Hierarchical. For more information, see Hierarchical
Data Display (page 279.)

Form Data Display

In situations where you would like to display data one record at a time, you can set the DataView
property to 3 - Form. You can set this property at either design time or run time to display data in an
editable form similar to the one in the following illustration.

If you need to adjust the width of the data column area or the caption column area, you can change the
ViewColumnWidth and ViewColumnCaptionWidth properties to create the appropriate column
spacing.
NOTE: The DataView property is only supported by the OLE DB version of True DBGrid Pro.

Inverted Data Display

The inverted option of the DataView property inverts each row in your data into columns. In effect, the
leftmost column becomes the top row, the second column becomes the second row, and so forth. You can
use this display to maximize screen real estate for tables that have many columns. Set the DataView
property to 4 - Inverted to display an inverted grid as depicted in the following illustration.

If you need to adjust the width of the data column area or the caption column area, you can change the
ViewColumnWidth and ViewColumnCaptionWidth properties to create the appropriate column
spacing.
NOTE: The DataView property is only supported by the OLE DB version of True DBGrid Pro.
NOTE: Splits cannot be used when using the Inverted display option.
 Owner-drawn Cells · 285

Owner-drawn Cells
For cases where you need to perform complex per-cell customizations using Windows API calls, you can
draw directly to the grid's device context by writing a handler for the OwnerDrawCell event. This event
is fired as needed to display the contents of cells that have their OwnerDraw property set to True.

To implement the example depicted here, add the following type and constant declarations to a code
module:
Public Type RECT
Left As Long
Top As Long
Right As Long
Bottom As Long
End Type
' DrawText constants
Public Const DT_CENTER = &H1
Public Const DT_VCENTER = &H4
Public Const DT_SINGLELINE = &H20
' SetBkMode constants
Public Const OPAQUE = 2
Public Const TRANSPARENT = 1
Next, add the following Windows API declarations to the code module:
Declare Function CreateRectRgn Lib "gdi32" _
(ByVal X1 As Long, ByVal Y1 As Long, _
ByVal X2 As Long, ByVal Y2 As Long) As Long
Declare Function CreateEllipticRgn Lib "gdi32" _
(ByVal X1 As Long, ByVal Y1 As Long, _
ByVal X2 As Long, ByVal Y2 As Long) As Long
Declare Function FillRgn Lib "gdi32" _
(ByVal hdc As Long, ByVal hRgn As Long,
ByVal hbrush As Long) As Long
Declare Function CreateSolidBrush Lib "gdi32" _
(ByVal crColor As Long) As Long
Declare Function SelectObject Lib "gdi32" _
(ByVal hdc As Long, ByVal hObject As Long) As Long
Declare Function DrawText Lib "user32" Alias "DrawTextA" _
(ByVal hdc As Long, ByVal lpStr As String, _
ByVal nCount As Long, lpRect As RECT, _
ByVal wFormat As Long) As Long
286 · Data Presentation Techniques

Declare Function CreateFont Lib "gdi32" Alias "CreateFontA" _

(ByVal lHeight As Long, ByVal lWidth As Long, _
ByVal lEscapement As Long, ByVal lOrientation As Long, _
ByVal lWeight As Long, ByVal lItalic As Long, _
ByVal lUnderline As Long, ByVal lStrikeOut As Long, _
ByVal lCharSet As Long, ByVal lOutPrecision As Long, _
ByVal lClipPrecision As Long, ByVal lQuality As Long, _
ByVal lPitch As Long, ByVal FaceName As String) As Long
Declare Function DeleteObject Lib "gdi32" _
(ByVal hObject As Long) As Long
Declare Function SetTextColor Lib "gdi32" _
(ByVal hdc As Long, ByVal crColor As Long) As Long
Declare Function SetBkColor Lib "gdi32" _
(ByVal hdc As Long, ByVal crColor As Long) As Long
Declare Function SetBkMode Lib "gdi32" _
(ByVal hdc As Long, ByVal nBkMode As Long) As Long
Add the following to the general declarations section of the form containing the grid:
Option Explicit
Dim BackBrush As Long
Dim EllBrush As Long
Dim NewFont As Long
Add the following handlers for the Form_Load and Form_Unload events:
Private Sub Form_Load()
BackBrush = CreateSolidBrush(vbWhite)
EllBrush = CreateSolidBrush(vbRed)
NewFont = CreateFont(10, 0, 0, 0, 700, 0, 0, 0, 0, _
0, 0, 0, 0, "MS Sans Serif")
End Sub
Private Sub Form_Unload(Cancel As Integer)
DeleteObject BackBrush
DeleteObject EllBrush
DeleteObject NewFont
End Sub
The Form_Load event creates two brushes and a font and saves their handles for use in the
OwnerDrawCell event. The Form_Unload event cleans up by deleting the brush and font handles.
Finally, implement the OwnerDrawCell event as follows:
Private Sub TDBGrid1_OwnerDrawCell(ByVal hdc As Long, _
ByVal Bookmark As Variant, _
ByVal Split As Integer, ByVal Col As Integer, _
ByVal Left As Integer, ByVal Top As Integer, _
ByVal Right As Integer, ByVal Bottom As Integer, _
Done As Integer)
Dim BackRegion As Long, EllRegion As Long
Dim OldFgColor As Long, OldBkMode As Long, OldFont As Long
' Fill the interior of the cell using the white
' background brush created in the Form_Load event.
BackRegion = CreateRectRgn(Left, Top, Right, Bottom)
FillRgn hdc, BackRegion, BackBrush
DeleteObject BackRegion
 Owner-drawn Cells · 287

' Draw a solid red ellipse within the cell.

EllRegion = CreateEllipticRgn(Left + 2, Top + 2, _
Right - 2, Bottom - 2)
FillRgn hdc, EllRegion, EllBrush
DeleteObject EllRegion
' Set the draw mode, text color, and font, saving
' the old values for later. The font handle NewFont
' was created in the Form_Load event.
OldBkMode = SetBkMode(hdc, TRANSPARENT)
OldFgColor = SetTextColor(hdc, vbWhite)
OldFont = SelectObject(hdc, NewFont)
Dim R As RECT
R.Bottom = Bottom
R.Left = Left
R.Right = Right
R.Top = Top
' Draw the cell text in white, and center it both
' horizontally and vertically within the cell.
Dim S As String
S = TDBGrid1.Columns(Col - 1).CellValue(Bookmark)
DrawText hdc, S, Len(S), R, _
DT_CENTER + DT_VCENTER + DT_SINGLELINE
' Restore device context defaults changed earlier.

SelectObject hdc, OldFont

SetTextColor hdc, OldFgColor
SetBkMode hdc, OldBkMode
' Tell the grid that this event was handled.
Done = True
End Sub
There are several key points worth noting in this example:
• If you set the Done argument to True, the grid will not fill in the cell's background, nor will it
display cell text or graphics. Therefore, you are responsible for filling in the entire cell, even if
there is no data to display.
• The background and foreground colors of the device context passed in as the hdc argument are
not initialized. In other words, you must explicitly call the SetBkColor (Windows API) and
SetTextColor (Windows API) functions or create an appropriate background brush to use with a
function such as FillRgn (Windows API).
• The font of the device context passed in as the hdc argument is not initialized. In other words, you
must explicitly create a font using the CreateFont (Windows API) function (or otherwise obtain a
valid HFONT handle from a control), then select it into the device context using the SelectObject
(Windows API) function.
• Any change made to the device context, such as selecting a different font, should be restored
before exiting the event.
• Even a relatively simple example such as the one illustrated here requires a fair amount of
coding, so you should consider using background bitmaps instead of owner-drawn cells if
possible.
288 · Data Presentation Techniques

Filtering Data in Recordsets

In some cases, you might want to filter the underlying recordset by limiting the number of items in a
given field or fields. By using the FilterBar property, and entering the filter text appropriately, you can
reduce the number of field entries. When the FilterBar property of a TDBGrid control is set, a blank row
with a gray separator line appears directly above the uppermost data row in the grid.

To set the filter bar, perform the following steps:

1. Place a Microsoft ADO Data Control (OLEDB), a True DBGrid OLE control and a command
button on a new form.
2. Connect the ADODC to the C:\Program Files\ComponentOne
Studio\Common\TDBG8DEMO.MDB database table and set the RecordSource property to
Composers. Then connect the True DBGrid to this data control by choosing it in the DataSource
property.
3. Set the caption of Command1 to Clear Filter and change its name to cmdClearFilter.
4. Open the TDBGrid property pages and select the Splits tab. Set the FilterBar property to True.
5. Add the following code to cmdClearFilter:
Dim col As TrueOleDBGrid80.Column
Dim cols As TrueOleDBGrid80.Columns
Private Sub cmdClearFilter_Click()
'Clears filter from grid
For Each col In TDBGrid1.Columns
col.FilterText = ""
Next col
Adodc1.Recordset.Filter = adFilterNone
End Sub
Private Sub TDBGrid1_FilterChange()
'Gets called when an action is performed on the filter bar
On Error GoTo errHandler
Set cols = TDBGrid1.Columns
Dim c As Integer
c = TDBGrid1.col
TDBGrid1.HoldFields
Adodc1.Recordset.Filter = getFilter()
TDBGrid1.col = c
TDBGrid1.EditActive = True
Exit Sub
errHandler:
MsgBox Err.Source & ":" & vbCrLf & Err.Description
Call cmdClearFilter_Click
End Sub
 Filtering Data in Recordsets · 289

Private Function getFilter() As String

'Creates the SQL statement in adodc1.recordset.filter
'and only filters text currently. It must be modified to
'filter other data types.
Dim tmp As String
Dim n As Integer
For Each col In cols
If Trim(col.FilterText) <> "" Then
n = n + 1
If n > 1 Then
tmp = tmp & " AND "
End If
tmp = tmp & col.DataField & " LIKE '" & col.FilterText &
"*'"
End If
Next col
getFilter = tmp
End Function
Note the use of the FilterChange event to manipulate the underlying recordset. When you run the
program you will see a form similar to this one.

If you type a "B" into the filter bar cell located above the Last column, you will see that the underlying
recordset is limited to just composers whose last names start with the letter B as in the example below.
Had we extended the filter to "BR", the list of composers would have been reduced to only those whose
last names started with BR.
290 · Data Presentation Techniques

Next, type a "G" into the filter bar cell located above the Country column. You will see that the
underlying recordset is limited to just composers whose last names start with the letter B and who were
born in countries starting with the letter G, as in the following illustration.

Finally, since the SQL statement in this example was set up to handle text only, if you press the Clear
Filter button and then type in the filter box located below the Birth column, you get an error message
from the provider because the filter bar is set to filter only text. To filter dates or any other type of data,
you must alter the code.
 Filtering Data in Recordsets · 291

For more information, see Tutorial 29 (page 108).

 Referencing Splits and their Properties · 293

How to Use Splits

In True DBGrid, a split is similar to the split window features of products such as Microsoft Excel and
Word. You can use splits to present your data in multiple vertical panes. These vertical panes, or splits,
can display data in different colors and fonts. They can scroll as a unit or individually, and they can
display different sets of columns or the same set. You can also use splits to prevent one or more columns
from scrolling. Unlike other grid products, fixed (nonscrolling) columns in True DBGrid do not have to
be at the left edge of the grid, but can be at the right edge or anywhere in the middle. You can even have
multiple groups of fixed columns within a grid. Splits open up an endless variety of possibilities for
presenting data to users of your applications.
Whenever you use True DBGrid, you are always using a split. A grid always contains at least one split,
and the default values for the split properties are set so that you can ignore splits until you want to use
them. Therefore, you can skip this chapter if you do not need to create and manipulate more than one
split within a grid.
You create and manipulate splits by working with Split objects and the Splits collection. Since an
individual column can be visible in one split but hidden in another, each Split object maintains its own
Columns collection. This gives you complete control over the appearance of each split and the columns
they contain.

Referencing Splits and their Properties

A TDBGrid object initially contains a single split. If additional splits are created, you can determine or set
the current split (that is, the split that has received focus) using the grid's Split property:
' Read the zero-based index of the current split
Variable% = TDBGrid1.Split
' Set focus to the split with an index equal to Variable%
TDBGrid1.Split = Variable%
Each split in a grid is a different view of the same data source, and behaves just like an independent grid.
If you create additional splits without customizing any of the split properties, all splits will be identical
and each will behave very much like the original grid with one split.
Note that some properties, such as RecordSelectors and MarqueeStyle, are supported by both the
TDBGrid and Split objects. Three rules of thumb apply to properties that are common to a grid and its
splits:
1. When you set or get the property of a Split object, you are accessing a specific split, and other
splits in the same grid are not affected.
2. When you get the property of a TDBGrid object, you are accessing the same property within the
current split.
3. When you set the property of a TDBGrid object, you are setting the same property within all
splits.
To understand how these rules work in code, consider a grid with two splits, and assume that the current
split index is 1 (that is, the grid's Split property returns 1). If you want to determine which marquee style
is in use, the following statements are equivalent:
marquee% = TDBGrid1.MarqueeStyle
marquee% = TDBGrid1.Splits(1).MarqueeStyle
294 · How to Use Splits

marquee% = TDBGrid1.Splits(TDBGrid1.Split).MarqueeStyle
To change the marquee style to a solid cell border for all of the splits in the grid, you would use:
TDBGrid1.MarqueeStyle = dbgSolidCellBorder
Note that this statement is equivalent to:
TDBGrid1.Splits(0).MarqueeStyle = dbgSolidCellBorder
TDBGrid1.Splits(1).MarqueeStyle = dbgSolidCellBorder
Likewise, to set the marquee style of each split to a different value:
TDBGrid1.Splits(0).MarqueeStyle = dbgNoMarquee
TDBGrid1.Splits(1).MarqueeStyle = dbgFloatingEditor
These rules apply only to a TDBGrid object and its associated Split objects. No other object pairs possess
similar relationships.

Split properties common to TDBGrid

The following properties, which are supported by both Split and TDBGrid objects, adhere to the rules
described in the preceding section:
AllowColMove Enables interactive column movement
AllowColSelect Enables interactive column selection
AllowRowSelect Enables interactive row selection
AllowRowSizing Enables interactive row resizing
AlternatingRowStyle Controls whether even/odd row styles are applied to a split
AnchorRightColumn Controls horizontal scrolling when the last column is visible
BackColor Sets/returns the background color
CaptionStyle Controls the caption style for a split
Columns Returns a collection of column objects for a split
CurrentCellVisible Sets/returns modification status of the current cell
EditBackColor Sets/returns the editor background color
EditForeColor Sets/returns the editor foreground color
EditorStyle Controls the editor style for a split
EvenRowStyle Controls the row style for even numbered rows
ExtendRightColumn Sets/returns extended right column for a split
FetchRowStyle Controls whether the FetchRowStyle event will be fired
FirstRow Bookmark of row occupying first display line
Font Specifies the overall font for a split
FooterBackColor Sets/returns the footing background color
FooterFont Specifies the footing font for a split
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a split
ForeColor Sets/returns the foreground color
HeadBackColor Sets/returns the heading background color
 Referencing Splits and their Properties · 295

HeadFont Specifies the heading font for a split

HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a split
HighlightRowStyle Controls the marquee style when set to Highlight Row
HScrollHeight Returns the horizontal scroll bar height, if present
InactiveBackColor Sets/returns the inactive heading background color
InactiveForeColor Sets/returns the inactive heading foreground color
InactiveStyle Controls the inactive heading style for a split
LeftCol Returns the leftmost visible column
MarqueeStyle Sets/returns marquee style for a split
OddRowStyle Controls the row style for odd numbered rows
PartialRightColumn True if rightmost column can be clipped to edge of split
RecordSelectors Shows/hides selection panel at left border
ScrollBars Sets/returns scroll bar style for a split
SelectedBackColor Sets/returns the selected row background color
SelectedForeColor Sets/returns the selected row foreground color
SelectedStyle Controls the selected row and column style for an object
SelEndCol Sets/returns rightmost selected column
SelStartCol Sets/returns leftmost selected column
Style Controls the normal style for an object
VScrollWidth Returns the vertical scroll bar width, if present
NOTE: The Caption property is not included in this list, even though it is supported by both objects.
Since grids and splits maintain separate caption bars, setting the Caption property of the grid does not
apply the same string to each split caption.

Split-only properties not supported by TDBGrid

The following properties are supported by Split objects but not by TDBGrid. Therefore, to apply a value
to the entire grid, you need to explicitly set the value for each split individually.
AllowFocus Allows cells within a split to receive focus
AllowSizing Enables interactive resizing for a split
DividerStyle Divider style for right split border
Index Returns the ordinal index of a split
Locked True if data entry is prohibited for a split
ScrollGroup Used to synchronize vertical scrolling between splits
Size Sets/returns split width according to SizeMode
SizeMode Controls whether a split is scalable or fixed size
296 · How to Use Splits

Creating and Removing Splits

At design time, you can create and remove splits using the grid's visual editing menu. Please refer to
Visual Editing Mode (page 130) for details.
At run time, you can create and remove splits using the Splits collection's Add and Remove methods.
Each method takes a zero-based split index:
Dim S As TrueDBGrid80.Split
Set S = TDBGrid1.Splits.Add(0) ' Create a split with index 0
TDBGrid1.Splits.Remove 1 ' Remove the split with index 1
The new Splits(0) object is "cloned" from the old Splits(0) object. Both splits will have the same
property values after the Add method executes. The old Splits(0) becomes Splits(1), the old
Splits(1) becomes Splits(2), and so on.
You can determine the number of splits in a grid using the Splits collection's Count property:
' Set variable equal to the number of splits in TDBGrid1
variable = TDBGrid1.Splits.Count
You can iterate through all splits using the Count property, for example:
For n = 0 To TDBGrid1.Splits.Count - 1
Debug.Print TDBGrid1.Splits(n).Caption
Next n
Of course, a more efficient way to code this would be to use a For Each...Next loop:
Dim S As TrueDBGrid80.Split
For Each S In TDBGrid1.Splits
Debug.Print S.Caption
Next
The Count property is primarily used to append a new split to the end of the Splits collection, as follows:
Dim S As TrueDBGrid80.Split
Set S = TDBGrid1.Splits.Add(TDBGrid1.Splits.Count)
The new Split object will inherit all of its properties from the last object in the collection.

Working with Columns in Splits

Each split in a True DBGrid control maintains its own Columns collection. This provides tremendous
flexibility for controlling the look and behavior of individual splits. The grid is connected to a single data
source, so the splits just present different views of the same data. Therefore, the Columns collection in
each split contains the same number of columns and the columns are bound to the same data fields.
Note that some Column object properties, such as Caption and DataField, have the same value in each
split. These properties are said to be global. For example, given a grid with two splits, the following code
will always print the same values for a given column index n:
Debug.Print TDBGrid1.Splits(0).Columns(n).Caption
Debug.Print TDBGrid1.Splits(1).Columns(n).Caption
Debug.Print TDBGrid1.Columns(n).Caption
More importantly, if you set any of the global properties of a column within a particular split, that
property will be set to the same value for all splits. For example, the following code will append a column
to all splits (not just the first one) and bind the columns to the same database field (LastName).
Dim Cols As TrueDBGrid80.Columns
Set Cols = TDBGrid1.Splits(0).Columns
 Working with Columns in Splits · 297

' Append a column to the end of the Columns collection

Dim C As TrueDBGrid80.Column
Set C = Cols.Add(Cols.Count)
' Set the DataField property of the newly created column
C.DataField = "LastName"
However, the values of other Column object properties, such as Visible and BackColor, may vary from
split to split. These properties are said to be split-specific. For example, a column created at run time is not
visible by default. Thus, the LastName column created in the preceding example is invisible in all splits.
The following code makes it visible in the second split:
TDBGrid1.Splits(1).Columns("LastName").Visible = True
Since Visible is a split-specific property, the LastName column remains invisible in other splits.

Global properties and methods of Column object

The following Column object properties are global; that is, they always have the same value in each split:
ButtonPicture Sets/returns the bitmap used for the in-cell button
Caption Sets/returns column heading text
ColIndex Returns the ordinal position of a column
DataChanged Sets/returns modification status of a column in the current row
DataField Data table field name for a column
DataWidth Maximum number of characters available for column input
DefaultValue Default value for new column data
DropDown Sets the name of a TDBDropDown control for a column
EditMask Input mask string for a column
EditMaskRight Control whether the edit mask is applied from right to left
EditMaskUpdate Controls whether masked data is used for updates
ExternalEditor Sets the ActiveX input control for a column
FooterText Column footing text
NumberFormat Data formatting string for a column
Text Sets/returns displayed column text for the current cell
Top Returns top column border in container coordinates
Value Sets/returns underlying data value for the current row
ValueItems Contains a collection of ValueItems for a column

The following Column object methods are also global:

CellText Returns displayed text for any visible row
CellValue Returns underlying value for any visible row
Refetch Refetches column data from its data source
RefetchCell Refetches data for a specified cell within a column
Refresh Updates a column's screen display
298 · How to Use Splits

RefreshCell Updates the display for a specified cell within a column

Split-specific properties and methods of Column object

The following Column object properties are split-specific; that is, they may have different values across
splits:
Alignment Specifies horizontal text alignment
AllowFocus Controls whether a column can receive focus
AllowSizing Enables interactive resizing for a column
AutoDropDown True if a drop-down control opens when a character is typed
BackColor Sets/returns the background color
Button Controls whether a button appears within the current cell
ButtonAlways Controls when an in-cell button is displayed
ButtonFooter Controls whether a column footer acts like a standard button
ButtonHeader Controls whether a column header acts like a standard button
ButtonText Controls whether a cell is rendered as a button
CellTop Returns top column border, adjusted for multiple lines
ColIndex Returns the ordinal position of a column
DividerStyle Divider style for right column border
DropDownList Controls whether a TDBDropDown control acts like a list
EditBackColor Sets/returns the editor background color
EditForeColor Sets/returns the editor foreground color
EditorStyle Controls the editor style for a column
FetchStyle Controls whether the FetchCellStyle event fires for a column
Font Specifies the overall font for a column
FooterAlignment Specifies column footing alignment
FooterBackColor Sets/returns the footing background color
FooterDivider Controls display of dividing line in column footer
FooterFont Specifies the footing font for a column
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a column
ForeColor Sets/returns the foreground color
HeadAlignment Specifies column heading alignment
HeadBackColor Sets/returns the heading background color
HeaderDivider Controls display of dividing line in column header
HeadFont Specifies the heading font for a column
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a column
 Sizing and Scaling Splits · 299

Left Returns column left border in container coordinates

Locked True if data entry is prohibited for a column
Merge True if a column merges adjacent rows of like-valued cells
Order Sets/returns the display position of a column
OwnerDraw Controls whether the OwnerDrawCell event fires for a column
Style Controls the normal style for a column
Visible Shows/hides a column
Width Sets/returns column width in container coordinates
WrapText True if cell text is word wrapped

The following Column object methods are also split-specific:

AddCellStyle Adds a cell condition to a column
AddRegexCellStyle Adds a regular expression cell condition to a column
ClearCellStyle Removes a cell condition from a column
ClearRegexCellStyle Removes a regular expression cell condition from a column

Sizing and Scaling Splits

True DBGrid gives you full control over the size and scaling of individual splits. You can configure a split
to occupy an exact width, hold a fixed number of columns, or adjust its size proportionally in relation to
other splits. If you are just starting out with True DBGrid, you can use splits in a variety of ways without
having to master all of the details.
At run time, the actual size of a Split object depends upon its Size and SizeMode properties. The
SizeMode property specifies the unit of measurement; the Size property specifies the number of units.
True DBGrid supports three different sizing modes for splits, as determined by the setting of the
SizeMode property:
0 - Scalable Size denotes relative width in relation to other splits
1 - Exact Size specifies a fixed width in container coordinates
2 - Number of Columns Size specifies a fixed number of columns
In code, you can use the constants dbgScalable, dbgExact, and dbgNumberOfColumns to refer to
these settings.
A scalable split uses the value of its Size property to determine the percentage of space the split will
occupy. For any scalable split, the percentage is determined by dividing its Size value by the sum of the
Size values of all other scalable splits. Thus, you can consider the Size property of a scalable split to be
the numerator of a fraction, the denominator of which is the sum of the scalable split sizes. Scalable splits
compete for the space remaining after nonscalable splits have been allocated. By default, all splits are
scalable, so they compete for the entire grid display region. SizeMode is always 0 - Scalable when a grid
contains only one split.
An exact split uses the value of its Size property as its fixed width in container coordinates. Exact splits
will be truncated if they will not fit within the horizontal grid boundaries. This mode is not applicable
when a grid contains only one split.
300 · How to Use Splits

A fixed-column split uses the Size property to indicate the exact number of columns that should always
be displayed within the split. These splits automatically reconfigure the entire grid if the size of the
displayed columns changes (either by code or user interaction), or if columns in the split are scrolled
horizontally so that the widths of the displayed columns are different. This mode is primarily used to
create fixed columns that do not scroll horizontally. However, it can be used for a variety of other
purposes as well. This mode is not applicable when a grid contains only one split.
Note that when there is only one split (the grid's default behavior), the split spans the entire width of the
grid, the SizeMode property is always 0 - Scalable, and the Size property is always 1. Setting either of
these properties has no effect when there is only one split. If there are multiple splits, and you then
remove all but one, the SizeMode and Size properties of the remaining split automatically revert to 0 and
1, respectively.
By default, the SizeMode property for a newly created split is 0 - Scalable, and the Size property is set to
1. For example, if you create two additional splits with the following code:
Dim S As TrueDBGrid80.Split
Set S = TDBGrid1.Splits.Add(0) ' Create a Split at the left
Set S = TDBGrid1.Splits.Add(0) ' Create another
the resulting grid display will look like this.

Notice that each split occupies 1/3 of the total grid space. This is because there are three scalable splits,
and each split has a Size of 1. If you change the sizes of the splits to 1, 2, and 3, respectively:
TDBGrid1.Splits(0).Size = 1 ' Change relative size to 1
TDBGrid1.Splits(1).Size = 2 ' Change relative size to 2
TDBGrid1.Splits(2).Size = 3 ' Change relative size to 3
 Sizing and Scaling Splits · 301

the resulting grid display will look like this.

Notice the sum of the split sizes (1+2+3) is 6, so the size of each split is a fraction with the numerator
being the value of its Size property and a denominator of 6.
When a split's SizeMode is set to 1 - Exact, that split receives space before the other splits. This behavior
is somewhat more complex, but understanding how scalable splits work is helpful. For example, assume
that splits are set in the following way:
Split0.SizeMode = dbgScalable
Split0.Size = 1

Split1.SizeMode = dbgExact
Split1.Size = 2500

Split2.SizeMode = dbgScalable
Split2.Size = 2
After configuring the splits in this way, the resulting grid display will look like this.

The fixed-size split in the middle (Split1) is configured to exactly 2500 twips, and the remaining splits
compete for the space remaining in the grid. Since the remaining splits are both scalable splits, they
divide the remaining space among themselves according to the percentages calculated using their Size
property values. So, the leftmost split occupies 1/3 of the remaining space, and the rightmost split
occupies 2/3.
302 · How to Use Splits

Splits with SizeMode set to 2 - Number of Columns behave almost identically to exact splits, except their
size is determined by the width of an integral number of columns. The width, however, is dynamic, so
resizing the columns or scrolling so that different columns are in view will cause the entire grid to
reconfigure itself.
Avoid creating a grid with no scalable splits. Although True DBGrid handles this situation, it is difficult
to work with a grid configured in this way. For example, if no splits are scalable, all splits will have an
exact size, which may not fill the entire horizontal width of the grid. If the total width of the splits is too
short, True DBGrid displays a "null-zone" where there are no splits. If the total width of the splits is
wider than the grid, then True DBGrid will show only the separator lines for the splits that cannot be
shown.

Creating and Resizing Splits through User Interaction

You can always create and resize splits in code. However, you can also let your users create and resize
splits interactively by setting the AllowSizing property of a split to True. By default, the AllowSizing
property is False, and users are prevented from creating and resizing splits.
A typical grid with AllowSizing set to False is shown in the following figure. Notice that there is no split
box at the left edge of the horizontal scroll bar.

If you set the split's AllowSizing property to True:

TDBGrid1.Splits(0).AllowSizing = True
a split box will appear at the left edge of the horizontal scroll bar, and the user will be able to create new
splits at run time.

When the user points to the split box, the pointer will turn into a double vertical bar with a down arrow,
which the user can drag to the right to create a new split, as shown in the next figure.
 Creating and Resizing Splits through User Interaction · 303

The new split will inherit its properties from the original split. The SizeMode properties of both splits
will be automatically set to 0 - Scalable, regardless of the SizeMode of the original split. The Size
properties of both splits will be set to the correct ratio of the splits' sizes. The values of the Size properties
may end up being rather large. This is because True DBGrid needs to choose the least common
denominator for the total split size, and the user may drag the pointer to an arbitrary position.
Note that both splits' AllowSizing properties are now True, and the divider between them is a double
line, which indicates that the splits' sizes are now adjustable. If the user points to the split box between
the two splits, the pointer will turn into a double vertical bar with horizontal arrows. The user can drag
this pointer to the left or right to adjust the relative sizes of the splits.
If you set AllowSizing to False for either split, the user will no longer be able to adjust the split sizes.
Suppose that you disable sizing for the first split:
TDBGrid1.Splits(0).AllowSizing = False
The split box at the left edge of the horizontal scroll bar in the first split will disappear and the divider
between the two splits will turn into a solid line. This means that the user will no longer be able to create
a new split from the first split, or adjust the sizes of either split. However, since the split box at the left
edge of the second split still exists, the user can now create new splits by pointing to this split box and
dragging the pointer to the right.

To summarize:
• You can always create or resize splits in code, but the AllowSizing property controls whether
users can create or resize splits interactively at run time.
• The user can resize the relative sizes of two splits only if both splits' AllowSizing properties are
True. When the user completes a resize operation, the total size of the two splits remains
unchanged, but the SizeMode properties of both splits will automatically be set to 0 - Scalable
304 · How to Use Splits

regardless of their previous settings. The Size properties of the two splits will be set to reflect the
ratio of their new sizes.
• The user can create a new split by dragging the split box to the right, as long as both of the
following conditions are met. First, the AllowSizing property of the split to the right of the split
box must be True. Second, the AllowSizing property of the split to the left of the split box must
be False, or the split box must belong to the leftmost split. The total size of the new split and the
parent split will be equal to the original size of the parent split. The SizeMode properties of the
two splits will be automatically set to 0 - Scalable, and the Size properties of the two splits will be
set to reflect the correct ratio of their new sizes.

Vertical Scrolling and Split Groups

By default, the grid has only one split, with split index 0, and its ScrollBars property is set to 4 -
Automatic. That is, the horizontal or vertical scroll bar will appear as necessary depending upon the
column widths and the number of data rows available. The default split's ScrollGroup property is 1.
Splits having the same ScrollGroup property setting will scroll vertically together. When a new split is
created, it will inherit both the ScrollBars and ScrollGroup properties from the parent split. If all of the
splits belonging to the same ScrollGroup have their ScrollBars properties set to 4 - Automatic, then True
DBGrid will display the vertical scroll bar only at the rightmost split of the scroll group. Manipulating
this scroll bar will cause all splits in the same scroll group to scroll simultaneously.
For example, if you create two additional splits with the following code:
Dim S As TrueDBGrid80.Split
Set S = TDBGrid1.Splits.Add(0) ' Create a Split at the left
Set S = TDBGrid1.Splits.Add(0) ' Create another
the resulting grid display will look like this.

All three splits will have the same ScrollBars and ScrollGroup properties of 4 and 1, respectively.
However, only one vertical scroll bar will be displayed, within the rightmost split. When the user
operates this scroll bar, all three splits will scroll simultaneously.
You can change the ScrollGroup property of splits to create split groups that scroll independently. In the
preceding example, setting the ScrollGroup property of the middle split to 2 creates a new scroll group:
TDBGrid1.Splits(1).ScrollGroup = 2 ' Create a new scroll group
After this statement executes, scrolling the middle split will not disturb the others, as shown in the
following figure, in which a single row is selected.
 Horizontal Scrolling and Fixed Columns · 305

Note that the middle split now contains a vertical scroll bar. This scroll bar operates only on the middle
split, since it is the only one with its ScrollGroup property equal to 2. The vertical scroll bar in the
rightmost split now controls the leftmost and rightmost splits only. It no longer affects the middle split.
You can create as many split groups as necessary by setting the ScrollGroup properties of the splits to
different values. You can also explicitly control whether scroll bars will be displayed in a split by setting
its ScrollBars property.
A common application of this feature is to create two independent split groups so that users can compare
field values from different records by scrolling each split to view a different set of rows.

Horizontal Scrolling and Fixed Columns

Horizontal scrolling is independent for each split. Often, you need to prevent one or more columns from
scrolling horizontally so that they will always be in view. True DBGrid provides you with an easy way to
keep any number of columns from scrolling at any location within the grid (even in the middle!) by
setting a few split properties.
As an example, assume that you have a grid with three splits. The following code will "fix" columns 0 and
1 in the middle split:
' Hide all columns in Splits(1) except for columns 0 and 1
Dim Cols As TrueDBGrid80.Columns
Dim C As TrueDBGrid80.Column
Set Cols = TDBGrid1.Splits(1).Columns
For Each C In Cols
C.Visible = False
Next C
Cols(0).Visible = True
Cols(1).Visible = True

' Configure Splits(1) to display exactly two columns, and

' disable resizing
With TDBGrid1.Splits(1)
.SizeMode = dbgNumberOfColumns
.Size = 2
.AllowSizing = False
End With
Usually, if you keep columns 0 and 1 from scrolling in one split, you will want to make them invisible in
the other splits:
' Make columns 0 and 1 invisible in splits 0 and 2
Dim Cols As Columns
Set Cols = TDBGrid1.Splits(0).Columns
Cols(0).Visible = False
Cols(1).Visible = False
306 · How to Use Splits

Set Cols = TDBGrid1.Splits(2).Columns

Cols(0).Visible = False
Cols(1).Visible = False

Navigation across Splits

Navigation across splits is controlled by the grid's TabAcrossSplits property and each split's AllowFocus
property. Navigation across splits is best discussed with grid navigation as a whole. For more
information, please refer to Run Time Interaction (page 181).
 Built-in Named Styles · 307

How to Use Styles

True DBGrid uses a style model similar to that of Microsoft Word and Excel to simplify the task of
customizing a grid's appearance. A Style object is a combination of font, color, picture, and formatting
information comprising the following properties:
Alignment Specifies the horizontal text alignment
BackColor Controls the background color
BackgroundPicture Sets/returns a style's background picture
BackgroundPictureDrawMode Controls how a style's background picture is
displayed
BorderAppearance Controls the appearance (3D effects) of cell borders
BorderColor Specifies the color of cell borders
BorderSize Specifies the size of cell borders
BorderType Controls which cell borders are displayed, if any
EllipsisText If true, displays an ellipsis (…) at the end of cell text
Font Specifies typeface, size, and other text
characteristics
ForeColor Controls the foreground color
ForegroundPicture Sets/returns a style's foreground picture
ForegroundPicturePosition Controls how a style's foreground picture is
positioned
Locked Disallows in-cell editing when true
Name Returns the programmer-specified style name
Parent Sets/returns the object from which a style inherits
TransparentForegroundPicture True if the foreground picture uses a transparent
color
VerticalAlignment Specifies vertical text alignment
WrapText Word wraps cell text when true

Built-in Named Styles

When a grid is first created, it has a collection of built-in named styles that control various aspects of its
display. For example, the Heading style determines the attributes used to display column headers. At
design time, you can change the appearance of the grid as a whole by modifying the built-in named styles
on the Style Factory property page. At run time, the Styles collection provides access to the same set of
named styles. Initially, all grids contain ten built-in styles, which control the display of the following grid
elements:
Normal Data cells in unselected, unhighlighted rows
Heading Column headers
Footing Column footers
308 · How to Use Styles

Selected Data cells in selected rows

Caption Grid and split caption bars
HighlightRow Data cells in highlighted rows
EvenRow Data cells in even numbered rows
OddRow Data cells in odd numbered rows
Record Selector Data in the record selector column
Filter Bar Data in the filter bar columns
A selected row is one whose bookmark has been added to the SelBookmarks collection, either in code or
through user interaction. The term highlighted row refers to the current row when the MarqueeStyle
property is set to 3 - Highlight Row or 4 - Highlight Row, Raise Cell.
The EvenRow and OddRow styles are used only when the AlternatingRowStyle property is set to True.

Named style defaults

As in Microsoft Word, a Style object in True DBGrid can inherit its characteristics from another style,
referred to as the parent style. For a newly created grid, the Normal style is the parent (or grandparent) of
all named styles. Its default properties are as follows:
Alignment 3 - General
BackColor System Window Background
BackgroundPicture None
BackgroundPictureDrawMode 0 - Center
BorderAppearance 0 - Flat
BorderColor System Window Background
BorderSize 0
BorderType 0
EllipsisText False
Font The ambient font of the grid's container
ForeColor System Window Text
ForegroundPicture None
ForegroundPicturePosition 0 - Left
Locked False
Parent None
TransparentForegroundPicture False
VerticalAlignment 0 - Top
WrapText False

Note that the Normal style is a root-level style, since it does not have a value for the Parent property.
The Heading and Footing styles are defined similarly. Each inherits from Normal, and each overrides the
following properties:
 Built-in Named Styles · 309

BackColor System Button Face

ForeColor System Button Text
VerticalAlignment 2 - Vertical Center

The Heading style overrides one additional property that the Footing style does not:
WrapText True

The Selected style also inherits from Normal and overrides two color properties:
BackColor System Highlight
ForeColor System Highlight Text

The same is true of the HighlightRow style, which uses the inverse of the color settings for the default
Normal style:
BackColor System Window Text
ForeColor System Window Background

The EvenRow, OddRow, and FilterBar styles inherit from Normal, but only EvenRow overrides any
properties:
BackColor Light Cyan

The only styles that do not inherit directly from Normal are Caption and RecordSelector, which inherit from
Heading. The reason that grid and split captions are centered by default is that the Caption style specializes
the following property:
Alignment 2 - Center

Named style inheritance

To see for yourself how named style inheritance works, place a grid on a form and set the Caption
property of the grid and its default columns. Set the FooterText property of the default columns and set
the ColumnFooters property of the grid to True. The grid should look something like this.

On the Style Factory property page, expand the Normal node, select its Font property, and check the Bold
box. Note that the column headers, column footers, and grid caption are all bold, since all built-in styles
inherit from the Normal style or one of its children.
310 · How to Use Styles

Next, expand the Heading node and select its ForeColor property. Choose Standard Colors from the Color
Set combo box, then select White. Note that the text color of both the column headers and the grid's
caption bar is now white, since the Caption style inherits its color properties from the Heading style. The
column footers remain the same because the Footing style inherits from Normal, not Heading.

Finally, expand the Caption node and select its BackColor property. Choose Standard Colors from the
Color Set combo box, then select Gray. Note that the background color of the column headers is not
changed, and that the Caption style continues to inherit its text color from its parent style, Heading.

Modifying named styles

You can change the appearance of the overall grid at design time by modifying a named style using the
Style Factory property page. For example, to force all column headers to center their caption text, you can
change the Alignment property of the built-in Heading style to 2 - Center.
 Working with Style Properties · 311

The following statement accomplishes the same result in code:

TDBGrid1.Styles("Heading").Alignment = dbgCenter
However, you are not required to use the Style Factory property page or manipulate named members of
the Styles collection in code, as the grid and its component objects expose several properties that return
Style objects. As the next section describes, you can fine tune the appearance of the grid by manipulating
these objects directly.

Working with Style Properties

Just as a document template in Microsoft Word specifies the overall appearance of individual paragraphs
in a document, the named members of the Styles collection provide an overall display template for a
TDBGrid or TDBDropDown control. However, to customize the appearance of individual Split or
Column objects, you need to modify the appropriate Style object property:
CaptionStyle Controls the caption style for an object
EditorStyle Controls the editor style for an object
EvenRowStyle Controls the row style for even-numbered rows
FilterBarStyle Controls the style of the columns in the filter bar
FooterStyle Controls the footing style for an object
HeadingStyle Controls the heading style for an object
HighlightRowStyle Controls the marquee style when set to Highlight Row
InactiveStyle Controls the inactive heading style for an object
OddRowStyle Controls the row style for odd-numbered rows
RecordSelectorStyle Controls the record selector style for an object
SelectedStyle Controls the selected row and column style for an object
312 · How to Use Styles

Style Controls the normal style for an object

NOTE: Not every property that ends with "Style" returns a Style object. For example, DividerStyle is an
enumerated property, and AlternatingRowStyle is a boolean.
The following grid shows which style properties are supported by the TDBGrid and TDBDropDown
controls, and which are supported by the Split and Column objects.

Modifying a style property directly

You can customize the appearance of a grid component by modifying one or more members of an
appropriate style property. For example, to make the grid's caption text bold, you can change the Font
object associated with the CaptionStyle property. At design time, this is done by expanding the
CaptionStyle tree node on the General property page, selecting the Font node, and checking the Bold
box. The change is committed to the grid when you click the OK or Apply button or select a different
property page tab.
 Working with Style Properties · 313

Note that the text of the CaptionStyle node ends with the word Caption enclosed in square brackets. This
indicates that the property inherits some or all of its attributes from a like-named member of the Styles
collection. However, if you switch to the Style Factory property page, you will see that the built-in
Caption style has not changed.

This means that the following statements are not equivalent:

TDBGrid1.CaptionStyle.Font.Bold = True
TDBGrid1.Styles("Caption").Font.Bold = True
The first statement specializes the font of the grid's caption bar without changing the named Caption style.
The second statement changes the named Caption style, which may or may not affect the display of the
grid's caption bar, depending on whether the Font member of the CaptionStyle property was specialized
previously. For example, if you change the grid's CaptionStyle font to Arial, then change the font of the
built-in Caption style to Courier, the grid caption will remain Arial. However, if you never change the
CaptionStyle font, then any font change to the built-in Caption style will be instantly reflected in the
grid's caption bar.

Assigning a value to a style property

You can also customize the appearance of a grid component by directly assigning a named style to an
appropriate style property. For example, suppose that you have defined a style named Verdana as
depicted in the following illustration.
314 · How to Use Styles

To render a grid caption using this font and color scheme, you can set the CaptionStyle property directly
instead of setting individual font and color properties. At design time, this is done by selecting the
CaptionStyle tree node on the General property page and selecting Verdana from the list of named styles
to the right of the property tree. The change is committed to the grid when you click the OK or Apply
button or select a different property page tab.

Note that the text of the CaptionStyle node now ends with the word Verdana enclosed in square brackets.
You can achieve the same result in code by writing:
 Working with Style Properties · 315

TDBGrid1.CaptionStyle = "Verdana"

Named styles versus anonymous styles

When setting style properties at design time, it is important to understand the distinction between named
styles and the anonymous styles exposed by grid properties.
Named styles provide templates that govern the appearance of the grid, its splits, and its columns. At
design time, you can create, modify, and delete named styles using the Style Factory property page. At
run time, the Styles collection is used to represent the same set of named Style objects.
When a grid is first created, several of its style properties inherit their attributes from named styles.
Within the property tree on the General page, such properties are indicated by the presence of a style
name in square brackets. The following figure shows four TDBGrid properties that return named style
objects: EvenRowStyle, FilterBarStyle, FooterStyle, and HeadingStyle.

Anonymous styles are not members of the Styles collection, however. They are provided so that you can
easily and directly customize the appearance of an individual split or column without having to define a
separate named style.
When a grid is first created, all style properties of its Split and Column objects return anonymous styles.
Therefore, within the property tree on the Splits page of TDBGrid (or the Columns page of
TDBDropDown), there are no style properties tagged with a name enclosed in square brackets. The
following figure shows three Column properties that return anonymous style objects: FooterStyle,
HeadingStyle, and Style.
316 · How to Use Styles

The following analogy should help to clarify the distinction between named and anonymous styles.
Consider a Microsoft Word document that consists of several paragraphs based on the default normal
style. Suppose that one of the paragraphs is a quotation that needs to be indented and displayed in italics.
If the document is part of a larger work that contains several quotations, it makes sense to define a special
style for that purpose and apply it to all paragraphs that contain quotations. If the document is an early
draft or is not likely to be updated, defining a style for one paragraph is overkill, and it would be more
convenient to apply indentation and italics to the quotation itself.
In this analogy, specifying paragraph attributes directly is akin to setting the members of a property that
returns an anonymous style. For example, if you want cell data to be vertically centered within a
particular grid column, you can modify the VerticalAlignment member of the column's Style property
on the Splits property page.
 Working with Style Properties · 317

Note that modifying an anonymous style is just like modifying a named style. You first expand the
desired Style object node in a property tree, then select and edit one or more of its member properties.

Anonymous style inheritance

Just as one named style can inherit font, color, and formatting characteristics from another, an
anonymous style in a Split object can inherit from its counterpart in the containing TDBGrid control.
Similarly, an anonymous style in a Column object can inherit from its counterpart in the containing Split
object. Since the TDBDropDown control does not have a Splits collection, the anonymous styles of its
Column objects can inherit values from the control itself.
When a grid is first created, its Style property inherits all of its attributes from the built-in Normal style,
which controls the appearance of all data cells. Any changes to the Normal style are propagated to all
splits, and in turn to the columns within each split. However, you can change the appearance of all data
cells within a Split or Column object by modifying the members of its anonymous Style property.
Consider the following grid layout, which uses the default values of all built-in styles and contains two
identical splits.

All of the subsequent examples use this layout as a starting point. For clarity, the examples use code to
illustrate the relationships between style properties and the grid's display; however, you can perform the
same operations at design time using the grid's property pages.
Example 1:
TDBGrid1.Style.Font.Bold = True

Since the default values of all built-in styles are in effect, columns inherit from their containing splits,
which in turn inherit from the grid as a whole. Therefore, this statement affects not only data cells, but all
headers, footers, and caption bars. This statement has the same visual effect as changing the Normal style
directly using the Style Factory property page; however, the built-in Normal style itself is not changed.
Example 2:
TDBGrid1.Splits(0).Style.Font.Bold = True
318 · How to Use Styles

In this example, only the data cells of the first split are affected. This is because the split caption, column
headers, and column footers inherit their fonts from the built-in styles Caption, Heading, and Footing,
respectively.
Example 3:
With TDBGrid1.Splits(0)
.Style.Font.Bold = True
.CaptionStyle.Font.Bold = True
.HeadingStyle.Font.Bold = True
.FooterStyle.Font.Bold = True
End With

This example extends the previous one to render all elements of the first split in bold. In addition to the
Style property, it is necessary to set the CaptionStyle, HeadingStyle, and FooterStyle properties.
Example 4:
TDBGrid1.Splits(0).Columns(0).Style.Font.Bold = True

In this example, only the data cells of the first column of the first split are affected. This is because the
column headers and column footers inherit their fonts from the built-in styles Heading and Footing,
respectively.
Example 5:
With TDBGrid1.Splits(0).Columns(0)
.Style.Font.Bold = True
.HeadingStyle.Font.Bold = True
.FooterStyle.Font.Bold = True
End With

This example extends the previous one to render all elements of the first column of the first split in bold.
In addition to the Style property, it is necessary to set the HeadingStyle and FooterStyle properties.
Example 6:
TDBGrid1.Style.BackColor = &H808080
 Working with Style Properties · 319

In the first example, setting the Font member of the grid's Style property affected the entire grid,
including each caption bar, column header, and column footer. However, the same is not true of the
BackColor and ForeColor properties. Since the built-in Caption, Heading, and Footing styles override both
of these properties, only the data cells of the grid are displayed with a dark gray background.
Example 7:
TDBGrid1.Splits(0).Style.BackColor = &H808080

In this example, only the data cells of the first split are affected. This is because the split caption, column
headers, and column footers inherit their background colors from the built-in styles Caption, Heading, and
Footing, respectively.
Example 8:
TDBGrid1.Splits(0).Columns(0).Style.BackColor = &H808080

In this example, only the data cells of the first column of the first split are affected. This is because the
column headers and column footers inherit their background colors from the built-in styles Heading and
Footing, respectively.
Example 9:
TDBGrid1.Splits(0).Columns(0).Style.Alignment = dbgCenter

Setting the Alignment property of a Column object affects not only its data cells, but also its header and
footer. The reason for this is that the default setting of the Alignment property for the built-in Heading
and Footing styles, which is inherited from Normal, is set to 3 - General. For data cells, the general setting
means that the underlying data type determines whether the cell text is left, center, or right aligned; for
320 · How to Use Styles

column headers and footers, the general setting means that the column's data cell alignment should be
followed.
Example 10:
With TDBGrid1.Splits(0).Columns(0)
.HeadingStyle.Alignment = dbgLeft
.FooterStyle.Alignment = dbgRight
.Alignment = dbgCenter
End With

This example illustrates the distinction between general and specific alignment for column headers and
footers. If the Alignment member of the HeadingStyle (or FooterStyle) property is not set to 3 - General,
then the header (or footer) is aligned independently of the data cells.
Note that all of the preceding examples used Style object properties to demonstrate the inheritance
relationships between grid components. In practice, you can achieve the same results in a more
straightforward manner using shortcut style properties, as described in the next section.

Shortcut style properties

For your convenience, and for compatibility with earlier versions of True DBGrid, several shortcut
properties are defined for accessing Style object members at either design time or run time:
Alignment Specifies horizontal text alignment
BackColor Sets/returns the background color
EditBackColor Sets/returns the editor background color
EditForeColor Sets/returns the editor foreground color
Font Specifies the typeface, size, and other text characteristics
FooterAlignment Specifies column footing alignment
FooterBackColor Sets/returns the footing background color
FooterFont Specifies the footing font for an object
FooterForeColor Sets/returns the footing foreground color
ForeColor Sets/returns the foreground color
HeadAlignment Specifies column heading alignment
HeadBackColor Sets/returns the heading background color
HeadFont Specifies the heading and caption font for an object
HeadForeColor Sets/returns the heading foreground color
InactiveBackColor Sets/returns the inactive heading background color
InactiveForeColor Sets/returns the inactive heading foreground color
Locked True if data entry is prohibited for an object
SelectedBackColor Sets/returns the selected row and column background color
 Applying Styles to Cells · 321

SelectedForeColor Sets/returns the selected row and column foreground color

WrapText True if cell text is word wrapped

The following grid shows the style property equivalent for each shortcut. It also indicates which
properties are supported by the TDBGrid and TDBDropDown controls, and which properties are
supported by the Split and Column objects.

For example, the following statements are equivalent:

TDBGrid1.Columns(0).HeadAlignment = dbgCenter
TDBGrid1.Columns(0).HeadingStyle.Alignment = dbgCenter

Applying Styles to Cells

True DBGrid gives you three ways to control the display characteristics of individual cells:
By Status Each grid cell has a cell status that identifies its disposition (any
combination of current, modified, part of a selected row, or part of a
highlighted row). Using the AddCellStyle method, you can set style
attributes that apply to any possible combination of cell status values.
By Contents You can specify a pattern (called a regular expression) that is used to
perform pattern matching on cell contents. When the contents match the
pattern supplied in the AddRegexCellStyle method, True DBGrid will
automatically apply pre-selected style attributes to the cell.
By Custom Criteria Using the FetchCellStyle (or FetchRowStyle) event, you can make
decisions about cell colors and fonts each time a cell (or row) is
displayed.
You can use Style objects defined at design time as arguments to the AddCellStyle and
AddRegexCellStyle methods. Or, you can create a temporary style in code and use it to specialize one or
more attributes.
322 · How to Use Styles

The FetchCellStyle and FetchRowStyle events pass a temporary Style object as the final parameter. By
setting its properties, you can control the appearance of the cell specified by the other event parameters.
In this version of True DBGrid, per-cell font and color control can only be achieved by writing code.
However, by creating styles at design time, you can keep this code to a minimum. To learn how to create
named styles at design time, see Using the Style Factory property page (page 163).

Specifying cell status values

True DBGrid recognizes 16 distinct cell status values which are used in code to indicate the disposition of
a cell. A cell status value is a combination of four separate conditions:
Current Cell The cell is the current cell as specified by the Bookmark, Col, and Split
properties. At any given time, only one cell can have this status. When the
floating editor MarqueeStyle property setting is in effect, this condition is
ignored.
Marquee Row The cell is part of a highlighted row marquee. When the MarqueeStyle
property indicates that the entire current row is to be highlighted, all visible
cells in the current row have this additional condition set.
Updated Cell The cell contents have been modified by the user but not yet written to the
database. This condition is also set when cell contents have been modified
in code with the Text or Value properties.
Selected Row The cell is part of a row selected by the user or in code. The SelBookmarks
collection contains a bookmark for each selected row.
True DBGrid defines the following constants corresponding to these cell conditions:
dbgCurrentCell 1 - Applies to the current cell
dbgMarqueeRow 2 - Applies to cells in a highlighted row marquee
dbgUpdatedCell 4 - Applies to cells that have been modified
dbgSelectedRow 8 - Applies to cells in a selected row
You can add these constants together to specify multiple cell conditions. For example, a cell status value
of 9 (dbgCurrentCell + dbgSelectedRow) denotes a current cell within a selected row.
True DBGrid also defines the following constants, which are not meant to be combined with those listed
earlier:
dbgAllCells -1 - Applies to all cells
dbgNormalCell 0 - Applies to cells without status conditions
Use dbgAllCells to refer to all cells regardless of status. Use dbgNormalCell to refer to only those
cells without any of the four basic cell conditions described earlier.

Applying cell styles by status

Each cell in the True DBGrid display has a status value which identifies its disposition (any combination
of current, modified, part of a selected row, or part of a highlighted row). Using the AddCellStyle
method, you can set style attributes which apply to any possible combination of cell status values. The
AddCellStyle method is supported by the TDBGrid, TDBDropDown, Split, and Column objects,
enabling you to control the range of cells for which certain conditions apply.
For each unique status combination, you can set the color, font, and picture attributes to be used for cells
of that status. When a cell's status changes, True DBGrid checks to see if any style property overrides are
 Applying Styles to Cells · 323

defined for that cell, and applies those attributes to the cell when it is displayed. Style objects are used to
specify the color and font for a cell, as in the following example:
Dim S As New TrueDBGrid80.Style
S.ForeColor = vbRed
S.Font.Bold = True
TDBGrid1.AddCellStyle dbgCurrentCell, S
Here, a new temporary style object is created to specify the color and font overrides (red text, bold) to be
applied to the current cell throughout the entire grid. Since the style object's BackColor property is not set
explicitly, the background color of the current cell is not changed.

You can also use styles defined at design time as arguments to the AddCellStyle method:
Dim S As TrueDBGrid80.Style
Set S = TDBGrid1.Styles("RedBold")
TDBGrid1.AddCellStyle dbgCurrentCell, S
The preceding example can be simplified since the AddCellStyle method accepts a style name as well as
an actual style object:
TDBGrid1.AddCellStyle dbgCurrentCell, "RedBold"
All of the preceding examples cause the text of the current cell to appear in red and bold. However, it is
important to note that the status dbgCurrentCell applies only to cells which have only this status.
Thus, cells which are current but also updated (dbgCurrentCell + dbgUpdatedCell) will not be
displayed in red and bold unless you also execute the following statement:
TDBGrid1.AddCellStyle dbgCurrentCell + dbgUpdatedCell, "RedBold"
NOTE: The current cell status is only honored when the MarqueeStyle property is not set to 6 - Floating
Editor. The floating editor marquee always uses the system highlight colors as determined by your
Control Panel settings.
Although this method of specifying cell conditions offers more control and flexibility, it also requires that
additional code be written for some common cases.
Calls to AddCellStyle take effect immediately, and can be used for interactive effects as well as overall
grid characteristics.

Applying cell styles by contents

You can tell True DBGrid to automatically apply colors and fonts to particular cells, based upon their
displayed contents. To do so, you provide a pattern, called a regular expression, which the grid tests
against the displayed value of each cell. Using the AddRegexCellStyle method, you can associate a
regular expression with a set of style attributes, then apply them to any possible combination of cell
status values. The AddRegexCellStyle method is supported by the TDBGrid, TDBDropDown, Split,
and Column objects, allowing you to control the range of cells for which certain conditions apply.
The AddRegexCellStyle method is similar to the AddCellStyle method, but it requires an additional
argument for the regular expression string. As with AddCellStyle, you can use either temporary or
324 · How to Use Styles

named styles. The following example uses a temporary style to display all cells in the first column that
contain the string "Windows" in bold:
Dim S As New TrueDBGrid80.Style
S.Font.Bold = True
TDBGrid1.Columns(0).AddRegexCellStyle dbgAllCells, S, "Windows"
This feature allows you to implement "visual queries" that attach distinctive font or color attributes to
cells that match a certain pattern.

Applying cell styles by custom criteria

For cases where regular expressions are insufficient to express your formatting requirements, you can
use the FetchCellStyle event to customize fonts and colors on a per-cell basis. This event will only be
fired for columns that have the FetchStyle property set to dbgFetchCellStyleColumn or
dbgFetchCellStyleAddNewColumn.
For example, you may want to provide color coding for values that fall within a certain range. The
following code assumes that the FetchStyle property is set to dbgFetchCellStyleColumn for a single column
of numeric data, and handles the FetchCellStyle event to display values greater than 1000 in blue:
Private Sub TDBGrid1_FetchCellStyle( _
ByVal Condition As Integer, _
ByVal Split As Integer, _
Bookmark As Variant, _
ByVal Col As Integer, _
ByVal CellStyle As TrueDBGrid80.StyleDisp)
Dim N As Long
N = Val(TDBGrid1.Columns(Col).CellText(Bookmark))
If N > 1000 Then CellStyle.ForeColor = vbBlue
End Sub
The Split, Bookmark, and Col arguments identify which cell the grid is displaying. The CellStyle argument
conveys formatting information from your application to the grid. Since the CellStyle argument is a Style
object, you can also change a cell's font characteristics in the FetchCellStyle event:
If N > 1000 Then CellStyle.Font.Italic = True
The FetchCellStyle event can also be used to apply formatting to one cell based upon the values of other
cells, or even other controls. For example, suppose that you want to:
• Make the cell text red in column 4 if column 1 minus column 2 is negative.
• Make the cell text bold in column 7 if it matches the contents of a text box.
 Applying Styles to Cells · 325

In this case, you need to set the FetchStyle property to dbgFetchCellStyleColumn for columns 4 and 7, and
handle the FetchCellStyle event as follows:
Private Sub TDBGrid1_FetchCellStyle( _
ByVal Condition As Integer, _
ByVal Split As Integer, _
Bookmark As Variant, _
ByVal Col As Integer, _
ByVal CellStyle As TrueDBGrid80.StyleDisp)
Select Case Col
Case 4
Dim Col1 As Long, Col2 As Long
Col1 = CLng(TDBGrid1.Columns(1).CellText(Bookmark))
Col2 = CLng(TDBGrid1.Columns(2).CellText(Bookmark))
If Col1 - Col2 < 0 Then CellStyle.ForeColor = vbRed
Case 7
Dim S As String
S = TDBGrid1.Columns(7).CellText(Bookmark)
If S = Text1.Text Then CellStyle.Font.Bold = True
Case Else
Debug.Print "FetchCellStyle not handled: " & Col
End Select
End Sub
For efficiency reasons, you should only set FetchStyle to dbgFetchCellStyleColumn for columns that you
plan to handle in the FetchCellStyle event.
NOTE: The preceding examples use the CellText method for simplicity. However, the CellText and
CellValue methods always create and destroy an internal clone of the dataset each time they are called,
which may make them too inefficient to use in the FetchCellStyle event. To improve the performance of
the grid's display cycle, use a Recordset clone to derive the cell text, if available. Unbound applications
can access the underlying data source directly, which is generally faster than calling CellText or
CellValue.
If you need to customize fonts and colors on a per-row instead of a per-cell basis, use the FetchRowStyle
event, which will only be fired once per row for grids that have the FetchRowStyle property set to True.
The syntax for this event is as follows:
Private Sub TDBGrid1_FetchRowStyle( _
ByVal Split As Integer, _
Bookmark As Variant, _
ByVal RowStyle As TrueDBGrid80.StyleDisp)
Although you can use the FetchRowStyle event to implement an alternating row color scheme, an easier
and more efficient way to accomplish the same task would be to use the AlternatingRowStyle property,
together with the built-in EvenRow and OddRow styles.
The FetchRowStyle event is ideally suited for coloring the entire row of a grid based on the value of one
or more columns. The following example demonstrates how to do this using a Recordset clone:
Dim RS As Recordset
Private Sub Form_Load()
Data1.Refresh
Set RS = Data1.Recordset.Clone
TDBGrid1.FetchRowStyle = True
End Sub
Private Sub TDBGrid1_FetchRowStyle( _
ByVal Split As Integer, _
Bookmark As Variant, _
ByVal RowStyle As TrueDBGrid80.StyleDisp)
326 · How to Use Styles

RS.Bookmark = Bookmark
If RS.Fields("Country") = "Germany" Then
RowStyle.BackColor = vbCyan
End If
End Sub

Cell style evaluation order

The following list defines the order in which cell styles are applied relative to the anonymous styles of a
grid, split, or column.
1. Style property, TDBGrid control. The default named parent of this anonymous style is Normal.
2. Style property, Split object. By default, this anonymous style inherits from its TDBGrid control
counterpart.
3. EvenRowStyle and OddRowStyle properties, Split object. By default, these anonymous styles
inherit from their TDBGrid control counterparts, which in turn have default named parents of
EvenRow and OddRow. These properties apply only if the AlternatingRowStyle property is True.
4. Style property, Column object. By default, this anonymous style inherits from its Split object
counterpart.
5. FetchRowStyle event. This event fires only if the FetchRowStyle property is True for a grid or
split.
6. SelectedStyle property, Split object. By default, this anonymous style inherits from its TDBGrid
control counterpart, which in turn has a default named parent of Selected. This property applies
only to selected rows; that is, rows whose bookmarks have been added to the SelBookmarks
collection through code or user interaction.
7. HighlightRowStyle property, Split object. By default, this anonymous style inherits from its
TDBGrid control counterpart, which in turn has a default named parent of HighlightRow. This
property applies only to highlighted rows; that is, the current row in a grid or split whose
MarqueeStyle property is set to 3 - Highlight Row or 4 - Highlight Row, Raise Cell.
8. AddCellStyle and AddRegexCellStyle methods, if called. Cell styles specified at the Column
object level have the highest priority, followed by those specified at the Split object and
TDBGrid control levels. Within an object level, cell styles are tested in the order in which they
were added in code. Cell styles do not inherit from one another; as soon as a match is found,
testing stops.
9. FetchCellStyle event. This event fires only if the FetchStyle property is set to
dbgFetchCellStyleColumn or dbgFetchCellStyleAddNewColumn for a Column object.
Thus, you always have final control over the rendering of a cell via the FetchCellStyle event.

Applying Pictures to Grid Elements

In earlier versions of True DBGrid, styles were used to specify font, color, and alignment attributes.
Version 6.0 extends the concept of styles to include background and foreground pictures, enabling you to
add adornments to headers, footers, and caption bars, specify a background pattern for data cells, and
render picture data in cells without having to populate a ValueItems collection. The following properties
of the Style object determine how pictures are displayed:
BackgroundPicture Sets/returns a style's background picture
 Applying Pictures to Grid Elements · 327

BackgroundPictureDrawMode Controls how a style's background picture is displayed

ForegroundPicture Sets/returns a style's foreground picture
ForegroundPicturePosition Controls how a style's foreground picture is positioned
TransparentForegroundPicture True if the foreground picture uses a transparent color
Since picture properties follow the same inheritance rules as other style attributes, any technique
described earlier in this chapter also works with pictures. This means that you can attach pictures to a
grid element using any of the following methods:
• Setting the BackgroundPicture or ForegroundPicture property of a built-in named style at design
time or run time.
• Setting the BackgroundPicture or ForegroundPicture property of an anonymous style at design
time or run time.
• Calling the AddCellStyle or AddRegexCellStyle methods.
• Writing a handler for the FetchCellStyle or FetchRowStyle events.

Displaying background pictures

You can use background pictures to customize static grid elements such as caption bars, column headers,
and column footers. For example, the following code applies a colored gradient bitmap to the
BackgroundPicture member of the Style object returned by the grid's CaptionStyle property:
With TDBGrid1.CaptionStyle
.BackgroundPicture = LoadPicture("gradient.bmp")
.ForeColor = vbWhite
.Font.Bold = True
End With
This code also adjusts the color of the caption text and makes it bold, producing the following display.

You can achieve the same effect at design time by editing either the built-in Caption style on the Style
Factory property page, or the members of the CaptionStyle property on the General property page.
By default, background pictures are centered within the associated grid element. Depending upon the
height of the background bitmap, you may need to adjust the value of the BackgroundPictureDrawMode
property to ensure that the entire area is filled. This property determines whether the picture is centered,
tiled, or stretched to fit the entire area, as shown in the following figure.
328 · How to Use Styles

You can also use background pictures within data cells to produce interesting visual effects. For example,
the following patterns were designed to be replicated in adjacent rows.

By eliminating the record selector column, the dividing lines between data rows, and the column header
dividers, these patterns can be used to produce the following display.

The trick is to insert an empty unbound column on the left to display the binder rings, as the following
code sample demonstrates:
' Give the grid a flat appearance and remove its record
' selectors, row dividers, and scroll bars. Assume that
' the ScaleMode of the containing form is in pixels.
With TDBGrid1
.Appearance = dbgFlat
.InactiveForeColor = vbWhite
.RecordSelectors = False
.RowDividerStyle = dbgNoDividers
.RowHeight = 16
.ScrollBars = dbgNone
.MarqueeStyle = dbgNoMarquee
End With
' Set the background pattern to be used by data cells in
' the default split (so as not to disturb the Normal style).
 Applying Pictures to Grid Elements · 329

With TDBGrid1.Splits(0).Style
.BackgroundPicture = LoadPicture("paper.bmp")
.BackgroundPictureDrawMode = dbgBPTile
End With
' Create an empty unbound column on the left to hold the
' binder rings. Remove its dividing lines and set the
' BackroundBitmap property of its Style object.
Dim C As TrueDBGrid80.Column
Set C = TDBGrid1.Columns.Add(0)
With C
.DividerStyle = dbgNoDividers
.HeaderDivider = False
.Width = 48
.Visible = True
.Style.BackgroundPicture = LoadPicture("rings.bmp")
End With
TDBGrid1.Col = 0 ' Scroll the unbound column into view
' Resize the Title column and remove its header dividers.
Set C = TDBGrid1.Columns("Title")
With C
.Width = 380
.HeaderDivider = False
End With
' Use a small corner of the binder ring bitmap as the
' background of the column headers, and adjust the font
' and text color accordingly.
With TDBGrid1.HeadingStyle
.BackgroundPicture = LoadPicture("corner.bmp")
.BackgroundPictureDrawMode = dbgBPTile
.Font.Bold = True
.Font.Size = 10
.ForeColor = vbWhite
End With

Displaying foreground pictures

You can use foreground pictures to add visual cues to static grid elements such as caption bars, column
headers, and column footers. For example, suppose that you want to sort a column when the user clicks
its header, then reverse the sort order when the user clicks it again. If you define two distinct styles for
the ascending and descending states, you can easily apply the correct style in the handler for the
HeadClick event.
At design time, use the Style Factory property page to create the new styles as follows:
1. Select the Heading style in the property tree to ensure that new styles will inherit from it. (If you
forget this step, you can still change the Parent property of the new style after it is created.)
2. Enter the name Ascending in the New Style Name text box, then click the New button.
3. Select and expand the Ascending item at the bottom of the property tree, then set the
ForegroundPicture property to an appropriate bitmap, as shown in the following figure.
330 · How to Use Styles

4. Depending upon the bitmap used, you may also want to set the TransparentForegroundPicture
property to True to ensure that the bitmap displays properly regardless of the heading
background color. If this property is True, then the color of the pixel at the lower left corner of the
bitmap is used as the transparent color.
5. Repeat the procedure for the Descending style.
Or, you can create the Ascending style in code as follows:
Dim S As TrueDBGrid80.Style
Set S = TDBGrid1.Styles.Add("Ascending")
S.Parent = "Heading"
S.ForegroundPicture = LoadPicture("atoz.bmp")
S.ForegroundPicturePosition = dbgFPRightOfText
S.TransparentForegroundPicture = True
Note that this example also sets the ForegroundPicturePosition property so that the bitmap appears after
the column header text. By default, the foreground picture is displayed at the left edge of the column
header. The relative placement of the bitmap is also affected by the setting of the column's Alignment
property, as shown in the following grid.
 Applying Pictures to Grid Elements · 331

To apply a style to a column header, set its HeadingStyle property to the name of the desired style. You
can also examine the string returned by this property in code to determine which style is in effect. The
following code illustrates how to implement a handler for the HeadClick event that inverts the sort order
and updates the heading style accordingly:
Private Sub TDBGrid1_HeadClick(ByVal ColIndex As Integer)
If ColIndex <> 1 Then Exit Sub

Dim SQL As String

SQL = "select * from composer order by last"

With TDBGrid1.Columns(1)
If .HeadingStyle = "Ascending" Then
.HeadingStyle = "Descending"
SQL = SQL & " desc"
Else
.HeadingStyle = "Ascending"
End If
End With

Data1.RecordSource = SQL
Data1.Refresh
End Sub
The first time the user clicks column 1, its HeadingStyle property is set to Ascending, and the foreground
bitmap associated with this style appears to the right of the text within the column header. Note that you
may have to adjust the HeadLines property at design time to accommodate the height of the bitmap.
332 · How to Use Styles

The next time the user clicks column 1, its HeadingStyle property is set to Descending, and the bitmap
within the column header is changed accordingly.

Since foreground pictures are components of Style objects, they are not restricted to static elements such
as column headers—they can also be displayed within data cells. For example, you can use the
AddRegexCellStyle method to attach a picture to cells that satisfy certain criteria:
Dim S As New TrueDBGrid80.Style
S.ForegroundPicture = LoadPicture("bach.bmp")
S.ForegroundPicturePosition = dbgFPRight
TDBGrid1.Columns(1).AddRegexCellStyle dbgAllCells, S, "Bach"
Note the similarity between this example and the one presented earlier in Applying cell styles by contents
(page 323. )The only difference is that this code sets picture properties instead of font properties, resulting
in the following display.

You can also use the FetchCellStyle event to assign a foreground picture to a cell:
Private Sub TDBGrid1_FetchCellStyle( _
ByVal Condition As Integer, _
ByVal Split As Integer, _
Bookmark As Variant, _
ByVal Col As Integer, _
ByVal CellStyle As TrueDBGrid80.StyleDisp)
If Col <> 1 Then Exit Sub
If TDBGrid1.Columns(1).CellText(Bookmark) = "Bach" Then
CellStyle.ForegroundPicture = LoadPicture("bach.bmp")
CellStyle.ForegroundPicturePosition = dbgFPRight
End If
End Sub
Tutorial 21 (page 84) demonstrates how to use styles to display arbitrary bitmaps within data cells.
 How Cell Editing Works · 333

Cell Editing Techniques

This chapter explains how to customize the behavior of cell editing in True DBGrid. For text entry fields,
you can write handlers for the grid's editing events, specify an input mask template, or display a drop-
down text editor for long strings. To provide a list of choices for the user, you can use the ValueItems
collection, the data-aware TDBDropDown control, or even an arbitrary intrinsic or third-party control.

How Cell Editing Works

True DBGrid provides many features for customizing and controlling in-cell editing. The grid's default
editing behavior depends on the setting of the MarqueeStyle property. If the floating editor marquee
style is used, the editing behavior differs from that of other marquee styles. The following sections
summarize True DBGrid's editing behavior and state any exceptions that arise when using the floating
editor.
For more information on the MarqueeStyle property, see Highlighting the Current Row or Cell (page
254).

Initiating cell editing

A cell is either in display or edit mode. The EditActive property sets and returns the desired mode. You
can place the current cell in edit mode by setting EditActive to True, or end editing by setting it to False.
The user may enter edit mode by clicking once on the current cell or by pressing the F2 key. A blinking
text cursor (caret) will appear in the cell—at the beginning of the text when the cell is clicked and at the
end when the F2 key is used. The BeforeColEdit event will be triggered when the cell enters edit mode.
The EditActive property is True when the cell is in edit mode.
Floating Editor Differences: A blinking caret already exists at the beginning of the cell highlight even when
in display mode. To enter edit mode, the user can click on any character location within the cell text to
specify the text insertion point. The BeforeColEdit event is not triggered and the EditActive property is
False until the user has made changes to the cell text.

Color and wordwrap

In edit mode, the cell color is determined by the EditForeColor and EditBackColor properties. The text
being edited will wordwrap, regardless of the setting of the column's WrapText property. If the text is too
big to fit into the cell, a built-in drop-down edit control will automatically appear. For more information,
see Working with Text (page 336).
Floating Editor Differences: In edit mode, the text highlight disappears, and the cell color is the same as the
normal cell color. The text being edited is wordwrapped only if the column's WrapText property is True.
The built-in drop-down edit control is not available.

Determining modification status

While editing is in progress, you can inspect the DataChanged property of the grid to determine whether
the user has made any changes to the current row. Similarly, you can inspect the DataChanged property
of an individual column to determine whether the user has made any changes to a specific cell within the
current row.
You can set the grid's DataChanged property to False to exit editing, discard all changes to the current
row, and refresh the current row display from the data source.
334 · Cell Editing Techniques

The DataChanged property of a Column object is read-only.

The icon in the record selector column of the current row reflects the status of the grid's DataChanged
property. If DataChanged is False, a triangle-shaped arrow will be shown in the record selector column. If
DataChanged is True, a pencil icon will appear instead.

Determining cell contents

While editing is in progress, the column's Text and Value properties contain the text the user currently
sees in the modified row. Whenever the user presses a key, the Change event fires to notify your
application that the user has just modified the current cell. However, the Change event doesn't mean the
user is finished with the process, only that a single change has been made and the grid is still in edit
mode.
The Change event does not fire when the grid is not in edit mode, such as when the contents of a cell are
changed through code or when the user clicks a cell to cycle through a ValueItems collection.

Terminating cell editing

The user completes the editing process by performing any of the following:
• Pressing the ENTER key.
• Pressing the F2 key.
• Pressing the ESC key.
• Moving to another cell with the arrow keys, the TAB key, or the mouse.
• Setting focus to another control on the form.

Handling Editing Events

The following sections describe how you can alter the default editing behavior of True DBGrid by
responding to its events.

Standard keystroke events

True DBGrid supports the standard keystroke events common to many ActiveX controls:
KeyDown Fired when the user presses a key.
KeyPress Fired when the user presses an ANSI key.
KeyUp Fired when the user releases a key.
The KeyDown and KeyUp events trap all keys, including function keys, ALT and SHIFT keys, and
numeric keypad keys. The KeyPress event only traps letters and numbers, punctuation marks and
symbols, and editing keys such as TAB, ENTER, and BACKSPACE.
You can use these events to restrict and modify user input as you would for any other intrinsic or ActiveX
control. For example, the following KeyPress event handler converts the user's keystrokes to upper case
letters, and prevents the user from entering non-alphanumeric characters:
Private Sub TDBGrid1_KeyPress(KeyAscii As Integer)
' Convert key to upper case
KeyAscii = Asc(UCase(Chr$(KeyAscii)))
' Don't disable the Esc or Backspace keys
If (KeyAscii = 27) Or (KeyAscii = 8) Then Exit Sub
 Handling Editing Events · 335

' Cancel user key input if it is not a letter or a digit

If (KeyAscii < 65 Or KeyAscii > 90) _
And (KeyAscii < 48 Or KeyAscii > 57) Then
KeyAscii = 0
End If
End Sub

Column editing events

True DBGrid gives you full control over the cell editing process with the following events, listed in the
order in which they occur during a successful editing attempt:
BeforeColEdit Fired upon an attempt to edit column data.
ColEdit Fired when the current cell enters edit mode.
AfterColEdit Fired after column data is edited.
You can use the BeforeColEdit event to control the editability of cells on a per-cell basis, or to translate
the initial keystroke into a default value.
The ColEdit event signals that the current cell has entered edit mode; the AfterColEdit event signals that
edit mode was terminated. You can use these two events to provide additional feedback while editing is
in progress:
Private Sub TDBGrid1_ColEdit(ByVal ColIndex As Integer)
Select Case TDBGrid1.Columns(ColIndex).Caption
Case "Code"
Label1.Caption = "Enter 4-digit company code"
Case "Description"
Label1.Caption = "Enter full company name"
End Select
End Sub
Private Sub TDBGrid1_AfterColEdit(ByVal ColIndex As Integer)
Label1.Caption = "" ' Clear editing instructions
End Sub

Changing cell contents with a single keystroke

The BeforeColEdit event is an extremely versatile way to customize the behavior of True DBGrid editing.
BeforeColEdit is fired before any other editing events occur, which gives you the opportunity to do
virtually anything you want to before editing begins. For example, you can cancel the edit request and
override the built-in text editor with your own drop-down list box.
A True DBGrid control can enter edit mode in one of four ways:
1. If the user clicks on the current cell with the mouse, editing begins with the current cell contents.
2. If the user presses the F2 key, editing also begins using the current cell contents.
3. If the user begins typing, the typed character replaces the contents of the cell and editing begins.
4. You can set the EditActive property in your code to force editing to begin.
The BeforeColEdit event fires in cases 1, 2, and 3, but not in case 4, since True DBGrid assumes you will
never want to cancel a request made from code.
You may want to differentiate a user's edit request based upon whether they used the mouse or the
keyboard to start editing. To facilitate this, one of the parameters to BeforeColEdit is KeyAscii, which will
336 · Cell Editing Techniques

be zero if the user clicked on the cell with the mouse, and will be an ASCII character if the user typed a
character to begin editing.
When BeforeColEdit is fired, the ASCII character hasn't yet been placed into the current cell, so if you
cancel editing in BeforeColEdit, the ASCII key is discarded. This leads to an interesting technique.
Assume you have a boolean field called Done, and you have set its NumberFormat property to specify
Yes/No as the display format. Further assume that, when the user presses Y or N, you want to change the
cell contents immediately instead of entering edit mode. Here's how you could accomplish this in
BeforeColEdit:
Private Sub TDBGrid1_BeforeColEdit(ByVal ColIndex As Integer, _
ByVal KeyAscii As Integer, Cancel As Integer)
With TDBGrid1.Columns(ColIndex)
' If this isn't the "Done" column, or if the user
' clicked with the mouse, then simply continue.
If .DataField <> "Done" Or KeyAscii = 0 Then Exit Sub
' Cancel normal editing and set the field to the
' proper result based upon KeyAscii. Beep if an
' invalid character was typed.
Cancel = True
Select Case UCase$(Chr$(KeyAscii))
Case "Y"
.Value = -1
Case "N"
.Value = 0
Case Else
Beep
End Select
End With
End Sub
Note that the event handler terminates when KeyAscii is zero, so mouse editing is still permitted.

Working with Text

This section briefly describes the properties related to text editing.

Limiting the size of data entry fields

You can use the DataWidth property of a Column object to restrict the number of characters the user can
enter. Setting this property to zero imposes no limits.

Providing a drop-down edit control for long fields

Whenever the user attempts to edit cell text that is too big to fit within the cell, the grid will automatically
activate a multiple-line drop-down text editor. While editing, text in the drop-down edit control will be
wordwrapped regardless of the setting of the column's WrapText property. You can turn off the drop-
down text editor and force editing to occur within cell boundaries by setting the grid's EditDropDown
property to False (the default is True). The drop-down text editor is not available if the grid's
MarqueeStyle property is set to 6 - Floating Editor. The following code uses the grid's built-in column
button feature to activate the drop-down edit control to modify the cell data in the Comments column:
Private Sub Form_Load()
With TDBGrid1
.MarqueeStyle = dbgSolidCellBorder
 Input Masking · 337

.Columns("Comments").Button = True
.EditDropDown = True ' Redundant since default = True
End With
End Sub
Private Sub TDBGrid1_ButtonClick(ByVal ColIndex As Integer)
TDBGrid1.EditActive = True ' Place the cell into edit mode
End Sub
If the current cell is in the Comments column, you can initiate editing either by clicking on the current cell
or by clicking the built-in button.

Changing the insertion mode

You can use the grid's InsertMode property to toggle between insert and overstrike modes within the
built-in text editor. This property is always available, regardless of the settings of the EditDropDown and
MarqueeStyle properties.
By default, InsertMode is True, and each character entered by the user is inserted at the current caret
position. If you set InsertMode to False, the editor operates in overstrike mode, and each character
entered by the user replaces the character immediately after the caret.
At run time, the user can press the INS key to toggle the insertion mode.

Selecting and replacing text

True DBGrid supports the standard text selection properties found in many ActiveX controls:
SelLength Sets/returns the length of the selected text.
SelStart Sets/returns the start position of the selected text.
SelText Sets/returns the selected text.
NOTE: These properties are only effective when the grid is in edit mode, that is, when its EditActive
property is True.

Input Masking
You can use the NumberFormat property to control the display format of column data. If your users need
to edit a formatted column, it is desirable to maintain a consistent format during the editing process. True
DBGrid provides an EditMask property that optionally works in concert with the NumberFormat
property to ensure consistent data entry.

Specifying an input mask for a column

The EditMask property of the Column object is used to specify an input mask template for end-user data
entry. You can construct your own input mask string using template characters similar to those
recognized by the Visual Basic Format$ function. The input mask string is composed of special characters
that represent either an input character that the user must enter, or a literal character that will be skipped
over on input. Valid template characters are as follows:
# Digit placeholder
@ Character placeholder
> All characters following will be in uppercase
< All characters following will be in lowercase
~ Turns off the previous "<" or ">"
338 · Cell Editing Techniques

? Digit or character
\ Next character is treated as a literal
& Any character
Any other character will be treated as a literal. For example, to specify a phone number template, you
could use:
TDBGrid1.Columns("Phone").EditMask = "(###) ###-####"
In this example, the parentheses, space, and hyphen are all literals, while the pound signs signify digit
placeholders.
After the user finishes editing a cell with this input mask, True DBGrid caches the modified cell text, but
any literal characters in the input mask template will be stripped from the modified cell text beforehand.
In the preceding example, only the 10 digits denoted by the # placeholders will be cached; the
punctuation marks and the space will be omitted.

Specifying a date mask for a column

The EditMask property also supports a built-in DateMask option for formatting date fields. When the
DateMask option is selected, the following input mask template will be used for editing:
mm/dd/yyyy
where
mm Month placeholder (01-12)
dd Date placeholder (01-31)
yyyy Year placeholder
The user can enter either 1, 2, 3, or 4 digits in the year portion of the date, and the grid will save the year
as entered by the user. If the user enters 1 or 2 digits for the year portion, the grid will make no
interpretation for the year; that is, the grid will not assume whether it is the century 1900 or 2000, but will
store the 1-digit or 2-digit year as entered. Before the date is updated to the database, you can interpret
the year yourself in code, or let the underlying database system handle the interpretation and storage.
Note that if you select the DateMask option for the EditMask property, the date separators are part of the
date format; they are not considered as literal characters and will always be cached by the grid. This is
because most databases and formatters require the separator characters to be present in order to interpret
the date correctly.

Using an input mask for formatting

Whereas the EditMask property is used to specify an input mask for data entry, the NumberFormat
property is used to specify the display format of data in a grid cell. If the NumberFormat property of the
column is not specified, the grid simply displays the cached text (stripped of literals) as is; if the
NumberFormat property is specified, the grid sends the cached text to the display formatter.
Since it is common for the input and display formats to be the same, the NumberFormat property has an
Edit Mask option. If you select this option, then the EditMask property setting will be used for both data
input and display. However, the input and display formats need not be the same, so you are free to select
a NumberFormat option that differs from the EditMask property.

Controlling how masked input is updated

Normally, after the user finishes editing a cell in a column which has its EditMask property set, True
DBGrid caches the modified cell text, but any literal characters in the input mask template will be
 In-cell Buttons · 339

stripped from the modified cell text beforehand. However, you can override this behavior with the
EditMaskUpdate property.
By default, the EditMaskUpdate property is False. This means that when the modified cell text is updated
to the database, the grid sends the cached text (stripped of literals), not the formatted text displayed in the
cell. You can override this default behavior by setting the EditMaskUpdate property to True, which
causes the cached text to be formatted according to the EditMask property before being updated to the
database.
Therefore, it is important to set EditMaskUpdate properly to ensure that the correct data is sent to the
database for update.

In-cell Buttons
True DBGrid supports a variety of in-cell button options for the current cell or for all cells within
specified columns. You can use in-cell buttons to indicate that a list of choices is available, to perform a
command associated with the contents of the cell, or to display an arbitrary control or form for editing.

Enabling the in-cell button

To enable the in-cell button for a Column object, set its Button property to True on the Splits property
page. Or, in code:
TDBGrid1.Columns(0).Button = True
The Button property is also enabled when the column's DropDown property is set to the name of a
TDBDropDown control, or when the Presentation property of the associated ValueItems collection is set
to one of the combo box options.
By default, the in-cell button displays only for the current cell, as shown in the following figure.

However, by setting the column's ButtonAlways property to True, you can force the in-cell button to be
displayed in every row.
340 · Cell Editing Techniques

Rendering cells as command buttons

To render the current cell as a non-editable command button within a Column object, set its ButtonText
property to True on the Splits property page. Or, in code:
TDBGrid1.Columns(0).ButtonText = True
When a cell within the column receives focus, it is rendered as a standard Windows command button
using the cell text as the caption. The cell text is not centered automatically, but respects the column's
horizontal and vertical alignment settings.

If both the Button and ButtonText properties are True, the ButtonText property takes precedence.
As with the default in-cell button, you can set the column's ButtonAlways property to True to force all of
its cells to be displayed as command buttons. Only the current cell is drawn with a focus rectangle,
however.

Detecting in-cell button clicks

The ButtonClick event is provided so that your code can respond when the user clicks the in-cell button.
Its syntax is as follows:
Private Sub TDBGrid1_ButtonClick(ByVal ColIndex As Integer)
In-cell buttons always fire this event when clicked, regardless of whether they were enabled by the
Button or ButtonText properties. An example of the ButtonClick event was presented earlier in the
section Working with Text (page 336.)

Customizing the in-cell button bitmap

By default, True DBGrid uses a down arrow for the in-cell button.

However, you can change the button bitmap for a Column object at design time by setting the
ButtonPicture property on the Columns property page (not the Splits page). Or, in code:
TDBGrid1.Columns(0).ButtonPicture = LoadPicture("dollar.bmp")
 Drop-down Controls · 341

The grid automatically draws the edges corresponding to the button's up/down states as appropriate, so
you need only provide the interior image of the button. A light gray background is recommended.

Drop-down Controls
True DBGrid offers a wide variety of built-in controls and programming constructs that enable you to
implement virtually any kind of drop-down cell editing interface. You can use the ValueItems collection
to provide a simple pick list, or the TDBDropDown control to implement a data-aware multicolumn
combo box. You can even use arbitrary Visual Basic or third-party controls to perform specialized editing
functions.

Using the built-in combo box

The Column object's ValueItems collection optionally provides a built-in combo box interface that works
in concert with its automatic data translation features. By default, the Presentation property is set to 0 -
Normal, and the usual cell editing behavior is in effect for textual data. However, if you set the
Presentation property to either 2 - Combo Box or 3 - Sorted Combo Box, then cells in the affected column
display the in-cell button upon receiving focus. When the user clicks the in-cell button, a drop-down
combo box appears.

The drop-down combo box contains one item for each member of the ValueItems collection. If the
collection's Translate property is True, then the DisplayValue text is used for the combo box items; if it is
False, then the Value text is used.
True DBGrid automatically sizes the drop-down combo box to fit the width of the column in which it is
displayed. The height of the combo box is determined by the number of items in the collection and the
MaxComboItems property. If the number of items is less than or equal to MaxComboItems, which has a
default value of 5, then all value items will be shown. If the number of items exceeds MaxComboItems,
only MaxComboItems will be shown, but a scroll bar will appear at the right edge of the combo box to
allow users to bring the other items into view.
The AnimateWindow property provides additional control over the animation behavior of the drop-
down combo box as it opens and closes. Use the AnimateWindowTime property to control the duration
of the animation, the AnimateWindowDirection property to control the direction of the animation effect,
342 · Cell Editing Techniques

and the AnimateWindowClose property for additional control over the behavior of the animation when
closing the drop-down combo box.
NOTE: These properties have a system requirement of Windows 98 or NT 5.0, or higher.

Detecting built-in combo box selections

The ComboSelect event is fired when the user selects an item from the built-in combo box. This event is
useful for determining the contents of the cell before the user exits edit mode.
Since the items displayed in the built-in combo box are often the only allowable values for the underlying
data source, you may need to prevent your users from typing in the cell after making a selection. By
setting the EditActive property to False within the ComboSelect event handler, you can force the grid to
exit editing mode without allowing the user a chance to alter the selection (provided that the
MarqueeStyle property is not set to 6 - Floating Editor).
Private Sub TDBGrid1_ComboSelect(ByVal ColIndex As Integer)
TDBGrid1.EditActive = False
End Sub
In this case, it is also a good idea to explicitly disallow keyboard input with the BeforeColEdit event:
Private Sub TDBGrid1_BeforeColEdit(ByVal ColIndex As Integer, _
ByVal KeyAscii As Integer, Cancel As Integer)
If KeyAscii <> 0 Then ' Editing initiated via the keyboard
If TDBGrid1.Columns(ColIndex).Caption = "Columns" Then
Cancel = True
End If
End If
End Sub

Using the TDBDropDown control

The built-in drop-down combo box described in the preceding example is most useful when the
allowable values are both known in advance and relatively few in number. A large ValueItems collection
can be unwieldy to maintain at design time, and requires substantial coding to set up at run time.
Moreover, you cannot bind the built-in combo box to a data control and have it populated automatically.
Using the techniques outlined later in this chapter, you could set up a secondary TDBGrid control to be
used as a drop-down. However, if you need to display a list of values from another data source, the
TDBDropDown control offers a more elegant solution, as it was designed explicitly for that purpose and
can be set up entirely at design time.

To use the drop-down control, set the DropDown property of a grid column to the name of a
TDBDropDown control at either design time or run time. At run time, when the user clicks the in-cell
 Drop-down Controls · 343

button for that column, the TDBDropDown control will appear below the grid's current cell. If the user
selects an item from the drop-down control, the grid's current cell is updated.
Since the TDBDropDown control is a subset of TDBGrid, it shares many of the same properties,
methods, and events. However, the following two properties are specific to the TDBDropDown control:
DataField Not to be confused with the DataField property of a Column object, this property
specifies the drop-down column used to update the associated grid column when a
selection is made.
ListField This property specifies the name of the drop-down column to be used for
incremental search.
When a TDBDropDown control becomes visible, its DropDownOpen event fires. Similarly, when the
user makes a selection or the control loses focus, its DropDownClose event fires.
The TDBDropDown control supports all of the DataMode settings of the TDBGrid control. However, in
order to enable incremental search for unbound, application, and storage modes, you need to implement
the UnboundFindData event.
For more information on the differences between TDBDropDown and TDBGrid, see TDBDropDown at
Design Time (page 179).

Automatic data translation with TDBDropDown

Suppose that you need a grid dropdown using data which contains a value and a corresponding text
representation, as in the following figure:

In this situation, you may not want the user to see the somewhat ambiguous TypeId, but instead want the
more understandable TypeDesc to show in the dropdown. The ValueTranslate property automatically
maps the TypeId value to the TypeDesc representation. In this way, when the user accesses the dropdown,
it will display the TypeDesc text.
The steps to perform the dropdown auto value translation can all be done without code, using the data
control properties, the True DBGrid property pages and the True DBDropDown property pages. To
produce a dropdown using the auto value translation, perform the following steps:
1. Place two data controls (VB Data Control, ADODC, or True DataControl), a True DBGrid control
and a True DBDropDown control on a form.
2. Connect one of the data controls to the C:\Program Files\ComponentOne
Studio\Common\TDBG8DEMO.MDB database table and set the RecordSource property to
Customers. Then connect the True DBGrid to this data control by choosing it in the DataSource
property.
3. Connect second data control to the C:\Program Files\ComponentOne
Studio\Common\TDBG8DEMO.MDB database and set the RecordSource property to CustType.
Then connect the True DBGrid to this data control by choosing it in the DataSource property.
4. Retrieve the fields for both the grid and the dropdown controls by right clicking on each and
selecting Retrieve Fields from the context menu.
344 · Cell Editing Techniques

5. Go to the TDBDropDown1 properties page, set DataField property to TypeID, the ListField
property to TypeDesc and the ValueTranslate property to True.
6. Go to the TDBGrid1 properties page and choose the Splits tab. Expand the Splits(00) tree, then
the Columns tree then the Columns(06) [CustType] tree. Set the Order property to 1, the
AutoCompletion property to True, the AutoDropDown property to True and the Width property
to 1300. Press Apply.
7. Choose the General tab in TDBGrid1 properties page. Expand the Columns tree then the
Columns(06) [CustType] tree. Set the DropDown property to TDBDropDown1. Press Ok to
accept the changes and close the property pages.
8. Go to the TDBDropDown1 properties. On the General tab, expand the Columns tree then the
Columns(00) [TypeID] tree. Set the Visible property to False. Press Ok to accept the changes and
close the property pages.
9. Run the program. The True DBGrid should look like this.

For more information, see Drop-down Controls (page 341 ) and Tutorial 26 (page 100).

Using an arbitrary drop-down control

Normally, True DBGrid's default editing behavior is sufficient for most applications. In some cases,
however, you may want to customize this behavior. One valuable technique is to use a drop-down list or
combo box, or even another True DBGrid control, to allow selection from a list of possible values. This is
easy to do with True DBGrid using virtually any Visual Basic or third-party control. The general
approach follows, and a working example is given in Tutorial 9 (page 46).
In general, displaying a drop-down list or combo instead of the standard True DBGrid editor involves the
following steps:
1. True DBGrid fires the BeforeColEdit event each time the user wants to edit a cell. To override the
default editing process, cancel True DBGrid's default editor by setting the Cancel argument to
True. Put code in BeforeColEdit to display the editing control you wish to show instead.
Typically, you place the substitute editing control or drop-down on the same form as the grid,
but make it invisible until you need it.
2. When BeforeColEdit is triggered, there are five properties and one method you can use to
determine the exact coordinates of the cell which is to be edited. The properties are Left (applies
 Drop-down Controls · 345

to grid and column), Top (grid and column), CellTop (column only, used with multiple line
displays), Width (column only), and RowHeight (grid only). The method is RowTop (grid only).
You can use these properties and method to position the custom editing control or drop-down
relative to a grid cell. For example, you can place a ListBox control at the right edge of a cell and
align its top border with that of the cell using the following code:
Dim Col As TrueDBGrid60.Column
Set Col = TDBGrid1.Columns(ColIndex)
With TDBGrid1
List1.Left = .Left + Col.Left + Col.Width
List1.Top = .Top + .RowTop(.Row)
End With
3. You need to put code in the drop-down or combo which completes the editing process by
assigning the selected value to the Text or Value property of the column being edited.
This method does not work, however, when the grid's MarqueeStyle property is set to the default value
of 6 - Floating Editor. When the floating editor marquee is used, the BeforeColEdit event does not fire
until the cell has been changed by the user. However, you can use the built-in column button feature to
activate the drop-down as described in the next section.
For illustrations of other MarqueeStyle settings, see Highlighting the Current Row or Cell (page 254). An
example of dropping down a Visual Basic ListBox control from a grid cell is given in Tutorial 9 (page 46).

Using the built-in column button

An alternative way to drop down a control from a cell is to use True DBGrid's built-in column button
feature. If you set a column's Button property to True, a button will be displayed at the right edge of the
current cell when it is in that column. Clicking the button fires the grid's ButtonClick event. You can then
drop down a control from the cell using code inside the ButtonClick event. You can also use this event to
trigger any action or calculation inside the cell.
For more information, see In-Cell Buttons (page 339.)
 True DBGrid All Members · 347

Object Reference
True DBGrid All Members
TDBGrid Control Properties
AddNewMode Returns the disposition of the grid's AddNew row
AllowAddNew Enables interactive record addition
AllowArrows Enables use of arrow keys for grid navigation
AllowColMove Enables interactive column movement
AllowColSelect Enables interactive column selection
AllowDelete Enables interactive record deletion
AllowRowSelect Enables interactive row selection
AllowRowSizing Enables interactive row resizing
AllowUpdate Enables interactive record updating
AlternatingRowStyle Controls whether even/odd row styles are applied to a grid
AnchorRightColumn Controls horizontal scrolling when the last column is visible
AnimateWindow Controls the object's animation style
AnimateWindowClose Controls the animation effect when the object is closed
AnimateWindowDirection Controls the direction of the animation effect
AnimateWindowTime Controls the duration of the animation effect
Appearance Controls 3-D display of headings, caption, record selectors
ApproxCount Sets/returns the approximate number of rows
Array Specifies an XArrayDB object as the data source
BackColor Sets/returns the background color
Bands Specifies the number of levels within a hierarchical recordset
BatchUpdates Specifies batch update mode
BOF Returns beginning-of-file status
Bookmark Sets/returns bookmark of current row
BookmarkType Sets/returns the variant type used for passing bookmarks
BorderStyle Sets/returns style for grid border
Caption Sets/returns grid caption text
CaptionStyle Controls the caption style for a grid
CellTips Enables pop-up cell tip window when the cursor is idle
CellTipsDelay Sets/returns idle time for cell tip window
CellTipsWidth Sets/returns width of cell tip window
348 · Object Reference

ChildGrid Sets the child grid control when using master/detail

Col Sets/returns current column number
CollapseColor Changes the color of the collapse icon for hierarchical recordsets
ColumnFooters Turns column footings on or off
ColumnHeaders Turns column headings on or off
Columns Contains a collection of True DBGrid columns
CurrentCellModified Sets/returns modification status of the current cell
CurrentCellVisible Sets/returns the visibility of the current cell
DataChanged Sets/returns modification status of the current row
DataMember Sets/returns a data member offered by an OLE DB provider
DataMode Specifies bound or unbound mode
DataSource Specifies source of grid data
DataView Returns or sets how the grid will display master-detail recordsets
DeadAreaBackColor Sets/returns the background color of the control's dead area
DefColWidth Specifies column width for auto-created columns
DestinationCol Returns destination column number during cell movement
DestinationRow Returns destination row bookmark during cell movement
DestinationSplit Returns destination split number during cell movement
DirectionAfterEnter Specifies the position of the next cell after enter
DirectionAfterTab Sets or returns the new cell position when the Tab key is pressed
EditActive Returns status or enters/exits the cell editor
EditBackColor Sets/returns the editor background color
EditDropDown Controls whether a drop-down window is used for editing
EditForeColor Sets/returns the editor foreground color
EditorStyle Controls the editor style for a grid
EmptyRows Enables empty rows in an underpopulated grid
Enabled Enables or disables user interaction
EOF Returns end-of-file status
Errors Contains a collection of TDBGrid error objects
ErrorText Returns the error message associated with the Error event
EvenRowStyle Controls the row style for even-numbered rows
ExpandColor Changes the color of the expand icon for hierarchical recordsets
ExportEOF True if there are no more rows to export
ExportNextBookmark Returns the bookmark after the last exported row
ExposeCellMode Controls behavior of clicked rightmost visible cell
ExtendRightColumn True if rightmost column extends to edge of split
FetchRowStyle Controls whether the FetchRowStyle event will be fired
 True DBGrid All Members · 349

FilterActive Returns True if you are currently editing within the filter bar
FilterBar When set to True, the grid displays a row of data under the column
headers in which the user can type.
FilterBarStyle Controls the style of the columns in the filter bar
FirstRow Bookmark of row occupying first display line
Font Specifies the overall font for a grid
FooterBackColor Sets/returns the footing background color
FooterFont Specifies the footing font for a grid
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a grid
FootLines Number of lines allocated for footing text
ForeColor Sets/returns the foreground color
GroupByCaption Sets/returns the text displayed in the grouping area when no group
is defined
GroupColumns Contains a collection of grouped grid column objects
HeadBackColor Sets/returns the heading background color
HeadFont Specifies the heading and caption font for a grid
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a grid
HeadLines Number of lines allocated for heading text
HighlightRowStyle Controls the marquee style when set to Highlight Row
HScrollHeight Returns the horizontal scroll bar height, if present
hWnd Returns the window handle of the grid
hWndEditor Returns the window handle of the grid's editor
InactiveBackColor Sets/returns the inactive heading background color
InactiveForeColor Sets/returns the inactive heading foreground color
InactiveStyle Controls the inactive heading style for a grid
InsertMode Sets/returns the insertion mode for the grid's editor
LayoutFileName Sets/returns the name of a file containing grid layouts
LayoutName Sets/returns the name of the current grid layout
Layouts Returns a collection of layout names
LayoutURL Sets/returns the URL used for downloading grid layouts
LeftCol Sets/returns the leftmost visible column
MarqueeStyle Returns current split marquee style, sets all splits
MarqueeUnique Restricts display of marquee to current split
MaxRows Maximum number of rows that can be shown in the control
MouseIcon Sets/returns a custom mouse icon
350 · Object Reference

MousePointer Sets/returns the mouse pointer type

MultipleLines Controls whether individual records span multiple lines
MultiSelect Sets/returns the type of selection allowed in the grid
OddRowStyle Controls the row style for odd-numbered rows
OLEDragMode Controls whether a grid handles OLE drag operations
OLEDropMode Controls whether a grid handles OLE drop operations
PartialRightColumn True if rightmost column can be clipped to edge of split
PictureAddNewRow Sets/returns the record selector bitmap for the AddNew row
PictureCurrentRow Sets/returns the record selector bitmap for the current row
PictureFilterBar Sets/returns the bitmap used in the record selector column
PictureFooterRow Sets/returns the record selector bitmap for the footer row
PictureHeaderRow Sets/returns the record selector bitmap for the header row
PictureModifiedRow Sets/returns the record selector bitmap for modified rows
PictureStandardRow Sets/returns the record selector bitmap for standard rows
PrintInfo Returns the default printer information object
PrintInfos Contains a collection of printer information objects
RecordSelectors Shows/hides selection panel at left border
RecordSelectorStyle Returns the style object that controls the appearance of
RecordSelectors
RecordSelectorWidth Sets/returns the width of the RecordSelector
RightToLeft When True, applies right to left text functionality
Row Specifies display line of current data row
RowDividerColor Controls the row divider color
RowDividerStyle Selects style of row divider lines
RowHeight Specifies height of all grid rows
RowSubDividerColor Controls the row subdivider color
ScrollBars Sets/returns scroll bar style for the grid
ScrollTips Determines whether the grid displays a pop-up window
ScrollTrack Scrollbar thumb causes the grid display to update
SelBookmarks Contains a collection of selected row bookmarks
SelectedBackColor Sets/returns the selected row background color
SelectedForeColor Sets/returns the selected row foreground color
SelectedStyle Controls the selected row and column style for a grid
SelEndCol Sets/returns rightmost selected column
SelLength Sets/returns length of selected text
SelRange Returns true if a range of cells is currently selected.
SelStart Sets/returns start of selected text
 True DBGrid All Members · 351

SelStartCol Sets/returns leftmost selected column

SelText Sets/returns the selected text
Split Sets/returns current split number
Splits Contains a collection of True DBGrid splits
SpringMode Sets/returns how columns size when the split is resized
Style Controls the normal style for a grid
Styles Contains a collection of True DBGrid styles
TabAcrossSplits Allows tab and arrow keys to cross split boundaries
TabAction Defines the behavior of the tab key
Text Sets/returns displayed cell text for the current row
TransparentRowPictures True if record selector pictures use a transparent color mask
ViewColumnCaptionWidth Width of the Column caption in Form or Inverted DataView
ViewColumnWidth Width of the Column in Form or Inverted DataView
VisibleCols Returns number of visible columns
VisibleRows Returns number of visible display rows
VScrollWidth Returns the vertical scroll bar width, if present
WrapCellPointer Defines behavior of tab and arrow keys at row boundaries
WrapRowPointer Defines behavior of tab and arrow keys at column boundaries

TDBGrid Control Methods

AboutBox Displays the About box
AddCellStyle Adds a cell condition to a grid
AddRegexCellStyle Adds a regular expression cell condition to a grid
CaptureImage Returns a captured image of a grid's display
CellContaining Identifies a row and column under an X, Y coordinate pair
ClearCellStyle Removes a cell condition from a grid
ClearFields Clears the current column/field layout
ClearRegexCellStyle Removes a regular expression cell condition from a grid
ClearSelCols Deselects all selected columns in the current split
Close Disconnects a grid from its data source
ColContaining Identifies a column under an X coordinate
CollapseBand Collapses all rows for the specified band
CollapseChild Collapses the child grid
Delete Deletes the current row and moves to the next row
ExpandBand Expands all rows for the specified band
ExpandChild Expands the child grid
ExportBegin Begins grid export to a file
352 · Object Reference

ExportEnd Ends grid export to a file

ExportRows Exports a sequence of grid rows to a file
ExportToDelimitedFile Exports specified rows to a delimited text file
ExportToFile Exports specified rows as an HTML table
GetBand Returns the band for a specified column index
GetBookmark Returns a bookmark relative to the current row
HoldFields Uses the current column/field layout for all displays
IsSelected Returns the SelBookmarks collection index for a bookmark
LoadLayout Loads a saved layout
MoveFirst Moves to the first row
MoveLast Moves to the last row
MoveNext Moves to the next row
MovePrevious Moves to the previous row
MoveRelative Moves to the specified row and offset
OLEDrag Initiates an OLE drag/drop operation
PointAt Returns the kind of grid element under an X, Y coordinate pair
PostMsg Posts a message to a grid to fire the PostEvent event
ReBind Reinitializes a grid from its data source
RefetchCol Refetches data for a specified grid column
RefetchRow Refetches data for a specified grid row
Refresh Updates a grid's screen display
RefreshCol Updates the display for a specified grid column
RefreshRow Updates the display for a specified grid row
ReOpen Reconnects a grid to its data source
RowBookmark Returns the bookmark corresponding to a display row
RowContaining Identifies a row under a Y coordinate
RowExpanded Returns True if current row is expanded within the specified band
RowTop Returns the Y position of a row's top border
Scroll Scrolls a grid's data area
SplitContaining Identifies a split under an X, Y coordinate pair
Update Updates a grid's current row

TDBGrid Control Events

AfterColEdit Fired after column data is edited
AfterColUpdate Occurs after data moves from cell to the grid buffer
AfterDelete Occurs after record deletion from grid
AfterInsert Occurs after record insertion in grid
 True DBGrid All Members · 353

AfterUpdate Occurs after record changes are written to the database

BeforeColEdit Fired upon an attempt to edit column data
BeforeColUpdate Occurs before data moves from cell to the grid buffer
BeforeDelete Occurs before record deletion from grid
BeforeInsert Occurs before record insertion in grid
BeforeOpen Occurs when the user clicks the + indicator in a cell
BeforeRowColChange Occurs before a different cell becomes current
BeforeUpdate Occurs before record changes are written to the database
ButtonClick Occurs when a column button has been clicked
Change Occurs when the grid contents have changed
ClassicAdd Fired when a new row is added to the unbound dataset
ClassicDelete Fired when an unbound row needs to be deleted
ClassicRead Fired when the grid requires unbound data for display
ClassicWrite Fired when an unbound row needs to be modified
Click Fired when a mouse click occurs
ColEdit Fired when column data is edited
Collapse Fired when a band is collapsed by a user
ColMove Occurs before grid repainting when columns are moved
ColResize Occurs before grid repainting when a column is resized
ComboSelect Fired when the user selects a ValueItems combo entry
DataSourceChanged Fired when the data source changes
DblClick Fired when a mouse double click occurs
DragCell Fired when a drag operation is initiated
Error Occurs when an associated action fails
Expand Fired when a band is expanded by a user
FetchCellStyle Fired when the FetchStyle property is set to
dbgFetchCellStyleColumn or dbgFetchCellStyleAddNewColumn for
a column
FetchCellTips Fired when the CellTips property is set to True
FetchRowStyle Fired when the FetchRowStyle property is set to True
FetchScrollTips Fired when ScrollTips is set to 0 – None
FirstRowChange Fired when the FirstRow property changes
FilterButtonClick If True, fires when the button is pressed in the filter cell
FilterChange Fired when a user types in the filter cell
FootClick Occurs when a column footer has been clicked
FormatText Fired when specified by the NumberFormat property
GroupColMove Occurs before a column is moved to or from the grouping area
354 · Object Reference

GroupHeadClick Occurs when a column header is clicked in the grouping area

HeadClick Occurs when a column header has been clicked
KeyDown Occurs when a key is pressed
KeyPress Occurs when an ANSI key is pressed and released
KeyUp Occurs when a key is released
LayoutReady Fired when downloading of a layout file is complete
LeftColChange Fired when the LeftCol property changes
MouseDown Occurs when a mouse button is pressed
MouseMove Occurs when the mouse moves
MouseUp Occurs when a mouse button is released
OLECompleteDrag Occurs when a drag action is performed or canceled
OLEDragDrop Occurs when a drop action is performed or canceled
OLEDragOver Occurs when a component is dragged over the grid
OLEGiveFeedback Occurs after every OLEDragOver event
OLESetData Occurs when data is requested in a particular format
OLEStartDrag Occurs when a drag operation is initiated
OnAddNew Fired when a user action causes an AddNew operation
OnInit Occurs when the grid is initially loaded
OwnerDrawCell Fired when an owner-drawn cell is about to be rendered
OwnerDrawCellPrint Fired when an owner-drawn cell is about to be printed
OwnerDrawPageFooter Fired to draw owner-drawn page footer while printing
OwnerDrawPageHeader Fired to draw owner-drawn page header while printing
Paint Fired when the grid repaints itself
PostEvent Occurs after a PostMsg method is called
RowColChange Occurs when a different cell becomes current
RowResize Occurs when rows are resized
Scroll Occurs when the grid is scrolled using the scroll bars
SelChange Occurs when the current selected cell range changes
SplitChange Occurs when a different split becomes current
UnboundAddData Fired when a new row is added to the unbound dataset
UnboundColumnFetch Fetches unbound column data when the grid is bound
UnboundDeleteRow Fired when an unbound row needs to be deleted
UnboundGetRelativeBookmark Fired when the grid needs a relative bookmark
UnboundReadData Fired when the grid requires unbound data for display
UnboundReadDataEx Fired when the grid requires unbound data for display
UnboundWriteData Fired when an unbound row needs to be modified
ValueItemError Fired when invalid data is typed into a ValueItems column
 True DBGrid All Members · 355

Column Object Properties

Alignment Specifies horizontal text alignment
AllowFocus Controls whether a column can receive focus
AllowSizing Enables interactive resizing for a column
AutoCompletion If True, the dropdown auto fills with the matched entry
AutoDropDown True if a drop-down control opens when a character is typed
BackColor Sets/returns the background color
Button Controls whether a button appears within the current cell
ButtonAlways Controls when an in-cell button is displayed
ButtonFooter Controls whether a column footer acts like a standard button
ButtonHeader Controls whether a column header acts like a standard button
ButtonPicture Sets/returns the bitmap used for the in-cell button
ButtonText Controls whether a cell is rendered as a button
Caption Sets/returns column heading text
CellTop Returns top column border, adjusted for multiple lines
ColIndex Returns the ordinal position of a column
ConvertEmptyCell Specifies if empty cells are saved as empty strings or Null values
Count This property returns the number of items in a collection.
DataChanged Sets/returns modification status of a column in current row
DataField Data table field name for a column
DataWidth Maximum number of characters available for column input
DefaultValue Default value for new column data
DisplayAlignment Returns the actual rendering of general horizontal alignment
DividerColor Controls the divider color of a split or column divider
DividerStyle Specifies the position of the next cell after enter
DropDown Sets the TDBDropDown control for a column
DropDownList Controls whether a TDBDropDown control acts like a list
EditBackColor Sets/returns the editor background color
EditForeColor Sets/returns the editor foreground color
EditMask Input mask string for a column
EditMaskRight Controls whether the edit mask is applied from right to left
EditMaskUpdate Controls whether masked data is used for updates
EditorStyle Controls the editor style for a column
ExternalEditor Sets the ActiveX input control for a column
FetchStyle Controls whether the FetchCellStyle event fires for a column
FilterButton If True, displays a button in the current filter cell
FilterButtonPicture Sets/returns the bitmap for the in-cell button in the current filter
356 · Object Reference

FilterText Sets/returns the data associated with the value of the filter
Font Specifies the overall font for a column
FooterAlignment Specifies column footing alignment
FooterBackColor Sets/returns the footing background color
FooterDivider Controls display of dividing line in column footer
FooterFont Specifies the footing font for a column
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a column
FooterText Column footing text
ForeColor Sets/returns the foreground color
Group Returns whether the column is being grouped
HeadAlignment Specifies column heading alignment
HeadBackColor Sets/returns the heading background color
HeaderDivider Controls display of dividing line in column header
HeadFont Specifies the heading font for a column
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a column
Left Returns column left border in container coordinates
Locked If true, data entry prohibited for a column
Name (Column) Returns the name of the associated database field (if available)
Merge True if a column should merge adjacent rows of like-valued cells
MinWidth Sets/returns the column can resize when in SpringMode
NumberFormat Data formatting string for a column
Order Sets/returns the display position of a column
OwnerDraw Controls whether the OwnerDrawCell event fires for a column
Style Controls the normal style for a column
TableName Returns the name of the associated table, if available
Tag Stores extra data needed for your program
Text Sets/returns displayed cell text for the current row
Top Returns top column border in container coordinates
Value Sets/returns underlying data value for the current row
ValueItems Contains a collection of ValueItems for a column
Visible Shows/hides a column
Width Sets/returns column width in container coordinates
WrapText True if cell text is word wrapped
 True DBGrid All Members · 357

Column Object Methods

AddCellStyle Adds a cell condition to a column
AddRegexCellStyle Adds a regular expression cell condition to a column
AutoSize Autosizes the column width
CellText Returns displayed text for any row
CellValue Returns underlying value for any row
ClearCellStyle Removes a cell condition from a column
ClearRegexCellStyle Removes a regular expression cell condition from a column
Fix Fixes or unfixes a column from scroll
Refetch Refetches column data from its data source
RefetchCell Refetches data for a specified cell within a column
Refresh Updates a column's screen display
RefreshCell Updates the display for a specified cell within a column

Columns Collection Properties

Count Returns the number of columns in the collection

Columns Collection Methods

Add Adds a new column to the collection
Clear Removes all items from a collection.
Item Returns a single column object given a name or index
Remove Removes an existing column from the collection

DataObject Object Properties

Files Contains a collection of filenames used by a DataObject object

DataObject Object Methods

Clear Deletes the contents of a data object
GetData Retrieves data of the specified format from a data object
GetFormat Determines if a data object supports a specified clipboard format
SetData Adds a supported format and possibly its data to a data object

Error Object Properties

Description Returns a short description of the error that occurred
HelpContext Returns context ID of help topic associated with error
HelpFile Returns pathname of help file associated with error
NativeError Returns provider-specific error code for this error
Number Returns number that uniquely identifies this error
Source Returns name of object that generated the error
358 · Object Reference

SQLState Returns five character SQL error code

Errors Collection Properties

Count Returns the number of error objects in the collection

Errors Collection Methods

Clear Removes all error objects from the collection
Item Returns a single error object given an index

GroupColumns Collection Properties

Count Returns the number of columns in the collection

GroupColumns Collection Methods

Add Adds a new column to the collection
Item Returns a single column object given a name or index
Remove Removes an existing column from the collection

Layouts Collection Properties

Count Returns the number of layouts in the collection

Layouts Collection Methods

Add Adds a new layout to the collection
Item Returns the name of a layout given an index
Remove Removes an existing layout from the collection

PrintInfos Collection Properties

Count Returns the number of PrintInfo objects in the collection

PrintInfos Collection Methods

Add Adds a new named printer information object to the collection
Clear Removes all printer information objects from the collection
Item Returns a single printer information object given an index
Remove Removes a printer information object from the collection

RowBuffer Object Properties

Bookmark Sets/returns bookmark of specified row
ColumnCount Returns the number of columns
ColumnIndex Returns the column index of a column
ColumnName Returns the field name of a column
RowCount Returns the number of rows
Value Sets/returns data value of specified row/column
 True DBGrid All Members · 359

SelBookmarks Collection Properties

Count Returns the number of selected rows

SelBookmarks Collection Methods

Add Adds a bookmark to the list of selected rows
Item Returns an individual selected row bookmark
Remove Removes a bookmark from the list of selected rows

Split Object Properties

AllowColMove Enables interactive column movement
AllowColSelect Enables interactive column selection
AllowFocus Allows cells within a split to receive focus
AllowRowSelect Enables interactive row selection
AllowRowSizing Enables interactive row resizing
AllowSizing Enables interactive resizing for a split
AlternatingRowStyle Controls whether even/odd row styles are applied to a split
AnchorRightColumn Controls horizontal scrolling when the last column is visible
BackColor Sets/returns the background color
Caption Sets/returns split caption text
CaptionStyle Controls the caption style for a split
Columns Returns a collection of column objects for a split
CurrentCellVisible Sets/returns modification status of the current cell
DividerStyle Specifies the position of the next cell after enter
EditBackColor Sets/returns the editor background color
EditForeColor Sets/returns the editor foreground color
EditorStyle Controls the editor style for a split
EvenRowStyle Controls the row style for even-numbered rows
ExtendRightColumn Sets/returns extended right column for a split
FetchRowStyle Controls whether the FetchRowStyle event will be fired
FilterActive Returns True if you are currently editing within the filter bar
FilterBar When True, displays a row of data under the column headers
FilterBarStyle Returns the style object that controls the FilterBar cell appearance
FirstRow Bookmark of row occupying first display line
Font Specifies the overall font for a split
FooterBackColor Sets/returns the footing background color
FooterFont Sets/returns the footing font for a split
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a split
360 · Object Reference

ForeColor Sets/returns the foreground color

HeadBackColor Sets/returns the heading background color
HeadFont Specifies the heading font for a split
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a split
HighlightRowStyle Controls the marquee style when set to Highlight Row
HScrollHeight Returns the horizontal scroll bar height, if present
InactiveBackColor Sets/returns the inactive heading background color
InactiveForeColor Sets/returns the inactive heading foreground color
InactiveStyle Controls the inactive heading style for a split
Index Returns the ordinal index of a split
LeftCol Returns the leftmost visible column
Locked If true, data entry prohibited for a split
MarqueeStyle Sets/returns marquee style for a split
OddRowStyle Controls the row style for odd-numbered rows
PartialRightColumn True if rightmost column can be clipped to edge of split
RecordSelectors Shows/hides selection panel at left border
ScrollBars Sets/returns scroll bar style for a split
ScrollGroup Used to synchronize vertical scrolling between splits
SelectedBackColor Sets/returns the selected row background color
SelectedForeColor Sets/returns the selected row foreground color
SelectedStyle Controls the selected row and column style for an object
SelEndCol Sets/returns rightmost selected column
SelRange If True, the user has selected a range of cells
SelStartCol Sets/returns leftmost selected column
ShowCollapseExpandIcons Used to disable the displaying of expand/collapse icons
Size Sets/returns split width according to SizeMode
SizeMode Controls whether a split is scalable or fixed size
Style Controls the normal style for an object
VScrollWidth Returns the vertical scroll bar width, if present

Split Object Methods

AddCellStyle Adds a cell condition to a split
AddRegexCellStyle Adds a regular expression cell condition to a split
ClearCellStyle Removes a cell condition from a split
ClearRegexCellStyle Removes a regular expression cell condition from a split
ClearSelCols Deselects all selected columns in a split
 True DBGrid All Members · 361

Splits Collection Properties

Count Returns the total number of splits

Splits Collection Methods

Add Adds a new split at the given index
Item Returns a single split object given an index
Remove Removes the split with the given index

Style Object Properties

Alignment Specifies the horizontal text alignment
BackColor Controls the background color
BackgroundPicture Sets/returns the background picture associated with a style
BackgroundPictureDrawMode Controls how a style's background picture is displayed
BorderAppearance Controls the appearance of the cell borders
BorderColor Specifies the color for the border
BorderSize Specifies the size of cell border
BorderType Controls which, if any, cell borders are displayed
EllipsisText When True, displays an ellipsis (…) at the end of cell text
Font Specifies the typeface, size, and other text characteristics
ForeColor Controls the foreground color
ForegroundPicture Sets/returns the foreground picture associated with a style
ForegroundPicturePosition Controls how a style's foreground picture is positioned
Locked Disallows in-cell editing when true
Name (Style) Returns the programmer-specified style name
Parent Sets/returns the object from which a style inherits
TransparentForegroundPicture True if a style's foreground picture uses a transparent color mask
Value Returns the programmer-specified style name
VerticalAlignment Specifies vertical text alignment
WrapText Word wraps cell text when true

Style Object Methods

Reset Resets style properties to inherited values

Styles Collection Properties

Count Returns the number of styles in the collection

Styles Collection Methods

Add Adds a new named style to the collection
Item Returns a single style object given a name or index
362 · Object Reference

Remove Removes an existing style from the collection

ValueItem Object Properties

DisplayValue Sets/returns displayed text or graphics
Value Sets/returns untranslated data value

ValueItems Collection Properties

AnnotatePicture True to show both underlying data and display value graphics
Count Returns the number of value items in the collection
CycleOnClick True to cycle through value items on click
DefaultItem Index of default value item, or -1 if no default
MatchCase Allows you to do case-sensitive searches for Translations
MaxComboItems Maximum number of items shown in a drop-down combo
Presentation Specifies how value items are displayed
Translate True to translate data values to display values
Validate True to auto-validate input values

ValueItems Collection Methods

Add Appends a new value item to the collection
Clear Removes all value items from the collection
Item Returns a single value item given an index
Remove Removes a value list item from the collection

True DBGrid Properties

AddNewMode Property
The AddNewMode property returns a value that describes the location of the current cell with respect to
the grid's AddNew row.
Syntax
TDBGrid.AddNewMode
Values
Run Time
0 - No AddNew pending dbgNoAddNew
1 - Current cell in AddNew row dbgAddNewCurrent
2 - AddNew pending dbgAddNewPending
Remarks
Read-only at run time. Not available at design time.
 Alignment Property · 363

If the AllowAddNew property is True, the last row displayed in the grid is left blank to permit users to
enter new records. If the AllowAddNew property is False, the blank row is not displayed, and
AddNewMode always returns 0.
When AllowAddNew is True, the AddNewMode property returns one of the following values:
dbgNoAddNew The current cell is not in the last row, and no AddNew operation is pending.
dbgAddNewCurrent The current cell is in the last row, but no AddNew operation is pending.
dbgAddNewPending The current cell is in the next to last row as a result of a pending AddNew
operation initiated by the user through the grid's user interface, or by code
as a result of setting the Value or Text properties of a column.
Note
This property is valid in both bound and unbound modes.
See Also
TDBGrid Control (page 118)

Alignment Property
The Alignment property returns or sets a value that determines the horizontal alignment of the values in
a grid column or style object.
Syntax
object.Alignment = value
Values
Design Time Run Time
0 - Left dbgLeft
1 - Right dbgRight
2 - Center dbgCenter
3 - General (default) dbgGeneral
Remarks
Read/Write at run time and design time.
For data cells, the setting 3 - General means that text will be left-aligned and numbers will be right-
aligned. This setting is only useful in bound mode, where the grid can query the data source to determine
the data types of individual columns.
For column headers and footers, the setting 3 - General means that the alignment of the column's data cells
should be used. Thus, if a column's data cells, headers, and footers all use general alignment, then the
underlying data type determines the alignment for all aspects of the column's display.
Note
At run time, you can use the DisplayAlignment property to determine how general alignment was
actually rendered in the grid's display.
364 · Object Reference

See Also
Column Object (page 119)
Style Object (page 122)

AllowAddNew Property
Enables interactive record addition.
Syntax
TDBGrid.AllowAddNew = boolean
Remarks
Read/Write at run time and design time.
If True, the user can add records to the data source underlying the TDBGrid control.
If False (the default), the user cannot add records to the data source underlying the TDBGrid control.
If the AllowAddNew property is True, the last row displayed in the grid is left blank to permit users to
enter new records. If the AllowAddNew property is False, the blank row (usually referred to as the
AddNew row) is not displayed.
The underlying data source may not permit insertions even if the AllowAddNew property is True for the
TDBGrid control. In this case, a trappable error occurs when the user tries to add a record.
Note
If AllowAddNew is True, you should also set AllowUpdate to True so that users will be able to type in
the cells of the AddNew row.
See Also
TDBGrid Control (page 118)

AllowArrows Property
Enables use of arrow keys for grid navigation.
Syntax
TDBGrid.AllowArrows = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the user can use the arrow keys to move from cell to cell within the same row.
If False, the left and right arrow keys will move focus from control to control and cannot be used to move
between cells.
The user cannot use the arrow keys to move out of the TDBGrid control when this property is set to True.
If the WrapCellPointer property is also set to True, then the arrow keys will wrap around rows and the
user can navigate the entire grid using the arrow keys.
See Also
TDBGrid Control (page 118)
 AllowColMove Property · 365

AllowColMove Property
Enables interactive column movement.
Syntax
object.AllowColMove = boolean
Remarks
Read/Write at run time and design time.
If True, the user can move selected columns.
If False (the default), the user cannot move selected columns.
Use the AllowColMove property to control whether the user can move selected columns by dragging the
column divider highlight bar to the desired location. Any change in column order causes a ColMove
event.
If AllowColMove is set to True, and the DataView property is set to 2 - Group, a grouping area is added
to the grid. Columns can be added or dragged to this area at run time, creating a new split for enhanced
data display.
See Outlook-Style Grouping (page 278) for more information.
Note
The AllowColSelect property must also be True in order for the user to move selected columns.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

AllowColSelect Property
Enables interactive column selection.
Syntax
object.AllowColSelect = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the user can select columns.
If False, the user cannot select columns.
Use the AllowColSelect property to control whether the user can select columns by clicking or dragging
within the column header area. Setting this property to False suppresses highlighting when the user clicks
a column header, which is useful for applications that respond to the HeadClick event.
Note
Both the AllowColSelect and AllowColMove properties must be True in order for the user to move
selected columns.
366 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

AllowDelete Property
Enables interactive record deletion.
Syntax
TDBGrid.AllowDelete = boolean
Remarks
Read/Write at run time and design time.
If True, the user can delete records from the data source underlying the TDBGrid control.
If False (the default), the user cannot delete records from the data source underlying the TDBGrid
control.
Use the AllowDelete property to prevent the user from deleting records from the data source through
interaction with the TDBGrid control.
The underlying data source may not permit deletions even if the AllowDelete property is True for the
TDBGrid control. In this case, a trappable error occurs when the user tries to delete a record.
See Also
TDBGrid Control (page 118)

AllowFocus Property
Controls whether a column can receive focus.
Syntax
object.AllowFocus = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the user will be able to interactively select the object, giving it focus.
If False, the user will not be able to interactively select the object. When clicked, the object will not receive
focus and the control (or grid column) that previously had focus will retain it.
For both split and column objects, setting AllowFocus to True enables cells within the object to receive
focus. If set to False, there is no way to change the focus to a cell within the object. However, if an object
already has the focus, setting AllowFocus to False will not give focus to another split, column, or control.
If a cell in a column which does not allow focus is clicked, and the cell is in a row other than the current
row, then the row is changed, but the column with the focus retains it.
 AllowRowSelect Property · 367

For splits, you can use this property in combination with the AllowSizing property to completely
prohibit the user from making any changes to a split (by setting both properties to False). Unselectable
splits are passed over when TabAcrossSplits is set to True.
For columns, AllowFocus is a split-specific property, which means that the following statements are
equivalent:
TDBGrid1.Columns(1).AllowFocus = True
TDBGrid1.Splits(TDBGrid1.Split).Columns(1).AllowFocus = True
In other words, both of these statements affect column 1 in the current split only.
Note
At design time, the AllowFocus property appears in both the Splits property page (for Split objects) and
the Layout property page (for Column objects).
See Also
Column Object (page 119)
Split Object (page 122)

AllowRowSelect Property
Enables interactive row selection.
Syntax
object.AllowRowSelect = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the user can select rows.
If False, the user cannot select rows.
Use the AllowRowSelect property to control whether the user can select rows by clicking the record
selector buttons. By setting this property to False, you can disable record selection without hiding the
record selectors altogether, since you may want to use the record selectors to provide visual feedback
when the current row is modified.
When AllowRowSelect is True, the MultiSelect property controls the behavior of the record selector
buttons with respect to the CTRL, SHIFT, and keypad navigation keys.
Note
The user cannot select rows if the RecordSelectors property is set to False for all splits, even if
AllowRowSelect is True.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

AllowRowSizing Property
Enables interactive row resizing.
368 · Object Reference

Syntax
object.AllowRowSizing = boolean
Remarks
Read/Write at run time. Read/Write at design time (TDBDropDown, Split). Read-only at design time
(TDBGrid).
If the AllowRowSizing property is True, the mouse pointer turns into a double-headed arrow when
positioned over the row divider in the RecordSelectors column between any pair of record selectors in
the grid. For a TDBDropDown control, the mouse cursor must be moved over a row divider at the left
edge of the control (where the RecordSelectors would be if they were present). In either case, the user
can interactively resize the rows by dragging the mouse while the double-headed arrow cursor is
showing. Any change in row size causes a RowResize event to fire.
If the AllowRowSizing property is False, the user cannot interactively resize rows.
All rows of the TDBGrid control are always the same height, which is determined by the RowHeight
property.
The default value of the property is True for the TDBGrid control and Split object, False for the
TDBDropDown control.
Note
RecordSelectors must be visible in a split in order for the user to resize rows interactively in that split. If
RecordSelectors are disabled for all splits in a TDBGrid control, the user cannot resize rows interactively
in that grid. This restriction does not apply to the TDBDropDown control.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

AllowSizing Property
Enables interactive resizing for a column or split.
Syntax
object.AllowSizing = boolean
Remarks
Read/Write at run time and design time.
If True, the user can resize the column or split.
If False, the user cannot resize the column or split.
For columns, AllowSizing defaults to True. For splits, AllowSizing defaults to False.
If AllowSizing is True for a column, the mouse pointer turns into a double-headed arrow when
positioned over that column's divider within the column heading area, and the user can resize the
column by dragging. Any change in column size causes a ColResize event.
 AllowUpdate Property · 369

For the leftmost split with AllowSizing set to True, the mouse pointer turns into a pair of vertical lines
with a downward arrow when positioned over that split's size box (at the lower left corner), and the user
can create a new split by dragging. The creation of a new split causes a SplitChange event.
If AllowSizing is True for any other split, the mouse pointer turns into a pair of vertical lines with a
double-headed arrow when positioned over that split's size box, and the user can resize the split by
dragging. No event is fired in this case (except for the standard mouse events).
See Also
Column Object (page 119)
Split Object (page 122)

AllowUpdate Property
Enables interactive record updating.
Syntax
TDBGrid.AllowUpdate = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the user can modify data in the TDBGrid control.
If False, the user cannot modify data in the TDBGrid control.
When the AllowUpdate property is False, the user can still scroll through the TDBGrid control and select
data, but cannot change any of the values; any attempt to change the data in the grid is ignored.
The underlying data source may not permit updates even if the AllowUpdate property is True for the
TDBGrid control. In this case, a trappable error occurs when the user tries to change the record.
You can also use the Column object's Locked property to make individual columns of the TDBGrid
control read-only, even if the AllowUpdate property is True. However, if AllowUpdate is False, then this
setting takes precedence over the column settings (without changing the column settings).
See Also
TDBGrid Control (page 118)

AlternatingRowStyle Property
This property determines whether a grid or split displays odd-numbered rows in one style and even-
numbered rows in another.
Syntax
object.AlternatingRowStyle = boolean
Remarks
Read/Write at run time and design time.
If True, the OddRowStyle and EvenRowStyle properties control the appearance of rows within the
specified object.
If False (the default), the Style property controls the display of rows within the specified object.
370 · Object Reference

At design time, you can change the colors and fonts used to render odd (even) rows by modifying the
built-in OddRow (EvenRow) style using the Styles property page.
At run time, you can change the colors and fonts used to render odd (even) rows by modifying the Style
object returned by the OddRowStyle (EvenRowStyle) property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

AnchorRightColumn Property
This property controls the behavior of horizontal scrolling in a grid or split when the last column is
visible.
Syntax
object.AnchorRightColumn = boolean
Remarks
Read/Write at run time and design time.
If True, the user can scroll horizontally until the last column is completely visible. If there is at least one
visible column to the left of the last column, then the last column cannot become the leftmost column.
If False (the default), the user can scroll horizontally until the last column becomes the leftmost column.
The area between the last column and the end of the grid or split will be filled using the system 3D
Objects color (or the system Button Face color) as determined by your Control Panel settings.
If a grid contains multiple splits, then setting its AnchorRightColumn property has the same effect as
setting the AnchorRightColumn property of each split individually.
Note
If PartialRightColumn is False, or ExtendRightColumn is True, then the value of the
AnchorRightColumn property is ignored, and the grid or split behaves as if it were set to True.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

AnimateWindow Property
Controls the object's animation style.
Syntax
TDBGrid.AnimateWindow = value
 AnimateWindowClose Property · 371

Values
Design Time Run Time
0 - No Animate (default) dbgNoAnimate
1 - Roll dbgRoll
2 - Slide dbgSlide
3 - Blend dbgBlend
Remarks
Read/Write at run time and design time.
For a TDBGrid control, this property controls the style of animation when the user opens or closes the
drop-down combo (either a built-in combo box or a separate TDBDropDown control).
This property also controls the animation effects of the CellTips window when the AnimateWindow
property has been set to a value other than 0 - No animation.
Use the AnimateWindowTime property to control the duration of the animation, the
AnimateWindowDirection property to control the direction of the animation effect, and the
AnimateWindowClose property for additional control over the behavior of the animation when closing
the object.
The allowable values for this property are as follows:
If set to 0 - No animate (the default), there will be no animation effect.
If set to 1 - Roll, the object will paint up or down (depending on the AnimateWindowDirection property
setting) from the first line.
If set to 2 - Slide, the object will open with an action like a window shade.
If set to 3 - Blend, the object will open and close by fading in and out. This value is to be used in NT 5.0
only. When the AnimateWindow property is set to 3 - Blend in Windows 98, the data in the drop-down or
built-in combo box will not be displayed correctly, if at all.
Note
System requirements: Windows 98 or NT 5.0, or higher. The setting 3 - Blend is not available in Windows
98.
See Window Animation (page 261) for more information.
See Also
TDBGrid Control (page 118)

AnimateWindowClose Property
For a TDBGrid control, this property controls the animation effect when the user closes the drop-down
combo (either a built-in combo box or a separate TDBDropDown control).
Syntax
TDBGrid.AnimateWindowClose = value
372 · Object Reference

Values
Design Time Run Time
0 - No Animate Close (default) dbgNoAnimateClose
1 - Opposite Direction dbgOppositeDirection
2 - Same Direction dbgSameDirection
Remarks
Read/Write at run time and design time.
This property also controls the animation effects of the CellTips window when the AnimateWindow
property has been set to a value other than 0 - No animation.
The allowable values for this property are as follows:
If set to 0 - No Animate (the default), there will be no animation when the object is closed.
If set to 1 - Opposite Direction, the animation of the object occurs in the opposite direction of that specified
by the AnimateWindowDirection property.
If set to 2 - Same Direction, the animation of the closing object occurs in the same direction as that specified
by the AnimateWindowDirection property.
Use the AnimateWindowTime property to control the duration of the object's closing animation.
Note
System requirements: Windows 98 or NT 5.0, or higher.
See Also
TDBGrid Control (page 118)

AnimateWindowDirection Property
For a TDBGrid control, this property controls the direction of the animation of the drop-down combo
(either a built-in combo box or a separate TDBDropDown control).
Syntax
TDBGrid.AnimateWindowDirection = value
Values
Design Time Run Time
0 - Default dbgDefaultDirection
1 - Top To Bottom dbgTopToBottom
2 - Bottom To Top dbgBottomToTop
3 - Left To Right dbgLeftToRight
4 - Right To Left dbgRightToLeft
5 - Top Left To Bottom Right dbgTopLeftToBottomRight
6 - Top Right To Bottom Left dbgTopRightToBottomLeft
7 - Bottom Left To Right dbgBottomLeftToTopRight
 AnimateWindowTime Property · 373

Design Time Run Time

8 - Bottom Right To Top Left dbgBottomRightToTopLeft
9 - Center dbgAnimateCenter
Remarks
Read/Write at run time and design time.
This property also controls the animation effects of the CellTips window when the AnimateWindow
property has been set to a value other than 0 - No animate.
Use the AnimateWindowClose property for additional control over the behavior of the animation while
the object is being closed. Use the AnimateWindowTime property to control the duration of the
animation effect.
If set to 0 - Default, the direction of the animation depends on the location of the object. For example, if the
control is too close to the bottom of the screen to display the entire drop-down combo or cell tips window
when opened by the user, the object will open upwards. The default value for the cell tips window is 1 -
Top To Bottom.
All of the remaining directional settings are under your complete control.
Note
System requirements: Windows 98 or NT 5.0, or higher.
See Also
TDBGrid Control (page 118)

AnimateWindowTime Property
Controls the duration of the animation effect.
Syntax
TDBGrid.AnimateWindowTime = long
Remarks
Read/Write at run time and design time.
This property controls the duration of the animation effects when the AnimateWindow property is set to
a value other than 0 - No Animate. Time is given in milliseconds; the default is 200 (1000 = 1 second).
Note
System requirements: Windows 98 or NT 5.0, or higher.
See Also
TDBGrid Control (page 118)

AnnotatePicture Property
This property determines whether the column associated with a ValueItems collection can display both
text and graphics in a single cell.
374 · Object Reference

Syntax
valueitems.AnnotatePicture = boolean
Remarks
Read/Write at run time and design time.
If True, both text and graphics are displayed in a cell when all of the following conditions are met:
• The Presentation property of the ValueItems collection is set to any value except 1 - Radio Button.
• The underlying data value for a cell matches the Value property of a ValueItem member.
• The corresponding DisplayValue contains a bitmap, not text.
If False (the default), matching cells are rendered as the Value or DisplayValue setting, depending upon
the value of the Translate property.
When both text and graphics are displayed, the horizontal placement of the bitmap with respect to the
cell text is determined by the Alignment and ForegroundPicturePosition properties of the column's
Style object. For example, if Alignment is set to 2 - Center, and ForegroundPicturePosition is set to 0 -
Left, the bitmap is placed at the left edge of the cell, and the cell text is centered in the remaining space.
For more information, see Displaying foreground pictures (page 329).
When editing, the editor uses all space available in the text portion of the cell. If the Presentation
property is set to one of the combo box options, the bitmap will not change until editing is completed.
Use the ValueItems property to access the ValueItems collection for a Column object.
See Also
ValueItems Object (page 123)

Appearance Property
Controls 3-D display of headings, caption, record selectors.
Syntax
object.Appearance = value
Values
Design Time Run Time
0 - Flat dbgFlat
1 - 3D (default) dbg3D
2 - 3D Track dbgTrack3D
3 - XP Theme dbgXPTheme
Remarks
Read/Write at run time and design time.
When this property is set to 1 - 3D, the control paints its caption bars, column headings, column footings,
and record selectors with three-dimensional effects.
When this property is set to 0 - Flat, no visual effects are used.
 ApproxCount Property · 375

When this property is set to 2 - 3D Track, the initial state of the control is the same as 0 - Flat. If the mouse
moves over a control element (e.g., Column Header) it takes on a 3D appearance for that particular
element.
When this property is set to 3 – XP Theme, the grid is displayed using XP theme elements when run on an
operating system that supports Themes. If this property is set and the operating system does not support
themes, it renders using the traditional 3D look.
The Appearance property is independent of the BorderStyle and BackColor properties and only affects
the control's caption bars, column headings, column footings, record selectors, and scroll bars. The
control's data cells, row dividers, and column dividers are not affected.
This property only affects the way in which static elements such as caption bars are drawn; it does not
affect their visibility. Use the Caption, ColumnHeaders, ColumnFooters, and RecordSelectors properties
to control the visibility of these components.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ApproxCount Property
This property sets or returns the approximate row count used by the grid to calibrate the vertical scroll
bar.
Syntax
object.ApproxCount = long
Remarks
Read/Write at run time. Not available at design time.
Typically, the ApproxCount property is used in unbound mode to improve the accuracy of the vertical
scroll bar. This is particularly useful for situations where the number of rows is known in advance, such
as when an unbound grid is used in conjunction with an array.
Note
For a bound grid, setting the ApproxCount property has no effect. However, getting the ApproxCount
property will query the underlying data source.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Array Property
Specifies an XArrayDB object as the data source.
Syntax
object.Array = XArrayDB
Remarks
Read/Write at run time. Not available at design time.
376 · Object Reference

For a grid with its DataMode property set to 4 - Storage, the Array property specifies a ComponentOne
XArrayDB object that acts as a data source. This property has no effect in other data modes.
Note
For backward compatibility, the Array property also accepts an XArray object. However, XArrayDB is
preferred, since it is optimized for the two-dimensional case and supports sorting and searching.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

AutoCompletion Property
This property determines whether matching incremental search values are automatically copied to the
text portion of the column drop down during editing.
Syntax
column.AutoCompletion = boolean
Remarks
Read/Write at run time and design time.
If True, when the user enters one or more characters that match a value in the drop down list, the entire
matching string is copied to the text portion of the control. The caret is positioned after the last character
typed, and the remainder of the string is selected.
If False (the default), the automatic completion does not occur, and the text portion of the control contains
only the characters entered by the user.
See Also
Column Object (page 119)

AutoDropDown Property
True if a drop-down control opens when a character is typed.
Syntax
column.AutoDropDown = boolean
Remarks
Read/Write at run time and design time.
For columns with a built-in ValueItems combo box or associated TDBDropDown control, this property
determines whether the drop-down control is displayed in response to keyboard input.
If True, the drop-down control automatically opens when the user types a character into a cell.
If False (the default), the user can only open the drop-down control by clicking the in-cell button or by
pressing ALT + DOWN ARROW when a cell within the column has focus.
See Also
Column Object (page 119)
 BackColor Property · 377

BackColor Property
This property controls the background color of an object. Colors may be specified as RGB values or
system default colors.
Syntax
object.BackColor = color
Remarks
Read/Write at run time and design time.
The background color of a grid, column, or split is determined by its Style property setting. For these
objects, the BackColor property is a shortcut to the BackColor member of the Style property.
For Style objects, the value of the BackColor property is inherited from the parent style (if any) unless
explicitly overridden.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Style Object (page 122)
Split Object (page 122)

BackgroundPicture Property
This property sets or returns the background bitmap of a style object.
Syntax
style.BackgroundPicture = variant
Remarks
Read/Write at run time and design time.
If a style has no background bitmap, then this property returns a null variant.
You can change a style's background bitmap at design time using the Style Factory property page. Or,
you can assign a bitmap to the BackgroundPicture property in code at run time:
TDBGrid1.HeadingStyle.BackgroundPicture = LoadPicture("seaside.bmp")
Note
Use the BackgroundPictureDrawMode property to control how the background bitmap is displayed
when the style is applied to an object.
See Also
Style Object (page 122)
378 · Object Reference

BackgroundPictureDrawMode Property
This property determines how a style's background bitmap is displayed when the style is applied to a
data cell, header, footer, or caption bar.
Syntax
style.BackgroundPictureDrawMode = value
Values
Design Time Run Time
0 - Center (default) dbgBPCenter
1 - Tile dbgBPTile
2 - Stretch dbgBPStretch
Remarks
Read/Write at run time and design time.
If set to 0 - Center (the default), the background bitmap is centered within the object to which the style is
applied.
If set to 1 - Tile, the background bitmap is drawn repeatedly, starting at the upper left corner of the object,
until the entire area is filled.
If set to 2 - Stretch, the bitmap displayed is resized to fit the area occupied by the object. The original
bitmap is not altered.
Note
Use the BackgroundPicture property to specify a background bitmap for a style.
See Also
Style Object (page 122)

Bands Property
The Bands property returns the number of levels within a hierarchical recordset.
Syntax
TDBGrid.Bands
Remarks
Read-only at run time. Read/Write at design time.
When a grid is bound to a master-detail data source, you can display related groups of hierarchical data
using bands. A band is created for each level in a hierarchical recordset, and may consist of entire tables
or a just a few selected fields. A band is a virtual representation of a hierarchical recordset; it is not the
data itself.
The Bands property is provided for cases where the number of levels in a hierarchical recordset is not
known in advance. The following example uses the Bands property and the ExpandBand method to
display all available bands:
Dim n As Integer
For n = 0 To TDBGrid1.Bands – 1
 BatchUpdates Property · 379

TDBGrid1.ExpandBand(n)
Next n
Note
This property is only supported by the OLE DB version of True DBGrid Pro. It is used only in bound
mode and has no effect in unbound or storage modes.
See Also
TDBGrid Control (page 118)

BatchUpdates Property
The BatchUpdates property specifies batch update mode.
Syntax
TDBGrid.BatchUpdates = boolean
Remarks
Read/Write at run time. Not available at design time.
If False, the grid will call Update upon leaving a row.
If True, the grid will not call Update upon leaving a row.
When an OLE DB grid is bound to a data source for which batch updates are in effect (such as an ADO
Recordset whose LockType property is set to adLockBatchOptimistic), the grid must not update the
current record. In most cases, the grid can derive this information even though it is not part of the OLE
DB specification. For the rare cases in which the grid cannot determine whether batch updates are in
effect, you can set the BatchUpdates property in code to override the grid's default behavior.
To prevent updates from occurring when the user moves off a modified row, set BatchUpdates to True.
To enable updates on a per-row basis, set BatchUpdates to False.
See Updating and Deleting the Current Record (page 241) for more information.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

BOF Property
Returns beginning-of-file status.
Syntax
TDBGrid.BOF
Remarks
Read-only at run time. Not available at design time.
The BOF property operates like its Recordset counterpart. It returns True if the current record position is
before the first record, False if the current record position is on or after the first record.
380 · Object Reference

If the data source contains no records, then BOF will always return True.
See Also
TDBGrid Control (page 118)

Bookmark Property (RowBuffer)

This property returns or sets a bookmark for the specified row within a RowBuffer object passed to an
unbound event procedure for a TDBGrid control.
Syntax
rowbuffer.Bookmark (Row) = variant
Remarks
Read/Write at run time. Not available at design time.
The Row argument is a long integer specifying the row where the bookmark is placed. The range of this
argument can be from 0 to RowCount - 1.
In unbound mode, a bookmark contains a user-defined value that uniquely identifies each row of data.
In the UnboundReadData and UnboundAddData events, your code must provide bookmarks for the
rows being fetched or added. In the UnboundWriteData and UnboundDeleteRow events, the grid
passes one of these bookmarks as a parameter so your code can take the appropriate action.
See Also
RowBuffer Object (page 121)

Bookmark Property
This property returns or sets the bookmark identifying the current row in a TDBGrid or TDBDropDown
control.
Syntax
object.Bookmark = variant
Remarks
Read/Write at run time. Not available at design time.
Use the value returned by the Bookmark property to save a reference to the current row that remains
valid even after another row becomes current.
When you set the Bookmark property to a valid value in code, the row associated with that value
becomes the current row, and the grid adjusts its display to bring the new current row into view if
necessary.
The Bookmark property is defined as a Variant to accommodate user-defined bookmarks in unbound
mode.
Note
In unbound mode, setting the Bookmark property to itself will force the current row to be updated via
the UnboundWriteData event.
 BookmarkType Property · 381

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

BookmarkType Property
The BookmarkType property returns or sets the variant type of bookmarks returned by a TDBGrid or
TDBDropDown control through its properties, methods, and events.
Syntax
object.BookmarkType = integer
Remarks
Read/Write at run time. Not available at design time.
Use this property to ensure that the control conforms to the bookmark type expected by a bound data
source, including ADODC and RDC controls. This property is used only in bound mode and has no effect
in unbound or storage modes.
In some cases, the bookmarks returned by the grid are incompatible with the ADO Recordset object
exposed by an OLE DB data source, even though the grid uses the same bookmarks internally to retrieve
and modify data. For example, code such as the following may generate a type mismatch error:
ADODC1.Recordset.Bookmark = TDBGrid1.RowBookmark(0)
You can use the BookmarkType property in conjunction with the DataSourceChanged event to
circumvent type mismatch errors that may occur when a grid-supplied bookmark is passed to an ADO
Recordset object (or vice versa). The workaround is as follows:
Sub TDBGrid1_DataSourceChanged()
TDBGrid1.BookmarkType = VarType(ADODC1.Recordset.Bookmark)
End Sub
This code ensures that any bookmarks returned by the grid are first converted to the appropriate type for
the bound data source. This workaround is only needed when using the grid in an HTML page; it is not
needed for Visual Basic 6.0.
Note
The same technique can be used when the grid is bound to a Remote Data Control (RDC). Prior to version
5.0c, a bookmark returned by the grid had to be converted to a long integer before it could be passed to
an rdoResultset (RDO) object.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

BorderAppearance Property
Controls the appearance (3D effects) of the cell borders.
Syntax
object.BorderAppearance = value
382 · Object Reference

Values
Design Time Run Time
0 - Flat(default) dbgFlatStyle
1 - 3D Raised dbg3DRaised
2 - 3D Inset dbg3DInset
3 - 3D Raised Bevel dbg3DRaisedBevel
4 - 3D Insert Bevel dbg3DInsetBevel
Remarks
Read/Write at run time and design time.
When this property is set to 0 - Flat, no visual effects are used when a cell is painted.
When this property is set to 1 – 3D Raised, the control paints the cell border as 3D raised.
When this property is set to 2 – 3D Inset, the control paints the cell border as 3D inset.
When this property is set to 3 – 3D Raised Bevel, the control paints the cell border as 3D raised with
bevel.
When this property is set to 4 – 3D InsetBevel, the control paints the cell border as 3D inset with bevel.
See Also
Style Object (page 122)

BorderColor Property
This property specifies the color for the border when used in conjunction with the style.BorderSize and
style.BorderAppearance property.
Syntax
object.BorderColor = value
Remarks
Read/Write at run time and design time.
See Also
Style Object (page 122)

BorderSize Property
The BorderSize property returns or sets the size of the cell border.
Syntax
object.BorderSize = single
Remarks
Read/Write at run time and design time.
See Also
Style Object (page 122)
 BorderStyle Property · 383

BorderStyle Property
This property determines whether a TDBGrid or TDBDropDown control has a border.
Syntax
object.BorderStyle = value
Values
Design Time Run Time
0 - None dbgNoBorder
1 - Fixed Single (default) dbgFixedSingle
Remarks
Read/Write at run time and design time.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

BorderType Property
Controls which, if any, cell borders are displayed.
Syntax
object.BorderType = value
Values
Design Time Run Time
0 - None (default) dbgBorderNone
1 - Left dbgBorderLeft
2 - Right dbgBorderRight
4 - Top dbgBorderTop
8 - Bottom dbgBorderBottom
Remarks
Read/Write at run time and design time.
When this property is set to 0 - None, no Borders will be displayed for a cell.
When this property is set to 1 – Left paints the border on the left.
When this property is set to 2 – Right paints the right cell border.
When this property is set to 4 – Top paints the top cell border.
When this property is set to 8 – Bottom paints the bottom cell border.
This property can be set to any combination of the above options. For example, to have a cell border on
all sides of a cell you can set the BorderType property to
dbgBorderLeft+dbgBorderRight+dbgBorderTop+dbgBorderBottom.
384 · Object Reference

See Also
Style Object (page 122)

Button Property
Controls whether a button appears within the current cell.
Syntax
column.Button = boolean
Remarks
Read/Write at run time and design time.
If True, a button will be displayed in the upper right corner of the current cell at run time.
If False (the default), no button will be displayed.
Typically, you enable the column button when you want to drop down a Visual Basic control (such as the
built-in combo box, a bound list box, or even another True DBGrid control) for editing or data entry.
When the button in the current cell is clicked, the ButtonClick event will be fired. You can then write
code to drop down the desired control from the cell.
When you set the Presentation property of a column's ValueItems collection to either of the combo box
options (sorted or unsorted), then the Button property for that column will be set to True. Similarly, if you
set the Presentation property to the normal (text) or radio button option, then the Button property for
that column will be set to False.
When you set the DropDown property of a column to the name of a TDBDropDown control, then the
Button property for that column will be set to True. Similarly, if you set the DropDown property of a
column to an empty string, then the Button property for that column will be set to False.
Note
If both the Button and ButtonAlways properties are True, then all cells within the column are displayed
with in-cell buttons, not just the current cell.
See Also
Column Object (page 119)

ButtonAlways Property
Controls when an in-cell button is displayed.
Syntax
column.ButtonAlways = boolean
Remarks
Read/Write at run time and design time.
For columns with in-cell buttons, this property determines whether a button is displayed on every row at
all times or only within the current cell.
If True, a button will always be displayed within every visible cell, even if another column or control has
focus.
 ButtonFooter Property · 385

If False (the default), a button will be displayed within the current cell only.
Note
This property has no effect on columns without in-cell buttons. In-cell buttons are enabled for a column
when any of the following are true:
• The column's Button property is set to True.
• The column's ButtonText property is set to True.
• The column's DropDown property is set to the name of a TDBDropDown control.
• The Presentation property of the column's ValueItems collection is set to 2 - Combo Box or 3 -
Sorted Combo Box.
See Also
Column Object (page 119)

ButtonFooter Property
Controls whether a column footer acts like a standard button.
Syntax
column.ButtonFooter = boolean
Remarks
Read/Write at run time and design time.
If True, the column footer depresses like a standard Windows command button when clicked by the user.
If False (the default), the column footer does not change its appearance when clicked by the user.
Typically, you set the ButtonFooter property to True when you want to perform a column-based action
(such as summation) when the user clicks a column footer. Note that the FootClick event always fires
when the user clicks a column footer, even if ButtonFooter is False.
See Also
Column Object (page 119)

ButtonHeader Property
Controls whether a column header acts like a standard button.
Syntax
column.ButtonHeader = boolean
Remarks
Read/Write at run time and design time.
If True, the column header depresses like a standard Windows command button when clicked by the
user.
If False (the default), the AllowColSelect property determines how the column header responds to mouse
input.
386 · Object Reference

Typically, you set the ButtonHeader property to True when you want to perform a column-based action
(such as sorting) when the user clicks a column header. Note that the HeadClick event always fires when
the user clicks a column header, even if ButtonHeader is False.
Note
If ButtonHeader is True, the user must hold down the CTRL key in order to select or move columns with
the mouse.
See Also
Column Object (page 119)

ButtonPicture Property
This property sets or returns the bitmap used to draw the in-cell button for the current cell in the
specified column.
Syntax
column.ButtonPicture = variant
Remarks
Read/Write at run time and design time.
The in-cell button bitmap is enabled when any of the following are true:
• The column's Button property is set to True.
• The column's DropDown property is set to the name of a TDBDropDown control.
• The Presentation property of the column's ValueItems collection is set to 2 - Combo Box or 3 -
Sorted Combo Box.
By default, True DBGrid uses a down arrow for the in-cell button.

However, you can change the button bitmap at design time using either the General or Columns property
page. Or, you can assign a bitmap to the ButtonPicture property in code at run time:
TDBGrid1.Columns(1).ButtonPicture = LoadPicture("arrow.bmp")
Note
The grid automatically draws the edges corresponding to the button's up/down states as appropriate, so
you need only provide the interior image (a light gray background is recommended).
See Also
Column Object (page 119)

ButtonText Property
This property controls whether the current cell takes on the appearance of a standard Windows
command button within the specified column.
Syntax
column.ButtonText = boolean
 Caption Property · 387

Remarks
Read/Write at run time and design time.
If True, the current cell is rendered as a command button with the cell text as the label. When clicked by
the user, the ButtonClick event fires, just as it does for a graphical in-cell button.
If False (the default), the current cell is rendered as normal text and editing is permitted (unless otherwise
restricted).
The ButtonText property takes precedence over the Button property. If both are True, then the graphical
in-cell button is not displayed.
Note
If both the ButtonText and ButtonAlways properties are True, then all cells within the column are
displayed as buttons, not just the current cell.
See Also
Column Object (page 119)

Caption Property
Sets or returns grid caption or column heading text.
Syntax
object.Caption = string
Remarks
Read/Write at run time and design time.
For a TDBGrid control, this property determines the text displayed in the caption bar at the top of the
grid.
For a Column or Split object, this property determines the text displayed in the object's heading area.
Setting the Caption property to an empty string for a TDBGrid control hides its caption bar.
Setting the Caption property to an empty string for a Split object hides the heading area, even if other
splits have non-empty captions.
Setting the Caption property to an empty string for a Column object clears the text in the column's
heading area but does not hide the heading. Column captions are only displayed if the grid's
ColumnHeaders property is set to True and the HeadLines property is not set to 0.
The Caption property is limited to 255 characters. Attempting to set the caption to more than 255
characters results in a trappable error.
See Also
TDBGrid Control (page 118)
Column Object (page 119)
Split Object (page 122)
388 · Object Reference

CaptionStyle Property
This property sets or returns the Style object that controls the appearance of a TDBGrid control's caption
bar or a Split object's heading area.
Syntax
object.CaptionStyle = variant
Remarks
Read/Write at run time and design time.
By default, this is the built-in Caption style.
The value of the Caption property is not affected by changes to the CaptionStyle property.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

CellTips Property
The CellTips property determines whether the grid displays a pop-up text window when the cursor is
idle.
Syntax
TDBGrid.CellTips = value
Values
Design Time Run Time
0 - None (default) dbgNoCellTips
1 - Anchored dbgAnchored
2 - Floating dbgFloating
Remarks
Read/Write at run time and design time.
By default, this property is set to 0 - None, and cell tips are not displayed.
If the CellTips property is set to either 1 - Anchored or 2 - Floating, the FetchCellTips event will be fired
whenever the grid has focus and the cursor is idle over a grid cell, record selector, column header, split
header, or grid caption. The event will not fire if the cursor is over the scroll bars.
The setting 1 - Anchored aligns the cell tip window with either the left or right edge of the cell. The left
edge is favored, but the right edge will be used if necessary in order to display as much text as possible.
The setting 2 - Floating displays the cell tip window below the cursor, if possible.
If you do not provide a handler for the FetchCellTips event, and the cursor is over a grid cell, the default
behavior is to display a text box containing the cell's contents (up to 256 characters). This enables the user
to peruse the contents of a cell even if it is not big enough to be displayed in its entirety. You can also
program the FetchCellTips event to override the default cell text display in order to provide users with
context-sensitive help.
 CellTipsDelay Property · 389

Note
Use the CellTipsDelay property to control the amount of idle time that must elapse before the cell tip
window is displayed.
Use the CellTipsWidth property to control the width of the cell tip window.
Use the AnimateWindow property to control the style of animation when the cell tip window is opened
and closed.
See Also
TDBGrid Control (page 118)

CellTipsDelay Property
The CellTipsDelay property controls the amount of idle time, in milliseconds, that must elapse before the
cell tip window is displayed.
Syntax
TDBGrid.CellTipsDelay = long
Remarks
Read/Write at run time and design time.
By default, this property is set to 1000 (one second).
Setting this property to zero does not disable cell tips, but restores the default value of 1000. To disable
cell tips, set the CellTips property to 0 - None.
See Also
TDBGrid Control (page 118)

CellTipsWidth Property
The CellTipsWidth property returns or sets the width of the cell tip window in terms of the coordinate
system of the grid's container.
Syntax
TDBGrid.CellTipsWidth = single
Remarks
Read/Write at run time and design time.
By default, this property is set to zero, which causes the cell tip window to grow or shrink to
accommodate the cell tip text. You can override this behavior and give the cell tip window a fixed width
by specifying a non-zero value for this property.
See Also
TDBGrid Control (page 118)
390 · Object Reference

CellTop Property
The CellTop property returns the vertical offset of the top of any cell in the specified column relative to
the top of the containing row in terms of the coordinate system of the grid's container.
Syntax
column.CellTop
Remarks
Read-only at run time. Not available at design time.
If the grid's MultipleLines property is 0 - Disabled (the default value), a single record cannot span
multiple lines in the grid, and the CellTop property returns zero for all columns.
If the grid's MultipleLines property is either 1 - Variable or 2 - Fixed, a single record may span multiple
lines in the grid. For columns on the first line, the CellTop property returns zero. For columns on the
second line, the CellTop property returns the cell height (the grid's RowHeight property). For columns
on the third line, the CellTop property returns twice the cell height, and so on.
For example, the following code places a text box on top of the grid cell in the first column of the fourth
displayed row:
With TDBGrid1
Text1.Top = .Top + .RowTop(3) + .Columns(0).CellTop
End With
Note
To overlay the text box exactly on a grid cell, you may need to account for an extra pixel in the width and
height, depending upon the settings of the DividerStyle and RowDividerStyle properties. In Visual
Basic, if the ScaleMode property of the parent form is set to pixels, then you can simply add 1. If the
ScaleMode is set to twips, then you can add the TwipsPerPixelX and TwipsPerPixelY properties of the
Screen (Visual Basic) object.
See Also
Column Object (page 119)

ChildGrid Property
This property associates the name of a TDBGrid control that can be used to represent hierarchical data at
run time.
Syntax
object.ChildGrid = string
Remarks
Read/Write at run time and design time.
When the user clicks the leftmost columns expand icon (“+”) the associated TDBGrid control is displayed
below the current cell.
Use the ChildGrid property and a TDBGrid control to implement a fully editable master/detail
presentation.
 Col Property · 391

See Also
TDBGrid Control (page 118)

Col Property
Sets or returns current column number.
Syntax
object.Col = integer
Remarks
Read/Write at run time. Not available at design time.
This property specifies the zero-based index of the current cell's column position. It may be set at run
time to highlight a different cell within the current row. If the column is visible, the caret or marquee will
be moved to the selected column. If the column is not visible, the grid will scroll to make it visible as a
result of setting this property.
Setting the Col property at run time does not affect selected columns. Use the SelEndCol and SelStartCol
properties to specify a selected region.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

CollapseColor Property
Allows the user to change the color of the collapse icon for hierarchical recordsets.
Syntax
object.CollapseColor = color
Remarks
Read/Write at run time and design time.
This property applies to TDBGrid control in hierarchical view only.
See Also
TDBGrid Control (page 118)

ColIndex Property
This property returns the zero-based index of a column within the Columns collection.
Syntax
column.ColIndex
Remarks
Read-only at run time. Not available at design time.
392 · Object Reference

See Also
Column Object (page 119)

ColumnCount Property
This property returns the number of columns in a RowBuffer object passed to an unbound event
procedure for a TDBGrid control.
Syntax
rowbuffer.ColumnCount
Remarks
Read-only at run time. Not available at design time.
See Also
RowBuffer Object (page 121)

ColumnFooters Property
Turns column footings on or off.
Syntax
object.ColumnFooters = boolean
Remarks
Read/Write at run time and design time.
If True, the control's column footers are displayed.
If False (the default), the control's column footers are not displayed.
Use the FooterText property to set the footing text of an individual Column object.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ColumnHeaders Property
Turns column headings on or off.
Syntax
object.ColumnHeaders = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the control's column headers are displayed.
If False, the control's column headers are not displayed.
Use the Caption property to set the heading text of an individual Column object.
 ColumnIndex Property · 393

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ColumnIndex Property
This property returns the index of a column in a RowBuffer object passed to an unbound event
procedure for a TDBGrid control.
Syntax
rowbuffer.ColumnIndex (Row, Col)
Remarks
Read-only at run time. Not available at design time.
The index corresponds to the ColIndex property of the grid column.
The Col argument is an integer specifying the desired column. The range of this argument can be from 0
to ColumnCount - 1.
The Row argument is an integer specifying the desired row. The range of this argument can be from 0 to
RowCount - 1.
The ColumnIndex property allows you to determine the column index associated with a RowBuffer
column. It is provided for identification of the column in order for the user to fill in the Value property
array with appropriate column data.
See Also
RowBuffer Object (page 121)

ColumnName Property
This property returns the name of a column in a RowBuffer object passed to an unbound event
procedure for a TDBGrid control.
Syntax
rowbuffer.ColumnName (Col)
Remarks
Read-only at run time. Not available at design time.
The name corresponds to the DataField property of the grid column.
The Col argument is an integer specifying the desired column. The range of this argument can be from 0
to ColumnCount - 1.
The ColumnName property allows you to determine the field name associated with a RowBuffer
column. It is provided for situations where the field names and/or column order are not known in
advance.
See Also
RowBuffer Object (page 121)
394 · Object Reference

Columns Property
This property returns a collection of Column objects for a grid, drop-down control, or split.
Syntax
object.Columns
Remarks
Read-only at run time. Not available at design time.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

ConvertEmptyCell Property
The ConvertEmptyCell property specifies whether an empty cell will be written to the underlying data
source as is (an empty string), or as a Null variant.
Syntax
column.ConvertEmptyCell
Values
Design Time Run Time
0 - Write as is (default) dbgNoConversion
1 - Write as Null value dbgAsNull
Remarks
Read-only at run time. Read/Write at design time.
Note
Prior to version 6.0a, null-valued updates could only be performed in code by setting the Value property
of a column to Null, typically in the AfterColUpdate event. You can now achieve the same effect at
design time by setting the ConvertEmptyCell property of the desired columns to 1 - Write as Null value.
See Also
Column Object (page 119)

Count Property
This property returns the number of items in a collection.
Syntax
collection.Count
Remarks
Read-only at run time. Not available at design time.
 CurrentCellModified Property · 395

Collections are zero-based, which means that the items in a collection are indexed from 0 to Count - 1.
See Also
Column Object, Columns Collection (page 119)
Error Object, Errors Collection (page 120)
GroupColumns Collection (page 120)
Layouts Collection (page 121)
PrintInfo Object, PrintInfos Collection (page 121)
SelBookmarks Collection (page 121)
Split Object, Splits Collection (page 122)
Style Object, Styles Collection (page 122)
ValueItem Object, ValueItems Collection (page 123)

CurrentCellModified Property
Sets or returns modification status of the current cell.
Syntax
TDBGrid.CurrentCellModified = boolean
Remarks
Read/Write at run time. Not available at design time.
This property returns True if editing is in progress and the current cell (indicated by the Bookmark and
Col properties) has been modified by the user. It returns False if the cell has not been modified or if
editing is not in progress.
You can use this property to cancel any changes the user has made to the current text. For example, to
program a function key to discard the user's changes (like the ESC key), trap the key code in the grid's
KeyDown event and set CurrentCellModified to False. This will revert the current cell to its original
contents.
See Also
TDBGrid Control (page 118)

CurrentCellVisible Property
Sets or returns the visibility of the current cell.
Syntax
object.CurrentCellVisible = boolean
Remarks
Read/Write at run time. Not available at design time.
This property returns True if the current cell (indicated by the Bookmark and Col properties) is visible
within the displayed area of a grid or split. It returns False if the cell is not visible.
396 · Object Reference

For a TDBGrid or TDBDropDown control, setting the CurrentCellVisible property to True causes the
grid to scroll so that the current cell is brought into view. If a grid contains multiple splits, then the
current cell becomes visible in each split.
For a Split object, setting the CurrentCellVisible property to True makes the current cell visible in that
split only.
In all cases, setting this property to False is meaningless and is ignored.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

CycleOnClick Property
This property determines whether the user can cycle through the ValueItem objects contained in a
column's ValueItems collection by clicking on the current cell.
Syntax
valueitems.CycleOnClick = boolean
Remarks
Read/Write at run time and design time.
If True, the user can click on the current cell to display the next available item. If the last value item is
displayed, then clicking displays the first item in the list.
If False (the default), then the mouse operates as usual within the associated column.
Use the ValueItems property to access the ValueItems collection for a Column object.
Note
The CycleOnClick property has no effect when the MarqueeStyle property is set to 6 - Floating Editor.
See Also
ValueItem Object, ValueItems Collection (page 123)

DataChanged Property
Sets or returns modification status of the current row or cell.
Syntax
object.DataChanged = boolean
Remarks
Read/Write at run time (TDBGrid). Read-only at run time (Column). Not available at design time.
For a TDBGrid control, the DataChanged property indicates the modification status of the current row. If
True, then one or more columns in the current row have been modified. If False, then no changes have
been made.
 DataField Property (Column) · 397

When the DataChanged property of a TDBGrid control is True, you can use the DataChanged property
of individual Column objects to determine the exact nature of the changes.
For a TDBGrid control, setting this property to True has no effect. Setting this property to False exits
editing, discards all changes to the current row, and refreshes the current row from the data source.
Setting this property within the BeforeColUpdate event is disallowed, however.
For a Column object, this property is read-only and cannot be set.
Note
The pencil in the RecordSelector column reflects the state of the grid's DataChanged property.
See Also
TDBGrid Control (page 118)
Column Object (page 119)

DataField Property (Column)

The DataField property returns or sets the name of the field in the database table to which a grid column
is bound.
Syntax
column.DataField = string
Remarks
Read/Write at run time and design time.
When the DataMode property of the grid is set to 0 - Bound, the DataField property is used to bind a
column to a particular field in the database table. If the specified field does not exist in the database table,
binding does not occur, and the column will be blank at run time.
To specify an unbound column in a bound grid, the DataField property must be empty in order for the
column data to be requested in the UnboundColumnFetch event.
See Also
TDBDropDown Control (page 118)
Column Object (page 119)

DataMember Property
This property returns or sets the name of the data member used to populate the grid. Typically, a data
member represents a database table or query.
Syntax
object.DataMember = string
Remarks
Read/Write at run time and design time.
A bound DataSource can expose multiple sets of data that consumers can bind to. Each set of data is
called a data member, and is identified by a unique string.
398 · Object Reference

Note
This property is only supported by the OLE DB version of True DBGrid Pro. It is used only in bound
mode and has no effect in unbound or storage modes.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DataMode Property
Specifies bound or unbound mode.
Syntax
object.DataMode = value
Values
Design Time Run Time
0 - Bound (default) dbgBound
1 - Unbound dbgUnbound
2 - Unbound Extended dbgUnboundEx
3 - Application dbgUnboundAp
4 - Storage dbgUnboundSt
Remarks
Read-only at run time. Read/Write at design time.
When set to 0 - Bound, the control displays data available from its bound DataSource.
When set to 1 - Unbound, the control uses the original DBGrid unbound events to retrieve and update
displayed data. When this mode is used, the grid fires the UnboundReadData event to fetch data. This
setting was retained for backward compatibility with DBGrid and earlier versions of True DBGrid. If you
are writing a new application, please use mode 2, 3, or 4 instead.
When set to 2 - Unbound Extended, the control uses the UnboundReadDataEx event to fetch data. The
UnboundReadDataEx event is more efficient and easier to use than the UnboundReadData event of
mode 1. This is the recommended setting for using the grid unbound with a database API that supports
multiple-row fetches.
When set to 3 - Application, the control uses the ClassicRead event to fetch data one cell at a time. This
mode is much easier to use than mode 2, particularly if data is being retrieved from a Visual Basic array.
However, it can be less efficient than mode 2 if there are many columns because the grid needs to fire
more events in order to retrieve data.
When set to 4 - Storage, the control uses an XArrayDB object as a data source, and no unbound data
retrieval or update events are fired. At run time, you create and populate an XArrayDB object just as you
would a standard Visual Basic array, then bind it to a TDBGrid or TDBDropDown control using the
Array property. This is by far the simplest way to use True DBGrid in unbound mode.
 DataSource Property · 399

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DataSource Property
The DataSource property specifies the data control used to bind a TDBGrid or TDBDropDown control
to a database.
Syntax
object.DataSource = datasource
Remarks
Read/Write at run time (OLE DB only) and design time.
In the OLE DB version of True DBGrid Pro, you can set this property in code as follows:
Set TDBGrid1.DataSource = ADODC1
However, the non-OLE DB version of True DBGrid Pro adheres to an older data binding specification
(ICursor), which requires that you set the DataSource property at design time in the Visual Basic
Properties window.
Note
To bind a TDBGrid or TDBDropDown control to a ComponentOne XArrayDB object, use the Array
property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DataView Property
The DataView property returns or sets the method by which the grid will display data.
Syntax
TDBGrid.DataView = value
Values
Design Time Run Time
0 - Normal (default) dbgNormalView
1 - Hierarchical dbgHierarchicalView
2 - Group dbgGroupView
3 - Form dbgFormView
4 - Inverted dbgInvertedView
Remarks
Read/Write at run time and design time.
400 · Object Reference

When set to 0 - Normal, the grid will only display flat files and will not support a hierarchical view. If the
data source is a hierarchical recordset, the grid will only display data from the master table.
When set to 1 - Hierarchical, the grid will display recordsets in a hierarchical format. At run time, users
can expand and collapse hierarchical recordset bands using a treeview-like interface.
For more information, see Hierarchical Data Display (page 279)
When set to 2 - Group, a grouping area is created at the top of the grid; any columns that are placed into
this area become part of the GroupColumns collection, forming a new split. When in group mode, grid
columns can be moved into or out of the grouping area with the Add and Remove methods, respectively.
Users can also perform this action by selecting and dragging a column into or out of the grouping area.
See Outlook-Style Grouping (page 278) for more information.
When set to 3 – Form, the grid will display the recordset data in a convenient data entry form.
For more information, see Form Data Display (page 284).
When set to 4 – Inverted, the grid will flip the display, rows will be represented horizontally and columns
vertically.
NOTE: Splits cannot be used when using the Inverted display option.
For more information, see Inverted Data Display (page 284).
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
DataView 1 – Hierarchical can only be used in bound mode and has no effect in unbound or storage
modes.
See Also
TDBGrid Control (page 118)

DataWidth Property
Maximum number of characters available for column input.
Syntax
column.DataWidth = long
Remarks
Read/Write at run time and design time.
This property holds the database width, in bytes, for a grid column. It is set to the appropriate field width
(not display width) automatically when the layout of a bound grid is initialized at run time.
This property does not affect the physical size of a column, but imposes a limit on the number of
characters that may be entered when editing a cell. If set to 0, no such limits are imposed. Setting this
property does not cause truncation of existing data.
For bound grids, if the data source does not supply a width value, then no limits are imposed. For both
bound and unbound grids, you can set the value of this property in code to restrict the amount of data
the user can enter.
 DeadAreaBackColor Property · 401

See Also
Column Object (page 119)

DeadAreaBackColor Property
This property controls the background color of the dead area object.
Syntax
object.DeadAreaBackColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
Setting this property will affect the appearance of the "dead area" of underpopulated controls, such as the
area to the right of the last column, the area below the last data row, and the Outlook Grouping area.
Note
If the EmptyRows property is True, the empty data rows it creates are not considered part of the "dead
area" and will not be displayed in the DeadAreaBackColor. If you wish for the area occupied by the
empty rows to be shown in the DeadAreaBackColor, you should first set the EmptyRows property to
False.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DefaultItem Property
This property returns or sets the zero-based index of the default item for a ValueItems collection
associated with a column.
Syntax
valueitems.DefaultItem = integer
Remarks
Read/Write at run time and design time.
The default value for this property is -1, which is used to indicate that there is no default item.
Use the DefaultItem property to provide an alternate display for data values not present in the
ValueItems collection.
When the DefaultItem property is set to a valid collection index (an integer between 0 and Count - 1,
inclusive), then the corresponding ValueItem is displayed when the grid encounters a value which is not
present in the ValueItems collection.
When the DefaultItem property is set to -1, then the grid will not substitute a ValueItem when it
encounters a value which is not present in the ValueItems collection.
A trappable error will occur if you attempt to set this property to an invalid value.
402 · Object Reference

Use the ValueItems property to access the ValueItems collection for a Column object.
Note
At design time, the DefaultItem property is specified in the Values property page by clicking the record
selector of the desired grid row. If no row is selected, then the DefaultItem property will be set to its
default value of -1. To deselect a selected row, click its record selector again.
See Also
ValueItem Object, ValueItems Collection (page 123)

DefaultValue Property
This property returns or sets the default value of an unbound grid column in a bound grid.
Syntax
column.DefaultValue = variant
Remarks
Read/Write at run time and design time.
Unbound columns are typically used to display calculated fields or local data not maintained by the
primary data source.
This property applies only to unbound columns. The value specified will be preloaded into the last
argument passed to the UnboundColumnFetch event.
The DefaultValue property can also be used to identify specific columns in the UnboundColumnFetch
event when columns are added, moved, or removed at run time.
For bound columns or columns of an unbound grid, the grid does not use this property itself, but
provides it as a placeholder for you to associate default values with the columns. In the
UnboundAddData event, you can use this property to retrieve default values for columns that were not
supplied by the end user. Such columns will contain a Null variant in the corresponding RowBuffer.Value
property array.
This property can also be used as a tag for a column (whether it is bound or unbound). Arbitrary values
can be stored and retrieved later
Note
Do not confuse unbound columns with unbound mode. The DefaultValue property has no effect on data
displayed in an unbound grid.
See Also
Column Object (page 119)

DefColWidth Property
This property returns or sets the default width for all grid columns in terms of the coordinate system of
the grid's container.
Syntax
object.DefColWidth = single
 Description Property · 403

Remarks
Read/Write at run time and design time.
For bound grids, the DefColWidth property is respected under the following circumstances:
• When you execute the Retrieve Fields command at design time.
• When the grid's layout is initialized at run time.
• When a new column is created at run time.
For unbound grids, the DefColWidth property is only respected when a new column is created at run
time.
If you set the DefColWidth property to 0, the grid automatically sizes all columns based on either the
width of the column heading or the display width of the underlying field, whichever is larger. For
example, to set the default column width to the width of the first column:
TDBGrid1.DefColWidth = TDBGrid1.Columns(0).Width
Note
Setting the DefColWidth property at run time does not affect existing columns, only those that are
subsequently created in code.
In bound mode, some data sources do not provide text field widths when requested by the grid.
Therefore, if DefColWidth is 0, the actual column widths may not be what you expect since the grid must
supply a default width.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Description Property
This property returns a string containing a brief description of the error that occurred.
Syntax
error.Description
Remarks
Read-only at run time. Not available at design time.
The description comes either directly from ADO itself, or from the OLE DB Provider.
Providers are responsible for passing specific error text to ADO. The grid adds an Error object to the
Errors collection for each provider error or warning it receives. Examine the Errors collection to trace the
errors that the provider passes.
The function of this property is identical to the ADO Description property.
Note
Property applies to Error object (OLE DB only).
See Also
Error Object (page 120)
404 · Object Reference

DestinationCol Property
Returns destination column number during cell movement.
Syntax
object.DestinationCol
Remarks
Read-only at run time. Not available at design time.
This property is used when moving from one cell to another in the grid. It indicates which grid column
will be the destination of the movement. The value returned is the zero-based index of the column
containing the destination cell. If you click outside of the column data area, (for example, in the record
selector area on the left), DestinationCol returns -1.
This property is available only during those events related to cell movement: AfterColEdit,
AfterColUpdate, BeforeColUpdate, BeforeRowColChange, ButtonClick, Click, DblClick, FootClick,
GroupHeadClick, HeadClick, MouseDown, MouseUp. Any attempt to access the DestinationCol
property outside of these events results in a trappable error ("Property not available in this context").
The property can only be used if the movement is initiated interactively by the user, via the keyboard or
mouse. The property is not available when movement is initiated programmatically (for example, when
setting the grid's Col property).
Note
Care must be exercised when using this property, because it is possible to use the value of this property
in an event (such as MouseDown) before knowing whether or not the movement will actually succeed.
The value returned by this property only indicates what the correct destination column will be if the cell
movement is successful.
The DestinationCol property does not guarantee that the cell movement will succeed (for example,
movement may fail if the contents of the current cell are not valid). In such cases, the DestinationCol
property will not reflect the actual destination position (usually the cell position will remain at the
previous location).
See Also
TDBGrid Control (page 118)

DestinationRow Property
Returns destination row bookmark during cell movement.
Syntax
object.DestinationRow
Remarks
Read-only at run time. Not available at design time.
This property is used when moving from one cell to another in the grid. It indicates which grid row will
be the destination of the movement. The value returned is the bookmark of the row containing the
destination cell. If you click outside any visible row (for example, on the header), DestinationRow
returns Null. If you click the AddNew row, DestinationRow returns "" (empty string).
 DestinationSplit Property · 405

This property is available only during those events related to cell movement: AfterColEdit,
AfterColUpdate, BeforeColUpdate, BeforeRowColChange, ButtonClick, Click, DblClick, FootClick,
GroupHeadClick, HeadClick, MouseDown, MouseUp. Any attempt to access the DestinationRow
property outside of these events results in a trappable error ("Property not available in this context").
The property can only be used if the movement is initiated interactively by the user, via the keyboard or
mouse. The property is not available when movement is initiated programmatically (for example, when
using the grid's MoveNext method).
Note
Care must be exercised when using this property, because it is possible to use the value of this property
in an event (such as MouseDown) before knowing whether or not the movement will actually succeed.
The value returned by this property only indicates what the correct destination row will be if the cell
movement is successful.
The DestinationRow property does not guarantee that the cell movement will succeed (for example,
movement may fail if contents of the current cell are not valid). In such cases, the DestinationRow
property will not reflect the actual destination position (usually the cell position will remain at the
previous location).
See Also
TDBGrid Control (page 118)

DestinationSplit Property
Returns destination split number during cell movement.
Syntax
object.DestinationSplit
Remarks
Read-only at run time. Not available at design time.
This property is used when moving from one cell to another in the grid. It indicates which grid split will
be the destination of the movement. The value returned is the zero-based index of the split containing the
destination cell. In the case of a click on an area of the grid not belonging to any split, such as the corner
between the vertical and horizontal scrollbars, or on a split border, DestinationSplit returns -1.
This property is available only during those events related to cell movement: AfterColEdit,
AfterColUpdate, BeforeColUpdate, BeforeRowColChange, ButtonClick, Click, DblClick, FootClick,
GroupHeadClick, HeadClick, MouseDown, MouseUp. Any attempt to access the DestinationSplit
property outside of these events results in a trappable error ("Property not available in this context").
The property can only be used if the movement is initiated interactively by the user, via the keyboard or
mouse. The property is not available when movement is initiated programmatically (for example, when
setting the grid's Split property).
Note
Care must be exercised when using this property, because it is possible to use the value of this property
in an event (such as MouseDown) before knowing whether or not the movement will actually succeed.
The value returned by this property only indicates what the correct destination split will be if the cell
movement is successful.
406 · Object Reference

The DestinationSplit property does not guarantee that the cell movement will succeed (for example,
movement may fail if the contents of the current cell are not valid). In such cases, the DestinationSplit
property will not reflect the actual destination position (usually the cell position will remain at the
previous location).
See Also
TDBGrid Control (page 118)

DirectionAfterEnter Property
Specifies the position of the next cell after enter.
Syntax
TDBGrid.DirectionAfterEnter = value
Values
Possible values for the MoveDirectionConstants enumeration are:
Design Time Run Time
0 - None dbgMoveNone
1 - Right (default) dbgMoveRight
2 - Down dbgMoveDown
3 - Left dbgMoveLeft
4 - Up dbgMoveUp
Remarks
Read/Write at run time and design time.
The DirectionAfterEnter property specifies the relative position of the next cell when the user presses the
ENTER key.
See Also
TDBGrid Control (page 118)

DirectionAfterTab Property
Sets or returns the new cell position when the Tab key is pressed.
Syntax
TDBGrid.DirectionAfterTab = value
Values
Possible values for the MoveDirectionConstants are:
Design Time Run Time
0 - None dbgMoveNone
1 - Right (default) dbgMoveRight
2 - Down dbgMoveDown
3 - Left dbgMoveLeft
 DisplayAlignment Property · 407

Design Time Run Time

4 - Up dbgMoveUp
Remarks
Read/Write at run time and design time.
See Also
TDBGrid Control (page 118)

DisplayAlignment Property
Returns the actual rendering of general horizontal alignment.
Syntax
column.DisplayAlignment
Values
Run Time
0 - Left dbgLeft
1 - Right dbgRight
2 - Center dbgCenter
Remarks
Read-only at run time. Not available at design time.
When the Alignment property is set to 3 - General, text will be left-aligned and numbers will be right-
aligned. If your code needs to determine how general alignment was actually rendered in the grid's
display, you can examine the value returned by the DisplayAlignment property.
This property is useful if you want to send formatted data to the printer based upon the grid's layout, or
if you want to set the ForegroundPicturePosition member of a column's Style property based upon the
actual alignment value.
If general alignment is not specified, then the DisplayAlignment property always returns the same value
as Alignment.
Note
Prior to version 6.0, the Alignment property of a Column object always returned the display result (left,
right, or center) when queried in code, even if explicitly set to 3 - General. In version 6.0, the Alignment
property always returns its assigned value, and the DisplayAlignment property returns the display
result.
See Also
Column Object (page 119)

DisplayValue Property
This property returns or sets the translated data value for a member of a ValueItems collection.
408 · Object Reference

Syntax
valueitem.DisplayValue = variant
Remarks
Read/Write at run time and design time.
The DisplayValue property may be set to a string that specifies the mapping between the underlying
data value and its displayed representation. It may also be set to a picture, such as that returned by the
LoadPicture function in Visual Basic.
If the DisplayValue property is not explicitly set, it returns the same result as the Value property.
Use the ValueItems property to access the ValueItems collection for a Column object.
See Also
ValueItem Object (page 123)

DividerColor Property
Controls the divider color of a split or column divider.
Syntax
object.DividerColor = value
Remarks
Read/Write at run time and design time.
This property controls the divider color of a split or column divider when DividerStyle is set to 7 -
Custom Color. Colors may be specified as RGB values or system default colors.
See Also
Column Object (page 119)
Split Object (page 122)

DividerStyle Property
This property determines the style of the border drawn on the right edge of a column or the left edge of a
split.
Syntax
object.DividerStyle = value
Values
Design Time Run Time
0 - No dividers (Split default) dbgNoDividers
1 - Black line dbgBlackLine
2 - Dark gray line (Column default) dbgDarkGrayLine
3 - Raised dbgRaised
 DropDown Property · 409

Design Time Run Time

4 - Inset dbgInset
5 - ForeColor dbgUseForeColor
6 - Light gray line dbgLightGrayLine
7 - Custom Color dbgCustomColor
8 – Double Line dbgDoubleLine
Remarks
Read/Write at run time and design time.
The DividerStyle property does not control whether a column can be resized by dragging its border. Use
the AllowSizing property to control this behavior.
Note
For splits, the setting 0 - No dividers does not eliminate the dividing line at the left edge, but causes it to be
drawn as a double line if the user can resize the split, or a solid line if the split's width is fixed. For more
information, see Creating and Resizing Splits through User Interaction (page 302).
See Also
Column Object (page 119)
Split Object (page 122)

DropDown Property
This property associates the name of a TDBDropDown control with a column in a TDBGrid control.
Syntax
column.DropDown = string
Remarks
Read/Write at run time and design time.
When the user clicks the column's in-cell button, the associated TDBDropDown control is displayed
below the current cell.
Use the DropDown property and a TDBDropDown control to implement a multicolumn drop-down list
box that works seamlessly with a TDBGrid control. The ListField property of the drop-down control
determines which column is used for incremental search. The DataField property of the drop-down
control determines which grid column is updated when the user selects an item.
Note
When you set the DropDown property of a column to the name of a TDBDropDown control, then the
Button property for that column will be set to True. Similarly, if you set the DropDown property of a
column to an empty string, then the Button property for that column will be set to False.
See Also
Column Object (page 119)
410 · Object Reference

DropDownList Property
For columns with a built-in ValueItems combo box or associated TDBDropDown control, this property
determines whether the drop-down control acts like a list box.
Syntax
column.DropDownList = boolean
Remarks
Read/Write at run time and design time.
If True, the drop-down control acts like a list box. That is, the user cannot type directly into the current
cell, but can select a new value from the drop-down control.
If False (the default), the drop-down control acts like a combo box. That is, the user can either type
directly into the current cell or select a new value from the drop-down control.
See Also
Column Object (page 119)

EditActive Property
Returns the status or enters/exits the cell editor.
Syntax
TDBGrid.EditActive = boolean
Remarks
Read/Write at run time. Not available at design time.
If this property returns True, then the current cell is currently being edited by the user. If False, then no
editing is in progress.
If the grid is not already in edit mode, setting EditActive to True will initiate editing on the current cell.
The caret will be positioned at the end of the cell and the ColEdit event will be triggered.
If the grid is already in edit mode, setting EditActive to False will exit edit mode. If the cell has been
modified, this will trigger the following events: BeforeColUpdate, AfterColUpdate, and AfterColEdit.
Note
To cancel editing completely, set the CurrentCellModified property to False, then set EditActive to False.
The EditActive property does not correspond to the pencil in the RecordSelector column. The pencil
reflects the state of the grid's DataChanged property.
See Also
TDBGrid Control (page 118)

EditBackColor Property
This property controls the background color of an object's editing window when editing is in progress.
 EditDropDown Property · 411

Syntax
object.EditBackColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
By default, the editor background color of a grid, column, or split is determined by its EditorStyle
property setting. For these objects, the EditBackColor property is a shortcut to the BackColor member of
the EditorStyle property.
Note
The EditBackColor property only applies when the floating editor marquee (MarqueeStyle = 6) is not in
effect.
See Also
TDBGrid Control (page 118)
Column Object (page 119)
Split Object (page 122)

EditDropDown Property
This property controls whether editing will take place in a popup window or within cell boundaries.
Syntax
TDBGrid.EditDropDown = boolean
Remarks
Read/Write at run time and design time.
If True (the default), an edit window will pop up when the user attempts to edit a cell whose contents
cannot be displayed completely within the confines of the current cell's boundaries. Unlike the built-in
combo box, the drop-down edit window will only extend to the bottom of the grid.
If False, editing will be confined to the current cell's boundaries.
The drop-down edit window behaves just like a standard multiple-line TextBox control in Visual Basic.
The SelLength, SelStart, and SelText properties are still available, and the arrow keys can be used to
navigate within the edit window.
Note
If the user tries to edit the last row in the grid, the drop-down edit window will not be displayed and the
user will have to edit within the current cell's boundaries.
The EditDropDown property only applies when the floating editor marquee (MarqueeStyle = 6) is not in
effect.
See Also
TDBGrid Control (page 118)
412 · Object Reference

EditForeColor Property
This property controls the foreground color of an object's editing window when editing is in progress.
Syntax
object.EditForeColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
By default, the editor foreground color of a grid, column, or split is determined by its EditorStyle
property setting. For these objects, the EditForeColor property is a shortcut to the ForeColor member of
the EditorStyle property.
Note
The EditForeColor property only applies when the floating editor marquee (MarqueeStyle = 6) is not in
effect.
See Also
TDBGrid Control (page 118)
Column Object (page 119)
Split Object (page 122)

EditMask Property
Input mask string for a column.
Syntax
column.EditMask = string
Remarks
Read/Write at run time and design time.
The EditMask property is used to specify an input mask template for end-user data entry. You can
construct your own input mask string using template characters similar to those recognized by the Visual
Basic Format$ function. The input mask string is composed of special characters that represent either an
input character that the user must enter, or a literal character that will be skipped over on input. Valid
template characters are as follows:
# Digit placeholder
@ Character placeholder
> All characters following will be in uppercase
< All characters following will be in lowercase
~ Turns off the previous "<" or ">"
? Digit or character
\ Next character is treated as a literal
& Any character
 EditMaskRight Property · 413

Any other character will be treated as a literal.

After the user finishes editing a cell with this input mask, True DBGrid caches the modified cell text, but
any literal characters in the input mask template will be stripped from the modified cell text beforehand.
The EditMask property also supports a built-in DateMask option for formatting date fields. When the
DateMask option is selected (by setting the property “Date Mask”), the following input mask template will
be used for editing:
mm/dd/yyyy
mm Month placeholder (01-12)
dd Date placeholder (01-31)
yyyy Year placeholder
The user can enter either 1, 2, 3, or 4 digits in the year portion of the date, and the grid will save the year
as entered by the user. If the user enters 1 or 2 digits for the year portion, the grid will make no
interpretation for the year; that is, the grid will not assume whether it is the century 1900 or 2000, but will
store the 1-digit or 2-digit year as entered. Before the date is updated to the database, you can interpret
the year yourself in code, or let the underlying database system handle the interpretation and storage.
Note that if you select the DateMask option for the EditMask property, the date separators are part of the
date format; they are not considered as literal characters and will always be cached by the grid. This is
because most databases and formatters require the separator characters to be present in order to interpret
the date correctly.
See Also
Column Object (page 119)

EditMaskRight Property
This property determines the direction in which a column's input mask is applied.
Syntax
column.EditMaskRight = boolean
Remarks
Read/Write at run time and design time.
The input mask is specified by the EditMask property.
If True, the input mask is applied from right to left. If a character is inserted, the characters to the left of
the new character are shifted left.
If False (the default), the input mask is applied from left to right. If a character is inserted, the characters
to the right of the new character are shifted right.
See Also
Column Object (page 119)

EditMaskUpdate Property
Controls whether masked data is used for updates.
414 · Object Reference

Syntax
column.EditMaskUpdate = boolean
Remarks
Read/Write at run time and design time.
Normally, after the user finishes editing a cell in a column which has its EditMask property set, True
DBGrid caches the modified cell text, but any literal characters in the input mask template will be
stripped from the modified cell text beforehand. However, you can override this behavior with the
EditMaskUpdate property.
By default, the EditMaskUpdate property is False. This means that when the modified cell text is updated
to the database, the grid sends the cached text (stripped of literals), not the formatted text displayed in the
cell. You can override this default behavior by setting the EditMaskUpdate property to True, which
causes the cached text to be formatted according to the EditMask property before being updated to the
database.
See Also
Column Object (page 119)

EditorStyle Property
This property returns the Style object that controls the appearance of the cell editor within a grid,
column, or split.
Syntax
object.EditorStyle = variant
Remarks
Read/Write at run time and design time.
Note
The EditorStyle property only applies when the floating editor marquee (MarqueeStyle = 6) is not in
effect.
See Also
TDBGrid Control (page 118)
Column Object (page 119)
Split Object (page 122)

EllipsisText Property
This property, when set to True, displays an ellipsis (…) as a marker at the end of the text within a cell if
all text does not fit within the cell.
Syntax
object.EllipsisText = boolean
Remarks
Read/Write at run time and design time.
 EmptyRows Property · 415

See Also
Style Object (page 122)

EmptyRows Property
The EmptyRows property returns or sets a value that determines how the grid displays rows below the
last data row.
Syntax
object.EmptyRows = boolean
Remarks
Read/Write at run time and design time.
If all of the records in the data source do not fill up the entire grid, setting EmptyRows to True will fill the
unpopulated grid area with empty data rows. If EmptyRows is False (the default), then the unpopulated
grid area will be blank and will be filled with the system 3D Objects color (or the system Button Face
color) as determined by your Control Panel settings.
Note
The RowDividerStyle property applies to data rows and empty rows alike. You cannot suppress row
dividers for just the empty rows when EmptyRows is True.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Enabled Property
This property returns or sets a value that determines whether a control can respond to user-generated
events.
Syntax
object.Enabled = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the user can give focus to the control and manipulate it with the keyboard or mouse.
If False, the user cannot manipulate the control directly.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

EOF Property
Returns end-of-file status.
416 · Object Reference

Syntax
TDBGrid.EOF
Remarks
Read-only at run time. Not available at design time.
The EOF property operates like its Recordset counterpart. It returns True if the current record position is
after the last record, False if the current record position is on or before the last record.
If the data source contains no records, then EOF will always return True.
See Also
TDBGrid Control (page 118)

Errors Property
This property returns a collection of Error objects for a grid.
Syntax
TDBGrid.Errors
Remarks
Read-only at run time. Not available at design time.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

ErrorText Property
This property returns the error message string from the underlying data source.
Syntax
object.ErrorText
Remarks
Read-only at run time. Not available at design time.
When a database error occurs as a result of user interaction with the grid, such as when the user enters
text into a numeric field and then attempts to update the current record by moving to another row, the
grid's Error event will fire. However, the error code passed to the event handler in the DataError
parameter may not identify the specific error that occurred. For these reasons, the ErrorText property is
provided so that your application can parse the actual error message to determine the nature of the error.
Note
The ErrorText property is only valid within a TDBGrid or TDBDropDown control's Error event handler.
A trappable error will occur if you attempt to access it in any other context.
 EvenRowStyle Property · 417

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

EvenRowStyle Property
Controls the row style for even-numbered rows.
Syntax
object.EvenRowStyle = variant
Remarks
Read/Write at run time and design time.
This property sets or returns the Style object that controls the appearance of an even-numbered row in a
grid or split where the AlternatingRowStyle property is set to True. By default, this is the built-in
EvenRow style.
To change the appearance of odd-numbered rows, set the OddRowStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

ExpandColor Property
Allows the user to change the color of the expand icon for hierarchical recordsets.
Syntax
object.ExpandColor = color
Remarks
Read/Write at run time and design time.
See Also
TDBGrid Control (page 118)

ExportEOF Property
The ExportEOF property returns True if the current exported record position is after the last record, or
False if the current exported record position is on or before the last record.
Syntax
TDBGrid.ExportEOF
Remarks
Read-only at run time. Not available at design time.
418 · Object Reference

Note
The ExportEOF property is only valid between calls to the ExportBegin and ExportEnd methods. A
trappable error will occur if you attempt to access it in any other context.
See Also
TDBGrid Control (page 118)

ExportNextBookmark Property
The ExportNextBookmark property returns the bookmark after the last row exported by the previous call
to the ExportRows method.
Syntax
TDBGrid.ExportNextBookmark = variant
Remarks
Read-only at run time. Not available at design time.
If ExportRows has not yet been called, this property returns the bookmark specified (or implied) by the
previous call to the ExportBegin method.
The ExportNextBookmark property is typically used in server-side applications that present ad hoc
query data as a series of HTML tables containing a small number of rows. In such applications, you can
store the value returned by the ExportNextBookmark property in a database or collection object for the
next call to the ExportBegin method, as in the following example.
Private Sub WebItem1_Respond()
If Request.Cookies.Count = 0 Then
TDBGrid1.ExportBegin
Else
TDBGrid1.ExportBegin Request.Cookies("user"))
End If
TDBGrid1.ExportRows FileName, False, 10
Response.Cookies("user") = TDBGrid1.ExportNextBookmark
TDBGrid1.ExportEnd
Response.Redirect FileName
End Sub
Note
The ExportNextBookmark property is only valid between calls to the ExportBegin and ExportEnd
methods. A trappable error will occur if you attempt to access it in any other context.
See Also
TDBGrid Control (page 118)

ExposeCellMode Property
This property controls how the rightmost column reacts when clicked by the user.
Syntax
TDBGrid.ExposeCellMode = value
 ExtendRightColumn Property · 419

Values
Design Time Run Time
0 - Scroll on Select (default) dbgScrollOnSelect
1 - Scroll on Edit dbgScrollOnEdit
2 - Never Scroll dbgScrollNever
Remarks
Read/Write at run time and design time.
If set to 0 - Scroll on Select (the default), the grid will scroll to the left to display the rightmost column in its
entirety. This can be somewhat disconcerting to users who commonly click on the grid to begin editing,
as the grid will always shift to the left when the user clicks on the rightmost column.
If set to 1 - Scroll on Edit, the grid will not move when the rightmost column is clicked initially. However,
if the user attempts to edit the cell, then the grid will scroll to the left to display the rightmost column in
its entirety. This is exactly how Microsoft Excel works and is probably the most intuitive setting.
If set to 2 - Never Scroll, the grid will always leave the rightmost column clipped when clicked, even if the
user subsequently attempts to edit the cell. Note that editing may be difficult if only a small portion of the
column is visible. The chief reason to use this setting is if you know there will always be enough space
available for editing (or if you disallow editing) and you never want the grid to shift accidentally.
Note
The ExposeCellMode property only governs mouse clicks, not keyboard navigation.
See Also
TDBGrid Control (page 118)

ExtendRightColumn Property
This property allows the rightmost column of a grid or split to extend to the object's right edge, provided
that the object can accommodate all of the visible columns.
Syntax
object.ExtendRightColumn = boolean
Remarks
Read/Write at run time and design time.
If True, the last column will extend to the end of the grid or split.
If False (the default), the area between the last column and the end of the grid or split will be filled using
the system 3D Objects color (or the system Button Face color) as determined by your Control Panel
settings.
If a grid contains multiple splits, then setting its ExtendRightColumn property has the same effect as
setting the ExtendRightColumn property of each split individually.
Note
This property now works even when the horizontal scroll bar is present. Prior to version 5.0, if a grid or
split could not accommodate all of the visible columns, then setting this property to True had no effect.
420 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

ExternalEditor Property
Sets the ActiveX input control for a column.
Syntax
column.ExternalEditor = variant
Remarks
Read/Write at run time and design time.
This property associates the name of a control that implements the ComponentOne External Editor
interface with a column in a TDBGrid control. When the user initiates editing within the associated
column, the specified control is used instead of the grid's built-in text editor.
Note
The online tutorials for True DBInput Pro (version 6.0 or greater) contain specific instructions for using
this property.
See Also
Column Object (page 119)

FetchRowStyle Property
Controls whether the FetchRowStyle event will be fired.
Syntax
object.FetchRowStyle = boolean
Remarks
Read/Write at run time and design time.
If True, the FetchRowStyle event will be fired whenever the grid is about to display a row of data.
If False (the default), the FetchRowStyle event is not fired.
Set this value to True when you need to perform complex per-row formatting operations that can only be
done using the FetchRowStyle event. For example, if you want to apply fonts and/or colors to all rows
that satisfy certain criteria, then you need to set the FetchRowStyle property to True and write code for
the FetchRowStyle event.
Note
To display every other row in a different color or font, you can simply set the AlternatingRowStyle
property to True.
 FetchStyle Property · 421

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

FetchStyle Property
Controls whether the FetchCellStyle event fires for a column.
Syntax
FetchStyle As FetchCellStyleConstants
Values
Possible values for the FetchCellStyleConstants are:

Design Time Run Time

0 – None (default) dbgFetchCellStyleNone
1 – Column dbgFetchCellStyleColumn
2 – Column and AddNew dbgFetchCellStyleAddNewColumn
Remarks
Read/Write at run time and design time.
If set to 0 - None (the default), no events will fire to retrieve cell styles.
If set to 1 - Column, events will be fired for rows not including the AddNewRow.
If set to 2 – Column and AddNew, events will fire for rows including the AddNewRow. The bookmark into
the event will be null for the AddNew row.
Note
If you want to apply the same formatting to all cells within a row, then you should set the FetchRowStyle
property instead of FetchStyle, and write code for the FetchRowStyle event instead of FetchCellStyle.
This is much more efficient because events are fired on a per-row rather than on a per-cell basis.
See Also
Column Object (page 119)

Files Property
Contains a collection of filenames used by a DataObject object.
Syntax
dataobject.Files
Remarks
Read-only at run time. Not available at design time.
422 · Object Reference

In Visual Basic, when a DataObject object contains data of type vbCFFiles, its Files property returns a
DataObjectFiles collection containing a list of filenames used by a source component in an OLE
drag/drop operation.
However, since this version of True DBGrid handles the vbCFText clipboard format only, the Files
property is not supported, and any attempt to access it in code always generates a trappable error.
The TDBGrid control supplies an argument of type DataObject when it fires the following events:
OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.
See Also
DataObject Object (page 119)

FilterActive Property
Returns True if you are currently editing within the filter bar.
Syntax
object.FilterActive = boolean
Remarks
Read/Write at run time. Not available at design time.
This property returns True if the user is currently editing within the filter bar. Use the Col property to
identify the filter column being edited.
Setting this property to True initiates editing in the filter bar.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

FilterBar Property
When set to True, the grid displays a row of data under the column headers in which the user can type.
Syntax
object.FilterBar = boolean
Remarks
Read/Write at run time and design time.
You can use the FilterButtonClick and FilterChange events to implement custom operations such as
incremental search or recordset filtering.
For more information, see Tutorial 29 (page 108).
See Also
TDBGrid Control (page 118)
Split Object (page 122)
 FilterBarStyle Property · 423

FilterBarStyle Property
This property returns the Style object that controls the appearance of the FilterBar cells within a grid or
split.
Syntax
object.FilterBarStyle = variant
Remarks
Read/Write at run time and design time.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

FilterButton Property
Determines whether a button is displayed in the current filter cell.
Syntax
column.FilterButton = boolean
Remarks
Read/Write at run time and design time.
If True, a button will be displayed in the upper right corner of the current filter cell at run time. If False
(the default), no button will be displayed. Typically, you enable the column button when you want to
drop down a Visual Basic control (such as the built-in combo box, a bound list box, or even another True
DBGrid control) for editing or data entry. When the button in the current cell is clicked, the
FilterButtonClick event will be fired. You can then write code to drop down the desired control from the
cell.
See Also
Column Object (page 119)

FilterButtonPicture Property
This property sets or returns the bitmap used to draw the in-cell button for the current filter in the
specified column.
Syntax
column.FilterButtonPicture = variant
Remarks
Read/Write at run time and design time.
The in-cell button bitmap is enabled when any of the following are true:
• The column's Button property is set to True.
• The column's DropDown property is set to the name of a TDBDropDown control.
424 · Object Reference

• The Presentation property of the column's ValueItems collection is set to 2 - Combo Box or 3 -
Sorted Combo Box.
See Also
Column Object (page 119)

FilterText Property
When applied to a Column object, this property returns or sets the data associated with the value of the
filter for the specified column.
Syntax
column.FilterText = string
Remarks
Read/Write at run time. Not available at design time.
See Also
Column Object (page 119)

FirstRow Property
This property returns or sets a value containing the bookmark for the first visible row in a grid or split.
Syntax
object.FirstRow = variant
Remarks
Read/Write at run time. Not available at design time.
For a TDBGrid or TDBDropDown control, setting the FirstRow property causes the grid to scroll so that
the specified row becomes the topmost row. If a grid contains multiple splits, then the topmost row
changes in each split, even if the splits have different ScrollGroup property settings.
For a Split object, setting the FirstRow property causes the specified row to become the topmost row for
that split only.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

Font Property
This property returns or sets the font object associated with a grid, column, split, or style.
Syntax
object.Font = font
 FooterAlignment Property · 425

Remarks
Read/Write at run time and design time.
The font used to display text in a grid, column, or split is determined by its Style property setting. For
these objects, the Font property is a shortcut to the Font member of the Style property.
For Style objects, the value of the Font property is inherited from the parent style (if any) unless explicitly
overridden.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)
Style Object (page 122)

FooterAlignment Property
The FooterAlignment property returns or sets a value that determines the alignment of the footings for
an individual column.
Syntax
column.FooterAlignment = value
Values
Design Time Run Time
0 - Left dbgLeft
1 - Right dbgRight
2 - Center dbgCenter
3 - General (default) dbgGeneral
Remarks
Read/Write at run time and design time.
The General setting means that the column's Alignment property will be used to format both the column
footings and the cell text.
See Also
Column Object (page 119)

FooterBackColor Property
Sets or returns the footing background color.
Syntax
object.FooterBackColor = color
426 · Object Reference

Remarks
Read/Write at run time and design time.
This property controls the background color of an object's column footings. Colors may be specified as
RGB values or system default colors.
The footing background color of a grid, column, or split is determined by its FooterStyle property setting.
For these objects, the FooterBackColor property is a shortcut to the BackColor member of the
FooterStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

FooterDivider Property
Controls the display of the dividing line in column footer,
Syntax
column.FooterDivider = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the right edge of the column's footer is drawn with a vertical dividing line.
If False, no dividing line is drawn in the column's header area.
See Also
Column Object (page 119)

FooterFont Property
This property returns or sets the font object associated with the column footings of a grid, column, or
split.
Syntax
object.FooterFont = font
Remarks
Read/Write at run time and design time.
The font used to display column footing text in a grid, column, or split is determined by its FooterStyle
property setting. For these objects, the FooterFont property is a shortcut to the Font member of the
FooterStyle property.
 FooterForeColor Property · 427

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

FooterForeColor Property
This property controls the foreground color of an object's column footings.
Syntax
object.FooterForeColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The footing foreground color of a grid, column, or split is determined by its FooterStyle property setting.
For these objects, the FooterForeColor property is a shortcut to the ForeColor member of the FooterStyle
property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

FooterStyle Property
This property returns the Style object that controls the appearance of column footings within a grid,
column, or split.
Syntax
object.FooterStyle = variant
Remarks
Read/Write at run time and design time.
By default, this is the built-in Footing style.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)
428 · Object Reference

FooterText Property
This property returns or sets the text displayed in the column's footing area.
Syntax
column.FooterText = string
Remarks
Read/Write at run time and design time.
Setting the FooterText property to an empty string clears the text in the column's footing area but does
not hide the footing. Column footings are only displayed if the grid's ColumnFooters property is set to
True and the FootLines property is not set to 0.
The FooterText property is limited to 255 characters. Attempting to set the footer text to more than 255
characters results in a trappable error.
See Also
Column Object (page 119)

FootLines Property
This property returns or sets a value indicating the number of lines of text displayed in a TDBGrid or
TDBDropDown control's column footers.
Syntax
object.FootLines = single
Remarks
Read/Write at run time and design time.
The FootLines property accepts a floating point number from 0 to 10. The default value is 1, which causes
the grid to display the FooterText value for each Column object on a single line within its footer area,
provided that ColumnFooters is True.
A setting of 0 removes the footings and has the same effect as setting the ColumnFooters property to
False.
Note
You must set the FooterText property explicitly. Unlike the Caption property, it does not derive a default
value from the name of the underlying database field.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ForeColor Property
This property controls the foreground color of an object.
Syntax
object.ForeColor = color
 ForegroundPicture Property · 429

Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The foreground color of a grid, column, or split is determined by its Style property setting. For these
objects, the ForeColor property is a shortcut to the ForeColor member of the Style property.
For Style objects, the value of the ForeColor property is inherited from the parent style (if any) unless
explicitly overridden.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)
Style Object (page 122)

ForegroundPicture Property
This property sets or returns the foreground bitmap of a style object.
Syntax
style.ForegroundPicture = variant
Remarks
Read/Write at run time and design time.
If a style has no foreground bitmap, then this property returns a null variant.
You can change a style's foreground bitmap at design time using the Style Factory property page. Or, you
can assign a bitmap to the ForegroundPicture property in code at run time:
TDBGrid1.HeadingStyle.ForegroundPicture = LoadPicture("bell.bmp")
Note
Use the ForegroundPicturePosition property to control the placement of the bitmap relative to the cell or
heading text when the style is applied to an object. Use the TransparentForegroundPicture property to
specify a background mask.
See Also
Style Object (page 122)

ForegroundPicturePosition Property
This property determines where a style's foreground bitmap is displayed when the style is applied to a
data cell, header, footer, or caption bar.
Syntax
style.ForegroundPicturePosition = value
430 · Object Reference

Values
Design Time Run Time
0 - Left (default) dbgFPLeft
1 - Right dbgFPRight
2 - Left of Text dbgFPLeftOfText
3 - Right of Text dbgFPRightOfText
4 - Top of Text dbgFPTopOfText
5 - Bottom of Text dbgFPBottomOfText
6 - Picture Only dbgFPPictureOnly
7 - Text Only dbgFPTextOnly
Remarks
Read/Write at run time and design time.
Note
Use the ForegroundPicture property to specify a foreground bitmap for a style.
See Also
Style Object (page 122)

Group Property
This property returns a boolean that indicates whether the column is being grouped.
Syntax
column.Group = boolean
Remarks
Read only at run time. Not available at design time.
If set to True, the given column is in the grouping area, as a member of the GroupColumns collection (the
DataView property must be set to 2 - Group).
If False, the given column is not in the grouping area.
Note
This property applies to Column object (OLE DB only).
See Outlook-Style Grouping (page 278) for more information.
See Also
Column Object (page 119)

GroupByCaption Property
This property sets or returns the text displayed in the grouping area when no group is defined.
Syntax
TDBGrid.GroupByCaption = string
 GroupColumns Property · 431

Remarks
Read/Write at run time and design time.
When the DataView property is set to 2 - Group, a grouping area is created above the grid. Until column
headers have been moved there, the GroupByCaption text is displayed in the grouping area. The default
caption is: "Drag a column header here to group by that column" The maximum length of the caption
string is 255 characters.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Outlook-Style Grouping (page 278) for more information.
See Also
TDBGrid Control (page 118)

GroupColumns Property
This property returns a collection of Column objects in the grid's grouping area.
Syntax
TDBGrid.GroupColumns
Remarks
Read-only at run time. Not available at design time.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Outlook-Style Grouping (page 278) for more information.
See Also
TDBGrid Control (page 118)

HeadAlignment Property
The HeadAlignment property returns or sets a value that determines the alignment of the headings for
an individual column.
Syntax
column.HeadAlignment = value
Values
Design Time Run Time
0 - Left dbgLeft
1 - Right dbgRight
2 - Center dbgCenter
3 - General (default) dbgGeneral
432 · Object Reference

Remarks
Read/Write at run time and design time.
The General setting means that the column's Alignment property will be used to format both the column
headings and the cell text.
See Also
Column Object (page 119)

HeadBackColor Property
This property controls the background color of an object's column headings.
Syntax
object.HeadBackColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The heading background color of a grid, column, or split is determined by its HeadingStyle property
setting. For these objects, the HeadBackColor property is a shortcut to the BackColor member of the
HeadingStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

HeaderDivider Property
Controls display of dividing line in column header.
Syntax
column.HeaderDivider = boolean
Read/Write at run time and design time.
Remarks
If True (the default), the right edge of the column's header is drawn with a vertical dividing line.
If False, no dividing line is drawn in the column's header area.
Note
Setting this property to False does not prevent the user from resizing the column. Set the AllowSizing
property to False to disable column resizing.
 HeadFont Property · 433

See Also
Column Object (page 119)

HeadFont Property
This property returns or sets the font object associated with the column headings of a grid, column, or
split.
Syntax
object.HeadFont = font
Remarks
Read/Write at run time and design time.
The font used to display column heading text in a grid, column, or split is determined by its
HeadingStyle property setting. For these objects, the HeadFont property is a shortcut to the Font
member of the HeadingStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

HeadForeColor Property
This property controls the foreground color of an object's column headings.
Syntax
object.HeadForeColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The heading foreground color of a grid, column, or split is determined by its HeadingStyle property
setting. For these objects, the HeadForeColor property is a shortcut to the ForeColor member of the
HeadingStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)
434 · Object Reference

HeadingStyle Property
This property returns the Style object that controls the appearance of column headings within a grid,
column, or split.
Syntax
object.HeadingStyle = variant
Remarks
Read/Write at run time and design time.
By default, this is the built-in Heading style.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

HeadLines Property
This property returns or sets a value indicating the number of lines of text displayed in a TDBGrid or
TDBDropDown control's column headers.
Syntax
object.HeadLines = single
Remarks
Read/Write at run time and design time.
The HeadLines property accepts a floating point number from 0 to 10. The default value is 1, which
causes the grid to display the caption for each Column object on a single line within its header area,
provided that ColumnHeaders is True.
A setting of 0 removes the headings and has the same effect as setting the ColumnHeaders property to
False.
Note
By default, a Column object's caption contains the name of its underlying field as specified by the
DataField property. You can use the Caption property to override the text displayed within column
headers.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

HelpContext Property
Returns or sets a context ID for a topic in a Help file.
 HelpFile Property · 435

Syntax
error.HelpContext
Remarks
Read-only at run time. Not available at design time.
This property returns a data type long containing the context ID of the help topic associated with this
particular error. The specified help topic is located in the Windows Help (.hlp) file named by the
HelpFile property.
If no help topic is associated with this error, this property returns 0.
This property is used in conjunction with the HelpFile property to automatically display the help
information related to the error.
The function of this property is identical to the ADO HelpContext property.
Note
This property applies to Error object (OLE DB only).
See Also
Error Object (page 120)

HelpFile Property
Returns pathname of help file associated with the error.
Syntax
error.HelpFile
Remarks
Read-only at run time. Not available at design time.
This property returns a string containing the fully qualified path name of the Windows Help (.hlp)
associated with this particular error. The topic in this help file that contains the specific information
about the error is given by the HelpContext property.
If no help file is associated with this error, this property returns an empty string.
This property is used in conjunction with the HelpContext property to automatically display the help
information related to the error.
The function of this property is identical to the ADO HelpFile property.
Note
This property applies to Error object (OLE DB only).
See Also
Error Object (page 120)

HighlightRowStyle Property
This property sets or returns the Style object that controls the appearance of a highlighted row or cell
marquee.
436 · Object Reference

Syntax
object.HighlightRowStyle = variant
Remarks
Read/Write at run time and design time.
By default, this is the built-in HighlightRow style.
The HighlightRowStyle value is only used when one of the following MarqueeStyle settings is in effect:
2 - Highlight Cell, 3 - Highlight Row, or 4 - HighlightRow, RaiseCell.
The value of the MarqueeStyle property is not affected by changes to the HighlightRowStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

HScrollHeight Property
Returns the horizontal scroll bar height, if present.
Syntax
object.HScrollHeight
Remarks
Read-only at run time. Not available at design time.
The HScrollHeight property returns the height of a split's horizontal scroll bar in container units, which
depend on the ScaleMode (Visual Basic) of the container. If no horizontal scroll bar exists, then the
returned value is zero. If object is a TDBGrid control, then its current split is used.
You can use the HScrollHeight and VScrollWidth properties to check if the scroll bars are present and to
obtain the scroll bar size when designing the grid layout and sizing the grid and its columns.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

hWnd Property
Returns the window handle of the grid.
Syntax
object.hWnd
Remarks
Read-only at run time. Not available at design time.
 hWndEditor Property · 437

The hWnd property returns the unique window handle assigned to a TDBGrid or TDBDropDown
control by the Microsoft Windows operating environment. Experienced users can pass the value of this
property to Windows API calls that require a valid window handle.
Note
Since the value of this property can change while a program is running, never store the hWnd value in a
variable.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

hWndEditor Property
Returns the window handle of the grid's editor.
Syntax
TDBGrid.hWndEditor
Remarks
Read-only at run time. Not available at design time.
The hWndEditor property returns the unique window handle assigned to a TDBGrid control's editing
window by the Microsoft Windows operating environment. Experienced users can pass the value of this
property to Windows API calls that require a valid window handle.
When editing is not is progress, this property returns 0.
Note
Since the value of this property can change while a program is running, never store the hWndEditor
value in a variable.
Do not use the hWndEditor property to test whether editing is in progress. The EditActive property is
provided for this purpose.
See Also
TDBGrid Control (page 118)

InactiveBackColor Property
This property controls the background color of an object's column headings when another object has
focus.
Syntax
object.InactiveBackColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
438 · Object Reference

The inactive background color of a grid or split is determined by its InactiveStyle property setting. For
these objects, the InactiveBackColor property is a shortcut to the BackColor member of the InactiveStyle
property.
Note
The inactive colors are only used when the grid's Appearance property is set to 0 - Flat. If the Appearance
property is set to the default value of 1 - 3D, then the headings do not change when a grid or split
receives or loses focus.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

InactiveForeColor Property
This property controls the foreground color of an object's column headings when another object has
focus.
Syntax
object.InactiveForeColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The inactive foreground color of a grid or split is determined by its InactiveStyle property setting. For
these objects, the InactiveForeColor property is a shortcut to the ForeColor member off the InactiveStyle
property.
Note
The inactive colors are only used when the grid's Appearance property is set to 0 - Flat. If the Appearance
property is set to the default value of 1- 3D, then the headings do not change when a grid or split
receives or loses focus.
See Also
TDBGrid Control (page 118)

InactiveStyle Property
This property returns the Style object that controls the appearance of column headings within a grid or
split when another object has focus.
Syntax
object.InactiveStyle = variant
Remarks
Read/Write at run time and design time.
 Index Property · 439

Note
The inactive style is only used when the grid's Appearance property is set to 0 - Flat. If the Appearance
property is set to the default value of 1 - 3D, then the headings do not change when a grid or split
receives or loses focus.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

Index Property
This property returns the zero-based index of a split within the Splits collection.
Syntax
split.Index
Remarks
Read-only at run time. Not available at design time.
See Also
Split Object (page 122)

InsertMode Property
This property determines whether the grid's editor operates in insert or overstrike mode.
Syntax
TDBGrid.InsertMode = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the editor is in insert mode, and each character entered by the user is inserted at the
current caret position.
If False, the editor is in overstrike mode, and each character entered by the user replaces the character
immediately after the caret.
See Also
TDBGrid Control (page 118)

LayoutFileName Property
This property sets or returns the string containing the filename used to save and retrieve grid layouts.
Syntax
object.LayoutFileName = string
Remarks
Read/Write at run time and design time.
440 · Object Reference

Setting this property alone has no effect on the grid layout; the property value is used by the LoadLayout
method of the grid and the Add and Remove methods of the Layouts collection.
You can create grid layout files at design time by setting the LayoutFileName and LayoutName
properties and using the layout commands on the grid's visual editing menu.
At design time, if you first set the LayoutFileName property to a valid filename in which grid layouts are
stored, you can then choose the LayoutName property from a drop-down list of layout names stored in
the specified layout file.
Note
If the LayoutFileName property is nonempty, it takes precedence over LayoutURL, and asynchronous
downloading will not occur.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

LayoutName Property
This property sets or returns the string (maximum length of 30 characters) containing the current layout
name.
Syntax
object.LayoutName = string
Remarks
Read/Write at run time and design time.
Setting this property alone has no effect on the grid layout; the property value is used by the LoadLayout
method of the grid.
At design time, if you first set the LayoutFileName property to a valid filename in which grid layouts are
stored, you can then choose the LayoutName property from a drop-down list of layout names stored in
the specified layout file.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Layouts Property
This property returns a collection of layout names corresponding to the current setting of the
LayoutFileName or LayoutURL property.
Syntax
object.Layouts
Remarks
Read-only at run time. Not available at design time.
 LayoutURL Property · 441

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

LayoutURL Property
This property sets or returns the string containing the URL (Uniform Resource Locator) used for
retrieving grid layouts.
Syntax
object.LayoutURL = string
Remarks
Read/Write at run time and design time.
The LayoutURL property is similar to LayoutFileName except that it downloads a grid layout file from
an HTTP server instead of opening a file on the local machine or a network.
You can create grid layout files at design time by setting the LayoutFileName and LayoutName
properties and using the layout commands on the grid's visual editing menu.
If you set the LayoutURL property to a nonempty string at design time (and LayoutFileName is empty),
the grid initiates asynchronous downloading at run time after it has been loaded. You can also initiate
downloading by setting the LayoutURL property in code. This technique is particularly useful for
initializing a grid on an HTML page.
In either case, the grid fires the LayoutReady event when the download operation has completed. You
should write a handler for this event that loads the desired layout as follows:
TDBGrid1.LayoutName = "MyLayout"
TDBGrid1.LoadLayout
Note
Since the grid downloads layout files asynchronously, the following code may not work as expected:
TDBGrid1.LayoutURL = "http://www.bigcorp.com/layouts.grx"
TDBGrid1.LayoutName = "MyLayout"
Depending upon file size and available bandwidth, the download initiated by the first statement may still
be in progress when the second statement executes. Therefore, the layout specified in the second
statement may not yet exist. Conversely, if the download finishes quickly, it is possible for the
LayoutReady event to fire before the second statement executes. For these reasons, the recommended
procedure is to set the LayoutName property in the LayoutReady handler, immediately before calling the
LoadLayout method.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Left Property
This property returns the position of a column's left edge in terms of the coordinate system of the grid's
container.
442 · Object Reference

Syntax
column.Left
Remarks
Read-only at run time. Not available at design time.
Use the Left property in conjunction with Width, RowHeight, and RowTop to determine the size and
placement of controls displayed on top of a grid cell.
See Also
Column Object (page 119)

LeftCol Property
This property returns or sets the zero-based index of the leftmost column in a grid or split.
Syntax
object.LeftCol = integer
Remarks
Read/Write at run time. Not available at design time.
For a TDBGrid or TDBDropDown control, setting the LeftCol property causes the grid to scroll so that
the specified column becomes the leftmost column. If a grid contains multiple splits, then the leftmost
column changes in each split.
For a Split object, setting the LeftCol property causes the specified column to become the leftmost
column for that split only.
Use the LeftCol property in code to scroll a grid or split horizontally. Use the FirstRow property to
determine the bookmark of the first visible row in a grid or split.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

Locked Property
This property returns or sets a value indicating whether an object can be edited.
Syntax
object.Locked = boolean
Remarks
Read/Write at run time and design time.
If True, the user cannot modify data in the column or split.
If False (the default), the user can modify data in the column or split.
 MarqueeStyle Property · 443

If the TDBGrid control's AllowUpdate property is set to False, then editing is disabled for the entire grid
regardless of the Locked property setting for individual columns and splits. If AllowUpdate is True, then
the Locked property can be used to control the editability of individual columns and splits.
For Split objects, setting the Locked property to True disables editing for all columns within that split
regardless of their Locked property setting. If Locked is False for a split, then the Locked settings of
individual columns within that split are respected.
For Style objects, the Locked property controls the editability of the object to which the style is applied. It
does not control the editability of the style object itself.
The locked state of a column or split is determined by its Style property setting. For these objects, the
Locked property is a shortcut to the Locked member of the Style property.
For Style objects, the value of the Locked property is inherited from the parent style (if any) unless
explicitly overridden.
Note
The default value of the Locked property for a column is not derived from the DataUpdatable property
for the underlying field. If both properties are False for a column, then an error will occur when the grid
attempts to write changed data to the database.
See Also
Column Object (page 119)
Split Object (page 122)
Style Object (page 122)

MarqueeStyle Property
This property determines how the current row and cell are highlighted within a grid or split.
Syntax
object.MarqueeStyle = value
Values
Design Time Run Time
0 - Dotted Cell Border dbgDottedCellBorder
1 - Solid Cell Border dbgSolidCellBorder
2 - Highlight Cell dbgHighlightCell
3 - Highlight Row dbgHighlightRow
4 - Highlight Row, Raise Cell dbgHighlightRowRaiseCell
5 - No Marquee dbgNoMarquee
6 - Floating Editor (default) dbgFloatingEditor
7 - Dotted Row Border dbgDottedRowBorder
Remarks
Read/Write at run time and design time.
444 · Object Reference

There are seven possible values for this property:

0 - Dotted Cell Border The current cell within the current row will be highlighted by drawing a
dotted border around the cell. In Microsoft Windows terminology, this
is usually called a focus rectangle.
1 - Solid Cell Border The current cell within the current row will be highlighted by drawing a
solid box around the current cell. This is more visible than the dotted
cell border, especially when 3-D divider properties are used for the
grid.
2 - Highlight Cell The entire current cell will be drawn using the attributes of the
HighlightRowStyle property. This provides a very distinctive block-
style highlight for the current cell.
3 - Highlight Row The entire row containing the current cell will be drawn using the
attributes of the HighlightRowStyle property. In this mode, it is not
possible to visually determine which cell is the current cell, only the
current row. When the grid or split is not editable, this setting is often
preferred, since cell position is then irrelevant.
4 - Highlight Row, Raise Cell The entire row will be highlighted as in setting 3, but the current cell
within the row will be "raised" so that it appears distinctive. This
setting doesn't appear clearly with all background color and divider
settings. The best effect is achieved by using 3-D dividers and a light
gray background.
5 - No Marquee The marquee will not be shown. This setting is useful for cases where
the current row is irrelevant, or where you don't want to draw the
user's attention to the grid until necessary.
6 - Floating Editor The current cell will be highlighted by a floating text editor window
with a blinking caret (as in Microsoft Access). This is the default
setting.
7 - Dotted Row Border The entire current row will be highlighted by drawing a dotted border
around it. This effect is similar to setting 0.
If a grid contains multiple splits, then setting its MarqueeStyle property has the same effect as setting the
MarqueeStyle property of each split individually.
Note
If the floating editor marquee setting is in effect and the current cell contains radio buttons or graphics,
then a dotted focus rectangle will be displayed.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

MarqueeUnique Property
This property controls the display of the current cell marquee when there is more than one split.
Syntax
TDBGrid.MarqueeUnique = boolean
 MatchCase Property · 445

Remarks
Read/Write at run time and design time.
The current cell marquee is only displayed when the MarqueeStyle property for a grid or split has a
value of 0, 1, 2, or 4.
If True (the default), then the current cell marquee is only displayed within the current split.
If False, then all splits with a MarqueeStyle setting of 0, 1, 2, or 4 will display a marquee at the current
cell, provided that the current cell is visible.
In most cases, a single current cell marquee is preferable, and you will not need to change this property.
If this property is set to False, you may then see several different current cell marquees. The actual current
cell is determined by the setting of the Split property.
Note
Although the floating editor MarqueeStyle (6) is technically a current cell marquee, only one floating
editor will be displayed, even if MarqueeUnique is set to False.
See Also
TDBGrid Control (page 118)

MatchCase Property
Allows you to do case-sensitive searches for Translations.
Syntax
valueitems.MatchCase = boolean
Remarks
Read/Write at run time and design time.
Setting this property to True allows you to only do case sensitive searches for Translations.
See Also
ValueItem Object, ValueItems Collection (page 123)

MaxComboItems Property
This property controls the maximum number of items to be displayed in the built-in combo box.
Syntax
valueitems.MaxComboItems = integer
Remarks
Read/Write at run time and design time.
The default value for this property is 5.
When the Presentation property of a column's ValueItems collection is set to either of the combo box
options (sorted or unsorted), the MaxComboItems property determines the combo box height in terms of
the number of value items displayed.
446 · Object Reference

If the total number of value items is less than or equal to MaxComboItems, then all value items will be
shown. If the total number of value items exceeds MaxComboItems, only MaxComboItems will be
shown, but a scroll bar will appear at the right edge of the drop-down combo to allow users to bring the
other value items into view.
Use the ValueItems property to access the ValueItems collection for a Column object.
See Also
ValueItem Object, ValueItems Collection (page 123)

MaxRows Property
This property controls the maximum number of data rows that can be displayed in the grid at any one
time.
Syntax
TDBGrid.MaxRows = long
Remarks
Read/Write at run time and design time.
The default value for this property is 250,000. Any rows in the grid's data source in excess of MaxRows
will not be scrolled into view when using the grid's vertical scroll bar. Therefore, if you wish to navigate
within a data source that contains more than 250,000 rows, use this property to extend the limit.
The minimum possible value of this property is 250,000 (the default), so if you display less than 250,000
rows in the grid, there is no need to set this property.
See Also
TDBGrid Control (page 118)

Merge Property
This property determines whether adjacent rows of like-valued data are merged within the specified
column.
Syntax
column.Merge = value
Values
Possible values for the MergeCellConstants are:

Design Time Run Time

0 - None dbgMergeNone
1 - Free dbgMergeFree
2 - Restricted dbgMergeRestricted

Remarks
Read/Write at run time and design time.
 MinWidth Property · 447

Note
If the underlying data is translated by the FormatText event or the ValueItems collection, the translated
(displayed) data is used for comparison.
See Also
Column Object (page 119)

MinWidth Property
This property returns or sets the minimum width that a column can be sized to when the grid is resized
and the SpringMode property is True.
Syntax
column.MinWidth = single
Remarks
Read/Write at run time and design time.
See Also
Column Object (page 119)

MouseIcon Property
This property sets or returns the custom mouse icon used when the MousePointer property is set to 99 -
Custom.
Syntax
TDBGrid.MouseIcon = variant
Remarks
Read/Write at run time and design time.
You can load a custom mouse icon from either a cursor (.cur) or icon (.ico) file at design time using the
General property page. Or, you can assign a cursor or icon to the MouseIcon property in code at run
time:
TDBGrid1.MouseIcon = LoadPicture("cross.cur")
See Also
TDBGrid Control (page 118)

MousePointer Property
This property sets or returns a value indicating the type of mouse pointer displayed when the mouse is
over the grid at run time.
Syntax
TDBGrid.MousePointer = value
448 · Object Reference

Values
Design Time Run Time
0 - Default (default) dbgMPDefault
1 - Arrow dbgMPArrow
2 - Cross dbgMPCross
3 - I-beam dbgMPIbeam
4 - Icon dbgMPIcon
5 - Size dbgMPSize
6 - Size NE SW dbgMPSizeNESW
7 - Size NS dbgMPSizeNS
8 - Size NW SE dbgMPSizeNWSE
9 - Size EW dbgMPSizeEW
10 - Up Arrow dbgMPUpArrow
11 - Hourglass dbgMPHourglass
12 - No Drop dbgMPNoDrop
13 - Arrow Hourglass dbgMPArrowHourglass
14 - Arrow Question dbgMPArrowQuestion
15 - Size All dbgMPSizeAll
99 - Custom dbgMPCustom
Remarks
Read/Write at run time and design time.
When this property is set to 99 - Custom, the MouseIcon property specifies the shape of the mouse
pointer.
See Also
TDBGrid Control (page 118)

MultipleLines Property
Controls whether individual records span multiple lines.
Syntax
TDBGrid.MultipleLines = value
Values
Design Time Run Time
0 - Disabled (default) dbgMultipleDisabled
1 - Variable dbgMultipleVariable
2 - Fixed dbgMultipleFixed
 MultiSelect Property · 449

Remarks
Read/Write at run time and design time.
This property determines whether a single row can span multiple lines. In this context, the terms line and
row are defined as follows:
• A line is a single physical row of cells displayed in a grid. Do not confuse this with a line of text
inside a grid cell; depending upon the settings of the RowHeight and WrapText properties, data
in a grid cell may be displayed in multiple lines of text.
• A row displays a single record and may contain multiple lines or multiple physical rows.
The default value of MultipleLines is 0 - Disabled, which means that a single record (row) cannot span
multiple lines. If necessary, the user can operate the horizontal scroll bar to view all of the columns within
a row. This is how the grid normally displays data.
However, if the MultipleLines property is 1 - Variable or 2 - Fixed, then a single record (row) may span
multiple lines. This feature enables the user to view simultaneously all of the columns (fields) of a record
within the width of the grid without scrolling horizontally.
When the MultipleLines property is changed to a value other than 0 - Disabled, the horizontal scroll bar
will be hidden if present, regardless of the setting of the ScrollBars property. The grid will automatically
span or wrap the columns to multiple lines so that all columns will be visible within the width of the grid.
If the resulting column layout is not to your liking, you can adjust it at design time or run time by
changing the widths and orders of the columns.
If MultipleLines is 1 - Variable, then changing the width of individual columns or the width of the grid
itself may cause one or more columns to be shifted to a different line, which may in turn affect the
number of lines displayed in a physical row. For example, enlarging a column may bump the next one
onto a different line, while shrinking the width of the grid may produce additional lines.
If MultipleLines is 2 - Fixed, then changing the width of individual columns or the width of the grid itself
preserves both the current column breaks and the number of lines displayed in a physical row. In this
case, enlarging a column reduces the width of its successors, while shrinking the width of the grid may
hide the rightmost columns altogether.
At design time, if the ScrollBars property is set to 4 - Automatic, and the MultipleLines property is
enabled, a vertical scroll bar appears even though no data is displayed. This is done so that you can take
the width of the scroll bar into account when adjusting columns at design time.
Note
Prior to version 6.0, the MultipleLines property was implemented as a boolean, with False meaning 0 -
Disabled, and True meaning 1 - Variable. The setting 2 - Fixed was added to preserve column breaks.
See Also
TDBGrid Control (page 118)

MultiSelect Property
Sets or returns the type of selection allowed in the grid.
Syntax
TDBGrid.MultiSelect = value
450 · Object Reference

Values
Design Time Run Time
0 - None dbgMultiSelectNone
1 - Simple (default) dbgMultiSelectSimple
2 - Extended dbgMultiSelectExtended
Remarks
Read/Write at run time and design time.
This property controls record selection behavior when the AllowRowSelect property is True. If
AllowRowSelect is False, the user cannot select records.
If set to 0 - None, multiple selection is disabled but single selection is permitted. When the user clicks a
record selector, the current selection is cleared, and the clicked row is then selected and added to the
SelBookmarks collection. The CTRL and SHIFT keys are ignored, and the user can only select one row at a
time. However, you can still select multiple rows in code using the Add method of the SelBookmarks
collection.
If set to 1 - Simple (the default), multiple selection is enabled using the mouse. When the user clicks a
record selector, the selection is cleared and the clicked row is selected and added to the SelBookmarks
collection. However, if the user holds down the CTRL key while clicking, the clicked row is added to the
current selection. The user can also select a range of rows by selecting the first row in the range, then
selecting the last row in the range while holding down the SHIFT key.
If set to 2 - Extended, multiple selection is enabled using the mouse as described in the previous
paragraph. The user can also select records with the following key combinations: SHIFT + UP ARROW,
SHIFT + DOWN ARROW, SHIFT + PGUP, and SHIFT + PGDN. NOTE: When 2 - Extended is chosen, the user
will not be able to select a single cell, instead the entire corresponding row will be selected.
See Also
TDBGrid Control (page 118)

Name Property (Column)

This property returns a string that identifies the name of the associated database field (if available).
Syntax
column.Name
Remarks
Read-only at run time. Not available at design time.
Use the TableName property to retrieve the name of the underlying database table.
See Also
Column Object, Columns Collection (page 119)

Name Property (Style)

This property returns the name of a Style object.
 NativeError Property · 451

Syntax
style.Name
Remarks
Read-only at run time. Read/Write at design time.
The Name property is set at design time in the Style Factory property page when a style is first created.
Styles cannot be renamed, even at design time.
When a TDBGrid control is first created, its Styles collection contains ten built-in styles named Normal,
Heading, Footing, Selected, Caption, HighlightRow, EvenRow, OddRow, RecordSelector, and FilterBar.
Note
For an independent style object, the Name property always returns an empty string. An independent
style object is not a member of the Styles collection, but is a standalone object created in code with a Dim
or Set statement using the New keyword.
See Also
Style Object (page 122)

NativeError Property
The NativeError property returns a long integer containing the OLE DB Provider's error code for this
Error object.
Syntax
error.NativeError
Remarks
Read-only at run time. Not available at design time.
The function of this property is identical to the ADO NativeError property.
Note
This property applies to Error object (OLE DB only).
See Also
Error Object (page 120)

Number Property
The Number property returns a long integer that uniquely identifies the error condition that has
occurred.
Syntax
error.Number
Remarks
Read-only at run time. Not available at design time.
This property that should be used to determine which error has occurred.
The function of this property is identical to the ADO Number property.
452 · Object Reference

Note
This property applies to Error object (OLE DB only).
See Also
Error Object (page 120)

NumberFormat Property
This property returns or sets a value indicating the format string for a grid column.
Syntax
column.NumberFormat = string
Remarks
Read/Write at run time and design time.
By default, the NumberFormat property contains an empty string, and column data is unformatted.
For numeric data, the following predefined format names can be used:
General Number Display number as is, with no thousand separators.
Currency Display number with thousand separator, if appropriate; display two digits to the
right of the decimal separator. Note that output is based on system locale
settings.
Fixed Display at least one digit to the left and two digits to the right of the decimal
separator.
Standard Display number with thousands separator, at least one digit to the left and two
digits to the right of the decimal separator.
Percent Display number multiplied by 100 with a percent sign (%) appended to the right;
always display two digits to the right of the decimal separator.
Scientific Use standard scientific notation.
Yes/No Display No if number is 0; otherwise, display Yes.
True/False Display False if number is 0; otherwise, display True.
On/Off Display Off if number is 0; otherwise, display On.
For date and time data, the following predefined format names can be used:
General Date Display a date and/or time. For real numbers, display a date and time (for
example, 4/3/93 05:34 PM); if there is no fractional part, display only a date (for
example, 4/3/93); if there is no integer part, display only a time (for example,
05:34 PM). Date display is determined by your system settings.
Long Date Display a date according to your system's long date format.
Medium Date Display a date using the medium date format appropriate for the language
version of Visual Basic.
Short Date Display a date using your system's short date format.
Long Time Display a time using your system's long time format: includes hours, minutes,
seconds.
Medium Time Display a time in 12-hour format using hours and minutes and the AM/PM
designator.
 OddRowStyle Property · 453

Short Time Display a time using the 24-hour format (for example, 17:45).
For arbitrary data, the following predefined format names can be used:
Edit Mask Use the column's EditMask property to format the data for display as well as
editing.
FormatText Event Fire the FormatText event for the associated column. This option allows you to
write your own formatting code for situations where Visual Basic's intrinsic
formatting is unavailable or does not suit your needs.
The NumberFormat property also accepts user-defined format strings. See the Microsoft Visual Basic
documentation (Format function) for details.
If the NumberFormat property is set to an invalid string, cell data are displayed as #ERR#.
Note
The NumberFormat property works only in container environments that support Visual Basic formatting
through OLE. If a container does not provide this support, the NumberFormat property can still be set
without causing an error, but cell data will not be formatted.
However, the FormatText Event option can be used in any container environment, even if Visual Basic
formatting is unavailable.
See Also
Column Object (page 119)

OddRowStyle Property
This property sets or returns the Style object that controls the appearance of an odd-numbered row in a
grid or split where the AlternatingRowStyle property is set to True.
Syntax
object.OddRowStyle = variant
Remarks
Read/Write at run time and design time.
By default, this is the built-in OddRow style.
To change the appearance of even-numbered rows, set the EvenRowStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

OLEDragMode Property
This property returns or sets a value that indicates whether the grid or the programmer handles an OLE
drag/drop operation.
Syntax
TDBGrid.OLEDragMode = value
454 · Object Reference

Values
Design Time Run Time
0 - Manual (default) dbgOLEDragManual
1 - Automatic dbgOLEDragAutomatic
Remarks
Read/Write at run time and design time.
When OLEDragMode is set to the default value of 0 - Manual, you must call the OLEDrag method to
start dragging, which then triggers the OLEStartDrag event.
When OLEDragMode is set to 1 - Automatic, the grid fills the DataObject parameter with data and sets
the Effects parameter before initiating the OLEStartDrag event (as well as the OLESetData and other
source-level OLE drag/drop events) when the user attempts to drag out of the grid.
See Also
TDBGrid Control (page 118)

OLEDropMode Property
This property returns or sets a value that indicates how the grid handles drop operations.
Syntax
TDBGrid.OLEDropMode = value
Values
Design Time Run Time
0 - None (default) dbgOLEDropNone
1 - Manual dbgOLEDropManual
2 - Automatic dbgOLEDropAutomatic
Remarks
Read/Write at run time and design time.
When OLEDropMode is set to the default value of 0 - None, the grid does not accept OLE drops and
displays the No Drop cursor.
When OLEDropMode is set to 1 - Manual, the grid triggers the OLE drop events, allowing the
programmer to handle the OLE drop operation in code.
When OLEDropMode is set to 2 - Automatic, the grid automatically accepts OLE drops if the DataObject
contains data in a format it recognizes. No mouse or OLE drag/drop events on the grid will occur when
OLEDropMode is set to 2 - Automatic.
Note
Currently, the only data format recognized by the grid is text.
See Also
TDBGrid Control (page 118)
 Order Property · 455

Order Property
This property sets or returns the zero-based display position of a column within the Columns collection.
Syntax
column.Order = integer
Remarks
Read/Write at run time and design time.
Use the Order property to determine the location of a column relative to other columns within the same
split, subject to end-user move operations. If AllowColMove is never set to True, then this property
returns the same value as ColIndex.
You can also set the Order property in code to move a single unselected column or all selected columns.
For example, consider a grid with four columns. To move the last column (index 3) all the way to the left,
you would code:
TDBGrid1.Columns(3).Order = 0
To reverse this action, you would set the order to the number of columns:
TDBGrid1.Columns(3).Order = TDBGrid1.Columns.Count
Note that you still use index 3 to refer to the original last column even after it has been moved. This
allows code that references columns by numeric index instead of by name to remain consistent, which is
especially critical for unbound mode applications.
Note
If one or more columns are selected, then setting the Order property of an unselected column has no
effect. However, setting the Order property of a selected column moves all columns in the selected range.
See Also
Column Object (page 119)

OwnerDraw Property
Controls whether the OwnerDrawCell event fires for a column.
Syntax
column.OwnerDraw = boolean
Remarks
Read/Write at run time and design time.
If True, the OwnerDrawCell event will be fired as needed to display the contents of each cell in the
associated column.
If False (the default), the OwnerDrawCell event will not be fired.
Set this value to True when you need to perform complex per-cell display operations that can only be
done using the OwnerDrawCell event. For example, if you want to display a metafile within a cell, then
you need to set OwnerDraw to True for the desired column and write code for the OwnerDrawCell
event.
456 · Object Reference

See Also
Column Object (page 119)

Parent Property
This property sets or returns the parent style of a named style object.
Syntax
style.Parent = variant
Remarks
Read/Write at run time and design time (with restrictions).
If a style has no parent, then this property returns a null variant.
The Parent property is used at run time to change the parent style from which the style in question
inherits. Typically, this is done when creating a new style in code, as in the following example:
Dim BoldHeading As TrueDBGrid60.Style
Set BoldHeading = TDBGrid1.Styles.Add("BoldHeading")
BoldHeading.Parent = "Heading"
BoldHeading.Font.Bold = True
This code first creates a new style, BoldHeading, then sets its parent to the built-in Heading style. This
causes the new style to inherit all attributes from the built-in style. The bold attribute of the new style's
font is then overridden.
Note
For an independent style object, a trappable error will occur if you attempt to set the Parent property. An
independent style object is not a member of the Styles collection, but is a standalone object created in
code with a Dim or Set statement using the New keyword.
See Also
Style Object (page 122)

PartialRightColumn Property
This property determines whether the rightmost column of a grid or split is clipped to the object's right
edge when it is scrolled into view but cannot be displayed in its entirety.
Syntax
object.PartialRightColumn = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the rightmost column will be clipped if the grid or split is not wide enough to
accommodate the entire column.
If False, the rightmost column will not be clipped while other columns are visible. In this case, the
rightmost column must be scrolled into view as the only visible column in the grid or split.
If a grid contains multiple splits, then setting its PartialRightColumn property has the same effect as
setting the PartialRightColumn property of each split individually.
 PictureAddNewRow Property · 457

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

PictureAddNewRow Property
This property sets or returns the bitmap used in the record selector column to indicate the AddNew row,
which is displayed after the last data row when the AllowAddNew property is True.
Syntax
TDBGrid.PictureAddNewRow = variant
Remarks
Read/Write at run time and design time.
By default, True DBGrid uses an asterisk to indicate the AddNew row.

However, you can specify a different bitmap at design time using the General property page. Or, you can
assign a bitmap to the PictureAddNewRow property in code at run time:
TDBGrid1.PictureAddNewRow = LoadPicture("asterisk.bmp")
Note
The grid draws 3-D effects within the record selector column, so you need only provide the interior
image. Use the TransparentRowPictures property to specify a background mask.
See Also
TDBGrid Control (page 118)

PictureCurrentRow Property
This property sets or returns the bitmap used in the record selector column to indicate the current row
when there are no modifications pending.
Syntax
TDBGrid.PictureCurrentRow = variant
Remarks
Read/Write at run time and design time.
By default, True DBGrid uses an arrow to indicate that the current row is unmodified.

However, you can specify a different bitmap at design time using the General property page. Or, you can
assign a bitmap to the PictureCurrentRow property in code at run time:
TDBGrid1.PictureCurrentRow = LoadPicture("arrow.bmp")
458 · Object Reference

Note
The grid draws 3-D effects within the record selector column, so you need only provide the interior
image. Use the TransparentRowPictures property to specify a background mask.
See Also
TDBGrid Control (page 118)

PictureFilterBar Property
This property sets or returns the bitmap used in the record selector column on the FilterBar row.
Syntax
TDBGrid.PictureFilterBar = variant
Remarks
Read/Write at run time and design time.
By default, True DBGrid does not display a picture for this row. However, you can specify a bitmap for
this row at design time using the General property page. Or, you can assign a bitmap to the
PictureFilterBar property in code at run time:
TDBGrid1.PictureFilterBar = LoadPicture("funnel.bmp")
Note
The grid draws 3-D effects within the record selector column, so you need only provide the interior
image. Use the TransparentRowPictures property to specify a background mask.
See Also
TDBGrid Control (page 118)

PictureFooterRow Property
This property sets or returns the bitmap used in the record selector column within the grid's footer row,
which is only displayed when the ColumnFooters property is True.
Syntax
TDBGrid.PictureFooterRow = variant
Remarks
Read/Write at run time and design time.
By default, True DBGrid does not display a picture within the footer row. However, you can specify a
bitmap for this row at design time using the General property page. Or, you can assign a bitmap to the
PictureFooterRow property in code at run time:
TDBGrid1.PictureFooterRow = LoadPicture("pattern.bmp")
Note
The grid draws 3-D effects within the record selector column, so you need only provide the interior
image. Use the TransparentRowPictures property to specify a background mask.
See Also
TDBGrid Control (page 118)
 PictureHeaderRow Property · 459

PictureHeaderRow Property
This property sets or returns the bitmap used in the record selector column within the grid's header row,
which is only displayed when the ColumnHeaders property is True.
Syntax
TDBGrid.PictureHeaderRow = variant
Remarks
Read/Write at run time and design time.
By default, True DBGrid does not display a picture within the header row. However, you can specify a
bitmap for this row at design time using the General property page. Or, you can assign a bitmap to the
PictureHeaderRow property in code at run time:
TDBGrid1.PictureHeaderRow = LoadPicture("pattern.bmp")
Note
The grid draws 3-D effects within the record selector column, so you need only provide the interior
image. Use the TransparentRowPictures property to specify a background mask.
See Also
TDBGrid Control (page 118)

PictureModifiedRow Property
This property sets or returns the bitmap used in the record selector column to indicate the current row
when there are unsaved modifications pending.
Syntax
TDBGrid.PictureModifiedRow = variant
Remarks
Read/Write at run time and design time.
By default, True DBGrid uses a pencil to indicate that the current row is modified.

However, you can specify a different bitmap at design time using the General property page. Or, you can
assign a bitmap to the PictureModifiedRow property in code at run time:
TDBGrid1.PictureModifiedRow = LoadPicture("pencil.bmp")
Note
The grid draws 3-D effects within the record selector column, so you need only provide the interior
image. Use the TransparentRowPictures property to specify a background mask.
See Also
TDBGrid Control (page 118)
460 · Object Reference

PictureStandardRow Property
This property sets or returns the bitmap used in the record selector column to indicate noncurrent,
unmodified rows.
Syntax
TDBGrid.PictureStandardRow = variant
Remarks
Read/Write at run time and design time.
By default, True DBGrid does not display a picture for standard rows. However, you can specify a
bitmap for these rows at design time using the General property page. Or, you can assign a bitmap to the
PictureStandardRow property in code at run time:
TDBGrid1.PictureStandardRow = LoadPicture("star.bmp")
Note
The grid draws 3-D effects within the record selector column, so you need only provide the interior
image. Use the TransparentRowPictures property to specify a background mask.
See Also
TDBGrid Control (page 118)

Presentation Property
This property determines how the members of a ValueItems collection are displayed within the
associated column.
Syntax
valueitems.Presentation = value
Values
Design Time Run Time
0 - Normal (default) dbgNormal
1 - Radio Button dbgRadioButton
2 - Combo Box dbgComboBox
3 - Sorted Combo Box dbgSortedComboBox
4 - Check Box dbgCheckBox
Remarks
Read/Write at run time and design time.
If set to 0 - Normal (the default), value items are displayed as text or graphics depending upon the setting
of the DisplayValue and Translate properties.
If set to 1 - Radio Button, value items are displayed as a group of radio buttons within the cell.
If set to 2 - Combo Box, value items are displayed in a drop-down combo box within the current cell.
If set to 3 - Sorted Combo Box, value items are displayed in sorted order in a drop-down combo box within
the current cell.
 PrintInfo Property · 461

If set to 4 - Check Box, value items are displayed as a check box within the current cell.
Use the ValueItems property to access the ValueItems collection for a Column object.
Use the AnimateWindow properties for additional control over the behavior of the Combo Box and the
Sorted Combo Box.
Note
If you are using setting 4 - Check Box with boolean data, you do not need to add any members to the
ValueItems collection, as boolean values are handled automatically.
See Also
ValueItem Object, ValueItems Collection (page 123)

PrintInfo Property
This property returns the default PrintInfo object of the grid's PrintInfos collection.
Syntax
TDBGrid.PrintInfo
Remarks
Read-only at run time. Not available at design time.
PrintInfo objects are used to specify page layout and print job characteristics.
See Also
TDBGrid Control (page 118)

PrintInfos Property
This property returns a collection of PrintInfo objects used to specify page layout and print job
characteristics.
Syntax
TDBGrid.PrintInfos
Remarks
Read-only at run time. Not available at design time.
See Also
TDBGrid Control (page 118)

RecordSelectors Property
This property returns or sets a value indicating if record selectors are displayed in a grid or split.
Syntax
object.RecordSelectors = boolean
Remarks
Read/Write at run time and design time.
462 · Object Reference

If True (the default), record selectors are displayed at the left edge of the grid or split.
If False, record selectors are not displayed.
If a grid contains multiple splits, then setting its RecordSelectors property has the same effect as setting
the RecordSelectors property of each split individually.
Note
When the user selects a row by clicking its record selector, the bookmark of the selected row is added to
the SelBookmarks collection.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

RecordSelectorStyle Property
This property returns the Style object that controls the appearance of RecordSelectors within a grid or
split.
Syntax
object.RecordSelectorStyle = variant
Remarks
Read/Write at run time and design time.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

RecordSelectorWidth Property
The RecordSelectorWidth property returns or sets the width of the RecordSelectors based on the
coordinate system of the grid's container.
Syntax
object.RecordSelectorWidth = single
Remarks
Read/Write at run time and design time.
The RecordSelectorWidth returns to default when set to 0. The default width of the record selector
column is equal to the width of the vertical scroll bar.
See Also
TDBGrid Control (page 118)
Split Object (page 122)
 RightToLeft Property · 463

RightToLeft Property
The property provides an appearance and functionality familiar to Middle East or Latin users.
Syntax
object.RightToLeft = boolean
Remarks
Read/Write at run time and design time.
When the RightToLeft property is set to True:
• Grid columns begin at the right boundary of the grid.
• Fixed columns are located on the right side of the grid.
• LeftCol identifies the rightmost visible column (the first column beyond the leftmost fixed
column).
• If there are selected columns, SelStartCol returns the index of the rightmost column in the range,
and SelEndCol returns the index of the leftmost column in the range.
• If the ScrollBars property is set to 3, a vertical scroll bar is placed on the left of the grid and a
horizontal scroll bar with the scroll box on the right is placed at the bottom. A ScrollBars
property setting of 1 places only the horizontal scroll bar, while a setting of 2 places only the
vertical scroll bar.
• Cell values (grid Text property) have right to left reading order.
When the RightToLeft property is set to False, the control behavior is the same as described in the
standard documentation.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Row Property
Specifies the display line of the current data's row.
Syntax
object.Row = integer
Remarks
Read/Write at run time. Not available at design time.
This property specifies the zero-based index of the current row relative to the first displayed row. It may
be set at run time to highlight a different cell within the current column.
The Row property accepts values ranging from 0 to VisibleRows - 1. An error occurs if you attempt to set
it to an invalid row index.
If the current row is not visible, then this property returns -1.
464 · Object Reference

For a TDBGrid control, changing the Row property at run time does not affect selected rows. Use the
collection returned by the SelBookmarks property to select or deselect individual rows.
For a TDBDropDown control, changing the Row property at run time also changes the value of the
SelectedItem property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowCount Property
This property returns or sets the number of rows in a RowBuffer object passed to an unbound event
procedure for a TDBGrid control.
Syntax
rowbuffer.RowCount = long
Remarks
Read/Write at run time. Not available at design time.
In the UnboundReadData event, this property indicates how many rows the grid is requesting. After
filling those rows by setting the Value and Bookmark properties, your event procedure should set the
RowCount property to the number of rows actually fetched.
In the UnboundAddData and UnboundWriteData events, this property is always set to 1, since only a
single row can be added or updated at a time. However, you can set this property to 0 to indicate that the
add or update operation failed.
Note
When a RowBuffer object is passed to an unbound event procedure, the initial value of the RowCount
property also specifies the maximum value. An error will occur if you attempt to exceed the maximum
value.
See Also
RowBuffer Object (page 121)

RowDividerColor Property
This property controls the row divider color of grid when RowDividerStyle is 7 - Custom Color.
Syntax
object.RowDividerColor = value
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
 RowDividerStyle Property · 465

RowDividerStyle Property
This property determines the style of the border drawn between grid rows.
Syntax
object.RowDividerStyle = value
Values
Design Time Run Time
0 - No dividers dbgNoDividers
1 - Black line dbgBlackLine
2 - Dark gray line (default) dbgDarkGrayLine
3 - Raised dbgRaised
4 - Inset dbgInset
5 - ForeColor dbgUseForeColor
6 - Light gray line dbgLightGrayLine
7 - Custom Color dbgCustomColor
Remarks
Read/Write at run time and design time.
The RowDividerStyle property does not control whether rows can be resized by dragging their border.
Use the AllowRowSizing property to control this behavior.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowHeight Property
This property returns or sets the height of all grid rows in terms of the coordinate system of the grid's
container.
Syntax
object.RowHeight = single
Remarks
Read/Write at run time and design time.
The RowHeight property accepts a floating point number from 0 to 10,000. The default value depends
upon the character height of the current font.
A setting of 0 causes the grid to readjust its display so that each row occupies a single line of text in the
current font. Therefore, the following statements will set the row height so that exactly two lines of text
are shown in each row:
TDBGrid1.RowHeight = 0
TDBGrid1.RowHeight = TDBGrid1.RowHeight * 2
466 · Object Reference

If the control's AllowRowSizing property is set to True, then the user can adjust the RowHeight property
at run time by dragging the row divider between any pair of record selectors.
Note
Increasing the RowHeight property does not wrap cell text at column boundaries unless the column's
WrapText property is True.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowSubDividerColor Property
This property controls the row subdivider color of grid when RowDividerStyle is 7 - Custom Color.
Syntax
TDBGrid.RowSubDividerColor = value
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
See Also
TDBGrid Control (page 118)

ScrollBars Property
This property returns or sets a value indicating whether a grid or split has horizontal or vertical scroll
bars.
Syntax
object.ScrollBars = value
Values
Design Time Run Time
0 - None dbgNone
1 - Horizontal dbgHorizontal
2 - Vertical dbgVertical
3 - Both dbgBoth
4 - Automatic (default) dbgAutomatic
Remarks
Read/Write at run time and design time.
The default setting for this property causes horizontal and/or vertical scroll bars to be displayed only if
the object's contents extend beyond its borders.
If a grid contains multiple splits, then setting its ScrollBars property has the same effect as setting the
ScrollBars property of each split individually.
 ScrollGroup Property · 467

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

ScrollGroup Property
This property is used to synchronize vertical scrolling between splits.
Syntax
split.ScrollGroup = integer
Remarks
Read/Write at run time and design time.
All splits with the same ScrollGroup setting will be synchronized when vertical scrolling occurs within
any one of them. Splits belonging to different groups can scroll independently, allowing different splits to
display different parts of the database.
If the ScrollBars property for a split is set to 4 - Automatic, then only the rightmost split of the group will
have a vertical scroll bar. If there is only one split, then setting this property has no effect.
Setting the FirstRow property for one split affects all other splits in the same group, keeping the group
synchronized.
Newly created splits have a ScrollGroup value of 1.
See Also
Split Object (page 122)

ScrollTips Property
The ScrollTips property determines whether the grid displays a pop-up text window when the scrollbar
thumb is dragged.
Syntax
object.ScrollTips = boolean
Remarks
Read/Write at run time and design time.
By default, this property is set to False, and ScrollTips are not displayed.
If the ScrollTips property is set to True, the FetchScrollTips event will be fired whenever the grid’s
scrollbar thumb is dragged.
If you do not provide a handler for the FetchScrollTips event, tips will not be displayed.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
468 · Object Reference

ScrollTrack Property
Scrollbar thumb causes the grid display to update.
Syntax
object.ScrollTrack = boolean
Remarks
Read/Write at run time and design time.
If True, moving the scrollbar thumb causes the grid’s display to update with new data.
If False (the default), moving the scrollbar thumb does not change the display.
If the ScrollTrack property is True, moving the scrollbar thumb causes the grid to scroll.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

SelBookmarks Property
This property returns a collection of selected row bookmarks.
Syntax
TDBGrid.SelBookmarks
Remarks
Read-only at run time. Not available at design time.
See Also
TDBGrid Control (page 118)

SelectedBackColor Property
This property controls the background color of selected rows and columns within a grid or split.
Syntax
object.SelectedBackColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The selected background color of a grid or split is determined by its SelectedStyle property setting. For
these objects, the SelectedBackColor property is a shortcut to the BackColor member of the
SelectedStyle property.
See Also
TDBGrid Control (page 118)
Split Object (page 122)
 SelectedForeColor Property · 469

SelectedForeColor Property
This property controls the foreground color of selected rows and columns within a grid or split.
Syntax
object.SelectedForeColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The selected foreground color of a grid or split is determined by its SelectedStyle property setting. For
these objects, the SelectedForeColor property is a shortcut to the ForeColor member of the SelectedStyle
property.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

SelectedStyle Property
This property returns or sets the Style object that controls the appearance of selected rows and columns
within a grid or split.
Syntax
object.SelectedStyle = variant
Remarks
Read/Write at run time and design time.
By default, this is the built-in Selected style.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

SelEndCol Property
This property returns or sets the zero-based ordinal position of the rightmost selected column in a split.
Syntax
object.SelEndCol = integer
Remarks
Read/Write at run time. Not available at design time.
If no columns are selected, then this property returns -1.
If a grid contains multiple splits, then setting its SelEndCol property has the same effect as setting the
SelEndCol property of the current split. The index of the current split is available through the TDBGrid
control's Split property.
470 · Object Reference

Setting this property to -1 deselects all columns and also sets the SelStartCol property to -1.
Note
You can also use the ClearSelCols method to deselect all columns within a split.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

SelLength Property
This property returns or sets the number of characters selected within the grid's editing window.
Syntax
TDBGrid.SelLength = long
Remarks
Read/Write at run time. Not available at design time.
When editing is not is progress, this property returns 0.
Setting SelLength to a value less than 0 causes a run time error.
Use the SelLength property in combination with the SelStart and SelText properties to set the insertion
point, establish an insertion range, select substrings, or clear text. These properties are useful for
implementing copy, cut, and paste operations that transfer string data to and from the clipboard.
See Also
TDBGrid Control (page 118)

SelRange Property
Returns true if a range of cells is currently selected.
Syntax
TDBGrid.SelRange
Remarks
Read-only at run time. Not available at design time.
This property returns True if the user has selected a range of cells (both rows and columns), False
otherwise.
See Also
TDBGrid Control (page 118)

SelStart Property
This property returns or sets the starting point of the text selection within the grid's editing window.
 SelStartCol Property · 471

Syntax
TDBGrid.SelStart = long
Remarks
Read/Write at run time. Not available at design time.
If no text is currently selected, then this property indicates the position of the insertion point.
When editing is not is progress, this property returns 0.
Setting SelStart to a value greater than the length of the text in the cell sets it to this length. Changing
SelStart moves the entire selection while preserving the value of SelLength, if possible. If there are not
enough characters, SelLength is decreased accordingly.
Use the SelStart property in combination with the SelLength and SelText properties to set the insertion
point, establish an insertion range, select substrings, or clear text. These properties are useful for
implementing copy, cut, and paste operations that transfer string data to and from the clipboard.
See Also
TDBGrid Control (page 118)

SelStartCol Property
This property returns or sets the zero-based ordinal position of the leftmost selected column in a split.
Syntax
object.SelStartCol = integer
Remarks
Read/Write at run time. Not available at design time.
If no columns are selected, then this property returns -1.
If a grid contains multiple splits, then setting its SelStartCol property has the same effect as setting the
SelStartCol property of the current split. The index of the current split is available through the TDBGrid
control's Split property.
Setting this property to -1 deselects all columns and also sets the SelEndCol property to -1.
Note
You can also use the ClearSelCols method to deselect all columns within a split.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

SelText Property
This property returns or sets the string containing the currently selected text within the grid's editing
window.
472 · Object Reference

Syntax
TDBGrid.SelText = string
Remarks
Read/Write at run time. Not available at design time.
If no text is currently selected, then this property returns an empty string.
Setting SelText to a new value sets SelLength to 0 and replaces the selected text with the new string.
Use the SelText property in combination with the SelStart and SelLength properties to set the insertion
point, establish an insertion range, select substrings, or clear text. These properties are useful for
implementing copy, cut, and paste operations that transfer string data to and from the clipboard.
See Also
TDBGrid Control (page 118)

ShowCollapseExpandIcons Property
Use this property to disable the displaying of expand/collapse icons.
Syntax
TDBGrid.ShowCollapseExpandIcons = boolean
Remarks
Read/Write at run time. Not available at design time.
See Also
Split Object (page 122)

Size Property
This property returns or sets the size of a split.
Syntax
split.Size = variant
Remarks
Read/Write at run time and design time.
The meaning of the value returned by this property is determined by the split's SizeMode property
setting.
If SizeMode is set to the default value of 0 - Scalable, then the value returned by the Size property is an
integer indicating the relative size of the split with respect to other scalable splits.
If SizeMode is set to 1 - Exact, then the value returned by the Size property is a floating point number
indicating the exact size of the split in terms of the coordinate system of the grid's container.
If SizeMode is set to 2 - Number of Columns, then the value returned by the Size property is an integer
indicating the number of columns displayed in the split.
 SizeMode Property · 473

Note
Note that when there is only one split (the grid's default behavior), the split spans the entire width of the
grid, the SizeMode property is always 0 - dbgScalable, and the Size property is always 1. Setting either of
these properties has no effect when there is only one split. If there are multiple splits, and you then
remove all but one, the SizeMode and Size properties of the remaining split automatically revert to 0 and
1, respectively.
See Also
Split Object (page 122)

SizeMode Property
This property determines how the Size property is used to determine the actual size of a split.
Syntax
split.SizeMode = value
Values
Design Time Run Time
0 - Scalable (default) dbgScalable
1 - Exact dbgExact
2 - Number of Columns dbgNumberOfColumns
Remarks
Read/Write at run time and design time.
If set to 0 - Scalable (the default), then the value returned by the Size property is an integer indicating the
relative size of the split with respect to other scalable splits. For example, if a grid contains 3 scalable
splits with Size properties equal to 1, 2, and 3, then the size of each split would be 1/6, 1/3, and 1/2 of
the total grid width, respectively.
If set to 1 - Exact, then the value returned by the Size property is a floating point number indicating the
exact size of the split in terms of the coordinate system of the grid's container. This setting allows you to
fix the size of the split so that it always has the same width, even if new splits are added or existing splits
are removed.
If set to 2 - Number of Columns, then the value returned by the Size property is an integer indicating the
number of columns displayed in the split, and the split will adjust its width to display the number of full
columns specified by the Size property. For example, if Size is set to 2, and the user scrolls the split
horizontally, then the width of the split will change so that 2 full columns are displayed, regardless of
how wide the columns are.
Note
Consider a grid containing both scalable splits and splits with a fixed number of columns. If a split with a
fixed number of columns is scrolled horizontally, the total width remaining for the scalable splits may
change because grid columns are generally of different widths. However, the ratios of the sizes of the
scalable splits remain the same as specified by their Size properties.
Note that when there is only one split (the grid's default behavior), the split spans the entire width of the
grid, the SizeMode property is always 0 - dbgScalable, and the Size property is always 1. Setting either of
these properties has no effect when there is only one split. If there are multiple splits, and you then
474 · Object Reference

remove all but one, the SizeMode and Size properties of the remaining split automatically revert to 0 and
1, respectively.
See Also
Split Object (page 122)

Source Property
The Source property returns a string that identifies the object or application from which the error
originated.
Syntax
error.Source
Remarks
Read-only at run time. Not available at design time.
The function of this property is identical to the ADO Source property.
Note
This property applies to Error object (OLE DB only).
See Also
Error Object (page 120)

Split Property
This property specifies the zero-based index of the current split.
Syntax
TDBGrid.Split = integer
Remarks
Read/Write at run time. Not available at design time.
See Also
TDBGrid Control (page 118)

Splits Property
This property returns a collection of Split objects.
Syntax
TDBGrid.Splits
Remarks
Read-only at run time. Not available at design time.
See Also
TDBGrid Control (page 118)
 SpringMode Property · 475

SpringMode Property
Sets or returns how columns size when the split is resized.
Syntax
object.SpringMode = boolean
Remarks
Read/Write at run time and design time.
When this property is set to True and the grid is horizontally resized, the column widths for visible
columns will expand and/or shrink proportionally.
When set to False (the default), column widths do not change as the grid is horizontally resized.
Note
You can control the minimum width on a per column basis by using the MinWidth property of
individual Column objects.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

SQLState Property
The SQLState property returns a five-character string that contains the error code produced when the
provider cannot process a SQL statement.
Syntax
error.SQLState
Remarks
Read-only at run time. Not available at design time.
The function of this property is identical to the ADO SQLState property.
Note
This property applies to Error object (OLE DB only).
See Also
Error Object (page 120)

Style Property
This property returns or sets the Style object that controls the normal appearance of a cell within a grid,
column, or split.
Syntax
object.Style = variant
Read/Write at run time and design time.
476 · Object Reference

Remarks
By default, this is the built-in Normal style.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

Styles Property
This property returns a collection of named Style objects.
Syntax
object.Styles
Remarks
Read-only at run time. Not available at design time.
When a grid is first created, it contains ten built-in styles, which control the following display aspects:
Normal Data cells in unselected, unhighlighted rows
Heading Column headers
Footing Column footers
Selected Data cells in selected rows
Caption Grid and split caption bars
HighlightRow Data cells in highlighted rows
EvenRow Data cells in even numbered rows
OddRow Data cells in odd numbered rows
FilterBar Cells in the filter bar row
RecordSelector Cells in the record selector column
Note
At design time, use the Style Factory property page to modify these built-in styles or create your own
named styles.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

TabAcrossSplits Property
This property controls the behavior of the tab and arrow keys at split borders.
Syntax
TDBGrid.TabAcrossSplits = boolean
 TabAction Property · 477

Remarks
Read/Write at run time and design time.
If True, the tab and arrow keys will move the current cell across split boundaries. When at the last column
of the rightmost split (or the first column of the leftmost split), they will either wrap to the next row, stop,
or move to other controls depending on the values of the WrapCellPointer and TabAction properties.
If False (the default), the tab and arrow keys will not move the current cell across split boundaries. They
will either wrap to the next row, stop, or move to other controls depending on the values of the
WrapCellPointer and TabAction properties.
Note
The TabAcrossSplits property does not determine if the tab and arrow keys will move from cell to cell, or
from control to control, or wrap to the next row. Use the AllowArrows, WrapCellPointer, and TabAction
properties to control this behavior. If the tab and arrow keys are able to move from cell to cell, this
property determines whether they will move across split boundaries to adjacent splits.
See Also
TDBGrid Control (page 118)

TabAction Property
This property defines the behavior of the tab key.
Syntax
TDBGrid.TabAction = value
Values
Design Time Run Time
0 - Control Navigation (default) dbgControlNavigation
1 - Column Navigation dbgColumnNavigation
2 - Grid Navigation dbgGridNavigation
3 - Grid Column Navigation dbgGridColumnNavigation
Remarks
Read/Write at run time and design time.
If set to 0 - Control Navigation (the default), the Tab key moves to the next or previous control on the form.
If set to 1 - Column Navigation, the Tab key moves the current cell to the next or previous column.
However, if this action would cause the current row to change, then the next or previous control on the
form receives focus.
If set to 2 - Grid Navigation, the Tab key moves the current cell to the next or previous column. The
behavior of the tab key at row boundaries is determined by the WrapCellPointer property. When this
setting is used, the tab key never results in movement to another control.
If set to 3 - Grid Column Navigation, the focus goes to the next control in the tab order when the Tab key is
entered on the last column of the last row.
478 · Object Reference

Note
The TabAction property does not determine if the tab key will cross split boundaries. Use the
TabAcrossSplits property to control this behavior.
See Also
TDBGrid Control (page 118)

TableName Property
Read-only at run time. Not available at design time.
Syntax
column.TableName
Remarks
The TableName property returns a string that identifies the name of the associated database table (if
available). You can use this property to distinguish between two columns that have the same DataField
value but are derived from different tables.
Use the Name property to retrieve the name of the associated database field.
See Also
Column Object (page 119)

Tag Property
This property returns or sets an expression that stores any extra data needed for your program.
Syntax
object.Tag = value
Remarks
Read/Write at run time. Not available at design time.
Unlike other properties, the value of the Tag property is not used by the grid.
See Also
Column Object (page 119)

Text Property
Sets or returns displayed cell text for the current row.
Syntax
object.Text = string
Remarks
Read/Write at run time. Not available at design time.
This is the default property of the TDBGrid and TDBDropDown controls.
 Top Property · 479

When applied to a Column object, this property returns or sets the formatted data value in a column for
the current row.
The value returned by the Text property is derived from the underlying data value by applying the
formatting as specified by the NumberFormat property of the Column object.
When the Text property is set for a formatted column, the underlying data value cannot be derived, and
the Text and Value properties will subsequently return the same result.
Use the Value property to access the underlying data value in a column for the current row.
When applied to a TDBGrid or TDBDropDown control, this property returns or sets the text of the
current cell. If the current cell is at EOF or BOF, an empty string is returned.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)

Top Property
This property returns the position of a column's top edge relative to the top of the grid in terms of the
coordinate system of the grid's container.
Syntax
column.Top
Remarks
Read-only at run time. Not available at design time.
If the column contains a header, the Top property returns the position of the header's top edge; if the
column does not contain a header, the Top property returns the position of the top edge of the column's
cell within the first displayed row.
If the grid's MultipleLines property is 0 - Disabled (the default value), a single record cannot span
multiple lines in the grid, and the Top property returns the same value for all columns.
If the grid's MultipleLines property is either 1 - Variable or 2 - Fixed, a single record may span multiple
lines in the grid. For columns on the first line, the Top property returns the height of the grid's caption
bar and split headings, if present. For columns on succeeding lines, the Top property returns this value
plus an appropriate multiple of the column header height.
Columns on the same line will return the same Top property value, while columns occupying lower lines
in a row will return larger Top property values since they are farther away from the top of the grid.
For example, the following code places a text box on top of the header for the first column:
Text1.Top = TDBGrid1.Top + TDBGrid1.Columns(0).Top
Use the Top property in conjunction with Left, Width, and RowTop to determine the exact location and
size of a column heading.
Note
To overlay the text box exactly on a column header, you may need to account for an extra pixel in the
width and height, depending upon the settings of the DividerStyle and RowDividerStyle properties. In
480 · Object Reference

Visual Basic, if the ScaleMode (Form) property of the parent form is set to pixels, then you can simply
add 1. If the ScaleMode (Form) is set to twips, then you can add the TwipsPerPixelX (Screen) and
TwipsPerPixelY (Screen) properties of the Screen (Visual Basic) object.
See Also
Column Object (page 119)

Translate Property
This property determines whether a column's underlying data values are automatically displayed in an
alternate form as specified by the ValueItem objects contained in a column's ValueItems collection.
Syntax
valueitems.Translate = boolean
Remarks
Read/Write at run time and design time.
If True, data values that match the Value property of a ValueItem are displayed using the corresponding
DisplayValue setting. The DisplayValue property may contain either text or graphics.
If False (the default), no translation is performed.
Use the ValueItems property to access the ValueItems collection for a Column object.
See Also
ValueItem Object, ValueItems Collection (page 123)

TransparentForegroundPicture Property
This property determines whether a style's foreground bitmap is rendered so that a particular color is
used as a transparent color.
Syntax
style.TransparentForegroundPicture = boolean
Remarks
Read/Write at run time and design time.
The foreground bitmap is specified by the ForegroundPicture property.
If True, the color of the lower left pixel of the foreground bitmap is used as the transparent color when the
style is applied to an object.
If False (the default), the foreground bitmap is displayed as is when the style is applied to an object.
See Also
Style Object (page 122)

TransparentRowPictures Property
This property determines whether custom record selector bitmaps are rendered so that a particular color
is used as a transparent color.
 Validate Property · 481

Syntax
TDBGrid.TransparentRowPictures = boolean
Remarks
Read/Write at run time and design time.
Record selector bitmaps are specified by the following properties: PictureAddNewRow,
PictureCurrentRow, PictureFooterRow, PictureHeaderRow, PictureModifiedRow, and
PictureStandardRow.
If True, the color of the lower left pixel of each record selector bitmap is used as the transparent color
when the bitmap is displayed.
If False (the default), each record selector bitmap is displayed as is.
See Also
TDBGrid Control (page 118)

Validate Property
This property determines whether values entered by the user must match one of the ValueItem objects
contained in a column's ValueItems collection.
Syntax
valueitems.Validate = boolean
Remarks
Read/Write at run time and design time.
If True, the grid automatically validates the user's input when the current cell is changed. If the cell
contents do not match the DisplayValue setting of one of the ValueItem objects, then focus remains on
the current cell and its prior contents are restored.
If False (the default), the grid performs no validation. However, you can still use the BeforeColUpdate
event to validate the user's changes.
The BeforeColUpdate event will not be executed for a column if both of the following are true:
1. The associated ValueItems collection contains at least one ValueItem.
2. The Validate property of the ValueItems collection is set to True.
Use the ValueItems property to access the ValueItems collection for a Column object.
See Also
ValueItem Object, ValueItems Collection (page 123)

Value Property (Column)

This property returns or sets the underlying data value in a column for the current row.
Syntax
column.Value = variant
482 · Object Reference

Remarks
Read/Write at run time. Not available at design time.
The Value property is useful for simulating data entry within a cell. When this property is set, the value
displayed in the cell respects the setting of the column's NumberFormat property.
This property always returns a string variant, even if the data type of the underlying field is numeric.
Use the Text property to access the formatted data value in a column for the current row.
See Also
Column Object (page 119)

Value Property (RowBuffer)

This property returns or sets the data value for the specified cell within a RowBuffer object passed to an
unbound event procedure for a TDBGrid control.
Syntax
rowbuffer.Value (Row, Col) = variant
Remarks
Read/Write at run time. Not available at design time.
The Row argument is a long integer specifying the row where the value is placed. The range of this
argument can be from 0 to RowCount - 1.
The Col argument is an integer specifying the column where the value is placed. The range of this
argument can be from 0 to ColumnCount - 1.
In the UnboundReadData event, your code must provide data values for the rows being fetched. In the
UnboundAddData and UnboundWriteData events, the user's changes are passed to your event
procedures via a RowBuffer object.
See Also
RowBuffer Object (page 121)

Value Property (Style)

This property returns the name of a style object.
Syntax
style.Value = variant
Remarks
Read/Write at run time (with restrictions). Not available at design time.
For style objects, the Value property is a synonym for the Name property, so the following statements are
equivalent:
Debug.Print TDBGrid1.Styles(0)
Debug.Print TDBGrid1.Styles(0).Name
For style objects that are members of the Styles collection, this property is read-only, and a trappable
error will occur if you attempt to set it in code. However, for independent style objects, and for
 Value Property (ValueItem) · 483

arguments passed to the FetchCellStyle, FetchCellTips, and FetchRowStyle events, the Value property
may be set in code to initialize the style object:
CellStyle.Value = "MyStyle"
CellStyle = "MyStyle" ' Both statements are equivalent
Note
For an independent style object, the Value property always returns an empty string. An independent
style object is not a member of the Styles collection, but is a standalone object created in code with a Dim
or Set statement using the New keyword.
See Also
Style Object (page 122)

Value Property (ValueItem)

This property returns or sets the underlying data value for a member of a ValueItems collection.
Syntax
valueitem.Value = variant
Remarks
Read/Write at run time and design time.
The DisplayValue property returns the translated data value for a value item.
Use the ValueItems property to access the ValueItems collection for a Column object.
See Also
ValueItem Object (page 123)

ValueItems Property
This property returns a collection of ValueItem objects for a column.
Syntax
column.ValueItems
Remarks
Read-only at run time. Not available at design time.
Note
At design time, use the Values property page to populate a column's ValueItems collection.
See Also
Column Object (page 119)

ViewColumnCaptionWidth Property
This property returns or sets the width of the presentation area of the column caption in terms of the
coordinate system of the grid's container.
484 · Object Reference

Syntax
TDBGrid.ViewColumnCaptionWidth = single
Remarks
Read/Write at run time and design time.
Note
This property is only applicable when the DataView property is set to 3 - Form or 4 - Inverted.
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

ViewColumnWidth Property
This property returns or sets the width of a column in terms of the coordinate system of the grid's
container.
Syntax
object.ViewColumnWidth = single
Remarks
Read/Write at run time and design time.
Note
This property is only applicable when the DataView property is set to 3 - Form or 4 - Inverted.
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

VerticalAlignment Property
This property returns or sets a value that determines the vertical alignment of data when the style is
applied to a data cell, header, footer, or caption bar.
Syntax
style.VerticalAlignment = value
Values
Design Time Run Time
0 - Top (default) dbgTop
1 - Bottom dbgBottom
2 - Vertical Center dbgVertCenter
Remarks
Read/Write at run time and design time.
Use the Alignment property to control horizontal alignment.
 Visible Property · 485

See Also
Style Object (page 122)

Visible Property
This property returns a boolean indicating whether a column in a grid or split is currently visible or
capable of being scrolled into view.
Syntax
column.Visible = boolean
Remarks
Read/Write at run time and design time.
If True, then the column has not been hidden in code or by the user.
If False, then the column is hidden and cannot be scrolled into view.
For columns created at design time, the default value of this property is True. For columns created in code
at run time, the default value of this property is False.
Note
If a column has been scrolled out of view, its Visible property remains True.
See Also
Column Object (page 119)

VisibleCols Property
Returns the number of visible columns.
Syntax
object.VisibleCols
Remarks
Read-only at run time.
For TDBGrid controls, this property returns the number of visible columns in the current split. The value
returned includes both fully and partially displayed columns. You can use the Split property of the
TDBGrid control to determine the index of the current split.
For TDBDropDown controls, this property returns the number of visible columns in the entire control,
since there can only be one split. The value returned includes both fully and partially displayed columns.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

VisibleRows Property
This property returns the number of visible rows in the control.
486 · Object Reference

Syntax
object.VisibleRows = integer
Remarks
Read-only at run time.
The value returned includes both fully and partially displayed rows.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

VScrollWidth Property
Returns the vertical scroll bar width, if present.
Syntax
object.VScrollWidth
Remarks
Read-only at run time. Not available at design time.
The VScrollWidth property returns the width of a split's vertical scroll bar in container units, which
depend on the ScaleMode (Visual Basic) of the container. If no vertical scroll bar exists, then the returned
value is zero. If object is a TDBGrid control, then its current split is used.
You can use the VScrollWidth and HScrollHeight properties to check if the scroll bars are present and to
obtain the scroll bar size when designing the grid layout and sizing the grid and its columns.
See Also
TDBGrid Control (page 118)
Split Object (page 122)

Width Property
This property returns or sets the width of a column in terms of the coordinate system of the grid's
container.
Syntax
column.Width = single
Remarks
Read/Write at run time and design time.
Use the Width property in conjunction with Left, RowHeight, and RowTop to determine the size and
placement of controls displayed on top of a grid cell.
Note
The DefColWidth property controls the default width of new columns created at run time.
 WrapCellPointer Property · 487

See Also
Column Object (page 119)

WrapCellPointer Property
This property determines the behavior of the arrow keys if AllowArrows is True.
Syntax
TDBGrid.WrapCellPointer = boolean
Remarks
Read/Write at run time and design time.
If True, the cell pointer will wrap from the last column to the first in the next row (or from the first
column to the last in the previous row).
If False (the default), the cell pointer will not wrap to the next (or previous) row, but will stop at the last
(or first) column of the current row.
If TabAcrossSplits is False, the cell pointer will wrap only within the current split. If TabAcrossSplits is
True, the cell pointer will move from one split to the next before wrapping occurs.
If TabAction is set to 2 - Grid Navigation, the tab key will behave like the arrow keys, and will
automatically wrap to the next or previous cell.
See Also
TDBGrid Control (page 118)

WrapRowPointer Property
This property defines behavior of tab and arrow keys at column boundaries.
Syntax
TDBGrid.WrapRowPointer = boolean
Remarks
Read/Write at run time and design time.
If True, the cell pointer will wrap from the last row to the first in the next column (or from the first row to
the last in the previous column).
If False (the default), the cell pointer will not wrap to the next (or previous) column, but will stop at the
last (or first) row of the current column.
See Also
TDBGrid Control (page 118)

WrapText Property
This property returns or sets a value indicating whether an object wordwraps text at cell boundaries.
Syntax
object.WrapText = boolean
488 · Object Reference

Remarks
Read/Write at run time and design time.
If True, a line break occurs before words that would otherwise be partially displayed.
If False (the default), no line break occurs and text is clipped at the cell's right edge.
Use this property in conjunction with the RowHeight property to produce multiline displays.
The wordwrap behavior of a column is determined by its Style property setting, and the WrapText
property is a shortcut to the WrapText member of the Style property.
For Style objects, the value of the WrapText property is inherited from the parent style (if any) unless
explicitly overridden.
See Also
Column Object (page 119)
Style Object (page 122)

True DBGrid Methods

AboutBox Method
This method displays the version number and copyright notice for the specified control.
Syntax
object.AboutBox
Arguments
None
Return Value
None
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Add Method
Adds a new item to a collection.
Syntax
object.Add (item)
Method applies to Columns, GroupColumns, Layouts, PrintInfos, SelBookmarks, Splits, Styles, and
ValueItems collections.
Arguments
item is an expression or object that specifies the member to add to the collection.
 AddCellStyle Method · 489

Return Value
A reference to the newly created object where appropriate, otherwise none.
Remarks
For the Columns, GroupColumns, PrintInfos, Splits, and Styles collections, this method creates a new
instance of the appropriate object, adds it to the collection, and returns it to the caller.
For the Layouts, SelBookmarks, and ValueItems collections, this method adds the specified object to the
collection without returning a value.
The data type of the item argument depends on the collection. For the Columns and Splits collections,
item is a zero-based integer denoting the index of the newly created Column or Split object.
For the SelBookmarks collection, item is a variant representing a bookmark that identifies a particular
row. Depending upon the setting of the DataMode property, item may have been obtained from a bound
data source, an unbound mode or application mode event, or an XArrayDB row index.
For the Styles collection, item is the unique name of the Style object to be created. Similarly, for the
PrintInfos collection, item is the unique name of the PrintInfo object to be created.
For the ValueItems collection, item is an independent ValueItem object.
For the Layouts collection, item is the name of a grid layout to be saved to the binary layout file specified
by the LayoutFileName property. All of the grid's persistent properties are saved in their current state. If
the named layout already exists in the file, the property settings are overwritten. If the named layout does
not already exist, it is added to the file.
See Also
Column Object, Columns Collection (page 119)
Split Object, Splits Collection (page 122)
Style Object, Styles Collection (page 122)
GroupColumns Collection (page 120)
PrintInfo Object, PrintInfos Collection (page 121)
Layouts Collection (page 121)
SelBookmarks Collection (page 121)
ValueItem Object, ValueItems Collection (page 123)

AddCellStyle Method
Adds a cell condition to an object.
Syntax
object.AddCellStyle condition, style
Arguments
condition is a combination of one or more CellStyleConstants.
style is a Style object that specifies font and color attributes.
490 · Object Reference

Return Value
None
Remarks
This method allows you to control the font and color of cells within a grid, column, or split according to
the status values (CellStyleConstants) specified by the condition argument:
1 - dbgCurrentCell The cell is the current cell as specified by the Bookmark, Col, and Split
properties. At any given time, only one cell can have this status. When the
MarqueeStyle property is set to 6 - Floating Editor, this condition is ignored.
2 - dbgMarqueeRow The cell is part of a highlighted row marquee. When the MarqueeStyle
property indicates that the entire current row is to be highlighted, all visible
cells in the current row have this additional condition set.
4 - dbgUpdatedCell The cell contents have been modified by the user but not yet written to the
database. This condition is also set when cell contents have been modified
in code with the Text or Value properties.
8 - dbgSelectedRow The cell is part of a row selected by the user or in code. The SelBookmarks
collection contains a bookmark for each selected row.
0 - dbgNormalCell The cell satisfies none of these conditions.
You can add the first four values together to specify multiple cell conditions. For example, a cell status
value of 9 (dbgCurrentCell + dbgSelectedRow) denotes a current cell within a selected row. You
can also use a cell status value of 0 (dbgNormalCell) to refer to only those cells without any of the four
basic cell conditions.
The style argument specifies the attributes that will override the default font and color characteristics for
cells within an object. For example, the following code causes updated cells to be displayed in red:
Dim S As New TrueDBGrid60.Style
S.ForeColor = vbRed
TDBGrid1.AddCellStyle dbgUpdatedCell, S
Each time the AddCellStyle method is invoked, the specified cell condition is added to the list of existing
conditions. Hence, by repeated use of this method it is possible to set up multiple conditions to affect the
appearance of a grid, column, or split.
Note
If a cell condition already exists for a particular condition value, the new style setting replaces the existing
one.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

AddRegexCellStyle Method
Adds a regular expression cell condition to an object.
 AddRegexCellStyle Method · 491

Syntax
object.AddRegexCellStyle condition, style, regex
Arguments
condition is a combination of one or more CellStyleConstants.
style is a Style object that specifies font and color attributes.
regex is a regular expression string.
Return Value
None
Remarks
This method allows you to control the font and color of cells within a grid, column, or split according to
their contents. The status values (CellStyleConstants) specified by the condition argument determine
which cells are affected:
1 - dbgCurrentCell The cell is the current cell as specified by the Bookmark, Col, and Split
properties. At any given time, only one cell can have this status. When the
floating editor MarqueeStyle property setting is in effect, this condition is
ignored.
2 - dbgMarqueeRow The cell is part of a highlighted row marquee. When the MarqueeStyle
property indicates that the entire current row is to be highlighted, all visible
cells in the current row have this additional condition set.
4 - dbgUpdatedCell The cell contents have been modified by the user but not yet written to the
database. This condition is also set when cell contents have been modified
in code with the Text or Value properties.
8 - dbgSelectedRow The cell is part of a row selected by the user or in code. The SelBookmarks
collection contains a bookmark for each selected row.
0 - dbgNormalCell The cell satisfies none of these conditions.
-1 - dbgAllCells All cells satisfy this condition.
You can add the first four values together to specify multiple cell conditions. For example, a cell status
value of 9 (dbgCurrentCell + dbgSelectedRow) denotes a current cell within a selected row. You
can also use a cell status value of 0 (dbgNormalCell) to refer to only those cells without any of the four
basic cell conditions. To designate that a cell condition should apply to all cells regardless of status, use a
cell status value of -1 (dbgAllCells).
The regex argument is a regular expression string that describes the pattern matching to be performed on
cell contents. The regular expressions supported by True DBGrid are a subset of standard Unix regular
expression syntax and are not compatible with the Visual Basic Like operator. The following special
characters are supported:
p* Any pattern followed by an asterisk matches zero or more occurrences of that pattern.
For example, ab*c matches ac, abc, and abbcy (partial match).
p+ Any pattern followed by a plus sign matches one or more occurrences of that pattern.
For example, ab+c matches abc and abbcy, but not ac.
492 · Object Reference

[list] A list of case-sensitive characters enclosed in brackets matches any one of those
characters in the given position in the string. Character ranges can be used, as in
[abcd], which is equivalent to [a-d]. Multiple ranges can also be used. For example, [A-
Za-z0-9] matches any letter or digit. Bracketed patterns can also be combined with
either the * or + operators. The pattern [A-Z]+ matches a sequence of one or more
uppercase letters.
[^list] If a list starts with a caret, it matches any character except those specified in the list.
. (period) A period represents any single character.
^p A caret at the beginning of a pattern forces a match to occur at the start of a cell.
Otherwise, the pattern can match anywhere within a cell.
p$ A dollar sign at the end of a pattern forces a match to occur at the end of a cell.
Otherwise, the pattern can match anywhere within a cell.
\c Any character preceded by a backslash represents itself, unless enclosed in brackets, in
which case the backslash is interpreted literally.
Any other character represents itself and will be compared with respect to case.
The style argument specifies the attributes that will override the default font and color characteristics for
cells within an object. For example, the following code causes normal cells containing the letters "SQL" to
be displayed in bold:
Dim S As New TrueDBGrid60.Style
S.Font.Bold = True
TDBGrid1.AddRegexCellStyle dbgNormalCell, S, "SQL"
Each time the AddRegexCellStyle method is invoked, the specified cell condition is added to the list of
existing conditions. Hence, by repeated use of this method it is possible to set up multiple conditions to
affect the appearance of a grid, column, or split.
Note
If a cell condition already exists for a particular pair of condition and regex values, the new style setting
replaces the existing one.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

AutoSize Method
Automatically sizes the column width.
Syntax
column.AutoSize
Arguments
None
 CaptureImage Method · 493

Return Value
None
Remarks
The AutoSize method adjusts the width of a column to accommodate the longest visible field within that
column. Calling this method in code has the same effect as the user double-clicking a column divider.
If the column is hidden or scrolled out of view, calling this method results in a trappable error.
The AllowSizing property must be set to True for columns to be resized by the user. However, you can
use the AutoSize method when the column's AllowSizing property is False, just as you can set the
column width when AllowSizing is False.
See Sizing Columns (page 188) for more information.
See Also
Column Object (page 119)

CaptureImage Method
This method returns an image of the grid in a format that you can assign to the Picture property of a
Visual Basic form or control, or the PaintPicture method of the Printer object.
Syntax
object.CaptureImage
Arguments
None
Return Value
A picture object containing a snapshot of the control's display.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

CellContaining Method
Identifies a row and column under an X, Y coordinate pair.
Syntax
TDBGrid.CellContaining (x, y, rowindex, colindex)
Arguments
x and y are singles that define a coordinate pair in twips.
rowindex is a long that receives the zero-based index of the row beneath the specified Y coordinate.
colindex is an integer that receives the zero-based index of the column beneath the specified X coordinate.
Return Value
A boolean that indicates whether a data cell is beneath the specified coordinate pair.
494 · Object Reference

Remarks
The CellContaining method combines the ColContaining and RowContaining methods into one call. If
the coordinate pair specified by x and y points to a data cell, this method returns True, and the rowindex
and colindex arguments receive zero-based indexes that identify the cell.
This method is useful when working with mouse and drag events when you are trying to determine
where the user clicked or dropped another control in terms of a grid cell.
If the specified coordinate is outside of the grid's data area, this method returns False. You can use the
PointAt method to determine what kind of grid element, if any, is beneath the specified coordinate.
Note
You must convert the x and y arguments to twips, even if the container's ScaleMode (Visual Basic)
setting specifies a different unit of measurement.
See Also
TDBGrid Control (page 118)

CellText Method
Returns displayed column text for any row.
Syntax
column.CellText (bookmark)
Arguments
bookmark is a variant representing a grid row.
Return Value
A string containing the displayed column text for the specified row.
Remarks
The CellText method returns a formatted string representation of the data in a column for the row
specified by the bookmark argument. Using the CellText method is similar to accessing the Text property,
except that you can select a specific row from which to retrieve the value.
The value returned by the CellText method is derived from the underlying data value by applying the
formatting as specified by the NumberFormat property of the Column object.
Using the CellText method to extract information from a cell doesn't affect the current selection.
Use the CellValue method to access the unformatted data value for the specified row.
See Also
Column Object (page 119)

CellValue Method
Returns displayed column text for any row.
Syntax
column.CellValue (bookmark)
 Clear Method · 495

Arguments
bookmark is a variant representing a grid row.
Return Value
A variant containing the underlying data value for the specified row.
Remarks
The CellValue method returns the raw data value in a column for the row specified by the bookmark
argument. Using the CellValue method is similar to accessing the Value property, except that you can
select a specific row from which to retrieve the value.
Using the CellValue method to extract information from a cell doesn't affect the current selection.
Use the CellText method to access the formatted data value for the specified row.
See Also
Column Object (page 119)

Clear Method
The Clear method removes all items from a collection.
Syntax
object.Clear
Arguments
None
Return Value
None
Remarks
For a Columns collection associated with a TDBGrid control, TDBDropDown control, or Split object,
this method removes all Column objects.
For a PrintInfos collection associated with a TDBGrid control, this method removes all PrintInfo objects,
then re-creates the default PrintInfo object.
For a SelBookmarks collection associated with a TDBGrid control, this method removes all bookmarks
and deselects the corresponding grid rows.
For a ValueItems collection associated with a Column object, the Clear method removes all ValueItem
objects.
See Also
Column Object, Columns Collection (page 119)
PrintInfo Object, PrintInfos Collection (page 121)
SelBookmarks Collection (page 121)
ValueItem Object, ValueItems Collection (page 123)
496 · Object Reference

Clear Method (DataObject)

This method deletes the contents of a DataObject object.
Syntax
dataobject.Clear
Arguments
None
Return Value
None
Remarks
The TDBGrid control supplies an argument of type DataObject when it fires the following events:
OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.
Note
This method is available only when the grid is the source component of a drag/drop operation (that is,
within the OLESetData and OLEStartDrag events). A trappable error will occur if you attempt to call it
in any other context.
See Also
DataObject Object (page 119)

Clear Method (Errors)

For an Errors collection associated with an OLE DB grid, the Clear method removes all of its Error
objects.
Syntax
errors.Clear
Arguments
None
Return Value
None
Remarks
The grid Errors collection is filled with Error objects when an error occurs. The information in the Errors
collection is accessible in the grid's Error event and from then onward, until: (1) another error occurs, or
(2) the user calls TDBGrid.Errors.Clear. This behavior mimics the standard ADO Errors collection: it
is not cleared automatically. The fact that the grid's Errors collection is non-empty does not necessarily
mean that an error just occurred; it only means that there was an error once and the collection has not
been cleared.
See Also
Error Object, Errors Collection (page 120)
 ClearCellStyle Method · 497

ClearCellStyle Method
The ClearCellStyle method removes a cell condition established with a previous call to the AddCellStyle
method for the object in question. If no such cell condition exists, then calling this method has no effect.
Syntax
object.ClearCellStyle condition
Arguments
condition is a combination of one or more CellStyleConstants.
Return Value
None
Remarks
If the condition argument is -1 (dbgAllCells), then all non-regex cell conditions are removed, regardless
of status.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

ClearFields Method
The ClearFields method restores the default grid layout (with two blank columns) so that subsequent
ReBind operations will automatically derive new column bindings from the (possibly changed) data
source.
Syntax
object.ClearFields
Arguments
None
Return Value
None
Remarks
You can cancel the grid's automatic layout behavior by invoking the HoldFields method.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
498 · Object Reference

ClearRegexCellStyle Method
The ClearRegexCellStyle method removes a cell condition established with a previous call to the
AddRegexCellStyle method for the object in question.
Syntax
object.ClearRegexCellStyle condition, [regex]
Arguments
condition is a combination of one or more CellStyleConstants.
regex is an optional regular expression string.
Return Value
None
Remarks
If no such cell condition exists, then calling this method has no effect.
If regex is omitted, then all cell conditions for any regular expression matching the condition argument are
removed. If condition is -1 (dbgAllCells), then all regex cell conditions are removed, regardless of status
or expression.
If regex is supplied, then the single cell condition matching both arguments is removed. However, if
condition is -1 (dbgAllCells), then all cell conditions for the specified regular expression are removed,
regardless of status.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

ClearSelCols Method
The ClearSelCols method deselects all columns in a split. If no columns are selected, then this method
does nothing.
Syntax
object.ClearSelCols
Arguments
None
Return Value
None
Remarks
If a grid contains multiple splits, then invoking its ClearSelCols method has the same effect as invoking
the ClearSelCols method for the current split. The index of the current split is available through the
TDBGrid control's Split property.
 Close Method · 499

Use the SelStartCol and SelEndCol properties to determine the current column selection range for a
split.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

Close Method
The Close method disconnects the grid from the data source.
Syntax
TDBGrid.Close [repaint]
Arguments
repaint is an optional boolean that determines whether the grid should clear its display.
Return Value
None
Remarks
The optional repaint argument instructs the grid whether or not to "clear" the grid of data. If repaint is True
(the default if not specified), the grid is cleared of all data; if repaint is False, the data currently on display
at the time of the close remains, but the grid's user interface is disabled so that no operations can be
performed on the grid. All database related coding operations (such as MoveNext, MovePrevious) will
return data access errors until the connection is re-established with any of the following methods:
ReBind, Refresh, or ReOpen.
Passing a value of False to the Close method is useful when operations are performed that would
otherwise "flicker" the display.
The data source connection is automatically reopened whenever the grid's ReBind, Refresh. or ReOpen
methods are executed. The grid will be repopulated with data and the appropriate row will be made
current. Care should be taken when using ReBind or ReOpen with unbound grids, as these operations
assume the current row bookmark still exists.
In the case of a bound grid, Close allows database operations to be performed without interference from
the grid. For example, closing the grid and closing the Recordset and Database objects associated with the
Data control:
TDBGrid1.Close
Data1.Recordset.Close
Data1.Database.Close
would allow database operations which manipulate the database files (such as pack or copy) to be
performed.
The Close method can also be used to temporarily disconnect a grid from its data source when many
notification-generating operations need to be performed. For example, if your application contains a loop
that deletes all of the selected records in a grid, you can first Close (disconnect) the grid as follows:
TDBGrid1.Close False
500 · Object Reference

so that no notifications will be processed by the grid. Otherwise, the grid will show every row movement
and deletion as the records are deleted. The False argument tells the grid not to repaint the screen, which
has the effect of leaving the grid display unchanged. When the record delete operations are completed,
perform a grid ReOpen (or ReBind) to reconnect and repaint the grid with the remaining (undeleted)
records. This technique is also useful for RDC/RDO where clones are not available.
See Also
TDBGrid Control (page 118)

ColContaining Method
The ColContaining method returns the ColIndex value of the grid column containing the specified
coordinate. This value ranges from 0 to Columns.Count - 1.
Syntax
object.ColContaining (coordinate)
Arguments
coordinate is a single that defines a horizontal coordinate (X value) in twips.
Return Value
An integer corresponding to the index of the column beneath the specified X coordinate.
Remarks
This method is useful when working with mouse and drag events when you are trying to determine
where the user clicked or dropped another control in terms of a grid column.
If coordinate is outside of the grid's data area, this method returns -1.
The ColContaining method returns the ColIndex of the column indicated, not the visible column
position. For example, if coordinate falls within the first visible column, but two columns have been
scrolled off the left side of the control, the ColContaining method returns 2, not 0 (assuming that the user
did not move any columns previously).
Note
You must convert the coordinate argument to twips, even if the container's ScaleMode (Visual Basic)
setting specifies a different unit of measurement.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

CollapseBand Method
The CollapseBand method collapses all rows in a hierarchical grid display for the specified band.
Syntax
TDBGrid.CollapseBand band
Arguments
band is a zero-based index that identifies a particular band.
 CollapseChild Method · 501

Return Value
None
Remarks
This is a useful way to quickly collapse all of the records in the band with one step, instead of one record
at a time. Note that all of the Bands that are below the one specified in the hierarchy will also be
collapsed.
You can use the GetBand method to obtain the band number corresponding to a particular grid column.
This method is only supported by the OLE DB version of True DBGrid Pro. It is used only in bound mode
and has no effect in unbound or storage modes.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

CollapseChild Method
Collapses the child grid.
Syntax
TDBGrid.CollapseChild
Return Value
None
Remarks
Method applies to TDBGrid control (OLE DB only).
See Also
TDBGrid Control (page 118)

Delete Method
The Delete method deletes the current record, then automatically moves to the next available record.
Syntax
TDBGrid.Delete
Arguments
None
Return Value
None
Remarks
If the last record is deleted, then EOF becomes the current position.
502 · Object Reference

See Also
TDBGrid Control (page 118)

ExpandBand Method
The ExpandBand method expands all rows in a hierarchical grid display for the specified band.
Syntax
TDBGrid.ExpandBand band
Arguments
band is a zero-based index that identifies a particular band.
Return Value
None
Remarks
This is a useful way to quickly expand the records in the specified band with one step, instead of one row
at a time.
You can use the GetBand method to obtain the band number corresponding to a particular grid column.
This method is only supported by the OLE DB version of True DBGrid Pro. It is used only in bound mode
and has no effect in unbound or storage modes.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

ExpandChild Method
Expands the child grid.
Syntax
TDBGrid.ExpandChild
Return Value
None
Remarks
Method applies to TDBGrid control (OLE DB only).
See Also
TDBGrid Control (page 118)

ExportBegin Method
The ExportBegin method prepares the grid for export to an HTML file by creating an internal clone of the
current recordset.
 ExportEnd Method · 503

Syntax
TDBGrid.ExportBegin [bookmark]
Arguments
bookmark is an optional bookmark that specifies the first row to be exported. If omitted, the first available
row is used.
Return Value
None
Remarks
Each call to the ExportBegin method must be matched by a corresponding call to the ExportEnd method.
You must call the ExportBegin method prior to calling the ExportRows method, which outputs an HTML
table to a specified file.
These methods are typically used in server-side applications that present ad hoc query data as a series of
HTML tables containing a small number of rows. In such applications, you can store the value returned
by the ExportNextBookmark property in a database or collection object for the next call to the
ExportBegin method, as in the following example:
Private Sub WebItem1_Respond()
' If there are no cookies, start exporting from the
' beginning of the file, otherwise the "user" cookie
' contains the bookmark of the next row to be exported.
If Request.Cookies.Count = 0 Then
TDBGrid1.ExportBegin
Else
TDBGrid1.ExportBegin Request.Cookies("user"))
End If

' Export ten rows, overwriting the file's contents

TDBGrid1.ExportRows FileName, False, 10

' Store the next bookmark in the "user" cookie

Response.Cookies("user") = TDBGrid1.ExportNextBookmark

' Terminate the export operation and redirect the

' browser to the file containing the HTML table.
TDBGrid1.ExportEnd
Response.Redirect FileName
End Sub
See Also
TDBGrid Control (page 118)

ExportEnd Method
The ExportEnd method releases the internal recordset clone created by the previous call to the
ExportBegin method.
Syntax
TDBGrid.ExportEnd
Arguments
None
504 · Object Reference

Return Value
None
See Also
TDBGrid Control (page 118)

ExportRows Method
The ExportRows method exports a sequence of rows from the grid to the specified file as an HTML table.
Syntax
TDBGrid.ExportRows pathname, append, rows, [tablewidth]
Arguments
pathname specifies the file to which grid rows are exported.
append is a boolean that specifies whether rows are added to the end of the file.
rows is a long integer that specifies the number of rows to be exported.
tablewidth is an optional variant used to qualify the generated <table> tag.
Return Value
None
Remarks
The append argument should be set to True to add the table to the end of an existing file, False to overwrite
the entire file. In either case, the file is created if it does not exist.
The ExportRows method must be preceded by a call to ExportBegin, which specifies the bookmark of the
first row to be exported. Failure to call ExportBegin before ExportRows results in a trappable error.
The maximum number of rows to be exported is given by the rows argument. The actual number of rows
exported may be less if the end of the data source is reached. You can use the ExportEOF property to
determine if there are more rows available for export.
If specified, the tablewidth argument is used as the width option of the generated <table> tag. This
argument is defined as a variant to accommodate both numeric and string qualifiers. For example, an
integer value denotes an absolute width in pixels, while the string "75%" indicates that the table should
occupy three-fourths of the available page width.
Note
The HTML code generated by this method contains a single <table> tag with a <tr> entry for each data
row and a <th> entry for each grid, split, and column caption. The output preserves as much of the grid's
original formatting as possible, including colors, fonts, alignment, and relative column widths.
See Also
TDBGrid Control (page 118)

ExportToDelimitedFile Method
The ExportToDelimitedFile method exports the specified rows from the grid to the specified file as
delimited ASCII text, where each row (record) occupies its own line.
 ExportToFile Method · 505

Syntax
TDBGrid.ExportToDelimitedFile pathname, [delim], [selector], [prefix], [suffix]
Arguments
pathname specifies the file to which grid rows are exported.
delim specifies an optional delimiter string used to separate fields.
selector is an optional value that specifies the rows to be exported.
prefix specifies an optional string used with suffix to surround each value.
suffix specifies an optional string used with prefix to surround each value.
Return Value
None
Remarks
Fields are delimited by the delim string (the default delim is empty). Field values can also be placed
between a prefix string and suffix string.
The selector argument determines the rows to be exported. It can be one of the following constant values:
0 - dbgAllRows All available rows are exported. If the selector argument is omitted, this value
is assumed.
1 - dbgSelectedRows Only selected rows are exported. The grid's SelBookmarks collection
contains a bookmark for each selected row.
2 - dbgCurrentRow Only the current row is exported.
See Also
TDBGrid Control (page 118)

ExportToFile Method
The ExportToFile method exports the specified rows from the grid to the specified file as an HTML table.
Syntax
TDBGrid.ExportToFile pathname, append, [selector], [tablewidth]
Arguments
pathname specifies the file to which grid rows are exported.
append is a boolean that specifies whether rows are added to the end of the file.
selector is an optional RowSelectorConstants value that specifies the rows to be exported.
tablewidth is an optional variant used to qualify the generated <table> tag.
Return Value
None
Remarks
The append argument should be set to True to add the table to the end of an existing file, False to overwrite
the entire file. In either case, the file is created if it does not exist.
506 · Object Reference

The selector argument determines the rows to be exported. It can be one of the following constant values:
0 - dbgAllRows All available rows are exported. If the selector argument is omitted, this value
is assumed.
1 - dbgSelectedRows Only selected rows are exported. The grid's SelBookmarks collection
contains a bookmark for each selected row.
2 - dbgCurrentRow Only the current row is exported.
If specified, the tablewidth argument is used as the width option of the generated <table> tag. This
argument is defined as a variant to accommodate both numeric and string qualifiers. For example, an
integer value denotes an absolute width in pixels, while the string "75%" indicates that the table should
occupy three-fourths of the available page width.
The HTML code generated by this method contains a single <table> tag with a <tr> entry for each data
row and a <th> entry for each grid, split, and column caption. Normally, you will insert this table into
another HTML file that serves as a template for the page to be browsed.
The output preserves as much of the grid's original formatting as possible, including colors, fonts,
alignment, and relative column widths.
Note
ExportToFile is a standalone method; it should not be surrounded by calls to ExportBegin and
ExportEnd. To export a subset of the available rows, use the ExportRows method instead of
ExportToFile.
See Also
TDBGrid Control (page 118)

Fix Method
Fixes or unfixes a column from scroll.
Syntax
Sub Fix(Fix As Boolean, pos As Integer)
Remarks
This method takes two arguments:
fix - True/False. True to fix the column.
pos - Where to position the column if you fix more than one.
See Also
Column Object (page 119)

GetBand Method
The GetBand method returns the band number corresponding to a grid column.
Syntax
TDBGrid.GetBand (columnindex)
 GetBookmark Method · 507

Arguments
columnindex is a zero-based integer that identifies a Column object.
Return Value
An integer corresponding to the index of the band of a particular grid column.
Remarks
The return value is used with the CollapseBand and ExpandBand methods when manipulating master-
detail displays in code.
This method is only supported by the OLE DB version of True DBGrid Pro. It is used only in bound mode
and has no effect in unbound or storage modes.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

GetBookmark Method
The GetBookmark method returns a bookmark for a row relative to the current row, which need not be
visible.
Syntax
object.GetBookmark (offset)
Arguments
offset is a long integer that defines the target row relative to the current row.
Return Value
A variant containing a bookmark relative to the current row as specified by offset.
Remarks
If offset is 0, this method returns the bookmark of the current row. The value returned will be the same as
that returned by the Bookmark property.
If offset is 1, this method returns the bookmark of the row following the current row. Similarly, if offset is -
1, this method returns the bookmark of the row preceding the current row.
If offset is an arbitrary integer N, this method returns the bookmark of the Nth row following the current
row if N is positive, or preceding the current row if N is negative.
If offset targets a row after the last available record or before the first available record, then this method
returns Null.
Note
Do not confuse the GetBookmark method with the RowBookmark method, which can only return
bookmarks for visible rows.
508 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

GetData Method
This method retrieves data from a DataObject object using the specified data format.
Syntax
dataobject.GetData (format)
Arguments
format is a constant or value that specifies the data format being requested.
Return Value
A variant containing the data for the requested format.
Remarks
The TDBGrid control supplies an argument of type DataObject when it fires the following events:
OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.
Note
In this version of True DBGrid, only the vbCFText format is supported. If you supply an argument of
zero, vbCFText is assumed.
See Also
DataObject Object (page 119)

GetFormat Method
Given a clipboard format constant or an equivalent value, this method returns True if a DataObject object
contains a matching value, False otherwise.
Syntax
dataobject.GetFormat (format)
Arguments
format is a constant or value that specifies the data format being queried.
Return Value
A boolean that indicates whether a data object contains an item that matches the specified format.
Remarks
The TDBGrid control supplies an argument of type DataObject when it fires the following events:
OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.
Note
In this version of True DBGrid, only the vbCFText format is supported. This constant has a value of 1 in
Visual Basic.
 HoldFields Method · 509

See Also
DataObject Object (page 119)

HoldFields Method
The HoldFields method sets the current column/field layout as the customized layout so that subsequent
ReBind operations will use the current layout for display.
Syntax
object.HoldFields
Arguments
None
Return Value
None
Remarks
You can resume the grid's automatic layout behavior by invoking the ClearFields method.
The HoldFields method is especially useful in the unbound modes when you have specified the column
layout in code and would like to keep it intact after a ReBind operation.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

IsSelected Method
The IsSelected method returns the zero-based index of the specified bookmark within the grid's
SelBookmarks collection.
Syntax
TDBGrid.IsSelected (bookmark)
Arguments
bookmark is a variant that identifies a particular row of data.
Return Value
An integer representing an index within the SelBookmarks collection.
Remarks
If the bookmark is not present in the SelBookmarks collection, this method returns -1.
See Also
TDBGrid Control (page 118)

Item Method
Use the Item method to access a specific member of a True DBGrid collection.
510 · Object Reference

Syntax
object.Item (index)
Method applies to Columns, Errors, GroupColumns, Layouts, PrintInfos, SelBookmarks, Splits, Styles,
and ValueItems collections.
Arguments
index is an expression that specifies the collection member to be accessed.
Return Value
A reference to the specified object.
Remarks
All collections accept a zero-based index argument. The Columns, GroupColumns, Layouts, PrintInfos,
and Styles collections also accept named arguments.
Note
The Item method is not required. The following expressions are equivalent:
TDBGrid1.Columns(0)
TDBGrid1.Columns.Item(0)
See Also
Column Object, Columns Collection (page 119)
Error Object, Errors Collection (page 120)
Split Object, Splits Collection (page 122)
Style Object, Styles Collection (page 122)
GroupColumns Collection (page 120)
PrintInfo Object, PrintInfos Collection (page 121)
Layouts Collection (page 121)
SelBookmarks Collection (page 121)
ValueItem Object, ValueItems Collection (page 123)

LoadLayout Method
The LoadLayout method loads a previously saved grid layout from a binary layout storage file and
configures the grid accordingly.
Syntax
TDBGrid.LoadLayout
Arguments
None
Return Value
None
 MoveFirst Method · 511

Remarks
You can use this method to easily switch to a predefined grid layout at run time.
The layout to be loaded is specified by the LayoutName property. The location of the binary layout
storage file is specified by the LayoutFileName property (or the LayoutURL property if downloadable
layouts are used). Before calling the LoadLayout method, you must set the LayoutName and
LayoutFileName (or LayoutURL) properties to valid values.
To save the current grid layout to a binary layout storage file, use the Add method of the Layouts
collection. To remove a named layout from a binary layout storage file, use the Remove method of the
Layouts collection.
See Also
TDBGrid Control (page 118)

MoveFirst Method
The MoveFirst method operates like its Recordset counterpart; it moves the current record to the first
record available.
Syntax
TDBGrid.MoveFirst
Arguments
None
Return Value
None
See Also
TDBGrid Control (page 118)

MoveLast Method
The MoveLast method operates like its Recordset counterpart; it moves the current record to the last
record available.
Syntax
TDBGrid.MoveLast
Arguments
None
Return Value
None
See Also
TDBGrid Control (page 118)
512 · Object Reference

MoveNext Method
The MoveNext method operates like its Recordset counterpart; it moves the current record to the next
record available.
Syntax
TDBGrid.MoveNext
Arguments
None
Return Value
None
See Also
TDBGrid Control (page 118)

MovePrevious Method
The MovePrevious method operates like its Recordset counterpart; it moves the current record to the
previous record available.
Syntax
TDBGrid.MovePrevious
Arguments
None
Return Value
None
See Also
TDBGrid Control (page 118)

MoveRelative Method
The MoveRelative method operates like the Move method of the Recordset object; it moves the current
record offset rows relative to the specified bookmark.
Syntax
TDBGrid.MoveRelative offset, [bookmark]
Arguments
offset is a long integer that specifies the number of records to move. A positive value indicates forward
movement; a negative value indicates backward movement.
bookmark is an optional variant that specifies the origin of the relative movement. If not specified, the
current record is assumed.
Return Value
None
 OLEDrag Method · 513

See Also
TDBGrid Control (page 118)

OLEDrag Method
The OLEDrag method initiates an OLE drag/drop operation.
Syntax
TDBGrid.OLEDrag
Arguments
None
Return Value
None
Remarks
When this method is called, the grid fires its OLEStartDrag event, enabling your application to supply
data to a target component.
See Also
TDBGrid Control (page 118)

PointAt Method
The PointAt method returns one of the constants in the preceding list, which indicates the kind of grid
element beneath the specified coordinate pair.
Syntax
TDBGrid.PointAt (x, y)
Arguments
x and y are singles that define a coordinate pair in twips.
Return Value
Remarks
Run Time
0 - Not in Grid dbgNotInGrid
1 - At Grid Caption dbgAtCaption
2 - At Split Header dbgAtSplitHeader
3 - At Split Size Box dbgAtSplitSizeBox
4 - At Row Select dbgAtRowSelect
5 - At Row Size dbgAtRowSize
6 - At Column Header dbgAtColumnHeader
7 - At Column Footer dbgAtColumnFooter
8 - At Column Size dbgAtColumnSize
514 · Object Reference

9 - At Data Area dbgAtDataArea

10 - At Group Area dbgAtGroupArea
11 - At Group Header dbgAtGroupHeader
Remarks
This method is useful when working with mouse and drag events when you are trying to determine
where the user clicked or dropped another control in terms of a grid element.
Note
You must convert the x and y arguments to twips, even if the container's ScaleMode (Visual Basic)
setting specifies a different unit of measurement.
See Also
TDBGrid Control (page 118)

PostMsg Method
The PostMsg method is used in conjunction with the PostEvent event to postpone operations which are
illegal within the grid's events.
Syntax
object.PostMsg MsgId
Arguments
MsgId is an integer that identifies the message being posted.
Return Value
None
Remarks
If the PostMsg method is called, the grid will fire the PostEvent event with the MsgId of the
corresponding PostMsg invocation after all pending operations are completed. You can then safely
perform all desired operations in the PostEvent event.
For example, it is not possible to perform the Data control's Refresh method within the grid's
AfterUpdate event because database operations are still pending, and the refresh cannot be tolerated.
Instead of performing the refresh in the AfterUpdate event, you can call the PostMsg method (with a
MsgId value of 1, for instance). After all pending database operations are completed, the grid will fire the
PostEvent event. You can then perform the refresh operation safely in this event, after confirming that the
MsgId argument passed in is 1.
You can use any non-zero integral value for MsgId, which will be passed to the PostEvent event for
identification purposes.
The special case where MsgId is zero is used to clear any pending PostMsg invocations which have not
yet been processed. A PostEvent event will fire for this case.
Note
Take care to avoid recursive situations when using PostMsg and PostEvent.
 ReBind Method · 515

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ReBind Method
This method re-establishes the connection with the bound data source, causing the control to perform the
same operations that occur when you set the DataSource property at design time.
Syntax
object.ReBind
Arguments
None
Return Value
None
Remarks
If you have not modified the grid columns at design time, then executing the ReBind method will reset
the columns, headings, and other properties based on the current data source.
However, if you have altered the columns in any way at design time (even if you leave the DataField
properties blank), then the grid will assume that you wish to maintain the modified grid layout and will
not automatically reset the columns.
For an unbound grid with its DataMode property set to 2 - Unbound Extended or 3 - Application, this
method discards all data and fires the UnboundReadDataEx or ClassicRead event to refill the grid with
records from the unbound data source. After the grid has finished refilling its cache, it fires the
FirstRowChange and RowColChange events.
For backward compatibility with earlier versions, the semantics of the Refresh and ReBind methods are
reversed in DataMode 1 - Unbound. The ReBind method attempts to restore the current and topmost
rows, but the Refresh method does not.
Note
To force the grid to reset the column bindings even if the columns were modified at design time, invoke
the ClearFields method immediately before ReBind. Conversely, to cancel the grid's automatic layout
response and force the grid to use the current column/field layout, invoke the HoldFields method
immediately before ReBind.
The HoldFields method is especially useful in the unbound modes when you have specified the column
layout in code and would like to keep it intact after a ReBind operation.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
516 · Object Reference

Refetch Method
The Refetch method repopulates the cells of the specified column from a data source control and/or
unbound events.
Syntax
column.Refetch
Arguments
None
Return Value
None
Remarks
It also repaints the column's visible cells, firing all events necessary for redisplay.
By default, the grid retrieves data automatically as needed. It fetches rows in blocks of ten, and only
gathers data for visible columns. However, in some cases, you can improve performance by fetching only
the data for a single (changed) column. The Refetch method is provided for this purpose.
Note
The Refetch method does not force the data source control to refresh its own data from the underlying
database. You must use data control methods or options to accomplish this.
See Also
Column Object (page 119)

RefetchCell Method
The RefetchCell method repopulates the specified cell from a data source control and/or unbound
events.
Syntax
column.RefetchCell [bookmark]
Arguments
bookmark is an optional variant that specifies the row containing the cell to refetch. If not specified, the
current row is assumed. If specified, it must be a valid bookmark.
Return Value
None
Remarks
It also repaints the cell, firing all events necessary for redisplay.
By default, the grid retrieves data automatically as needed. It fetches rows in blocks of ten, and only
gathers data for visible columns. However, in some cases, you can improve performance by fetching only
the data for a single (changed) cell. The RefetchCell method is provided for this purpose.
 RefetchCol Method · 517

Note
The RefetchCell method does not force the data source control to refresh its own data from the
underlying database. You must use data control methods or options to accomplish this.
See Also
Column Object (page 119)

RefetchCol Method
The RefetchCol method repopulates the specified column from a data source control and/or unbound
events.
Syntax
TDBGrid.RefetchCol [index]
Arguments
index is an optional variant that specifies the column to refetch. If not specified, the current column is
assumed. If specified, it must be a valid column number or name.
Return Value
None
Remarks
It also repaints the column's visible cells, firing all events necessary for redisplay.
By default, the grid retrieves data automatically as needed. It fetches rows in blocks of ten, and only
gathers data for visible columns. However, in some cases, you can improve performance by fetching only
the data for a single (changed) column. The RefetchCol method is provided for this purpose.
Note
The RefetchCol method does not force the data source control to refresh its own data from the
underlying database. You must use data control methods or options to accomplish this.
See Also
TDBGrid Control (page 118)

RefetchRow Method
The RefetchRow method repopulates the specified row from a data source control and/or unbound
events.
Syntax
TDBGrid.RefetchRow [bookmark]
Arguments
bookmark is an optional variant that specifies the row to refetch. If not specified, the current row is
assumed. If specified, it must be a valid bookmark.
Return Value
None
518 · Object Reference

Remarks
It also repaints the row, firing all events necessary for redisplay.
By default, the grid retrieves data automatically as needed. It fetches rows in blocks of ten, and only
gathers data for visible columns. However, in some cases, you can improve performance by fetching only
the data for a single (changed) row. The RefetchRow method is provided for this purpose.
Note
The RefetchRow method does not force the data source control to refresh its own data from the
underlying database. You must use data control methods or options to accomplish this.
See Also
TDBGrid Control (page 118)

Refresh Method
For a TDBGrid or TDBDropDown control, the Refresh method discards all data and repopulates all
cells from a data source control and/or unbound events.
Syntax
object.Refresh
Arguments
None
Return Value
None
Remarks
It also repaints the control's visible cells, firing all events necessary for redisplay.
When a control is refreshed, it attempts to restore the current and topmost rows. This behavior differs
from the intrinsic Data control's Refresh method, which makes the first available row both current and
topmost.
For backward compatibility with earlier versions, the semantics of the Refresh and ReBind methods are
reversed in DataMode 1 - Unbound. The ReBind method attempts to restore the current and topmost
rows, but the Refresh method does not.
For a Column object, the Refresh method repaints the entire column. Normally, the grid repaints
automatically as needed. However, if you have written handlers for the Paint or OwnerDrawCell events,
you can use this method to force a column to be repainted and hence cause the appropriate events to fire.
Note
If the grid's data source has been disconnected with the Close method, calling Refresh will implicitly
ReOpen the data source and set the current row to the first available row.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
 RefreshCell Method · 519

RefreshCell Method
The RefreshCell method repaints the specified cell. Normally, the grid repaints automatically as needed.
Syntax
column.RefreshCell [bookmark]
Arguments
bookmark is an optional variant that specifies the row containing the cell to refresh. If not specified, the
current row is assumed. If specified, it must be a valid bookmark.
Return Value
None
Remarks
However, if you have written handlers for the Paint or OwnerDrawCell events, you can use this method
to force a cell to be repainted and hence cause the appropriate events to fire.
Note
The RefreshCell method does not refetch data from a data source control or unbound events.
See Also
Column Object (page 119)

RefreshCol Method
The RefreshCol method repaints the visible cells in the specified column.
Syntax
TDBGrid.RefreshCol [index]
Arguments
index is an optional variant that specifies the column to refresh. If not specified, the current column is
assumed. If specified, it must be a valid column number or name.
Return Value
None
Remarks
Normally, the grid repaints automatically as needed. However, if you have written handlers for the Paint
or OwnerDrawCell events, you can use this method to force a column to be repainted and hence cause
the appropriate events to fire.
Note
The RefreshCol method does not refetch data from a data source control or unbound events.
See Also
TDBGrid Control (page 118)
520 · Object Reference

RefreshRow Method
The RefreshRow method repaints the specified row.
Syntax
TDBGrid.RefreshRow [bookmark]
Arguments
bookmark is an optional variant that specifies the row to refresh. If not specified, the current row is
assumed. If specified, it must be a valid bookmark.
Return Value
None
Remarks
Normally, the grid repaints automatically as needed. However, if you have written handlers for the Paint
or OwnerDrawCell events, you can use this method to force a row to be repainted and hence cause the
appropriate events to fire.
Note
The RefreshRow method does not refetch data from a data source control or unbound events.
See Also
TDBGrid Control (page 118)

Remove Method
Use the Remove method to delete a specific member of a True DBGrid collection.
Syntax
object.Remove (index)
Arguments
index is an expression that specifies the collection member to be removed.
Return Value
None
Remarks
If the object is a member of the GroupColumns collection, it will be removed from the grouping area and
returned to the grid, not deleted.
All collections accept a zero-based index argument. The Columns, GroupColumns, Layouts, PrintInfos,
and Styles collections also accept named arguments.
See Also
Column Object, Columns Collection (page 119)
Split Object, Splits Collection (page 122)
Style Object, Styles Collection (page 122)
GroupColumns Collection (page 120)
 ReOpen Method · 521

See Also
PrintInfo Object, PrintInfos Collection (page 121)
Layouts Collection (page 121)
SelBookmarks Collection (page 121)
ValueItem Object, ValueItems Collection (page 123)

ReOpen Method
The ReOpen method reconnects the grid to its data source.
Syntax
TDBGrid.ReOpen [bookmark]
Arguments
bookmark is an optional variant that specifies the row to position to immediately after the data source is
reopened. If specified, it must be a valid bookmark.
Return Value
None
Remarks
The grid is repopulated and the current row is positioned to the row identified by the optional bookmark
argument. If bookmark is not specified, then the current row reflects the current row of the data source.
In unbound mode, if the current row needs to be changed after the ReOpen operation, you can
significantly reduce the number of UnboundReadData (or UnboundReadDataEx) events that fire by
specifying the optional bookmark argument.
Note
If ReOpen is called while the grid is still connected to its data source, the grid implicitly performs a Close
first:
TDBGrid1.Close False
The optional bookmark is honored as usual when the data source is reopened.
See Also
TDBGrid Control (page 118)

Reset Method
This method causes a style to inherit all of its properties from its parent style.
Syntax
style.Reset
Arguments
None
522 · Object Reference

Return Value
None
See Also
Style Object (page 122)

RowBookmark Method
The RowBookmark method returns a bookmark for a visible row relative to the first displayed row.
Syntax
object.RowBookmark (rownumber)
Arguments
rownumber is an integer denoting a displayed row.
Return Value
A variant containing a bookmark corresponding to the display row specified by rownumber.
Remarks
If rownumber is 0, this method returns the bookmark of the first displayed row. The value returned will be
the same as that returned by the FirstRow property.
Allowable values for the rownumber argument range from 0 to VisibleRows - 1.
This method only returns the current row (as determined by the grid's Bookmark property) if the current
row is visible and the rownumber argument is equal to the grid's Row property.
Note
Do not confuse the RowBookmark method with the GetBookmark method, which returns a bookmark
relative to the current row, even if the row is not visible.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowContaining Method
The RowContaining method returns the zero-based index of the display row containing the specified
coordinate.
Syntax
object.RowContaining (coordinate)
Arguments
coordinate is a single that defines a vertical coordinate (Y value) in twips.
Return Value
An integer corresponding to the display row beneath the specified Y coordinate.
 RowExpanded Method · 523

Remarks
This value ranges from 0 to VisibleRows - 1.
When handling mouse and drag events, this method is useful when you need to determine where the
user clicked or dropped another control in terms of a grid row.
If coordinate is outside of the grid's data area, this method returns -1.
Note
You must convert the coordinate argument to twips, even if the container's ScaleMode (Visual Basic)
setting specifies a different unit of measurement.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowExpanded Method
The RowExpanded method returns True if the specified band is expanded within the current row.
Syntax
TDBGrid.RowExpanded (band)
Arguments
band is a zero-based index that identifies which level holds the current row within a master-detail
hierarchy.
Return Value
A boolean that indicates whether a row in the specified band has been expanded.
Remarks
You can use this method to determine whether the current row of a hierarchical grid has been expanded
to display its related data.
This method is only supported by the OLE DB version of True DBGrid Pro. It is used only in bound mode
and has no effect in unbound or storage modes.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

RowTop Method
The RowTop method returns the Y coordinate of the top of a visible row relative to the top of the grid, as
given by the grid's Top property.
Syntax
object.RowTop (rownumber)
524 · Object Reference

Arguments
rownumber is an integer denoting a displayed row.
Return Value
A single corresponding to the Y position of the specified display row, based on the coordinate system of
the grid's container.
Remarks
Allowable values for the rownumber argument range from 0 to VisibleRows - 1.
Use the RowTop method in conjunction with RowHeight, Left, and Width to determine the size and
placement of controls displayed on top of a grid cell.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Scroll Method
This method scrolls the grid horizontally and vertically in a single operation.
Syntax
object.Scroll coloffset, rowoffset
Arguments
coloffset is a long integer denoting the number of columns to scroll and the direction in which to scroll
them.
rowoffset is a long integer denoting the number of rows to scroll and the direction in which to scroll them.
Return Value
None
Remarks
Positive offsets scroll right and down. Negative offsets scroll left and up. Column offsets that are out of
range cause a trappable error. Row offsets that are out of range scroll to the beginning or end of the
database.
The same effect can be achieved by setting the LeftCol and FirstRow properties, but these must be set
independently.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

SetData Method
This method inserts data into a DataObject object using the specified data format.
Syntax
dataobject.SetData [value], [format]
 SplitContaining Method · 525

Arguments
value is an optional variant containing the data to be passed to the data object.
format is an optional constant or value that specifies the format of the data.
Return Value
None
Remarks
The TDBGrid control supplies an argument of type DataObject when it fires the following events:
OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.
Note
In this version of True DBGrid, only the vbCFText format is supported. If you omit the format argument,
vbCFText is assumed.
See Also
DataObject Object (page 119)

SplitContaining Method
The SplitContaining method returns the Index value of the split containing the specified coordinate pair.
Syntax
TDBGrid.SplitContaining (x, y)
Arguments
x and y are singles that define a coordinate pair in twips.
Return Value
An integer corresponding to the index of the split beneath the specified coordinate pair.
Remarks
This value ranges from 0 to Splits.Count - 1.
This method is useful when working with mouse and drag events when you are trying to determine
where the user clicked or dropped another control in terms of a grid column.
If either argument is outside of the grid's data area, this method returns -1.
Note
You must convert the x and y arguments to twips, even if the container's ScaleMode (Visual Basic)
setting specifies a different unit of measurement.
See Also
TDBGrid Control (page 118)

Update Method
This methods forces data from the current row to be updated to the underlying database.
526 · Object Reference

Syntax
TDBGrid.Update
Arguments
None
Return Value
None
Remarks
This method applies to both a bound grid and an unbound grid.
See Also
TDBGrid Control (page 118)

True DBGrid Events

AfterColEdit Event
The AfterColEdit event occurs after editing is completed in a grid cell.
Syntax
TDBGrid_AfterColEdit (ByVal ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column that was edited.
Remarks
When the user completes editing within a grid cell, as when tabbing to another column in the same row,
pressing the ENTER key, or clicking on another cell, the BeforeColUpdate and AfterColUpdate events are
executed, and data from the cell is moved to the grid's copy buffer. The AfterColEdit event immediately
follows the AfterColUpdate event.
When editing is completed in a grid cell, this event is always triggered, even if no changes were made to
the cell or the BeforeColUpdate event was canceled.
The AfterColEdit event will not be fired if the BeforeColEdit event is canceled.
See Also
TDBGrid Control (page 118)

AfterColUpdate Event
The AfterColUpdate event occurs after data is moved from a cell to the grid's internal copy buffer.
Syntax
TDBGrid_AfterColUpdate (ByVal ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column that was updated.
 AfterDelete Event · 527

Remarks
When the user completes editing within a grid cell, as when tabbing to another column in the same row,
pressing the ENTER key, or clicking on another cell, the BeforeColUpdate event is executed, and unless
canceled, data from the cell is moved to the grid's copy buffer. Once moved, the AfterColUpdate event is
executed.
The AfterColUpdate event occurs after the BeforeColUpdate event, and only if the Cancel argument in
the BeforeColUpdate event is not set to True.
Once the AfterColUpdate event procedure begins, the cell data has already been moved to the grid's
copy buffer and can't be canceled, but other updates can occur before the data is committed to the
Recordset.
See Also
TDBGrid Control (page 118)

AfterDelete Event
The AfterDelete event occurs after the user deletes a selected record from the grid.
Syntax
TDBGrid_AfterDelete ( )
Arguments
None
Remarks
When the user selects a record selector in the grid and presses DEL or CTRL+X, the BeforeDelete event is
executed, and unless canceled, the row is deleted. Once the row is deleted, the AfterDelete event is
executed.
While the AfterDelete event procedure is executing, the bookmark of the deleted row is available in the
collection provided by the SelBookmarks property.
The AfterDelete event cannot be canceled. It is fired in both bound and unbound modes.
See Also
TDBGrid Control (page 118)

AfterInsert Event
The AfterInsert event occurs after the user inserts a new record into the grid. It can be used to update
other tables or to perform post-update cleanup of other controls.
Syntax
TDBGrid_AfterInsert ( )
Arguments
None
528 · Object Reference

Remarks
When the user selects the AddNew row (the last row in the grid) and enters a character in one of the cells,
the BeforeInsert event is executed, and unless canceled, the row is scrolled up one line and its record
selector changes to show that it has been modified. However, a new row has not yet been added to the
database.
Once the user commits the new row by moving to another row within the grid, the BeforeUpdate event is
triggered, followed by the AfterUpdate and AfterInsert events. If the BeforeUpdate event is canceled,
then the AfterUpdate and AfterInsert events will not be fired.
When the AfterInsert event is triggered, the record has already been added to the database. The
Bookmark property can be used to access the new record.
The AfterInsert event cannot be canceled. It is fired in both bound and unbound modes.
See Also
TDBGrid Control (page 118)

AfterUpdate Event
The AfterUpdate event occurs after changed data has been written to the database from the grid.
Syntax
TDBGrid_AfterUpdate ( )
Arguments
None
Remarks
When the user moves to another row, or the Update method of the grid or Recordset object is executed,
data is moved from the grid's copy buffer to the Data control's copy buffer and written to the database.
Once the write operation is complete, the AfterUpdate event is triggered.
The Bookmark property does not reflect the newly added row because of the row being inserted.
The AfterUpdate event cannot be canceled. It is fired in both bound and unbound modes.
See Also
TDBGrid Control (page 118)

BeforeColEdit Event
The BeforeColEdit event occurs just before the user enters edit mode by typing a character.
Syntax
TDBGrid_BeforeColEdit (ByVal ColIndex As Integer, ByVal KeyAscii As Integer, Cancel As Integer)
Arguments
ColIndex is an integer that identifies the column about to be edited.
KeyAscii is an integer representing the ANSI key code of the character typed by the user to initiate
editing, or 0 if the user initiated editing by clicking the mouse. KeyAscii is passed by value, not by
reference; you cannot change its value to initiate editing with a different character.
 BeforeColUpdate Event · 529

Cancel is an integer that may be set to True to prevent the user from editing the cell.
Remarks
If a floating editor marquee is not in use, this event also occurs when the user clicks the current cell or
double clicks another cell.
If your event procedure sets the Cancel argument to True, the cell will not enter edit mode. Otherwise, the
ColEdit event is fired immediately, followed by the Change and KeyUp events for the KeyAscii
argument, if non-zero.
Use this event to control the editability of cells on a per-cell basis.
Note
The KeyAscii argument can only be 0 if a floating editor marquee is not in use.
See Also
TDBGrid Control (page 118)

BeforeColUpdate Event
The BeforeColUpdate event occurs after editing is completed in a cell, but before data is moved from the
cell to the grid's internal copy buffer.
Syntax
TDBGrid_BeforeColUpdate (ByVal ColIndex As Integer, OldValue As Variant, Cancel As Integer)
Arguments
ColIndex is an integer that identifies the column about to be updated.
OldValue is a variant containing the original data.
Cancel is an integer that may be set to True to prevent the update from occurring.
Remarks
The data specified by the OldValue argument moves from the cell to the grid's copy buffer when the user
completes editing within a cell, as when tabbing to another column in the same row, pressing the ENTER
key, or clicking on another cell. Before the data has been moved from the cell into the grid's copy buffer,
the BeforeColUpdate event is triggered. This event gives your application an opportunity to check the
individual grid cells before they are committed to the grid's copy buffer.
If your event procedure sets the Cancel argument to True, the previous value is restored in the cell, the
grid retains focus, and the AfterColUpdate event is not triggered. You can also change the current cell
text by setting OldValue to the value you want to display (other than the previous value).
To restore OldValue in the cell and permit the user to move focus off of the cell, set Cancel to False and set
the cell to OldValue as follows:
Cancel = False
TDBGrid1.Columns(ColIndex).Value = OldValue
Setting the Cancel argument to True prevents the user from moving focus away from the control until the
application determines that the data can be safely moved back to the grid's copy buffer.
See Also
TDBGrid Control (page 118)
530 · Object Reference

BeforeDelete Event
The BeforeDelete event occurs before a selected record is deleted from the grid.
Syntax
TDBGrid_BeforeDelete (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to prevent the deletion from occurring.
Remarks
When the user selects a record selector in the grid and presses DEL or CTRL+X, the BeforeDelete event is
triggered to give your application a chance to override the user's action.
If your event procedure sets the Cancel argument to True, the row is not deleted. Otherwise, the grid
deletes the row and triggers the AfterDelete event.
The bookmark of the row selected for deletion is available in the collection provided by the
SelBookmarks property.
Note
If more than one row is selected, the error message Cannot delete multiple rows is displayed, and the
BeforeDelete event will not be fired.
See Also
TDBGrid Control (page 118)

BeforeInsert Event
The BeforeInsert event occurs before a new record is added from the grid.
Syntax
TDBGrid_BeforeInsert (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to prevent the insertion from occurring.
Remarks
When the user selects the AddNew row (the last row in the grid) and enters a character in one of the cells,
the BeforeInsert event is triggered to give your application a chance to override the user's action.
If your event procedure sets the Cancel argument to True, no insertion takes place and the cell is cleared.
Otherwise, the AddNew row is scrolled up one line and its record selector changes to show that it has
been modified. However, a new row has not yet been added to the database.
Once the user commits the new row by moving to another row within the grid, the BeforeUpdate event is
triggered, followed by the AfterUpdate and AfterInsert events. If the BeforeUpdate event is canceled,
then the AfterUpdate and AfterInsert events will not be fired.
See Also
TDBGrid Control (page 118)
 BeforeOpen Event · 531

BeforeOpen Event
The BeforeOpen event occurs when the user clicks the + indicator in a cell.
Syntax
TDBGrid_BeforeOpen (Cancel as Integer)
Arguments
Cancel is an integer that may be set to True to prevent the user from displaying the detail grid for the row.
Description
Setting the Cancel argument to True prevents the detail grid from opening.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

BeforeRowColChange Event
The BeforeRowColChange event occurs when the user attempts to move to a different cell using the
navigation keys or the mouse.
Syntax
TDBGrid_BeforeRowColChange (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to prevent the user from changing the current cell.
Remarks
This event fires regardless of whether the current cell is modified.
Setting the Cancel argument to True prevents the user from moving to a different cell. If you do not cancel
this event, the behavior depends upon the modification status of the current cell. If the current cell is
unmodified, then cell movement proceeds as usual and the RowColChange event fires. If the current cell
is modified, then cell movement may be restricted by the BeforeColUpdate, BeforeUpdate, or
BeforeInsert events, in which case the RowColChange event will not fire.
Note
The BeforeRowColChange event does not fire if the current cell is changed in code, such as by setting the
Bookmark or Col properties of the grid.
See Also
TDBGrid Control (page 118)

BeforeUpdate Event
The BeforeUpdate event occurs before data is moved from the grid's internal copy buffer to the Data
control's copy buffer and then written to the database.
532 · Object Reference

Syntax
TDBGrid_BeforeUpdate (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to prevent the update from occurring.
Remarks
When the user moves to another row, or the Update method of the grid or Recordset object is executed,
data is moved from the grid's copy buffer to the Data control's copy buffer and then written to the
database.
Just before the data is moved from the grid's copy buffer back into the Data control's copy buffer, the
BeforeUpdate event is triggered. Unless the copy operation is canceled, the AfterUpdate event is
triggered after the data has been moved back into the Data control's copy buffer and written to the
database.
The Bookmark property can be used to access the updated record.
If your event procedure sets the Cancel argument to True, focus remains on the control, the AfterUpdate
event is not triggered, and the record is not saved to the database.
You can use this event to validate data in a record before permitting the user to commit the change to the
Data control's copy buffer. Setting the Cancel argument to True prevents the user from moving focus to
another control until the application determines whether the data can be safely moved back to the Data
control's copy buffer.
Note
The event will not fire when the grid (OLE DB only) is bound to a Recordset or ADODC that has the
.LockType property set to adLockBatchOptimistic.
See Also
TDBGrid Control (page 118)

ButtonClick Event
This event is fired when the current cell's built-in button is clicked.
Syntax
TDBGrid_ButtonClick (ByVal ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column whose button was clicked.
Remarks
The built-in button is enabled for a column when its Button property is set to True, its DropDown
property is set to the name of a valid TDBDropDown control, or the Presentation property of its
associated ValueItems collection is set to one of the combo box options.
Typically, you enable the column button when you want to drop down a Visual Basic control (such as the
built-in combo box, a bound list box, or even another True DBGrid control) for editing or data entry.
When the button in the current cell is clicked, the ButtonClick event will be fired. You can then write
code to drop down the desired control from the cell.
 Change Event · 533

See Also
TDBGrid Control (page 118)

Change Event
The Change event occurs when the user changes the text within a grid cell.
Syntax
TDBGrid_Change ( )
Arguments
None
Remarks
This event is only fired when the current cell is being edited and the user enters or deletes a character,
pastes text from the clipboard, or cuts text to the clipboard. It does not apply to database changes.
See Also
TDBGrid Control (page 118)

ClassicAdd Event
The ClassicAdd event is fired when the user adds a new row of data to an application mode grid (one
with its DataMode property set to 3 - Application).
Syntax
TDBGrid_ClassicAdd (NewRowBookmark As Variant, ByVal Col As Integer, Value As Variant)
Arguments
NewRowBookmark is a variant that must be set to a unique bookmark for subsequent references to the
newly added row.
Col is an integer that identifies the column to receive the new value.
Value is a variant used to transfer the new data from the grid to the unbound data source.
Remarks
This event alerts your application that it must add a new row of data to its unbound dataset.
This event adds data one cell at a time, so it may fire multiple times in order to add data for all the
columns in a row. The Col argument contains the column index corresponding to the newly entered cell
data. If the user has not added data to a column, the ClassicAdd event will not fire for that column index.
If you want to add a default value to a column, you can do that in the grid's BeforeUpdate event.
The Value argument contains the cell data entered by the user.
NewRowBookmark must be set to the bookmark of the newly added row, or else the user will not be able to
move to another row without first canceling the new row with the ESC key. If the NewRowBookmark is set
to different values when the event is called with different column indexes, the grid will use the last non
Null value returned by the user.
This event will not be fired if the AllowAddNew property is set to False. Conversely, if you do not
implement this event, then you must ensure that AllowAddNew is never set to True.
534 · Object Reference

Note
If the add operation fails in the underlying data source, then you should set NewRowBookmark to Null.
See Also
TDBGrid Control (page 118)

ClassicDelete Event
The ClassicDelete event is fired when the user deletes an existing row within an unbound grid (one with
its DataMode property set to 3).
Syntax
TDBGrid_ClassicDelete (Bookmark As Variant)
Arguments
Bookmark is a variant that uniquely identifies the row to be deleted.
Remarks
This event alerts your application that it must delete the row specified by the Bookmark argument from its
unbound dataset.
The Bookmark argument contains a bookmark supplied by your application in either the ClassicRead or
ClassicAdd event.
This event will not be fired if the AllowDelete property is set to False. Conversely, if you do not
implement this event, then you must ensure that AllowDelete is never set to True.
Note
If the delete operation fails in the underlying data source, then you should set Bookmark to Null to inform
the grid of the failure. This will cause the grid's Error event to fire. The row specified by Bookmark will
remain selected.
See Also
TDBGrid Control (page 118)

ClassicRead Event
The ClassicRead event is fired when an unbound grid (one with its DataMode property set to 3) needs to
display the value of a cell as specified by the Bookmark and CoI arguments.
Syntax
object_ClassicRead (Bookmark As Variant, ByVal Col As Integer, Value As Variant)
Arguments
Bookmark is a variant that identifies the row being requested.
Col is an integer that identifies the column being requested.
Value is a variant used to transfer unbound column data to the grid.
 ClassicWrite Event · 535

Remarks
To return an unbound value to the grid, simply set the Value argument to the desired result. If you do not
assign a value, the cell will remain blank.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ClassicWrite Event
The ClassicWrite event is fired when the user modifies an existing row within an application mode grid
(one with its DataMode property set to 3 - Application) and attempts to commit the changes by moving to
a different row or by calling the Update method.
Syntax
TDBGrid_ClassicWrite (Bookmark As Variant, ByVal Col As Integer, Value As Variant)
Arguments
Bookmark is a variant that uniquely identifies the row to be updated.
Col is an integer that identifies the column to be updated.
Value is a variant used to transfer data from the grid to the unbound data source.
Remarks
This event alerts your application that it must update the cell specified by the Bookmark and Col
arguments within its unbound dataset.
The Bookmark argument contains a bookmark supplied by your application in either the ClassicRead or
ClassicAdd event.
The Value argument contains the cell data entered by the user.
This event will not be fired if the AllowUpdate property is set to False. Conversely, if you do not
implement this event, then you must ensure that AllowUpdate is never set to True.
Note
If the update operation fails in the underlying data source, then you should set the Bookmark argument to
Null.
You can force the ClassicWrite event to occur in code by calling the Update method. This method is
particularly valuable when the unbound dataset contains a single row and AllowAddNew is False, since
there is no way for the user to trigger the update by moving to another row in this case.
See Also
TDBGrid Control (page 118)

Click Event
The Click event occurs when the user presses then releases a mouse button over the grid.
Syntax
object_Click ( )
536 · Object Reference

Arguments
None
Remarks
Clicking a grid also generates MouseDown and MouseUp events in addition to the Click event. The
order of events for both the TDBGrid and TDBDropDown controls is MouseDown, MouseUp, and
Click.
When the user clicks a noncurrent row, the Click event fires before the grid attempts to reposition to the
row that was clicked. If the attempt succeeds, the grid then fires the RowColChange (or RowChange)
event. For this reason, you should not use the Click event to perform operations that depend upon the
current row.
Note
You can use the PostMsg method and PostEvent event to defer processing until the row change has
completed.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ColEdit Event
The ColEdit event occurs when a cell first enters edit mode by typing a character.
Syntax
TDBGrid_ColEdit (ByVal ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column being edited.
Remarks
If a floating editor marquee is not in use, this event also occurs when the user clicks the current cell or
double clicks another cell.
The ColEdit event immediately follows the BeforeColEdit event only when the latter is not canceled.
When the user completes editing within a grid cell, as when tabbing to another column in the same row,
pressing the ENTER key, or clicking on another cell, the BeforeColUpdate and AfterColUpdate events are
executed if the data has been changed. The AfterColEdit event is then fired to indicate that editing is
completed.
See Also
TDBGrid Control (page 118)

Collapse Event
The Collapse event is fired when a user clicks on the collapse row icon ("–") in an expanded hierarchical
grid row.
 ColMove Event · 537

Syntax
TDBGrid_Collapse (Band As Integer, Cancel as Integer)
Arguments
Band is a zero-based index that identifies which recordset level holds the current row within a master-
detail hierarchy.
Cancel is an integer that may be set to True to prohibit the user from collapsing the current row.
Remarks
Event applies to TDBGrid control (OLE DB only).
Note
Setting the Cancel parameter to True ignores the user action and does not collapse the row.
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

ColMove Event
The ColMove event occurs when the user has finished moving the selected columns. Your event
procedure can either accept the movement or cancel it altogether.
Syntax
object_ColMove (ByVal Position As Integer, Cancel As Integer)
Arguments
Position is an integer that specifies the target location of the selected columns.
Cancel is an integer that may be set to True to prohibit movement.
Remarks
The Position argument ranges from 0, which denotes the left edge, to the total number of columns, which
denotes the right edge.
To determine which columns are being moved, examine the SelStartCol and SelEndCol properties.
If you set the Cancel argument to True, no movement occurs. Selected columns always remain selected,
regardless of the Cancel setting.
Note
This event is only fired when the user moves the selected columns to a new location.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
538 · Object Reference

ColResize Event
The ColResize event occurs after the user has finished resizing a column, but before columns to the right
are repositioned.
Syntax
object_ColResize (ByVal ColIndex As Integer, Cancel As Integer)
Arguments
ColIndex is an integer that identifies the column that was resized.
Cancel is an integer that may be set to True to undo resizing.
Remarks
Your event procedure can accept the change, alter the degree of change, or cancel the change completely.
If you set the Cancel argument to True, the previous column width is restored and no repainting occurs.
To alter the degree of change, set the Width property of the Column object specified by the ColIndex
argument to the desired value.
It is not necessary to execute the Refresh method within this event procedure. Doing so causes the grid to
be repainted even if the Cancel argument is True.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ComboSelect Event
The ComboSelect event is triggered when the user selects (by clicking) a built-in combo box item.
Syntax
TDBGrid_ComboSelect (ByVal ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column being edited.
Remarks
The built-in combo box is enabled for a column when the Presentation property of its associated
ValueItems collection is set to one of the combo box options.
This event is useful for determining the contents of the cell before the user exits editing mode. By setting
the EditActive property to False within this event procedure, you can force the grid to exit editing mode
without allowing the user a chance to edit his selection.
See Also
TDBGrid Control (page 118)

DataSourceChanged Event
The DataSourceChanged event occurs when a bound data source is changed or requeried. This event
also fires when a bound grid control is first loaded.
 DblClick Event · 539

Syntax
object_DataSourceChanged ( )
Arguments
None
Remarks
The DataSourceChanged event fires before the grid is filled with data. Therefore, you can use this event
to initialize the grid according to information obtained from the data source, if necessary.
This event does not fire in unbound or storage modes.
Note
With the OLE DB version of True DBGrid, you can use the DataSourceChanged event in conjunction
with the BookmarkType property to circumvent type mismatch errors that may occur when a grid-
supplied bookmark is passed to an ADO Recordset object (or vice versa). The workaround is as follows:
Sub TDBGrid1_DataSourceChanged()
TDBGrid1.BookmarkType = VarType(ADODC1.Recordset.Bookmark)
End Sub
This code ensures that any bookmarks returned by the grid are first converted to the appropriate type for
the bound data source. This workaround is only needed when using the grid in an HTML page; it is not
needed for Visual Basic 6.0.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DblClick Event
The DblClick event occurs when the user presses then releases a mouse button twice in rapid succession
over the grid.
Syntax
object_DblClick ( )
Arguments
None
Remarks
Double clicking a grid also generates MouseDown, MouseUp, and Click events in addition to the
DblClick event. The order of events for the TDBGrid control is MouseDown, MouseUp, Click,
DblClick, and MouseUp.
Note
When the MarqueeStyle property of a TDBGrid control is set to the default value of 6 - Floating Editor,
the DblClick event will not fire when the user double-clicks a noncurrent cell within the grid. This is
because the first click is used by the floating editor to begin editing, placing the cell into edit mode at the
character on which the click occurred. Double-clicking the current cell of the grid fires the DblClick event
normally, however.
540 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DragCell Event
The DragCell event is triggered when the user presses the left mouse button and starts dragging the
mouse.
Syntax
TDBGrid_DragCell (ByVal SplitIndex As Integer, RowBookmark As Variant, ByVal ColIndex As Integer)
Arguments
SplitIndex is an integer that identifies the split containing the cell being dragged.
RowBookmark is a variant that identifies the row containing the cell being dragged.
ColIndex is an integer that identifies the column containing the cell being dragged.
Remarks
This event is used to notify your application when the user wants to begin a drag-and-drop operation.
Using the SplitIndex, RowBookmark, and Col arguments, you can determine the exact location of the mouse
pointer at the start of the drag-and-drop operation.
You can initiate dragging in this event automatically by invoking the grid's Drag method.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Error Event
The Error event occurs only as the result of a data access error that takes place when no Visual Basic code
is being executed.
Syntax
object_Error (DataError As Integer, Response As Integer)
Arguments
DataError is an integer that identifies the error that occurred.
Response is an integer that may be set to 0 to suppress error message display.
Remarks
Even if your application handles run time errors in code, errors can still occur when none of your code is
executing, as when the user clicks a Data control button or changes the current record by interacting with
a bound control. If a data access error results from such an action, the Error event is fired.
If you set the Response argument to 0, no error message will be displayed.
If the Response argument retains its default value of 1, or if you do not code an event procedure for the
Error event, the message associated with the error will be displayed.
 Expand Event · 541

Note
Use the ErrorText property to retrieve the error string that will be displayed.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Expand Event
The Expand event is fired when a user clicks on the expand row icon ("+") in a collapsed hierarchical grid
row.
Syntax
TDBGrid_Expand (Band As Integer, Cancel as Integer)
Arguments
Band is a zero-based index that identifies which recordset level holds the current row within a master-
detail hierarchy.
Cancel is an integer that may be set to True to prohibit the user from expanding the current row.
Remarks
Event applies to TDBGrid control (OLE DB only).
Setting the Cancel parameter to True ignores the user action and does not expand the row.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Also
TDBGrid Control (page 118)

FetchCellStyle Event
The FetchCellStyle event occurs when the grid is about to display cell data in a column whose
FetchStyle property is set to dbgFetchCellStyleColumn or dbgFetchCellStyleAddNewColumn.
Syntax
TDBGrid_FetchCellStyle (ByVal Condition As Integer, ByVal Split As Integer, Bookmark As Variant, ByVal Col
As Integer, ByVal CellStyle As TrueDBGrid80.StyleDisp)
TDBDropDown_FetchCellStyle (ByVal Condition As Integer, Bookmark As Variant, ByVal Col As Integer,
ByVal CellStyle As TrueDBGrid80.StyleDisp)
Arguments
Condition is the sum of one or more CellStyleConstants describing the disposition of the cell being
displayed.
Split is an integer that identifies the split containing the cell being displayed. This argument is omitted for
TDBDropDown controls.
Bookmark is a variant that identifies the row containing the cell being displayed.
542 · Object Reference

Col is an integer that identifies the column containing the cell being displayed.
CellStyle is a Style object used to override the font and color characteristics of the cell being displayed.
Remarks
By setting one or more properties of the Style object passed in the CellStyle parameter, your application
can change the appearance of individual cells.
You can also set the ForegroundPicture property of the CellStyle parameter to display distinct bitmaps on
a per-cell basis.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FetchCellTips Event
If the CellTips property is not set to 0 - None, the FetchCellTips event will be fired whenever the grid
has focus and the cursor is idle for a small amount of time (defined by the CellTipsDelay property) over
a data cell, record selector, column header, column footer, split header, or grid caption bar.
Syntax
TDBGrid_FetchCellTips (ByVal SplitIndex As Integer, ByVal ColIndex As Integer, ByVal RowIndex As Long,
CellTip As String, ByVal FullyDisplayed As Boolean, ByVal TipStyle As TrueDBGrid80.StyleDisp)
Arguments
SplitIndex is the zero-based index of the split the cursor is over.
ColIndex is an integer that identifies the column the cursor is over. This is either a zero-based column
index or a (negative) CellTipConstants value.
RowIndex is an integer that identifies the row the cursor is over. This is either a zero-based row index or a
(negative) CellTipConstants value.
CellTip contains the text to be displayed in the pop-up text box.
FullyDisplayed is a boolean that is True if CellTip will fit entirely within the boundaries of the cell.
TipStyle is a Style object used to override the font and color characteristics of the cell tip text.
Remarks
This event will not fire if the cursor is over the scroll bars.
If the cursor is over a data cell, CellTip contains the contents of the cell as text. By default, the grid will
display up to 256 characters of the cell contents in a pop-up text box, enabling the user to peruse the
contents of a cell even if it is not big enough to be displayed in its entirety. Instead of displaying the cell
text, you can also modify CellTip to display your own message. However, if you set CellTip to Null or an
empty string, the text box will not be displayed.
If the cursor is not over a grid column, ColIndex will be negative and equal to one of the following
CellTipConstants, depending upon the cursor position:
dbgOnRecordSelector Cursor is over a record selector
dbgOnEmptyColumn Cursor is over the blank area to the right of the last column
 FetchRowStyle Event · 543

If the cursor is not over a data row, RowIndex will be negative and equal to one of the following
CellTipConstants, depending upon the cursor position:
dbgOnColumnHeader Cursor is over a column header
dbgOnSplitHeader Cursor is over a split header
dbgOnEmptyRow Cursor is over the empty rows area (if EmptyRows is True)
or the blank area (if EmptyRows is False)
dbgOnCaption Cursor is over the grid caption
dbgOnAddNew Cursor is over the AddNew row
dbgOnColumnFooter Cursor is over a column footer
If the cursor is over an empty row (that is, a row below the AddNew row), or is not over the grid cells
area, the value of CellTip is Null, and the pop-up text box will not be displayed. If you modify CellTip so
that it is no longer Null, the text box will display the changed value.
By setting the properties of the TipStyle object, you can control the background color, text color, and font
of the pop-up text box. By default, the TipStyle object uses the system ToolTip colors and the font
attributes of the current column.
You can program this event to provide context-sensitive help or tips to your users. For example, if the
user points to column header, you can provide a more detailed description of the column. If the user
points to a record selector, you can display instructions for selecting multiple records.
You can also provide content-sensitive help to your users using this event. By default, CellTip contains the
text of the cell under the cursor. However, you can also determine other cell values if desired. Using the
grid's Row property and RowBookmark method, you can retrieve the bookmark of the row under the
cursor, then use the CellValue or CellText method to derive other cell values.
See Also
TDBGrid Control (page 118)

FetchRowStyle Event
The FetchRowStyle event is fired whenever the grid is about to display a row of data, but only if the
FetchRowStyle property is True for the grid or one of its splits.
Syntax
TDBGrid_FetchRowStyle (ByVal Split As Integer, Bookmark As Variant, ByVal RowStyle As
TrueDBGrid80.StyleDisp)
TDBDropDown_FetchRowStyle (Bookmark As Variant, ByVal RowStyle As TrueDBGrid80.StyleDisp)
Arguments
Split is the zero-based index of the split for which formatting information is being requested. This
argument is omitted for TDBDropDown controls.
Bookmark is a variant that uniquely identifies the row to be displayed.
RowStyle is a Style object used to convey font and color information to the grid.
Remarks
Use the FetchRowStyle event to control formatting on a per-row basis, as it is much more efficient than
coding the FetchCellStyle event to apply the same formatting to all columns.
544 · Object Reference

Note
A common application of row-based formatting is to present rows in alternating colors to enhance their
readability. Although you could use the FetchRowStyle event to achieve this effect, the
AlternatingRowStyle property is easier to use, as it requires no coding.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FetchScrollTips Event
If the ScrollTips property is True, the FetchScrollTips event will be fired whenever the grid has focus
and the scrollbar thumb is moved using the mouse.
Syntax
TDBGrid_FetchScrollTips (ByVal SplitIndex As Integer, ByVal ColIndex as Integer, Bookmark As Variant,
ByVal ScrollBar as ScrollBarsConstants, ScrollTip As String, ByVal TipStyle As TrueOleDBGrid80.StyleDisp)
TDBDropDown_FetchScrollTips (ByVal ColIndex as Integer, Bookmark As Variant, ByVal ScrollBar as
ScrollBarsConstants, ScrollTip As String, ByVal TipStyle As TrueOleDBGrid80.StyleDisp)
Arguments
SplitIndex is the zero-based index of the split that the scrollbar is associated with. This argument is
omitted for TDBDropDown controls.
ColIndex is the leftmost column in the current split.
Bookmark is a variant that uniquely identifies the topmost grid row.
ScrollBar identifies the scrollbar that was moved (dbgVertical or dbgHorizontal).
ScrollTip contains the text to be displayed in the pop-up text box.
TipStyle is a Style object used to override the font and color characteristics of the scroll tip text.
Description
By setting the properties of the TipStyle object, you can control the background color, text color, and font
of the pop-up text box. By default, the TipStyle object uses the system ToolTip colors and the font
attributes of the current split.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FirstRowChange Event
The FirstRowChange event occurs when the first displayed row of a control or split is changed.
Syntax
TDBGrid_FirstRowChange (ByVal SplitIndex As Integer)
TDBDropDown_FirstRowChange ( )
 FilterButtonClick Event · 545

Arguments
SplitIndex is the zero-based index of the split in which the row change occurred. This argument is omitted
for TDBDropDown controls.
Remarks
This event is triggered under several circumstances:
• When the grid is first displayed.
• When the user scrolls through the grid with the vertical scroll bar or navigation keys.
• When data in the grid is changed in a way that implicitly affects the first row, such as when the
first displayed record is deleted.
• When the FirstRow property is changed in code to a different value.
When multiple cell change events are sent, the order will be SplitChange, FirstRowChange,
LeftColChange, and RowColChange. None of these events will be sent until any modified data has been
validated with the BeforeColUpdate event.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FilterButtonClick Event
If the FilterBar property is set to True, the FilterButtonClick event will be fired whenever the user clicks
the in-cell button within a filter cell.
Syntax
TDBGrid_FilterButtonClick (ByVal ColIndex As Integer)
Arguments
ColIndex is the zero-based index of the column whose filter button was pressed.
See Also
TDBGrid Control (page 118)

FilterChange Event
This event is fired when a user types in the filter cell.
Syntax
TDBGrid_FilterChange ( )
Arguments
None
See Also
TDBGrid Control (page 118)
546 · Object Reference

FootClick Event
The FootClick event occurs when the user clicks on the footer for a particular grid column.
Syntax
object_FootClick (ByVal ColIndex As Integer)
Event applies to TDBGrid and TDBDropDown controls.
Arguments
ColIndex is an integer that identifies the column footer that was clicked.
Remarks
One possible action for this event is to re-sort the Recordset object based on the selected column.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FormatText Event
The FormatText event occurs when the grid is about to display cell data in a column whose
NumberFormat property is set to the string FormatText Event.
Syntax
object_FormatText (ByVal ColIndex As Integer, Value As Variant, Bookmark As Variant)
Arguments
ColIndex is an integer that identifies the column being displayed.
Value is a variant containing the underlying data value.
Bookmark is a variant that uniquely identifies the row from which the underlying data value was
obtained.
Remarks
The Value argument contains the underlying data value and also serves as a placeholder for the formatted
data to be displayed.
This event allows you to provide your own text formatting for cases where Visual Basic's intrinsic
formatting is either unavailable or does not suit your needs.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

GroupColMove Event
The GroupColMove event occurs before a selected column is moved to or from the grouping area.
 GroupHeadClick Event · 547

Syntax
TDBGrid_GroupColMove (ByVal Position As Integer, ByVal ColIndex As Integer, Cancel As Integer)
Arguments
Position is an integer that specifies the target location of the selected columns.
ColIndex is an integer that identifies the column being moved. This is the absolute index.
Cancel is an integer that may be set to True to prohibit movement.
Remarks
Event applies to TDBGrid control (OLE DB only).
Your event procedure can either accept the movement or cancel it altogether.
The Position argument ranges from 0, which denotes the left edge, to the total number of columns, which
denotes the right edge. A position of -1 is used to indicate that a column is being moved from the
grouping area back to the grid.
To determine which column is being moved, use the Item method.
If you set the Cancel argument to True, no movement occurs. Selected columns always remain selected,
regardless of the Cancel setting.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Outlook-Style Grouping (page 278) for more information.
See Also
TDBGrid Control (page 118)

GroupHeadClick Event
The GroupHeadClick event occurs when the user clicks on the header for a particular grid column in the
grouping area.
Syntax
TDBGrid_GroupHeadClick (ByVal ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column header that was clicked.
Remarks
Event applies to TDBGrid control (OLE DB only).
One possible action for this event is to re-sort the Recordset object based on the selected column.
Note
This property is only supported by the OLE DB version of True DBGrid Pro.
See Outlook-Style Grouping (page 278) for more information.
548 · Object Reference

See Also
TDBGrid Control (page 118)

HeadClick Event
The HeadClick event occurs when the user clicks on the header for a particular grid column.
Syntax
object_HeadClick (ByVal ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column header that was clicked.
Remarks
One possible action for this event is to re-sort the Recordset object based on the selected column.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

KeyDown Event
The KeyDown event occurs when the user presses a key.
Syntax
object_KeyDown (KeyCode As Integer, Shift As Integer)
Arguments
KeyCode is an integer or constant representing a Windows key code. For example, the Visual Basic object
library provides the constants vbKeyF1 (the F1 key) and vbKeyHome (the HOME key).
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys at the time of the event.
The Shift argument is a bit field with the least-significant bits corresponding to the SHIFT key (bit 0), the
CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively.
Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For
example, if both CTRL and ALT are pressed, the value of Shift is 6.
Remarks
The KeyDown event occurs when the user presses a key. Although this event is fired for most keystrokes,
it is most often used for:
• Extended character keys such as function keys.
• Navigation keys.
• Combinations of keys with standard keyboard modifiers.
• Distinguishing between the numeric keypad and regular number keys.
 KeyPress Event · 549

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

KeyPress Event
Occurs when an ANSI key is pressed and released.
Syntax
object_KeyPress (KeyAscii As Integer)
Arguments
KeyAscii is an integer representing an ANSI key code. KeyAscii is passed by reference; changing it sends a
different character to the grid. Changing KeyAscii to 0 cancels the keystroke so the grid receives no
character.
Remarks
The KeyPress event occurs when the user presses and releases one of the following kinds of keys:
• A printable keyboard character.
• The CTRL key combined with an alphabetic or special character.
• The ENTER or BACKSPACE key.
Use the KeyPress event to test keystrokes for validity or to format characters as they are typed.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

KeyUp Event
The KeyUp event occurs when the user releases a key.
Syntax
object_KeyUp (KeyCode As Integer, Shift As Integer)
Arguments
KeyCode is an integer or constant representing a Windows key code. For example, the Visual Basic object
library provides the constants vbKeyF1 (the F1 key) and vbKeyHome (the HOME key).
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys at the time of the event.
The Shift argument is a bit field with the least-significant bits corresponding to the SHIFT key (bit 0), the
CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively.
Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For
example, if both CTRL and ALT are pressed, the value of Shift is 6.
Remarks
Although this event is fired for most keystrokes, it is most often used for:
550 · Object Reference

• Extended character keys such as function keys.

• Navigation keys.
• Combinations of keys with standard keyboard modifiers.
• Distinguishing between the numeric keypad and regular number keys.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

LayoutReady Event
The LayoutReady event fires when asynchronous downloading of a grid layout file has completed.
Syntax
object_LayoutReady ( )
Arguments
None
Remarks
The location of the layout file is determined by the LayoutURL property.
If you set the LayoutURL property to a nonempty string at design time (and LayoutFileName is empty),
the grid initiates asynchronous downloading at run time after it has been loaded. You can also initiate
downloading by setting the LayoutURL property in code. This technique is particularly useful for
initializing a grid on an HTML page.
In either case, the grid fires the LayoutReady event when the download operation has completed. You
should write a handler for this event that loads the desired layout as follows:
TDBGrid1.LayoutName = "MyLayout"
TDBGrid1.LoadLayout
Note
You can create grid layout files at design time by setting the LayoutFileName and LayoutName
properties and using the layout commands on the grid's visual editing menu.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

LeftColChange Event
The LeftColChange event occurs when the first visible column of a grid or split is changed.
Syntax
TDBGrid_LeftColChange (ByVal SplitIndex As Integer)
TDBDropDown_LeftColChange ( )
 MouseDown Event · 551

Arguments
SplitIndex is the zero-based index of the split in which the column change occurred. This argument is
omitted for TDBDropDown controls.
Remarks
This event is triggered under several circumstances:
• When the grid is first displayed.
• When the user scrolls through the grid with the horizontal scroll bar or navigation keys.
• When the LeftCol property is changed in code to a different value.
• When the Visible property of the current left column is set to False.
• When the Width property of the current left column is set to 0.
• When the user resizes the current left column so that it is no longer visible.
• When the user moves the current left column or moves another column into its place.
When multiple cell change events are sent, the order will be SplitChange, FirstRowChange,
LeftColChange, and RowColChange. None of these events will be sent until any modified data has been
validated with the BeforeColUpdate event.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

MouseDown Event
Use a MouseDown event procedure to specify actions that will occur when a given mouse button is
pressed.
Syntax
object_MouseDown (Button As Integer, Shift As Integer, X As Single, Y As Single)
Arguments
Button is an integer that identifies the button that was pressed or released to cause the event. The Button
argument is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle
button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set,
indicating the button that caused the event.
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys when the button specified
in the Button argument is pressed or released. A bit is set if the key is down. The Shift argument is a bit
field with the least-significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT
key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can
be set, indicating that some, all, or none of the keys are pressed. For example, if both CTRL and ALT are
pressed, the value of Shift is 6.
X and Y are single-precision numbers that specify the current location of the mouse pointer. They are
always expressed in terms of the coordinate system of the grid's container.
552 · Object Reference

Remarks
Unlike the Click and DblClick events, MouseDown and MouseUp events enable you to distinguish
between the left, right, and middle mouse buttons. You can also write code for mouse/keyboard
combinations that use the SHIFT, CTRL, and ALT keyboard modifiers.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

MouseMove Event
The MouseMove event is generated continually as the mouse pointer moves across the grid.
Syntax
object_MouseMove (Button As Integer, Shift As Integer, X As Single, Y As Single)
Arguments
Button is an integer that corresponds to the state of the mouse buttons in which a bit is set if the button is
down. The Button argument is a bit field with bits corresponding to the left button (bit 0), right button (bit
1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. The Button
argument indicates the complete state of the mouse buttons; some, all, or none of these three bits can be
set, indicating that some, all, or none of the buttons are pressed.
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys. A bit is set if the key is
down. The Shift argument is a bit field with the least-significant bits corresponding to the SHIFT key (bit
0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4,
respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are
pressed. For example, if both CTRL and ALT are pressed, the value of Shift is 6.
X and Y are single-precision numbers that specify the current location of the mouse pointer. They are
always expressed in terms of the coordinate system of the grid's container.
Remarks
This event is primarily useful for implementing drag-and-drop behavior on a per-column basis.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

MouseUp Event
Use a MouseUp event procedure to specify actions that will occur when a given mouse button is
released.
Syntax
object_MouseUp (Button As Integer, Shift As Integer, X As Single, Y As Single)
 OLECompleteDrag Event · 553

Arguments
Button is an integer that identifies the button that was pressed or released to cause the event. The Button
argument is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle
button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set,
indicating the button that caused the event.
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys when the button specified
in the Button argument is pressed or released. A bit is set if the key is down. The Shift argument is a bit
field with the least-significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT
key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can
be set, indicating that some, all, or none of the keys are pressed. For example, if both CTRL and ALT are
pressed, the value of Shift is 6.
X and Y are single-precision numbers that specify the current location of the mouse pointer. They are
always expressed in terms of the coordinate system of the grid's container.
Remarks
Unlike the Click and DblClick events, MouseDown and MouseUp events enable you to distinguish
between the left, right, and middle mouse buttons. You can also write code for mouse/keyboard
combinations that use the SHIFT, CTRL, and ALT keyboard modifiers.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

OLECompleteDrag Event
The OLECompleteDrag event occurs when a grid is the source component of a drag/drop operation.
Syntax
TDBGrid_OLECompleteDrag (Effect As Long)
Arguments
Effect is a long integer set by the source object identifying the action that has been performed, thus
allowing the source to take appropriate action if the component was moved (such as the source deleting
data if it is moved from one component to another). The possible values of Effect are as follows:
0 - vbDropEffectNone Drop target cannot accept the data or the drop operation was canceled.
1 - vbDropEffectCopy Drop results in a copy of data from the source to the target. The original
data is unaltered by the drag operation.
2 - vbDropEffectMove Drop results in a link to the original data being created between drag
source and drop target.
Remarks
This event informs the grid that a drag action was either performed or canceled by the target control.
The OLECompleteDrag event is the final event to be called in an OLE drag/drop operation. Based on the
value returned, the source grid control can then determine the appropriate action it needs to take. For
example, if the object was moved into the target (2 - vbDropEffectMove), the source grid control needs to
delete the object from itself after the move.
554 · Object Reference

See Also
TDBGrid Control (page 118)

OLEDragDrop Event
The OLEDragDrop event occurs when a grid control is the target component of a drag/drop operation
and its OLEDropMode is set to 1 - Manual.
Syntax
TDBGrid_OLEDragDrop (Data As TrueDBGrid80.DataObject, Effect As Long, Button As Integer, Shift As
Integer, X As Single, Y As Single)
Arguments
Data is a DataObject object containing formats that the source will provide and possibly the data for
those formats. If no data is contained in the DataObject, it is provided when the control calls the GetData
method. The SetData and Clear methods cannot be used here.
Effect is a long integer set by the source object identifying the action that has been performed, thus
allowing the source to take appropriate action if the component was moved (such as the source deleting
data if it is moved from one component to another). The possible values of Effect are as follows:
0 - vbDropEffectNone Drop target cannot accept the data or the drop operation was canceled.
1 - vbDropEffectCopy Drop results in a copy of data from the source to the target. The original data
is unaltered by the drag operation.
2 - vbDropEffectMove Drop results in a link to the original data being created between drag source
and drop target.
Button is an integer that corresponds to the state of the mouse buttons in which a bit is set if the button is
down. The Button argument is a bit field with bits corresponding to the left button (bit 0), right button (bit
1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. The Button
argument indicates the complete state of the mouse buttons; some, all, or none of these three bits can be
set, indicating that some, all, or none of the buttons are pressed.
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys. A bit is set if the key is
down. The Shift argument is a bit field with the least-significant bits corresponding to the SHIFT key (bit
0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4,
respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are
pressed. For example, if both CTRL and ALT are pressed, the value of Shift is 6.
X and Y are single-precision numbers that specify the current location of the mouse pointer. They are
always expressed in terms of the coordinate system of the grid's container.
Remarks
This event informs the grid that a drop action was either performed or canceled by the source control, the
location of the drop, and the mouse button and shift key states.
See Also
TDBGrid Control (page 118)
 OLEDragOver Event · 555

OLEDragOver Event
The OLEDragOver event occurs when a grid control is the target component of a drag/drop operation
and its OLEDropMode is set to 1 - Manual.
Syntax
TDBGrid_OLEDragOver (Data As TrueDBGrid80.DataObject, Effect As Long, Button As Integer, Shift As
Integer, X As Single, Y As Single, State As Integer)
Arguments
Data is a DataObject object containing formats that the source will provide and possibly the data for
those formats. If no data is contained in the DataObject, it is provided when the control calls the GetData
method. The SetData and Clear methods cannot be used here.
Effect is a long integer set by the source object identifying the action that has been performed, thus
allowing the source to take appropriate action if the component was moved (such as the source deleting
data if it is moved from one component to another). The possible values of Effect, which may be combined
with a logical Or operator, are as follows:
0 - vbDropEffectNone Drop target cannot accept the data or the drop operation was canceled.
1 - vbDropEffectCopy Drop results in a copy of data from the source to the target. The original
data is unaltered by the drag operation.
2 - vbDropEffectMove Drop results in a link to the original data being created between drag
source and drop target.
The OLEDragOver event should check these effects and other parameters to determine which actions are
appropriate for it and set the Effect parameter to one of the allowable effects above.
Button is an integer that corresponds to the state of the mouse buttons in which a bit is set if the button is
down. The Button argument is a bit field with bits corresponding to the left button (bit 0), right button (bit
1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. The Button
argument indicates the complete state of the mouse buttons; some, all, or none of these three bits can be
set, indicating that some, all, or none of the buttons are pressed.
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys. A bit is set if the key is
down. The Shift argument is a bit field with the least-significant bits corresponding to the SHIFT key (bit
0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4,
respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are
pressed. For example, if both CTRL and ALT are pressed, the value of Shift is 6.
X and Y are single-precision numbers that specify the current location of the mouse pointer. They are
always expressed in twips, which are suitable for use with the grid's ColContaining, RowContaining,
and SplitContaining methods.
State is an integer that corresponds to the transition state of the control being dragged in relation to the
target grid control. The value will be one of the following:
0 - vbEnter The source component is being dragged within the range of the target grid
control.
1 - vbLeave The source component is being dragged out of the range of the target grid
control.
2 - vbOver The source component has moved from one position within the target grid
control to another.
556 · Object Reference

Remarks
This event informs the grid that a source component is being dragged into, within, or out of its range, the
current drag location, and the mouse button and shift key states.
See Also
TDBGrid Control (page 118)

OLEGiveFeedback Event
The OLEGiveFeedback event occurs after every OLEDragOver event of the target component.
Syntax
TDBGrid_OLEGiveFeedback (Effect As Long, DefaultCursors As Boolean)
Arguments
Effect is a long integer set by the source object identifying the action that has been performed, thus
allowing the source to take appropriate action if the component was moved (such as the source deleting
data if it is moved from one component to another). The possible values of Effect are as follows:
0 - vbDropEffectNone Drop target cannot accept the data or the drop operation was
canceled.
1 - vbDropEffectCopy Drop results in a copy of data from the source to the target. The
original data is unaltered by the drag operation.
2 - vbDropEffectMove Drop results in a link to the original data being created between
drag source and drop target.
DefaultCursors is a boolean that determines whether appropriate default cursors are used to indicate the
state of the drag/drop operation, or if custom cursors are used instead. If True (the default), the default
mouse cursor is used. If False, custom cursors are used, and the mouse cursor must be set with the
MousePointer property of the Screen object.
Remarks
The OLEGiveFeedback event occurs when a grid control is the source component of a drag/drop
operation. This event enables your application to provide feedback to the user, such as changing the
mouse cursor to indicate what will happen if the user drops the object.
If there is no code in the OLEGiveFeedback event, or if the DefaultCursors parameter is False, then the
mouse cursors are set automatically.
See Also
TDBGrid Control (page 118)

OLESetData Event
The OLESetData event occurs when a grid control is the source component of a drag/drop operation and
a target component performs the GetData method on the source's DataObject object, but the data for the
specified format has not yet been loaded.
Syntax
TDBGrid_OLESetData (Data As TrueDBGrid80.DataObject, DataFormat As Integer)
 OLEStartDrag Event · 557

Arguments
Data is a DataObject object used as a placeholder for the requested data. You can load the data with the
SetData method of the DataObject.
DataFormat is an integer specifying the format of the data that the target control is requesting.
Remarks
In certain cases, it is more efficient to defer loading data into the DataObject object of a source
component to save time, especially if it supports many formats. This event enables the source to respond
to only one request for a given format of data. When this event is called, the source should check the
format parameter to determine what needs to be loaded and then perform the SetData method on the
DataObject object to load the data which is then passed back to the target component.
Note
Currently, the only data format recognized by the grid is text.
See Also
TDBGrid Control (page 118)

OLEStartDrag Event
The OLEStartDrag event occurs when a grid control is a source component of a drag/drop operation
and its OLEDrag method is called.
Syntax
TDBGrid_OLEStartDrag (Data As TrueDBGrid80.DataObject, AllowedEffects As Long)
Arguments
Data is a DataObject object containing formats that the source will provide and possibly the data for
those formats. If no data is contained in the DataObject, it is provided when the control calls the GetData
method.
AllowedEffects is a long integer that should be set by your event handler to indicate which effects the
source grid control supports. The target component uses this value to determine the appropriate response
to a drop request. The supported effects are represented by the following values, which may be combined
with a logical Or operator:
0 - vbDropEffectNone Drop target cannot accept the data or the drop operation was
canceled.
1 - vbDropEffectCopy Drop results in a copy of data from the source to the target. The
original data is unaltered by the drag operation.
2 - vbDropEffectMove Drop results in a link to the original data being created between
drag source and drop target.
Remarks
This event enables your application to specify the data formats and drop effects that the source grid will
support.
The OLEStartDrag event also occurs if the component's OLEDragMode property is set to 1 - Automatic
and a drag/drop operation is initiated by the user. You can use this event to add formats and data to the
DataObject object after the component has done so. You can also override the default behavior of the
558 · Object Reference

component by clearing the DataObject object (using the Clear method) and then adding new data and
formats (using the SetData method).
See Also
TDBGrid Control (page 118)

OnAddNew Event
Fired when a user action causes an AddNew operation.
Syntax
TDBGrid_OnAddNew ( )
Arguments
None
Remarks
The OnAddNew event occurs when an AddNew operation has been initiated by either of the following:
• The user modifies a cell within the AddNew row. Typically, this occurs as soon as the user types
a character, but may also occur as a result of a built-in radio button or combo box selection.
• The Value or Text property of a column is set in code when the current cell is within the
AddNew row.
This event is fired in both bound and unbound modes. However, it will only be fired if the grid's
AllowAddNew property is True.
When the OnAddNew event is fired, the value of the AddNewMode property is 2 - AddNew Pending.
See Also
TDBGrid Control (page 118)

OnInit Event
The OnInit event occurs after the grid is initially loaded.
Syntax
TDBGrid_OnInit ( )
Arguments
None
Remarks
This event precedes DataSourceChanged as well as the unbound events. You can always use this event
to initialize the grid independent of its container.
See Also
TDBGrid Control (page 118)
 OwnerDrawCell Event · 559

OwnerDrawCell Event
The OwnerDrawCell event occurs just before the cell specified by the Bookmark, Col, and Split arguments
is to be painted.
Syntax
TDBGrid_OwnerDrawCell (ByVal hDC As Long, ByVal Bookmark As Variant, ByVal Split as Integer, ByVal
Col As Integer, ByVal Left As Integer, ByVal Top As Integer, ByVal Right As Integer, ByVal Bottom As Integer,
Done As Integer)
Arguments
hDC is a handle to the control's device context, which is required by all Windows GDI calls.
Bookmark is a variant that uniquely identifies the row to be painted.
Split is an integer that identifies the current split.
Col is an integer that identifies the column to be painted.
Left is an integer that indicates the left coordinate of the cell to be painted.
Top is an integer that indicates the top coordinate of the cell to be painted.
Right is an integer that indicates the right coordinate of the cell to be painted.
Bottom is an integer that indicates the bottom coordinate of the cell to be painted.
Done is an integer that should be set to True to indicate that the event did in fact handle the drawing of
the cell. Set it to False to indicate that the control should draw the cell instead.
Remarks
This event is only fired for columns in which the OwnerDraw property is set to True.
You can use this event to customize the appearance of individual cells by drawing directly to the grid's
device context using standard Windows GDI calls.
Note
The Left, Top, Right, and Bottom arguments are supplied in pixels so that they can be used directly in GDI
calls.
See Also
TDBGrid Control (page 118)

OwnerDrawCellPrint Event
The OwnerDrawCellPrint event occurs just before the cell specified by the Bookmark, Col, and Split
arguments is to be printed.
Syntax
TDBGrid_OwnerDrawCellPrint (ByVal hDC As Long, ByVal Bookmark As Variant, ByVal Split as Integer,
ByVal Col As Integer, ByVal Left As Integer, ByVal Top As Integer, ByVal Right As Integer, ByVal Bottom As
Integer, Done As Integer)
Event applies to TDBGrid control.
560 · Object Reference

Arguments
hDC is a handle to the printer device context, which is required by all Windows GDI calls.
Bookmark is a variant that uniquely identifies the row to be painted.
Split is an integer that identifies the current split.
Col is an integer that identifies the column to be painted.
Left is an integer that indicates the left coordinate of the cell to be painted.
Top is an integer that indicates the top coordinate of the cell to be painted.
Right is an integer that indicates the right coordinate of the cell to be painted.
Bottom is an integer that indicates the bottom coordinate of the cell to be painted.
Done is an integer that should be set to True to indicate that the event did in fact handle the printing of the
cell. Set it to False to indicate that the control should print the cell instead.
Remarks
This event is only fired for columns in which the OwnerDraw property is set to True.
You can use this event to customize the appearance of individual cells by drawing directly to the printer
device context using standard Windows GDI calls. Note that this is an enhanced metafile device context,
so some operations (such as BitBlt) are not available.
Note
Since the mapping mode of the printer device context is MM_ISOTROPIC, not MM_TEXT, the Left, Top,
Right, and Bottom arguments are in logical units, not Pixels. Use the UnitsPerInch property to determine
the resolution of the printer device context.
See Also
TDBGrid Control (page 118)

OwnerDrawPageFooter Event
The OwnerDrawPageFooter event occurs just before the footer is to be printed.
Syntax
TDBGrid_OwnerDrawPageFooter (ByVal hDC As Long, ByVal Page As Long, ByVal Pages As Long, ByVal
Group As Long, ByVal Groups As Long, ByVal Subpage As Long, ByVal Subpages As Long, ByVal Left As
Integer, ByVal Top As Integer, ByVal Right As Integer, ByVal Bottom As Integer)
Arguments
hDC is a handle to the printer device context, which is required by all Windows GDI calls.
Page is the current page number.
Pages is the total number of pages.
Group is the current group number.
Groups is the total number of groups.
Subpage is the current subpage.
 OwnerDrawPageHeader Event · 561

Arguments
Subpages is the total number of subpages.
Left is an integer that indicates the left coordinate of the cell to be painted.
Top is an integer that indicates the top coordinate of the cell to be painted.
Right is an integer that indicates the right coordinate of the cell to be painted.
Bottom is an integer that indicates the bottom coordinate of the cell to be painted.
Remarks
This event is only fired for PrintInfo objects in which the PageFooterOwnerDraw property is set to True.
You can use this event to customize the appearance of the footer by drawing directly to the printer device
context using standard Windows GDI calls. Note that this is an enhanced metafile device context, so
some operations (such as BitBlt) are not available.
Note
Since the mapping mode of the printer device context is MM_ISOTROPIC, not MM_TEXT, the Left, Top,
Right, and Bottom arguments are in logical units, not Pixels. Use the UnitsPerInch property to determine
the resolution of the printer device context.
See Also
TDBGrid Control (page 118)

OwnerDrawPageHeader Event
The OwnerDrawPageHeader event occurs just before the header is to be printed.
Syntax
TDBGrid_OwnerDrawPageHeader (ByVal hDC As Long, ByVal Page As Long, ByVal Pages As Long, ByVal
Group As Long, ByVal Groups As Long, ByVal Subpage As Long, ByVal Subpages As Long, ByVal Left As
Integer, ByVal Top As Integer, ByVal Right As Integer, ByVal Bottom As Integer)
Arguments
hDC is a handle to the printer device context, which is required by all Windows GDI calls.
Page is the current page number.
Pages is the total number of pages.
Group is the current group number.
Groups is the total number of groups.
Subpage is the current subpage.
Subpages is the total number of subpages.
Left is an integer that indicates the left coordinate of the cell to be painted.
Top is an integer that indicates the top coordinate of the cell to be painted.
Right is an integer that indicates the right coordinate of the cell to be painted.
Bottom is an integer that indicates the bottom coordinate of the cell to be painted.
562 · Object Reference

Remarks
This event is only fired for PrintInfo objects in which the PageHeaderOwnerDraw property is set to True.
You can use this event to customize the appearance of the header by drawing directly to the printer
device context using standard Windows GDI calls. Note that this is an enhanced metafile device context,
so some operations (such as BitBlt) are not available.
Note
Since the mapping mode of the printer device context is MM_ISOTROPIC, not MM_TEXT, the Left, Top,
Right, and Bottom arguments are in logical units, not Pixels. Use the UnitsPerInch property to determine
the resolution of the printer device context.
See Also
TDBGrid Control (page 118)

Paint Event
The Paint event is triggered whenever the grid repaints itself (that is, whenever it receives a WM_PAINT
message).
Syntax
object_Paint ( )
Arguments
None
Remarks
This occurs frequently in the Windows environment and is generally useful only for special
circumstances. In this event, programmers familiar with the Windows API may use the grid's hWnd
property to paint special effects such as lines, bitmaps, and icons in appropriate cells of the grid.
Note
This event is included for backward compatibility with earlier versions of True DBGrid. New
applications should use the OwnerDrawCell event to draw directly into the grid's device context.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

PostEvent Event
The PostEvent event is used in conjunction with the PostMsg method to postpone operations that are
illegal within the grid's events.
Syntax
object_PostEvent (ByVal MsgId As Integer)
Arguments
MsgId is an integer that identifies the message posted by the PostMsg method.
 RowColChange Event · 563

Remarks
If the PostMsg method is called, the grid will fire the PostEvent event with the MsgId of the
corresponding PostMsg invocation after all pending operations are completed. You can then safely
perform all desired operations in the PostEvent event.
For example, it is not possible to perform the Data control's Refresh method within the grid's
AfterUpdate event because database operations are still pending, and the refresh cannot be tolerated.
Instead of performing the refresh in the AfterUpdate event, you can call the PostMsg method (with a
MsgId value of 1, for instance). After all pending database operations are completed, the grid will fire the
PostEvent event. You can then perform the refresh operation safely in this event, after confirming that the
MsgId argument passed in is 1.
The special case where MsgId is zero is used to clear any pending PostMsg invocations that have not yet
been processed. A PostEvent event will fire for this case.
The following code illustrates a typical PostEvent handler:
Private Sub TDBGrid1_PostEvent(ByVal MsgId As Integer)
Select Case MsgId
Case 0
Exit Sub
Case 1
Data1.Refresh
Case 2
' Process other postponed operations
End Select
End Sub
Note
Take care to avoid recursive situations when using PostMsg and PostEvent.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowColChange Event
The RowColChange event occurs when the current cell changes to a different cell.
Syntax
TDBGrid_RowColChange (LastRow As Variant, ByVal LastCol As Integer)
Arguments
LastRow is a variant bookmark that identifies the former current row.
LastCol is an integer that identifies the former current column.
Remarks
This event is triggered under several circumstances:
• When the grid is first displayed.
• When the user moves the current cell by clicking another cell or using the navigation keys.
• When data in the grid is changed in a way that implicitly affects the current row, such as when
the current row is deleted when it is the last row in the grid.
564 · Object Reference

• When the Bookmark, Row, Col, or Split properties are changed in code to a different value.
The current cell position is provided by the Bookmark and Col properties. The previous cell position is
specified by the LastRow and LastCol arguments.
If the user edits data and then moves the current cell position to a new row, the update events for the
original row are completed before another cell becomes the current cell.
If a cell change also results in a change to the current split, then the SplitChange event will always
precede the RowColChange event.
See Also
TDBGrid Control (page 118)

RowResize Event
The RowResize event occurs when the user has finished resizing a grid row.
Syntax
object_RowResize (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to undo resizing.
Remarks
Your event procedure can accept the change, alter the degree of change, or cancel the change completely.
The TDBGrid control's RowHeight property determines the height of all rows in the control.
If you set the Cancel argument to True, the previous row height is restored and no repainting occurs. To
alter the degree of change, set the RowHeight property to the desired value.
It is not necessary to execute the Refresh method within this event procedure. Doing so causes the grid to
be repainted even if the Cancel argument is True.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Scroll Event
The Scroll event occurs when the user scrolls the grid horizontally or vertically using the scroll bars.
Syntax
object_Scroll (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to prevent the scroll operation from occurring.
Remarks
This event is fired before the grid is repainted to display the results of the scroll operation. If you set the
Cancel argument to True, the scroll operation fails and no repainting occurs.
 SelChange Event · 565

It is not necessary to execute the Refresh method within this event procedure. Doing so causes the grid to
be repainted even if the Cancel argument is True.
You can use this event to perform calculations or to manipulate controls that must be coordinated with
ongoing changes in the grid's scroll bars.
Note
Within this event procedure, the values of the FirstRow and LeftCol properties are not updated to reflect
the pending scroll operation. You cannot determine the orientation or magnitude of the pending scroll
operation by examining these properties.
Avoid using a MsgBox (Visual Basic) statement or function in this event.
This event only fires when the user operates the scroll bars; it will not fire in response to keyboard
navigation, data control notifications, or code.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

SelChange Event
The SelChange event occurs when the user selects a different range of rows or columns.
Syntax
object_SelChange (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to undo the new selection.
Remarks
This event is triggered under several circumstances:
• When the user selects a single row by clicking its record selector.
• When the user adds a row to the list of selected rows by clicking its record selector while holding
down the CTRL key.
• When the user selects a single column by clicking its header.
• When the user changes the range of selected columns by dragging to an adjacent column within
the header row.
• When the user extends the range of selected columns by holding down the SHIFT key and clicking
an unselected column header.
• When the user clears the current row or column selection by clicking an individual cell, in which
case this event precedes RowColChange.
The current range of selected columns is provided by the SelStartCol and SelEndCol properties. The
bookmarks of the selected rows are available in the SelBookmarks collection. Within this event
procedure, these properties and collections reflect the user's pending selection(s).
If your event procedure sets the Cancel argument to True, the previous row and column selections (if any)
are restored, and the aforementioned properties revert to their previous values.
566 · Object Reference

This event is only triggered by user interaction with the grid. It cannot be triggered by code.
Note
When the user selects a column, any row selections are cleared. Similarly, when the user selects a row,
any column selections are cleared.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

SplitChange Event
The SplitChange event occurs when the current cell changes to a different cell in another split.
Syntax
TDBGrid_SplitChange ( )
Event applies to TDBGrid control.
Arguments
None
Remarks
This event is triggered under several circumstances:
• When the grid is first displayed.
• When the user clicks a cell in another split, subject to the setting of the AllowFocus property.
• When the user presses a navigation key to cross a split boundary, subject to the setting of the
TabAcrossSplits property.
• When the Split property is changed in code to a different value.
• When a new split is inserted before the current split via code or user interaction.
• When the current split is removed via code or user interaction.
If the user edits data and then moves the current cell position to a new row in another split, the update
events for the original row are completed before the SplitChange event is executed.
If a split change also results in a change to the current row or column, then the SplitChange event will
always precede the RowColChange event.
See Also
TDBGrid Control (page 118)

UnboundAddData Event
The UnboundAddData event is fired when the user adds a new row of data to an unbound grid (one
with its DataMode property set to 1 - Unbound or 2 - Unbound Extended).
Syntax
TDBGrid_UnboundAddData (ByVal RowBuf As TrueDBGrid80.RowBuffer, NewRowBookmark As Variant)
 UnboundColumnFetch Event · 567

Arguments
RowBuf is a RowBuffer object used to transfer new row data to the grid.
NewRowBookmark is a variant that must be set to a unique bookmark for subsequent references to the
newly added row.
Remarks
This event alerts your application that it must add a new row of data to its unbound dataset.
The RowBuf argument contains a single row of data to be written to the unbound dataset. Since only one
row of data can be added at a time, the value of its RowCount property will always be 1. The number of
columns in a RowBuffer is given by its ColumnCount property.
The Value property of the RowBuf argument contains the cell data entered by the user. If the user did not
modify a particular cell, then the corresponding entry in the Value property will contain a Null variant. In
Visual Basic, the IsNull function can be used to test for this condition.
Before returning from this event, NewRowBookmark must be set to the bookmark of the newly added row,
or else the user will not be able to move to another row without first canceling the new row with the ESC
key.
This event will not be fired if the AllowAddNew property is set to False. Conversely, if you do not
implement this event, then you must ensure that AllowAddNew is never set to True.
Note
If the add operation fails in the underlying data source, then you should set the row buffer's RowCount
property to 0 to inform the grid of the failure. The grid will not display an error message, but will leave
the row in a modified state. At that point, the user can either correct the data or press the ESC key to
cancel the operation.
See Also
TDBGrid Control (page 118)

UnboundColumnFetch Event
The UnboundColumnFetch event is fired when a bound grid (one with its DataMode property set to 0 -
Bound) needs to display the value of a cell in an unbound column as specified by the Bookmark and Col
arguments.
Syntax
TDBGrid_UnboundColumnFetch (Bookmark As Variant, Col As Integer, Value As Variant)
Arguments
Bookmark is a variant that identifies the row being requested.
Col is an integer that identifies the column being requested.
Value is a variant used to transfer unbound column data to the grid.
Remarks
For a bound grid, any column with an empty DataField property and a non-empty Caption property is
considered an unbound column.
568 · Object Reference

To return an unbound value to the grid, simply set the Value argument to the desired result. If you do not
assign a value, the cell will remain blank.
Use this event to implement calculated fields based on other columns or to display local data alongside
remote bound data.
Your application is responsible for storing data entered into an unbound column by the user. Use the
Column object's Text property to retrieve unbound values within the BeforeUpdate and BeforeInsert
events.
If an unbound column is used to display a calculated result based on other columns, then you do not
need to store the unbound values since they can always be calculated "on the fly" using either the
Column object's Text property or data access objects.
Note
Do not confuse unbound columns with unbound mode. The UnboundColumnFetch event is only fired
when a bound grid contains one or more unbound columns.
During the execution of this event, row movement is not permitted.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

UnboundDeleteRow Event
The UnboundDeleteRow event is fired when the user deletes an existing row within an unbound grid
(one with its DataMode property set to 1 - Unbound or 2 - Unbound Extended).
Syntax
TDBGrid_UnboundDeleteRow (Bookmark As Variant)
Arguments
Bookmark is a variant that uniquely identifies the row to be deleted.
Remarks
This event alerts your application that it must delete the row specified by the Bookmark argument from its
unbound dataset.
The Bookmark argument contains a bookmark supplied by your application in the UnboundReadData,
UnboundReadDataEx, or UnboundAddData event.
This event will not be fired if the AllowDelete property is set to False. Conversely, if you do not
implement this event, then you must ensure that AllowDelete is never set to True.
Note
If the delete operation fails in the underlying data source, then you should set Bookmark to Null to inform
the grid of the failure. This will cause the grid's Error event to fire. The row specified by Bookmark will
remain selected.
See Also
TDBGrid Control (page 118)
 UnboundGetRelativeBookmark Event · 569

UnboundGetRelativeBookmark Event
Fired when the dropdown needs a relative bookmark.
Syntax
object_UnboundGetRelativeBookmark (StartLocation As Variant, ByVal Offset As Long, NewLocation As
Variant, ApproximatePosition As Long)
Arguments
StartLocation is a bookmark that, together with Offset, specifies the row to be returned in NewLocation. A
StartLocation of Null indicates a request for a row from BOF or EOF.
Offset specifies the relative position (from StartLocation) of the row to be returned in NewLocation. A
positive number indicates a forward relative position; a negative number indicates a backward relative
position.
NewLocation is a variable that receives the bookmark of the row specified by StartLocation plus Offset. If
the row specified is beyond the first or the last row (that is, beyond BOF or EOF), then NewLocation
should be set to Null.
ApproximatePosition is a variable that optionally receives the ordinal position of NewLocation. Setting this
variable will enhance the ability of the grid to display its vertical scroll bar accurately. If the exact ordinal
position of NewLocation is not known, you can set it to a reasonable, approximate value, or just ignore this
parameter.
Remarks
This event is mandatory when the DataMode property is set to 3 - Application. For DataMode 1 -
Unbound, this event is optional. It is not used when the DataMode property is set to 2 - Unbound Extended.
This event is used in conjunction with the UnboundReadData or ClassicRead events when the grid
needs to obtain positional information about your underlying data. By coding this event for DataMode
setting 1 - Unbound, you can dramatically improve the performance of the grid. However, you do not
need to change existing applications; you can ignore this event and they will continue to function
properly.
Before returning from this event, you must set NewLocation to a valid bookmark. For example, if Offset is 1
(or -1), then you must return in NewLocation the bookmark of the row that follows (or precedes)
StartLocation. However, if the requested row is beyond the first or last row, then you should return Null in
NewLocation to inform the grid of BOF/EOF conditions.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

UnboundReadData Event
The UnboundReadData event is fired when an unbound grid (one with its DataMode property set to 1 -
Unbound) requires data for display, such as when it is first loaded or the user scrolls the grid display.
Syntax
object_UnboundReadData (ByVal RowBuf As TrueDBGrid80.RowBuffer, StartLocation As Variant, ByVal
ReadPriorRows As Boolean)
570 · Object Reference

Arguments
RowBuf is a RowBuffer object used to transfer row data to the grid.
StartLocation is a variant bookmark that identifies the row to position to before fetching the next or
previous page of records. If Null, the grid is requesting the first or last page of records as determined by
the ReadPriorRows argument.
ReadPriorRows is a boolean that determines the direction in which rows are to be fetched. If True, the grid
is requesting records that precede StartLocation. If False, the grid is requesting records that follow
StartLocation.
Remarks
The RowBuf argument acts like a two-dimensional array of variants corresponding to the grid cells being
fetched. By populating its Value property with the appropriate data, your event procedure transfers rows
from the unbound dataset to the grid.
Use the row buffer's RowCount property to determine how many rows of data the grid is requesting. Use
its ColumnCount property to determine the number of columns to be populated.
The RowBuf argument is also used to store a set of variant bookmarks that uniquely identify rows in the
unbound dataset. The format of these bookmarks is determined solely by your application. For example,
they may be primary key fields, row numbers, or array indexes, depending upon the nature of the
unbound dataset.
Your event procedure supplies bookmarks to the grid by populating the row buffer's Bookmark property
for each row returned. Keep in mind that the bookmarks you provide in the UnboundReadData event
may be subsequently passed to the UnboundWriteData and UnboundDeleteRow events depending on
how the user interacts with the grid. In addition, bookmark-based TDBGrid properties and methods
such as Bookmark, FirstRow, GetBookmark, and RowBookmark are also designed to work with these
unbound bookmarks.
It is not necessary to fill the row buffer completely, and it is in fact acceptable to return no rows at all. The
row buffer's RowCount property can be set to indicate that fewer rows were returned than requested.
The grid interprets this to mean that there are no more rows to retrieve in the indicated direction. Thus, it
is only necessary to fill the row buffer completely if there are more valid rows to be retrieved.
Note
True DBGrid is very conservative in its assumptions about row counts and BOF/EOF conditions. As a
result, it may seem that the UnboundReadData event fires "too often." This should not be interpreted as
a sign of inefficiency, but rather as an assurance that an unbound grid performs accurately with large
multiuser databases.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

UnboundReadDataEx Event
The UnboundReadDataEx event is fired when an unbound grid (one with its DataMode property set to 2
- Unbound Extended) requires a bookmark for a specific row or data for display, such as when it is first
loaded or the user scrolls the grid display.
 UnboundReadDataEx Event · 571

Syntax
object_UnboundReadDataEx (ByVal RowBuf As TrueDBGrid80.RowBuffer, StartLocation As Variant, ByVal
Offset As Long, ApproximatePosition As Long)
Arguments
RowBuf is a RowBuffer object used to transfer row data to the grid.
StartLocation is a bookmark that, together with Offset, specifies the starting row for data transfer. A
StartLocation of Null indicates a request for data from BOF or EOF. For example, if StartLocation is Null
and Offset is 2 (or -2), then you should retrieve data starting from the second (or second to last) row.
Offset specifies the relative position (from StartLocation) of the first row of data to be transferred. A
positive number indicates a forward relative position; a negative number indicates a backward relative
position.
ApproximatePosition is a variable that optionally receives the ordinal position of the first row of data to be
transferred. Setting this variable will enhance the ability of the grid to display its vertical scroll bar
accurately. If the exact ordinal position of the row is not known, you can set it to a reasonable,
approximate value, or just ignore this parameter.
Remarks
Before returning from the UnboundReadDataEx event, you must fill the Bookmark array of RowBuf with
unique row identifiers, and the Value array with the actual data. For example, if Offset is 1 (or -1), then
you must fill in RowBuf, starting from the row that follows (or precedes) StartLocation.
The RowBuf argument acts like a two-dimensional array of variants corresponding to the grid cells being
fetched. By populating its Value property with the appropriate data, your event procedure transfers rows
from the unbound dataset to the grid.
Use the row buffer's RowCount property to determine how many rows of data the grid is requesting. Use
its ColumnCount property to determine the number of columns to be populated, if any. If ColumnCount
is zero, the grid is requesting the bookmark of a single row; if ColumnCount is nonzero, the grid is
requesting RowCount rows of data and their corresponding bookmarks.
The ColumnIndex property specifies the grid column index corresponding to a row buffer column index;
you must fill in the Value property array with column data according to the column index specified by
the ColumnIndex property array.
The RowBuf argument is also used to store a set of variant bookmarks that uniquely identify rows in the
unbound dataset. The format of these bookmarks is determined solely by your application. For example,
they may be primary key fields, row numbers, or array indexes, depending upon the nature of the
unbound dataset.
Your event procedure supplies bookmarks to the grid by populating the row buffer's Bookmark property
for each row returned. Keep in mind that the bookmarks you provide in the UnboundReadDataEx event
may be subsequently passed to the UnboundWriteData and UnboundDeleteRow events depending on
how the user interacts with the grid. In addition, bookmark-based TDBGrid properties and methods
such as Bookmark, FirstRow, GetBookmark, and RowBookmark are also designed to work with these
unbound bookmarks.
It is not necessary to fill the row buffer completely, and it is in fact acceptable to return no rows at all. The
row buffer's RowCount property can be set to indicate that fewer rows were returned than requested.
The grid interprets this to mean that there are no more rows to retrieve in the indicated direction. Thus, it
is only necessary to fill the row buffer completely if there are more valid rows to be retrieved.
572 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

UnboundWriteData Event
The UnboundWriteData event is fired when the user modifies an existing row within an unbound grid
(one with its DataMode property set to 1 - Unbound or 2 - Unbound Extended) and attempts to commit the
changes by moving to a different row.
Syntax
TDBGrid_UnboundWriteData (ByVal RowBuf As TrueDBGrid80.RowBuffer, WriteLocation As Variant)
Arguments
RowBuf is a RowBuffer object used to transfer modified row data from the grid to the unbound data
source.
WriteLocation is a variant bookmark that uniquely identifies the row to be updated.
Remarks
This event alerts your application that it must update the row specified by the WriteLocation argument
within its unbound dataset.
The RowBuf argument contains a single row of data to be written to the unbound dataset. Since only one
row of data can be updated at a time, the value of its RowCount property will always be 1. The number
of columns in a RowBuffer is given by its ColumnCount property.
The WriteLocation argument contains a bookmark supplied by your application in either the
UnboundReadData, UnboundReadDataEx, or UnboundAddData event.
The Value property of the RowBuf argument contains the cell data entered by the user. If the user did not
modify a particular cell, then the corresponding entry in the Value property will contain a Null variant,
not the current cell contents. In Visual Basic, the IsNull function can be used to test for this condition.
This event will not be fired if the AllowUpdate property is set to False. Conversely, if you do not
implement this event, then you must ensure that AllowUpdate is never set to True.
Note
If the update operation fails in the underlying data source, then you should set the row buffer's
RowCount property to 0 to inform the grid of the failure. The grid will not display an error message, but
will leave the row in a modified state. At that point, the user can either correct the data or press the ESC
key to cancel the operation.
You can force the UnboundWriteData event to occur in code by calling the Update method. This method
is particularly valuable when the unbound dataset contains a single row and AllowAddNew is False,
since there is no way for the user to trigger the update by moving to another row in this case.
See Also
TDBGrid Control (page 118)
 ValueItemError Event · 573

ValueItemError Event
The ValueItemError event is triggered when the user attempts to enter invalid data into a column that is
using value lists.
Syntax
object_ValueItemError (ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column being edited.
Remarks
This event is only triggered when the associated ValueItems collection has its Validate property set to
True.
This event is useful even if the user is permitted to enter values not present in the ValueItems collection,
as you may want to add the new value to the collection in this event. It also allows you to control how
you want to respond to incorrect input.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

TDBDropDown All Members

TDBDropDown Control Properties
AllowColMove Enables interactive column movement
AllowColSelect Enables interactive column selection
AllowRowSizing Enables interactive row resizing
AlternatingRowStyle Controls whether even/odd row styles are applied
AnchorRightColumn Controls horizontal scrolling when the last column is visible
Appearance Controls 3-D display of column headings
ApproxCount Sets/returns the approximate number of rows
Array Specifies an XArrayDB object as the data source
BackColor Sets/returns the background color
Bookmark Sets/returns bookmark of current row
BookmarkType Sets/returns the variant type used for passing bookmarks
BorderStyle Sets/returns style for drop-down border
Col Sets/returns current column number
ColumnFooters Turns column footings on or off
ColumnHeaders Turns column headings on or off
Columns Contains a collection of drop-down columns
CurrentCellVisible Sets/returns the visibility of the current cell
574 · Object Reference

DataField Drop-down column used to update associated grid column

DataMember Sets/returns a data member offered by an OLE DB provider
DataMode Specifies bound or unbound mode
DataSource Specifies source of drop-down data
DeadAreaBackColor Sets/returns the background color of the control's dead area
DefColWidth Specifies column width for auto-created columns
EmptyRows Enables empty rows in an underpopulated drop-down
Enabled Enables or disables user interaction
ErrorText Returns the error message associated with the Error event
EvenRowStyle Controls the row style for even-numbered rows
ExtendRightColumn True if rightmost column extends to edge of split
FetchRowStyle Controls whether the FetchRowStyle event will be fired
FirstRow Bookmark of row occupying first display line
Font Specifies the overall font for a drop-down
FooterBackColor Sets/returns the footing background color
FooterFont Specifies the footing font for a drop-down
FooterForeColor Sets/returns the footing foreground color
FooterStyle Controls the footing style for a drop-down
FootLines Number of lines allocated for footing text
ForeColor Sets/returns the foreground color
HeadBackColor Sets/returns the heading background color
HeadFont Specifies the heading font for a drop-down
HeadForeColor Sets/returns the heading foreground color
HeadingStyle Controls the heading style for a drop-down
HeadLines Number of lines allocated for heading text
HighlightRowStyle Controls the marquee style when set to Highlight Row
hWnd Returns the window handle of the drop-down
IntegralHeight Controls whether partial rows are displayed
LayoutFileName Sets/returns the name of a file containing drop-down layouts
LayoutName Sets/returns the name of the current drop-down layout
Layouts Returns a collection of layout names
LayoutURL Sets/returns the URL used for downloading drop-down layouts
LeftCol Sets/returns the leftmost visible column
ListField Sets/returns the name of the incremental search column
OddRowStyle Controls the row style for odd-numbered rows
 TDBDropDown All Members · 575

PartialRightColumn True if rightmost column can be clipped to edge of split

RightToLeft When True, applies right to left text functionality
Row Specifies display line of current data row
RowDividerColor Controls the row divider color
RowDividerStyle Selects style of row divider lines
RowHeight Specifies height of all grid rows
RowTracking When True, cursor position determines current selected row
ScrollBars Sets/returns scroll bar style for the drop-down
ScrollTips Determines whether the grid displays a pop-up window
ScrollTrack Scrollbar thumb causes the grid display to update
SelectedItem Sets/returns bookmark of currently selected item
SelEndCol Sets/returns rightmost selected column
SelStartCol Sets/returns leftmost selected column
Style Controls the normal style for a drop-down
Styles Contains a collection of drop-down styles
Text Sets/returns displayed cell text for the current row
ValueTranslate Determines if a grid column performs automatic value translation
VisibleCols Returns number of visible columns
VisibleRows Returns number of visible display rows

TDBDropDown Control Methods

AboutBox Displays the About box
AddCellStyle Adds a cell condition to a dropdown
AddRegexCellStyle Adds a regular expression cell condition to a dropdown
CaptureImage Returns a captured image of a dropdown's display
ClearCellStyle Removes a cell condition from a dropdown
ClearFields Clears the current column/field layout
ClearRegexCellStyle Removes a regular expression cell condition from a dropdown
ClearSelCols Deselects all selected columns
ColContaining Identifies a column under an X coordinate
GetBookmark Returns a bookmark relative to the current row
HoldFields Uses the current column/field layout for all displays
PostMsg Posts a message to the dropdown to fire the PostEvent event
ReBind Reinitializes a dropdown from its data source
Refresh Updates a dropdown's screen display
RowBookmark Returns the bookmark corresponding to a display row
576 · Object Reference

RowContaining Identifies a row under a Y coordinate

RowTop Returns the Y position of a row's top border
Scroll Scrolls a dropdown's data area

TDBDropDown Control Events

ClassicRead Fired when the dropdown needs unbound data for display
Click Fired when a mouse click occurs
ColMove Occurs before repainting when columns are moved
ColResize Occurs before repainting when a column is resized
DataSourceChanged Fired when the data source changes
DblClick Fired when a mouse double click occurs
DropDownClose Fired when the dropdown is closed
DropDownOpen Fired when the dropdown is displayed
Error Occurs when an associated action fails
FetchCellStyle Fired when the FetchStyle property is set to
dbgFetchCellStyleColumn or dbgFetchCellStyleAddNewColumn for a
column
FirstRowChange Fired when the FirstRow property changes
FootClick Occurs when a column footer has been clicked
FormatText Fired when specified by the NumberFormat property
HeadClick Occurs when a column header has been clicked
KeyDown Occurs when a key is pressed
KeyPress Occurs when an ANSI key is pressed and released
KeyUp Occurs when a key is released
LayoutReady Fired when downloading of a layout file is complete
LeftColChange Fired when the LeftCol property changes
MouseDown Occurs when a mouse button is pressed
MouseMove Occurs when the mouse moves
MouseUp Occurs when a mouse button is released
Paint Fired when the dropdown repaints itself
PostEvent Occurs after a PostMsg method is called
RowChange Occurs when a different row becomes current
RowResize Occurs when rows are resized
Scroll Occurs when the dropdown is scrolled with the scroll bars
SelChange Occurs when the current selected cell range changes
UnboundColumnFetch Fetches unbound column data when the control is bound
UnboundFindData Fired when the dropdown needs to find a row
 AllowColMove Property (TDBDropDown) · 577

UnboundGetRelativeBookmark Fired when the dropdown needs a relative bookmark

UnboundReadData Fired when the dropdown needs unbound data for display
UnboundReadDataEx Fired when the dropdown needs unbound data for display
ValueItemError Fired when invalid data is typed into a ValueItems column

TDBDropDown Properties
AllowColMove Property (TDBDropDown)
Enables interactive column movement.
Syntax
object.AllowColMove = boolean
Remarks
Read/Write at run time and design time.
If True, the user can move selected columns.
If False (the default), the user cannot move selected columns.
Use the AllowColMove property to control whether the user can move selected columns by dragging the
column divider highlight bar to the desired location. Any change in column order causes a ColMove
event.
If AllowColMove is set to True, and the DataView property is set to 2 - Group, a grouping area is added
to the grid. Columns can be added or dragged to this area at run time, creating a new split for enhanced
data display.
See Outlook-Style Grouping (page 278) for more information.
Note
The AllowColSelect property must also be True in order for the user to move selected columns.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

AllowColSelect Property (TDBDropDown)

Enables interactive column selection.
Syntax
object.AllowColSelect = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the user can select columns.
578 · Object Reference

If False, the user cannot select columns.

Use the AllowColSelect property to control whether the user can select columns by clicking or dragging
within the column header area. Setting this property to False suppresses highlighting when the user clicks
a column header, which is useful for applications that respond to the HeadClick event.
Note
Both the AllowColSelect and AllowColMove properties must be True in order for the user to move
selected columns.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

AllowRowSizing Property (TDBDropDown)

Enables interactive row resizing.
Syntax
object.AllowRowSizing = boolean
Remarks
Read/Write at run time. Read/Write at design time (TDBDropDown, Split). Read-only at design time
(TDBGrid).
If the AllowRowSizing property is True, the mouse pointer turns into a double-headed arrow when
positioned over the row divider in the RecordSelectors column between any pair of record selectors in
the grid. For a TDBDropDown control, the mouse cursor must be moved over a row divider at the left
edge of the control (where the RecordSelectors would be if they were present). In either case, the user
can interactively resize the rows by dragging the mouse while the double-headed arrow cursor is
showing. Any change in row size causes a RowResize event to fire.
If the AllowRowSizing property is False, the user cannot interactively resize rows.
All rows of the TDBGrid control are always the same height, which is determined by the RowHeight
property.
The default value of the property is True for the TDBGrid control and Split object, False for the
TDBDropDown control.
Note
RecordSelectors must be visible in a split in order for the user to resize rows interactively in that split. If
RecordSelectors are disabled for all splits in a TDBGrid control, the user cannot resize rows interactively
in that grid. This restriction does not apply to the TDBDropDown control.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)
 AlternatingRowStyle Property (TDBDropDown) · 579

AlternatingRowStyle Property (TDBDropDown)

This property determines whether a grid or split displays odd-numbered rows in one style and even-
numbered rows in another.
Syntax
object.AlternatingRowStyle = boolean
Remarks
Read/Write at run time and design time.
If True, the OddRowStyle and EvenRowStyle properties control the appearance of rows within the
specified object.
If False (the default), the Style property controls the display of rows within the specified object.
At design time, you can change the colors and fonts used to render odd (even) rows by modifying the
built-in OddRow (EvenRow) style using the Styles property page.
At run time, you can change the colors and fonts used to render odd (even) rows by modifying the Style
object returned by the OddRowStyle (EvenRowStyle) property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

AnchorRightColumn Property (TDBDropDown)

This property controls the behavior of horizontal scrolling in a grid or split when the last column is
visible.
Syntax
object.AnchorRightColumn = boolean
Remarks
Read/Write at run time and design time.
If True, the user can scroll horizontally until the last column is completely visible. If there is at least one
visible column to the left of the last column, then the last column cannot become the leftmost column.
If False (the default), the user can scroll horizontally until the last column becomes the leftmost column.
The area between the last column and the end of the grid or split will be filled using the system 3D
Objects color (or the system Button Face color) as determined by your Control Panel settings.
If a grid contains multiple splits, then setting its AnchorRightColumn property has the same effect as
setting the AnchorRightColumn property of each split individually.
Note
If PartialRightColumn is False, or ExtendRightColumn is True, then the value of the
AnchorRightColumn property is ignored, and the grid or split behaves as if it were set to True.
580 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

Appearance Property (TDBDropDown)

Controls 3-D display of headings, caption, record selectors.
Syntax
object.Appearance = value
Values
Design Time Run Time
0 - Flat dbgFlat
1 - 3D (default) dbg3D
2 - 3D Track dbgTrack3D
3 - XP Theme dbgXPTheme
Remarks
Read/Write at run time and design time.
When this property is set to 1 - 3D, the control paints its caption bars, column headings, column footings,
and record selectors with three-dimensional effects.
When this property is set to 0 - Flat, no visual effects are used.
When this property is set to 2 - 3D Track, the initial state of the control is the same as 0 - Flat. If the mouse
moves over a control element (e.g., Column Header) it takes on a 3D appearance for that particular
element.
When this property is set to 3 – XP Theme, the grid is displayed using XP theme elements when run on an
operating system that supports Themes. If this property is set and the operating system does not support
themes, it renders using the traditional 3D look.
The Appearance property is independent of the BorderStyle and BackColor properties and only affects
the control's caption bars, column headings, column footings, record selectors, and scroll bars. The
control's data cells, row dividers, and column dividers are not affected.
This property only affects the way in which static elements such as caption bars are drawn; it does not
affect their visibility. Use the Caption, ColumnHeaders, ColumnFooters, and RecordSelectors properties
to control the visibility of these components.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
 ApproxCount Property (TDBDropDown) · 581

ApproxCount Property (TDBDropDown)

This property sets or returns the approximate row count used by the grid to calibrate the vertical scroll
bar.
Syntax
object.ApproxCount = long
Remarks
Read/Write at run time. Not available at design time.
Typically, the ApproxCount property is used in unbound mode to improve the accuracy of the vertical
scroll bar. This is particularly useful for situations where the number of rows is known in advance, such
as when an unbound grid is used in conjunction with an array.
Note
For a bound grid, setting the ApproxCount property has no effect. However, getting the ApproxCount
property will query the underlying data source.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Array Property (TDBDropDown)

Specifies an XArrayDB object as the data source.
Syntax
object.Array = XArrayDB
Remarks
Read/Write at run time. Not available at design time.
For a grid with its DataMode property set to 4 - Storage, the Array property specifies a ComponentOne
XArrayDB object that acts as a data source. This property has no effect in other data modes.
Note
For backward compatibility, the Array property also accepts an XArray object. However, XArrayDB is
preferred, since it is optimized for the two-dimensional case and supports sorting and searching.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

BackColor Property (TDBDropDown)

This property controls the background color of an object. Colors may be specified as RGB values or
system default colors.
582 · Object Reference

Syntax
object.BackColor = color
Remarks
Read/Write at run time and design time.
The background color of a grid, column, or split is determined by its Style property setting. For these
objects, the BackColor property is a shortcut to the BackColor member of the Style property.
For Style objects, the value of the BackColor property is inherited from the parent style (if any) unless
explicitly overridden.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Style Object (page 122)
Split Object (page 122)

Bookmark Property (TDBDropDown)

This property returns or sets the bookmark identifying the current row in a TDBGrid or TDBDropDown
control.
Syntax
object.Bookmark = variant
Remarks
Read/Write at run time. Not available at design time.
Use the value returned by the Bookmark property to save a reference to the current row that remains
valid even after another row becomes current.
When you set the Bookmark property to a valid value in code, the row associated with that value
becomes the current row, and the grid adjusts its display to bring the new current row into view if
necessary.
The Bookmark property is defined as a Variant to accommodate user-defined bookmarks in unbound
mode.
Note
In unbound mode, setting the Bookmark property to itself will force the current row to be updated via
the UnboundWriteData event.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
 BookmarkType Property (TDBDropDown) · 583

BookmarkType Property (TDBDropDown)

The BookmarkType property returns or sets the variant type of bookmarks returned by a TDBGrid or
TDBDropDown control through its properties, methods, and events.
Syntax
object.BookmarkType = integer
Remarks
Read/Write at run time. Not available at design time.
Use this property to ensure that the control conforms to the bookmark type expected by a bound data
source, including ADODC and RDC controls. This property is used only in bound mode and has no effect
in unbound or storage modes.
In some cases, the bookmarks returned by the grid are incompatible with the ADO Recordset object
exposed by an OLE DB data source, even though the grid uses the same bookmarks internally to retrieve
and modify data. For example, code such as the following may generate a type mismatch error:
ADODC1.Recordset.Bookmark = TDBGrid1.RowBookmark(0)
You can use the BookmarkType property in conjunction with the DataSourceChanged event to
circumvent type mismatch errors that may occur when a grid-supplied bookmark is passed to an ADO
Recordset object (or vice versa). The workaround is as follows:
Sub TDBGrid1_DataSourceChanged()
TDBGrid1.BookmarkType = VarType(ADODC1.Recordset.Bookmark)
End Sub
This code ensures that any bookmarks returned by the grid are first converted to the appropriate type for
the bound data source. This workaround is only needed when using the grid in an HTML page; it is not
needed for Visual Basic 6.0.
Note
The same technique can be used when the grid is bound to a Remote Data Control (RDC). Prior to version
5.0c, a bookmark returned by the grid had to be converted to a long integer before it could be passed to
an rdoResultset (RDO) object.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

BorderStyle Property (TDBDropDown)

This property determines whether a TDBGrid or TDBDropDown control has a border.
Syntax
object.BorderStyle = value
Values
Design Time Run Time
0 - None dbgNoBorder
1 - Fixed Single (default) dbgFixedSingle
584 · Object Reference

Remarks
Read/Write at run time and design time.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Col Property (TDBDropDown)

Sets or returns current column number.
Syntax
object.Col = integer
Remarks
Read/Write at run time. Not available at design time.
This property specifies the zero-based index of the current cell's column position. It may be set at run
time to highlight a different cell within the current row. If the column is visible, the caret or marquee will
be moved to the selected column. If the column is not visible, the grid will scroll to make it visible as a
result of setting this property.
Setting the Col property at run time does not affect selected columns. Use the SelEndCol and SelStartCol
properties to specify a selected region.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ColumnFooters Property (TDBDropDown)

Turns column footings on or off.
Syntax
object.ColumnFooters = boolean
Remarks
Read/Write at run time and design time.
If True, the control's column footers are displayed.
If False (the default), the control's column footers are not displayed.
Use the FooterText property to set the footing text of an individual Column object.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
 ColumnHeaders Property (TDBDropDown) · 585

ColumnHeaders Property (TDBDropDown)

Turns column headings on or off.
Syntax
object.ColumnHeaders = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the control's column headers are displayed.
If False, the control's column headers are not displayed.
Use the Caption property to set the heading text of an individual Column object.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Columns Property (TDBDropDown)

This property returns a collection of Column objects for a grid, drop-down control, or split.
Syntax
object.Columns
Remarks
Read-only at run time. Not available at design time.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

CurrentCellVisible Property (TDBDropDown)

Sets or returns the visibility of the current cell.
Syntax
object.CurrentCellVisible = boolean
Remarks
Read/Write at run time. Not available at design time.
This property returns True if the current cell (indicated by the Bookmark and Col properties) is visible
within the displayed area of a grid or split. It returns False if the cell is not visible.
For a TDBGrid or TDBDropDown control, setting the CurrentCellVisible property to True causes the
grid to scroll so that the current cell is brought into view. If a grid contains multiple splits, then the
current cell becomes visible in each split.
586 · Object Reference

For a Split object, setting the CurrentCellVisible property to True makes the current cell visible in that
split only.
In all cases, setting this property to False is meaningless and is ignored.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

DataField Property (TDBDropDown)

The DataField property returns or sets the name of the drop-down column used to update the associated
grid column when the user selects an item from a TDBDropDown control.
Syntax
TDBDropDown.DataField = string
Remarks
Read/Write at run time and design time.
The DataField property need not be the same as the ListField property used for incremental search.
If the DataField property is not specified, the ListField property specifies the column to be used for both
incremental search and the selection value. If neither property is specified, then the first column in the
TDBDropDown control will be used.
Note
Do not confuse the DataField property of the TDBDropDown control with the DataField property of the
Column object or intrinsic Visual Basic controls.
To associate a TDBDropDown control with a Column object that belongs to a TDBGrid control, set the
column's DropDown property to the name of the drop-down control at either design time or run time.
See Also
TDBDropDown Control (page 118)
Column Object (page 119)

DataMember Property (TDBDropDown)

This property returns or sets the name of the data member used to populate the grid. Typically, a data
member represents a database table or query.
Syntax
object.DataMember = string
Remarks
Read/Write at run time and design time.
A bound DataSource can expose multiple sets of data that consumers can bind to. Each set of data is
called a data member, and is identified by a unique string.
 DataMode Property (TDBDropDown) · 587

Note
This property is only supported by the OLE DB version of True DBGrid Pro. It is used only in bound
mode and has no effect in unbound or storage modes.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DataMode Property (TDBDropDown)

Specifies bound or unbound mode.
Syntax
object.DataMode = value
Values
Design Time Run Time
0 - Bound (default) dbgBound
1 - Unbound dbgUnbound
2 - Unbound Extended dbgUnboundEx
3 - Application dbgUnboundAp
4 - Storage dbgUnboundSt
Remarks
Read-only at run time. Read/Write at design time.
When set to 0 - Bound, the control displays data available from its bound DataSource.
When set to 1 - Unbound, the control uses the original DBGrid unbound events to retrieve and update
displayed data. When this mode is used, the grid fires the UnboundReadData event to fetch data. This
setting was retained for backward compatibility with DBGrid and earlier versions of True DBGrid. If you
are writing a new application, please use mode 2, 3, or 4 instead.
When set to 2 - Unbound Extended, the control uses the UnboundReadDataEx event to fetch data. The
UnboundReadDataEx event is more efficient and easier to use than the UnboundReadData event of
mode 1. This is the recommended setting for using the grid unbound with a database API that supports
multiple-row fetches.
When set to 3 - Application, the control uses the ClassicRead event to fetch data one cell at a time. This
mode is much easier to use than mode 2, particularly if data is being retrieved from a Visual Basic array.
However, it can be less efficient than mode 2 if there are many columns because the grid needs to fire
more events in order to retrieve data.
When set to 4 - Storage, the control uses an XArrayDB object as a data source, and no unbound data
retrieval or update events are fired. At run time, you create and populate an XArrayDB object just as you
would a standard Visual Basic array, then bind it to a TDBGrid or TDBDropDown control using the
Array property. This is by far the simplest way to use True DBGrid in unbound mode.
588 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DataSource Property (TDBDropDown)

The DataSource property specifies the data control used to bind a TDBGrid or TDBDropDown control
to a database.
Syntax
object.DataSource = datasource
Remarks
Read/Write at run time (OLE DB only) and design time.
In the OLE DB version of True DBGrid Pro, you can set this property in code as follows:
Set TDBGrid1.DataSource = ADODC1
However, the non-OLE DB version of True DBGrid Pro adheres to an older data binding specification
(ICursor), which requires that you set the DataSource property at design time in the Visual Basic
Properties window.
Note
To bind a TDBGrid or TDBDropDown control to a ComponentOne XArrayDB object, use the Array
property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DeadAreaBackColor Property (TDBDropDown)

This property controls the background color of the dead area object.
Syntax
object.DeadAreaBackColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
Setting this property will affect the appearance of the "dead area" of underpopulated controls, such as the
area to the right of the last column, the area below the last data row, and the Outlook Grouping area.
Note
If the EmptyRows property is True, the empty data rows it creates are not considered part of the "dead
area" and will not be displayed in the DeadAreaBackColor. If you wish for the area occupied by the
empty rows to be shown in the DeadAreaBackColor, you should first set the EmptyRows property to
False.
 DefColWidth Property (TDBDropDown) · 589

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DefColWidth Property (TDBDropDown)

This property returns or sets the default width for all grid columns in terms of the coordinate system of
the grid's container.
Syntax
object.DefColWidth = single
Remarks
Read/Write at run time and design time.
For bound grids, the DefColWidth property is respected under the following circumstances:
• When you execute the Retrieve Fields command at design time.
• When the grid's layout is initialized at run time.
• When a new column is created at run time.
For unbound grids, the DefColWidth property is only respected when a new column is created at run
time.
If you set the DefColWidth property to 0, the grid automatically sizes all columns based on either the
width of the column heading or the display width of the underlying field, whichever is larger. For
example, to set the default column width to the width of the first column:
TDBGrid1.DefColWidth = TDBGrid1.Columns(0).Width
Note
Setting the DefColWidth property at run time does not affect existing columns, only those that are
subsequently created in code.
In bound mode, some data sources do not provide text field widths when requested by the grid.
Therefore, if DefColWidth is 0, the actual column widths may not be what you expect since the grid must
supply a default width.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

EmptyRows Property (TDBDropDown)

The EmptyRows property returns or sets a value that determines how the grid displays rows below the
last data row.
Syntax
object.EmptyRows = boolean
590 · Object Reference

Remarks
Read/Write at run time and design time.
If all of the records in the data source do not fill up the entire grid, setting EmptyRows to True will fill the
unpopulated grid area with empty data rows. If EmptyRows is False (the default), then the unpopulated
grid area will be blank and will be filled with the system 3D Objects color (or the system Button Face
color) as determined by your Control Panel settings.
Note
The RowDividerStyle property applies to data rows and empty rows alike. You cannot suppress row
dividers for just the empty rows when EmptyRows is True.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Enabled Property (TDBDropDown)

This property returns or sets a value that determines whether a control can respond to user-generated
events.
Syntax
object.Enabled = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the user can give focus to the control and manipulate it with the keyboard or mouse.
If False, the user cannot manipulate the control directly.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ErrorText Property (TDBDropDown)

This property returns the error message string from the underlying data source.
Syntax
object.ErrorText
Remarks
Read-only at run time. Not available at design time.
When a database error occurs as a result of user interaction with the grid, such as when the user enters
text into a numeric field and then attempts to update the current record by moving to another row, the
grid's Error event will fire. However, the error code passed to the event handler in the DataError
parameter may not identify the specific error that occurred. For these reasons, the ErrorText property is
provided so that your application can parse the actual error message to determine the nature of the error.
 EvenRowStyle Property (TDBDropDown) · 591

Note
The ErrorText property is only valid within a TDBGrid or TDBDropDown control's Error event handler.
A trappable error will occur if you attempt to access it in any other context.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

EvenRowStyle Property (TDBDropDown)

Controls the row style for even-numbered rows.
Syntax
object.EvenRowStyle = variant
Remarks
Read/Write at run time and design time.
This property sets or returns the Style object that controls the appearance of an even-numbered row in a
grid or split where the AlternatingRowStyle property is set to True. By default, this is the built-in
EvenRow style.
To change the appearance of odd-numbered rows, set the OddRowStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

ExtendRightColumn Property (TDBDropDown)

This property allows the rightmost column of a grid or split to extend to the object's right edge, provided
that the object can accommodate all of the visible columns.
Syntax
object.ExtendRightColumn = boolean
Remarks
Read/Write at run time and design time.
If True, the last column will extend to the end of the grid or split.
If False (the default), the area between the last column and the end of the grid or split will be filled using
the system 3D Objects color (or the system Button Face color) as determined by your Control Panel
settings.
If a grid contains multiple splits, then setting its ExtendRightColumn property has the same effect as
setting the ExtendRightColumn property of each split individually.
592 · Object Reference

Note
This property now works even when the horizontal scroll bar is present. Prior to version 5.0, if a grid or
split could not accommodate all of the visible columns, then setting this property to True had no effect.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

FetchRowStyle Property (TDBDropDown)

Controls whether the FetchRowStyle event will be fired.
Syntax
object.FetchRowStyle = boolean
Remarks
Read/Write at run time and design time.
If True, the FetchRowStyle event will be fired whenever the grid is about to display a row of data.
If False (the default), the FetchRowStyle event is not fired.
Set this value to True when you need to perform complex per-row formatting operations that can only be
done using the FetchRowStyle event. For example, if you want to apply fonts and/or colors to all rows
that satisfy certain criteria, then you need to set the FetchRowStyle property to True and write code for
the FetchRowStyle event.
Note
To display every other row in a different color or font, you can simply set the AlternatingRowStyle
property to True.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

FirstRow Property (TDBDropDown)

This property returns or sets a value containing the bookmark for the first visible row in a grid or split.
Syntax
object.FirstRow = variant
Remarks
Read/Write at run time. Not available at design time.
For a TDBGrid or TDBDropDown control, setting the FirstRow property causes the grid to scroll so that
the specified row becomes the topmost row. If a grid contains multiple splits, then the topmost row
changes in each split, even if the splits have different ScrollGroup property settings.
 Font Property (TDBDropDown) · 593

For a Split object, setting the FirstRow property causes the specified row to become the topmost row for
that split only.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

Font Property (TDBDropDown)

This property returns or sets the font object associated with a grid, column, split, or style.
Syntax
object.Font = font
Remarks
Read/Write at run time and design time.
The font used to display text in a grid, column, or split is determined by its Style property setting. For
these objects, the Font property is a shortcut to the Font member of the Style property.
For Style objects, the value of the Font property is inherited from the parent style (if any) unless explicitly
overridden.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)
Style Object (page 122)

FooterBackColor Property (TDBDropDown)

Sets or returns the footing background color.
Syntax
object.FooterBackColor = color
Remarks
Read/Write at run time and design time.
This property controls the background color of an object's column footings. Colors may be specified as
RGB values or system default colors.
The footing background color of a grid, column, or split is determined by its FooterStyle property setting.
For these objects, the FooterBackColor property is a shortcut to the BackColor member of the
FooterStyle property.
594 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

FooterFont Property (TDBDropDown)

This property returns or sets the font object associated with the column footings of a grid, column, or
split.
Syntax
object.FooterFont = font
Remarks
Read/Write at run time and design time.
The font used to display column footing text in a grid, column, or split is determined by its FooterStyle
property setting. For these objects, the FooterFont property is a shortcut to the Font member of the
FooterStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

FooterForeColor Property (TDBDropDown)

This property controls the foreground color of an object's column footings.
Syntax
object.FooterForeColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The footing foreground color of a grid, column, or split is determined by its FooterStyle property setting.
For these objects, the FooterForeColor property is a shortcut to the ForeColor member of the FooterStyle
property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
 FooterStyle Property (TDBDropDown) · 595

See Also
Split Object (page 122)

FooterStyle Property (TDBDropDown)

This property returns the Style object that controls the appearance of column footings within a grid,
column, or split.
Syntax
object.FooterStyle = variant
Remarks
Read/Write at run time and design time.
By default, this is the built-in Footing style.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

FootLines Property (TDBDropDown)

This property returns or sets a value indicating the number of lines of text displayed in a TDBGrid or
TDBDropDown control's column footers.
Syntax
object.FootLines = single
Remarks
Read/Write at run time and design time.
The FootLines property accepts a floating point number from 0 to 10. The default value is 1, which causes
the grid to display the FooterText value for each Column object on a single line within its footer area,
provided that ColumnFooters is True.
A setting of 0 removes the footings and has the same effect as setting the ColumnFooters property to
False.
Note
You must set the FooterText property explicitly. Unlike the Caption property, it does not derive a default
value from the name of the underlying database field.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
596 · Object Reference

ForeColor Property (TDBDropDown)

This property controls the foreground color of an object.
Syntax
object.ForeColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The foreground color of a grid, column, or split is determined by its Style property setting. For these
objects, the ForeColor property is a shortcut to the ForeColor member of the Style property.
For Style objects, the value of the ForeColor property is inherited from the parent style (if any) unless
explicitly overridden.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)
Style Object (page 122)

HeadBackColor Property (TDBDropDown)

This property controls the background color of an object's column headings.
Syntax
object.HeadBackColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The heading background color of a grid, column, or split is determined by its HeadingStyle property
setting. For these objects, the HeadBackColor property is a shortcut to the BackColor member of the
HeadingStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)
 HeadFont Property (TDBDropDown) · 597

HeadFont Property (TDBDropDown)

This property returns or sets the font object associated with the column headings of a grid, column, or
split.
Syntax
object.HeadFont = font
Remarks
Read/Write at run time and design time.
The font used to display column heading text in a grid, column, or split is determined by its
HeadingStyle property setting. For these objects, the HeadFont property is a shortcut to the Font
member of the HeadingStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

HeadForeColor Property (TDBDropDown)

This property controls the foreground color of an object's column headings.
Syntax
object.HeadForeColor = color
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
The heading foreground color of a grid, column, or split is determined by its HeadingStyle property
setting. For these objects, the HeadForeColor property is a shortcut to the ForeColor member of the
HeadingStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

HeadingStyle Property (TDBDropDown)

This property returns the Style object that controls the appearance of column headings within a grid,
column, or split.
598 · Object Reference

Syntax
object.HeadingStyle = variant
Remarks
Read/Write at run time and design time.
By default, this is the built-in Heading style.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

HeadLines Property (TDBDropDown)

This property returns or sets a value indicating the number of lines of text displayed in a TDBGrid or
TDBDropDown control's column headers.
Syntax
object.HeadLines = single
Remarks
Read/Write at run time and design time.
The HeadLines property accepts a floating point number from 0 to 10. The default value is 1, which
causes the grid to display the caption for each Column object on a single line within its header area,
provided that ColumnHeaders is True.
A setting of 0 removes the headings and has the same effect as setting the ColumnHeaders property to
False.
Note
By default, a Column object's caption contains the name of its underlying field as specified by the
DataField property. You can use the Caption property to override the text displayed within column
headers.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

HighlightRowStyle Property (TDBDropDown)

This property sets or returns the Style object that controls the appearance of a highlighted row or cell
marquee.
Syntax
object.HighlightRowStyle = variant
 hWnd Property (TDBDropDown) · 599

Remarks
Read/Write at run time and design time.
By default, this is the built-in HighlightRow style.
The HighlightRowStyle value is only used when one of the following MarqueeStyle settings is in effect:
2 - Highlight Cell, 3 - Highlight Row, or 4 - HighlightRow, RaiseCell.
The value of the MarqueeStyle property is not affected by changes to the HighlightRowStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

hWnd Property (TDBDropDown)

Returns the window handle of the grid.
Syntax
object.hWnd
Remarks
Read-only at run time. Not available at design time.
The hWnd property returns the unique window handle assigned to a TDBGrid or TDBDropDown
control by the Microsoft Windows operating environment. Experienced users can pass the value of this
property to Windows API calls that require a valid window handle.
Note
Since the value of this property can change while a program is running, never store the hWnd value in a
variable.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

IntegralHeight Property
This property determines whether partial rows are displayed in a TDBDropDown control.
Syntax
TDBDropDown.IntegralHeight = boolean
Remarks
Read/Write at run time and design time.
If True, partial rows are not displayed, and the height of the control will be reduced to eliminate the last
partial row if necessary.
If False, partial rows are displayed, and the control retains its design-time height.
600 · Object Reference

See Also
TDBDropDown Control (page 118)

LayoutFileName Property (TDBDropDown)

This property sets or returns the string containing the filename used to save and retrieve grid layouts.
Syntax
object.LayoutFileName = string
Remarks
Read/Write at run time and design time.
Setting this property alone has no effect on the grid layout; the property value is used by the LoadLayout
method of the grid and the Add and Remove methods of the Layouts collection.
You can create grid layout files at design time by setting the LayoutFileName and LayoutName
properties and using the layout commands on the grid's visual editing menu.
At design time, if you first set the LayoutFileName property to a valid filename in which grid layouts are
stored, you can then choose the LayoutName property from a drop-down list of layout names stored in
the specified layout file.
Note
If the LayoutFileName property is nonempty, it takes precedence over LayoutURL, and asynchronous
downloading will not occur.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

LayoutName Property (TDBDropDown)

This property sets or returns the string (maximum length of 30 characters) containing the current layout
name.
Syntax
object.LayoutName = string
Remarks
Read/Write at run time and design time.
Setting this property alone has no effect on the grid layout; the property value is used by the LoadLayout
method of the grid.
At design time, if you first set the LayoutFileName property to a valid filename in which grid layouts are
stored, you can then choose the LayoutName property from a drop-down list of layout names stored in
the specified layout file.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
 Layouts Property (TDBDropDown) · 601

Layouts Property (TDBDropDown)

This property returns a collection of layout names corresponding to the current setting of the
LayoutFileName or LayoutURL property.
Syntax
object.Layouts
Remarks
Read-only at run time. Not available at design time.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

LayoutURL Property (TDBDropDown)

This property sets or returns the string containing the URL (Uniform Resource Locator) used for
retrieving grid layouts.
Syntax
object.LayoutURL = string
Remarks
Read/Write at run time and design time.
The LayoutURL property is similar to LayoutFileName except that it downloads a grid layout file from
an HTTP server instead of opening a file on the local machine or a network.
You can create grid layout files at design time by setting the LayoutFileName and LayoutName
properties and using the layout commands on the grid's visual editing menu.
If you set the LayoutURL property to a nonempty string at design time (and LayoutFileName is empty),
the grid initiates asynchronous downloading at run time after it has been loaded. You can also initiate
downloading by setting the LayoutURL property in code. This technique is particularly useful for
initializing a grid on an HTML page.
In either case, the grid fires the LayoutReady event when the download operation has completed. You
should write a handler for this event that loads the desired layout as follows:
TDBGrid1.LayoutName = "MyLayout"
TDBGrid1.LoadLayout
Note
Since the grid downloads layout files asynchronously, the following code may not work as expected:
TDBGrid1.LayoutURL = "http://www.bigcorp.com/layouts.grx"
TDBGrid1.LayoutName = "MyLayout"
Depending upon file size and available bandwidth, the download initiated by the first statement may still
be in progress when the second statement executes. Therefore, the layout specified in the second
statement may not yet exist. Conversely, if the download finishes quickly, it is possible for the
LayoutReady event to fire before the second statement executes. For these reasons, the recommended
602 · Object Reference

procedure is to set the LayoutName property in the LayoutReady handler, immediately before calling the
LoadLayout method.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

LeftCol Property (TDBDropDown)

This property returns or sets the zero-based index of the leftmost column in a grid or split.
Syntax
object.LeftCol = integer
Remarks
Read/Write at run time. Not available at design time.
For a TDBGrid or TDBDropDown control, setting the LeftCol property causes the grid to scroll so that
the specified column becomes the leftmost column. If a grid contains multiple splits, then the leftmost
column changes in each split.
For a Split object, setting the LeftCol property causes the specified column to become the leftmost
column for that split only.
Use the LeftCol property in code to scroll a grid or split horizontally. Use the FirstRow property to
determine the bookmark of the first visible row in a grid or split.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

ListField Property
The ListField property returns or sets the name of the column used for incremental search within a
TDBDropDown control.
Syntax
TDBDropDown.ListField = string
Read/Write at run time and design time.
Remarks
The ListField property need not be the same as the DataField property used to specify the name of the
drop-down column used to update the associated grid column when the user selects an item from a
TDBDropDown control.
If the ListField property is not specified, the DataField property specifies the column to be used for both
incremental search and the selection value. If neither property is specified, then the first column in the
TDBDropDown control will be used.
 OddRowStyle Property (TDBDropDown) · 603

Note
To associate a TDBDropDown control with a Column object that belongs to a TDBGrid control, set the
column's DropDown property to the name of the drop-down control at either design time or run time.
See Also
TDBDropDown Control (page 118)

OddRowStyle Property (TDBDropDown)

This property sets or returns the Style object that controls the appearance of an odd-numbered row in a
grid or split where the AlternatingRowStyle property is set to True.
Syntax
object.OddRowStyle = variant
Remarks
Read/Write at run time and design time.
By default, this is the built-in OddRow style.
To change the appearance of even-numbered rows, set the EvenRowStyle property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

PartialRightColumn Property (TDBDropDown)

This property determines whether the rightmost column of a grid or split is clipped to the object's right
edge when it is scrolled into view but cannot be displayed in its entirety.
Syntax
object.PartialRightColumn = boolean
Remarks
Read/Write at run time and design time.
If True (the default), the rightmost column will be clipped if the grid or split is not wide enough to
accommodate the entire column.
If False, the rightmost column will not be clipped while other columns are visible. In this case, the
rightmost column must be scrolled into view as the only visible column in the grid or split.
If a grid contains multiple splits, then setting its PartialRightColumn property has the same effect as
setting the PartialRightColumn property of each split individually.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
604 · Object Reference

See Also
Split Object (page 122)

RightToLeft Property (TDBDropDown)

The property provides an appearance and functionality familiar to Middle East or Latin users.
Syntax
object.RightToLeft = boolean
Remarks
Read/Write at run time and design time.
When the RightToLeft property is set to True:
• Grid columns begin at the right boundary of the grid.
• Fixed columns are located on the right side of the grid.

• LeftCol identifies the rightmost visible column (the first column beyond the leftmost fixed
column).
• If there are selected columns, SelStartCol returns the index of the rightmost column in the range,
and SelEndCol returns the index of the leftmost column in the range.
• If the ScrollBars property is set to 3, a vertical scroll bar is placed on the left of the grid and a
horizontal scroll bar with the scroll box on the right is placed at the bottom. A ScrollBars
property setting of 1 places only the horizontal scroll bar, while a setting of 2 places only the
vertical scroll bar.

• Cell values (grid Text property) have right to left reading order.
When the RightToLeft property is set to False, the control behavior is the same as described in the
standard documentation.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Row Property (TDBDropDown)

Specifies the display line of the current data's row.
Syntax
object.Row = integer
Remarks
Read/Write at run time. Not available at design time.
This property specifies the zero-based index of the current row relative to the first displayed row. It may
be set at run time to highlight a different cell within the current column.
The Row property accepts values ranging from 0 to VisibleRows - 1. An error occurs if you attempt to set
it to an invalid row index.
 RowDividerColor Property (TDBDropDown) · 605

If the current row is not visible, then this property returns -1.
For a TDBGrid control, changing the Row property at run time does not affect selected rows. Use the
collection returned by the SelBookmarks property to select or deselect individual rows.
For a TDBDropDown control, changing the Row property at run time also changes the value of the
SelectedItem property.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowDividerColor Property (TDBDropDown)

This property controls the row divider color of grid when RowDividerStyle is 7 - Custom Color.
Syntax
object.RowDividerColor = value
Remarks
Read/Write at run time and design time.
Colors may be specified as RGB values or system default colors.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowDividerStyle Property (TDBDropDown)

This property determines the style of the border drawn between grid rows.
Syntax
object.RowDividerStyle = value
Values
Design Time Run Time
0 - No dividers dbgNoDividers
1 - Black line dbgBlackLine
2 - Dark gray line (default) dbgDarkGrayLine
3 - Raised dbgRaised
4 - Inset dbgInset
5 - ForeColor dbgUseForeColor
6 - Light gray line dbgLightGrayLine
7 - Custom Color dbgCustomColor
Remarks
Read/Write at run time and design time.
606 · Object Reference

The RowDividerStyle property does not control whether rows can be resized by dragging their border.
Use the AllowRowSizing property to control this behavior.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowHeight Property (TDBDropDown)

This property returns or sets the height of all grid rows in terms of the coordinate system of the grid's
container.
Syntax
object.RowHeight = single
Remarks
Read/Write at run time and design time.
The RowHeight property accepts a floating point number from 0 to 10,000. The default value depends
upon the character height of the current font.
A setting of 0 causes the grid to readjust its display so that each row occupies a single line of text in the
current font. Therefore, the following statements will set the row height so that exactly two lines of text
are shown in each row:
TDBGrid1.RowHeight = 0
TDBGrid1.RowHeight = TDBGrid1.RowHeight * 2
If the control's AllowRowSizing property is set to True, then the user can adjust the RowHeight property
at run time by dragging the row divider between any pair of record selectors.
Note
Increasing the RowHeight property does not wrap cell text at column boundaries unless the column's
WrapText property is True.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowTracking Property
When True, cursor position determines the currently selected row.
Syntax
TDBDropDown.RowTracking = boolean
Remarks
Read/Write at run time and design time.
When set to True, moving the mouse within the client area of TDBDropDown causes the row under the
mouse to be the currently selected row.
If False (the default), moving the mouse does not change the selection.
 ScrollBars Property (TDBDropDown) · 607

See Also
TDBDropDown Control (page 118)

ScrollBars Property (TDBDropDown)

This property returns or sets a value indicating whether a grid or split has horizontal or vertical scroll
bars.
Syntax
object.ScrollBars = value
Values
Design Time Run Time
0 - None dbgNone
1 - Horizontal dbgHorizontal
2 - Vertical dbgVertical
3 - Both dbgBoth
4 - Automatic (default) dbgAutomatic
Remarks
Read/Write at run time and design time.
The default setting for this property causes horizontal and/or vertical scroll bars to be displayed only if
the object's contents extend beyond its borders.
If a grid contains multiple splits, then setting its ScrollBars property has the same effect as setting the
ScrollBars property of each split individually.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

ScrollTips Property (TDBDropDown)

The ScrollTips property determines whether the grid displays a pop-up text window when the scrollbar
thumb is dragged.
Syntax
object.ScrollTips = boolean
Remarks
Read/Write at run time and design time.
By default, this property is set to False, and ScrollTips are not displayed.
If the ScrollTips property is set to True, the FetchScrollTips event will be fired whenever the grid’s
scrollbar thumb is dragged.
If you do not provide a handler for the FetchScrollTips event, tips will not be displayed.
608 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ScrollTrack Property (TDBDropDown)

Scrollbar thumb causes the grid display to update.
Syntax
object.ScrollTrack = boolean
Remarks
Read/Write at run time and design time.
If True, moving the scrollbar thumb causes the grid’s display to update with new data.
If False (the default), moving the scrollbar thumb does not change the display.
If the ScrollTrack property is True, moving the scrollbar thumb causes the grid to scroll.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

SelectedItem Property
This property returns or sets the bookmark identifying the selected item in a TDBDropDown control.
Syntax
TDBDropDown.SelectedItem = variant
Remarks
Read/Write at run time. Not available at design time.
Use the value returned by the SelectedItem property to determine the current row in a TDBDropDown
control.
When you set the SelectedItem property to a valid value in code, the row associated with that value
becomes the current row, and the drop-down grid adjusts its display to bring the new current row into
view if necessary.
The SelectedItem property is defined as a Variant to accommodate user-defined bookmarks in unbound
mode.
Note
For the TDBDropDown control, the SelectedItem and Bookmark properties are synonymous.
See Also
TDBDropDown Control (page 118)
 SelEndCol Property (TDBDropDown) · 609

SelEndCol Property (TDBDropDown)

This property returns or sets the zero-based ordinal position of the rightmost selected column in a split.
Syntax
object.SelEndCol = integer
Remarks
Read/Write at run time. Not available at design time.
If no columns are selected, then this property returns -1.
If a grid contains multiple splits, then setting its SelEndCol property has the same effect as setting the
SelEndCol property of the current split. The index of the current split is available through the TDBGrid
control's Split property.
Setting this property to -1 deselects all columns and also sets the SelStartCol property to -1.
Note
You can also use the ClearSelCols method to deselect all columns within a split.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

SelStartCol Property (TDBDropDown)

This property returns or sets the zero-based ordinal position of the leftmost selected column in a split.
Syntax
object.SelStartCol = integer
Remarks
Read/Write at run time. Not available at design time.
If no columns are selected, then this property returns -1.
If a grid contains multiple splits, then setting its SelStartCol property has the same effect as setting the
SelStartCol property of the current split. The index of the current split is available through the TDBGrid
control's Split property.
Setting this property to -1 deselects all columns and also sets the SelEndCol property to -1.
Note
You can also use the ClearSelCols method to deselect all columns within a split.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)
610 · Object Reference

Style Property (TDBDropDown)

This property returns or sets the Style object that controls the normal appearance of a cell within a grid,
column, or split.
Syntax
object.Style = variant
Read/Write at run time and design time.
Remarks
By default, this is the built-in Normal style.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

Styles Property (TDBDropDown)

This property returns a collection of named Style objects.
Syntax
object.Styles
Remarks
Read-only at run time. Not available at design time.
When a grid is first created, it contains ten built-in styles, which control the following display aspects:
Normal Data cells in unselected, unhighlighted rows
Heading Column headers
Footing Column footers
Selected Data cells in selected rows
Caption Grid and split caption bars
HighlightRow Data cells in highlighted rows
EvenRow Data cells in even numbered rows
OddRow Data cells in odd numbered rows
FilterBar Cells in the filter bar row
RecordSelector Cells in the record selector column
Note
At design time, use the Style Factory property page to modify these built-in styles or create your own
named styles.
 Text Property (TDBDropDown) · 611

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Text Property (TDBDropDown)

Sets or returns displayed cell text for the current row.
Syntax
object.Text = string
Remarks
Read/Write at run time. Not available at design time.
This is the default property of the TDBGrid and TDBDropDown controls.
When applied to a Column object, this property returns or sets the formatted data value in a column for
the current row.
The value returned by the Text property is derived from the underlying data value by applying the
formatting as specified by the NumberFormat property of the Column object.
When the Text property is set for a formatted column, the underlying data value cannot be derived, and
the Text and Value properties will subsequently return the same result.
Use the Value property to access the underlying data value in a column for the current row.
When applied to a TDBGrid or TDBDropDown control, this property returns or sets the text of the
current cell. If the current cell is at EOF or BOF, an empty string is returned.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)

ValueTranslate Property
This property determines whether a grid column associated with a TDBDropDown control automatically
performs value translation at run time.
Syntax
TDBDropDown.ValueTranslate = boolean
Remarks
Read/Write at run time and design time.
To use this property you must set the following TDBDropDown properties:
• DataField is the field containing the underlying data.
• ListField is the field that contains a descriptive version of DataField.
612 · Object Reference

When this property is set to True, the grid will automatically display the ListField values in the
associated column.
See Also
TDBDropDown Control (page 118)

VisibleCols Property (TDBDropDown)

Returns the number of visible columns.
Syntax
object.VisibleCols
Remarks
Read-only at run time.
For TDBGrid controls, this property returns the number of visible columns in the current split. The value
returned includes both fully and partially displayed columns. You can use the Split property of the
TDBGrid control to determine the index of the current split.
For TDBDropDown controls, this property returns the number of visible columns in the entire control,
since there can only be one split. The value returned includes both fully and partially displayed columns.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

VisibleRows Property (TDBDropDown)

This property returns the number of visible rows in the control.
Syntax
object.VisibleRows = integer
Remarks
Read-only at run time.
The value returned includes both fully and partially displayed rows.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

TDBDropDown Methods
AboutBox Method (TDBDropDown)
This method displays the version number and copyright notice for the specified control.
 AddCellStyle Method (TDBDropDown) · 613

Syntax
object.AboutBox
Arguments
None
Return Value
None
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

AddCellStyle Method (TDBDropDown)

Adds a cell condition to an object.
Syntax
object.AddCellStyle condition, style
Arguments
condition is a combination of one or more CellStyleConstants.
style is a Style object that specifies font and color attributes.
Return Value
None
Remarks
This method allows you to control the font and color of cells within a grid, column, or split according to
the status values (CellStyleConstants) specified by the condition argument:
1 - dbgCurrentCell The cell is the current cell as specified by the Bookmark, Col, and Split
properties. At any given time, only one cell can have this status. When the
MarqueeStyle property is set to 6 - Floating Editor, this condition is ignored.
2 - dbgMarqueeRow The cell is part of a highlighted row marquee. When the MarqueeStyle
property indicates that the entire current row is to be highlighted, all visible
cells in the current row have this additional condition set.
4 - dbgUpdatedCell The cell contents have been modified by the user but not yet written to the
database. This condition is also set when cell contents have been modified
in code with the Text or Value properties.
8 - dbgSelectedRow The cell is part of a row selected by the user or in code. The
SelBookmarks collection contains a bookmark for each selected row.
0 - dbgNormalCell The cell satisfies none of these conditions.
You can add the first four values together to specify multiple cell conditions. For example, a cell status
value of 9 (dbgCurrentCell + dbgSelectedRow) denotes a current cell within a selected row. You
can also use a cell status value of 0 (dbgNormalCell) to refer to only those cells without any of the four
basic cell conditions.
614 · Object Reference

The style argument specifies the attributes that will override the default font and color characteristics for
cells within an object. For example, the following code causes updated cells to be displayed in red:
Dim S As New TrueDBGrid60.Style
S.ForeColor = vbRed
TDBGrid1.AddCellStyle dbgUpdatedCell, S
Each time the AddCellStyle method is invoked, the specified cell condition is added to the list of existing
conditions. Hence, by repeated use of this method it is possible to set up multiple conditions to affect the
appearance of a grid, column, or split.
Note
If a cell condition already exists for a particular condition value, the new style setting replaces the existing
one.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

AddRegexCellStyle Method (TDBDropDown)

Adds a regular expression cell condition to an object.
Syntax
object.AddRegexCellStyle condition, style, regex
Arguments
condition is a combination of one or more CellStyleConstants.
style is a Style object that specifies font and color attributes.
regex is a regular expression string.
Return Value
None
Remarks
This method allows you to control the font and color of cells within a grid, column, or split according to
their contents. The status values (CellStyleConstants) specified by the condition argument determine
which cells are affected:
1 - dbgCurrentCell The cell is the current cell as specified by the Bookmark, Col, and Split
properties. At any given time, only one cell can have this status. When the
floating editor MarqueeStyle property setting is in effect, this condition is
ignored.
2 - dbgMarqueeRow The cell is part of a highlighted row marquee. When the MarqueeStyle
property indicates that the entire current row is to be highlighted, all visible
cells in the current row have this additional condition set.
 AddRegexCellStyle Method (TDBDropDown) · 615

4 - dbgUpdatedCell The cell contents have been modified by the user but not yet written to the
database. This condition is also set when cell contents have been modified
in code with the Text or Value properties.
8 - dbgSelectedRow The cell is part of a row selected by the user or in code. The SelBookmarks
collection contains a bookmark for each selected row.
0 - dbgNormalCell The cell satisfies none of these conditions.
-1 - dbgAllCells All cells satisfy this condition.
You can add the first four values together to specify multiple cell conditions. For example, a cell status
value of 9 (dbgCurrentCell + dbgSelectedRow) denotes a current cell within a selected row. You
can also use a cell status value of 0 (dbgNormalCell) to refer to only those cells without any of the four
basic cell conditions. To designate that a cell condition should apply to all cells regardless of status, use a
cell status value of -1 (dbgAllCells).
The regex argument is a regular expression string that describes the pattern matching to be performed on
cell contents. The regular expressions supported by True DBGrid are a subset of standard Unix regular
expression syntax and are not compatible with the Visual Basic Like operator. The following special
characters are supported:
p* Any pattern followed by an asterisk matches zero or more occurrences of
that pattern. For example, ab*c matches ac, abc, and abbcy (partial match).
p+ Any pattern followed by a plus sign matches one or more occurrences of that
pattern. For example, ab+c matches abc and abbcy, but not ac.
[list] A list of case-sensitive characters enclosed in brackets matches any one of
those characters in the given position in the string. Character ranges can be
used, as in [abcd], which is equivalent to [a-d]. Multiple ranges can also be
used. For example, [A-Za-z0-9] matches any letter or digit. Bracketed
patterns can also be combined with either the * or + operators. The pattern
[A-Z]+ matches a sequence of one or more uppercase letters.
[^list] If a list starts with a caret, it matches any character except those specified in
the list.
. (period) A period represents any single character.
^p A caret at the beginning of a pattern forces a match to occur at the start of a
cell. Otherwise, the pattern can match anywhere within a cell.
p$ A dollar sign at the end of a pattern forces a match to occur at the end of a
cell. Otherwise, the pattern can match anywhere within a cell.
\c Any character preceded by a backslash represents itself, unless enclosed in
brackets, in which case the backslash is interpreted literally.
Any other character represents itself and will be compared with respect to case.
The style argument specifies the attributes that will override the default font and color characteristics for
cells within an object. For example, the following code causes normal cells containing the letters "SQL" to
be displayed in bold:
Dim S As New TrueDBGrid60.Style
S.Font.Bold = True
TDBGrid1.AddRegexCellStyle dbgNormalCell, S, "SQL"
616 · Object Reference

Each time the AddRegexCellStyle method is invoked, the specified cell condition is added to the list of
existing conditions. Hence, by repeated use of this method it is possible to set up multiple conditions to
affect the appearance of a grid, column, or split.
Note
If a cell condition already exists for a particular pair of condition and regex values, the new style setting
replaces the existing one.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

CaptureImage Method (TDBDropDown)

This method returns an image of the grid in a format that you can assign to the Picture property of a
Visual Basic form or control, or the PaintPicture method of the Printer object.
Syntax
object.CaptureImage
Arguments
None
Return Value
A picture object containing a snapshot of the control's display.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ClearCellStyle Method (TDBDropDown)

The ClearCellStyle method removes a cell condition established with a previous call to the AddCellStyle
method for the object in question. If no such cell condition exists, then calling this method has no effect.
Syntax
object.ClearCellStyle condition
Arguments
condition is a combination of one or more CellStyleConstants.
Return Value
None
Remarks
If the condition argument is -1 (dbgAllCells), then all non-regex cell conditions are removed, regardless
of status.
 ClearFields Method (TDBDropDown) · 617

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

ClearFields Method (TDBDropDown)

The ClearFields method restores the default grid layout (with two blank columns) so that subsequent
ReBind operations will automatically derive new column bindings from the (possibly changed) data
source.
Syntax
object.ClearFields
Arguments
None
Return Value
None
Remarks
You can cancel the grid's automatic layout behavior by invoking the HoldFields method.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ClearRegexCellStyle Method (TDBDropDown)

The ClearRegexCellStyle method removes a cell condition established with a previous call to the
AddRegexCellStyle method for the object in question.
Syntax
object.ClearRegexCellStyle condition, [regex]
Arguments
condition is a combination of one or more CellStyleConstants.
regex is an optional regular expression string.
Return Value
None
Remarks
If no such cell condition exists, then calling this method has no effect.
618 · Object Reference

If regex is omitted, then all cell conditions for any regular expression matching the condition argument are
removed. If condition is -1 (dbgAllCells), then all regex cell conditions are removed, regardless of status
or expression.
If regex is supplied, then the single cell condition matching both arguments is removed. However, if
condition is -1 (dbgAllCells), then all cell conditions for the specified regular expression are removed,
regardless of status.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
Split Object (page 122)

ClearSelCols Method (TDBDropDown)

The ClearSelCols method deselects all columns in a split. If no columns are selected, then this method
does nothing.
Syntax
object.ClearSelCols
Arguments
None
Return Value
None
Remarks
If a grid contains multiple splits, then invoking its ClearSelCols method has the same effect as invoking
the ClearSelCols method for the current split. The index of the current split is available through the
TDBGrid control's Split property.
Use the SelStartCol and SelEndCol properties to determine the current column selection range for a
split.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Split Object (page 122)

ColContaining Method (TDBDropDown)

The ColContaining method returns the ColIndex value of the grid column containing the specified
coordinate. This value ranges from 0 to Columns.Count - 1.
Syntax
object.ColContaining (coordinate)
 GetBookmark Method (TDBDropDown) · 619

Arguments
coordinate is a single that defines a horizontal coordinate (X value) in twips.
Return Value
An integer corresponding to the index of the column beneath the specified X coordinate.
Remarks
This method is useful when working with mouse and drag events when you are trying to determine
where the user clicked or dropped another control in terms of a grid column.
If coordinate is outside of the grid's data area, this method returns -1.
The ColContaining method returns the ColIndex of the column indicated, not the visible column
position. For example, if coordinate falls within the first visible column, but two columns have been
scrolled off the left side of the control, the ColContaining method returns 2, not 0 (assuming that the user
did not move any columns previously).
Note
You must convert the coordinate argument to twips, even if the container's ScaleMode (Visual Basic)
setting specifies a different unit of measurement.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

GetBookmark Method (TDBDropDown)

The GetBookmark method returns a bookmark for a row relative to the current row, which need not be
visible.
Syntax
object.GetBookmark (offset)
Arguments
offset is a long integer that defines the target row relative to the current row.
Return Value
A variant containing a bookmark relative to the current row as specified by offset.
Remarks
If offset is 0, this method returns the bookmark of the current row. The value returned will be the same as
that returned by the Bookmark property.
If offset is 1, this method returns the bookmark of the row following the current row. Similarly, if offset is -
1, this method returns the bookmark of the row preceding the current row.
If offset is an arbitrary integer N, this method returns the bookmark of the Nth row following the current
row if N is positive, or preceding the current row if N is negative.
If offset targets a row after the last available record or before the first available record, then this method
returns Null.
620 · Object Reference

Note
Do not confuse the GetBookmark method with the RowBookmark method, which can only return
bookmarks for visible rows.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

HoldFields Method (TDBDropDown)

The HoldFields method sets the current column/field layout as the customized layout so that subsequent
ReBind operations will use the current layout for display.
Syntax
object.HoldFields
Arguments
None
Return Value
None
Remarks
You can resume the grid's automatic layout behavior by invoking the ClearFields method.
The HoldFields method is especially useful in the unbound modes when you have specified the column
layout in code and would like to keep it intact after a ReBind operation.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

PostMsg Method (TDBDropDown)

The PostMsg method is used in conjunction with the PostEvent event to postpone operations which are
illegal within the grid's events.
Syntax
object.PostMsg MsgId
Arguments
MsgId is an integer that identifies the message being posted.
Return Value
None
Remarks
If the PostMsg method is called, the grid will fire the PostEvent event with the MsgId of the
corresponding PostMsg invocation after all pending operations are completed. You can then safely
perform all desired operations in the PostEvent event.
 ReBind Method (TDBDropDown) · 621

For example, it is not possible to perform the Data control's Refresh method within the grid's
AfterUpdate event because database operations are still pending, and the refresh cannot be tolerated.
Instead of performing the refresh in the AfterUpdate event, you can call the PostMsg method (with a
MsgId value of 1, for instance). After all pending database operations are completed, the grid will fire the
PostEvent event. You can then perform the refresh operation safely in this event, after confirming that the
MsgId argument passed in is 1.
You can use any non-zero integral value for MsgId, which will be passed to the PostEvent event for
identification purposes.
The special case where MsgId is zero is used to clear any pending PostMsg invocations which have not
yet been processed. A PostEvent event will fire for this case.
Note
Take care to avoid recursive situations when using PostMsg and PostEvent.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ReBind Method (TDBDropDown)

This method re-establishes the connection with the bound data source, causing the control to perform the
same operations that occur when you set the DataSource property at design time.
Syntax
object.ReBind
Arguments
None
Return Value
None
Remarks
If you have not modified the grid columns at design time, then executing the ReBind method will reset
the columns, headings, and other properties based on the current data source.
However, if you have altered the columns in any way at design time (even if you leave the DataField
properties blank), then the grid will assume that you wish to maintain the modified grid layout and will
not automatically reset the columns.
For an unbound grid with its DataMode property set to 2 - Unbound Extended or 3 - Application, this
method discards all data and fires the UnboundReadDataEx or ClassicRead event to refill the grid with
records from the unbound data source. After the grid has finished refilling its cache, it fires the
FirstRowChange and RowColChange events.
For backward compatibility with earlier versions, the semantics of the Refresh and ReBind methods are
reversed in DataMode 1 - Unbound. The ReBind method attempts to restore the current and topmost
rows, but the Refresh method does not.
622 · Object Reference

Note
To force the grid to reset the column bindings even if the columns were modified at design time, invoke
the ClearFields method immediately before ReBind. Conversely, to cancel the grid's automatic layout
response and force the grid to use the current column/field layout, invoke the HoldFields method
immediately before ReBind.
The HoldFields method is especially useful in the unbound modes when you have specified the column
layout in code and would like to keep it intact after a ReBind operation.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Refresh Method (TDBDropDown)

For a TDBGrid or TDBDropDown control, the Refresh method discards all data and repopulates all
cells from a data source control and/or unbound events.
Syntax
object.Refresh
Arguments
None
Return Value
None
Remarks
It also repaints the control's visible cells, firing all events necessary for redisplay.
When a control is refreshed, it attempts to restore the current and topmost rows. This behavior differs
from the intrinsic Data control's Refresh method, which makes the first available row both current and
topmost.
For backward compatibility with earlier versions, the semantics of the Refresh and ReBind methods are
reversed in DataMode 1 - Unbound. The ReBind method attempts to restore the current and topmost
rows, but the Refresh method does not.
For a Column object, the Refresh method repaints the entire column. Normally, the grid repaints
automatically as needed. However, if you have written handlers for the Paint or OwnerDrawCell events,
you can use this method to force a column to be repainted and hence cause the appropriate events to fire.
Note
If the grid's data source has been disconnected with the Close method, calling Refresh will implicitly
ReOpen the data source and set the current row to the first available row.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
Column Object (page 119)
 RowBookmark Method (TDBDropDown) · 623

RowBookmark Method (TDBDropDown)

The RowBookmark method returns a bookmark for a visible row relative to the first displayed row.
Syntax
object.RowBookmark (rownumber)
Arguments
rownumber is an integer denoting a displayed row.
Return Value
A variant containing a bookmark corresponding to the display row specified by rownumber.
Remarks
If rownumber is 0, this method returns the bookmark of the first displayed row. The value returned will be
the same as that returned by the FirstRow property.
Allowable values for the rownumber argument range from 0 to VisibleRows - 1.
This method only returns the current row (as determined by the grid's Bookmark property) if the current
row is visible and the rownumber argument is equal to the grid's Row property.
Note
Do not confuse the RowBookmark method with the GetBookmark method, which returns a bookmark
relative to the current row, even if the row is not visible.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowContaining Method (TDBDropDown)

The RowContaining method returns the zero-based index of the display row containing the specified
coordinate.
Syntax
object.RowContaining (coordinate)
Arguments
coordinate is a single that defines a vertical coordinate (Y value) in twips.
Return Value
An integer corresponding to the display row beneath the specified Y coordinate.
Remarks
This value ranges from 0 to VisibleRows - 1.
When handling mouse and drag events, this method is useful when you need to determine where the
user clicked or dropped another control in terms of a grid row.
If coordinate is outside of the grid's data area, this method returns -1.
624 · Object Reference

Note
You must convert the coordinate argument to twips, even if the container's ScaleMode (Visual Basic)
setting specifies a different unit of measurement.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowTop Method (TDBDropDown)

The RowTop method returns the Y coordinate of the top of a visible row relative to the top of the grid, as
given by the grid's Top property.
Syntax
object.RowTop (rownumber)
Arguments
rownumber is an integer denoting a displayed row.
Return Value
A single corresponding to the Y position of the specified display row, based on the coordinate system of
the grid's container.
Remarks
Allowable values for the rownumber argument range from 0 to VisibleRows - 1.
Use the RowTop method in conjunction with RowHeight, Left, and Width to determine the size and
placement of controls displayed on top of a grid cell.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Scroll Method (TDBDropDown)

This method scrolls the grid horizontally and vertically in a single operation.
Syntax
object.Scroll coloffset, rowoffset
Arguments
coloffset is a long integer denoting the number of columns to scroll and the direction in which to scroll
them.
rowoffset is a long integer denoting the number of rows to scroll and the direction in which to scroll them.
Return Value
None
 ClassicRead Event (TDBDropDown) · 625

Remarks
Positive offsets scroll right and down. Negative offsets scroll left and up. Column offsets that are out of
range cause a trappable error. Row offsets that are out of range scroll to the beginning or end of the
database.
The same effect can be achieved by setting the LeftCol and FirstRow properties, but these must be set
independently.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

TDBDropDown Events
ClassicRead Event (TDBDropDown)
The ClassicRead event is fired when an unbound grid (one with its DataMode property set to 3) needs to
display the value of a cell as specified by the Bookmark and CoI arguments.
Syntax
object_ClassicRead (Bookmark As Variant, ByVal Col As Integer, Value As Variant)
Arguments
Bookmark is a variant that identifies the row being requested.
Col is an integer that identifies the column being requested.
Value is a variant used to transfer unbound column data to the grid.
Remarks
To return an unbound value to the grid, simply set the Value argument to the desired result. If you do not
assign a value, the cell will remain blank.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Click Event (TDBDropDown)

The Click event occurs when the user presses then releases a mouse button over the grid.
Syntax
object_Click ( )
Arguments
None
626 · Object Reference

Remarks
Clicking a grid also generates MouseDown and MouseUp events in addition to the Click event. The
order of events for both the TDBGrid and TDBDropDown controls is MouseDown, MouseUp, and
Click.
When the user clicks a noncurrent row, the Click event fires before the grid attempts to reposition to the
row that was clicked. If the attempt succeeds, the grid then fires the RowColChange (or RowChange)
event. For this reason, you should not use the Click event to perform operations that depend upon the
current row.
Note
You can use the PostMsg method and PostEvent event to defer processing until the row change has
completed.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ColMove Event (TDBDropDown)

The ColMove event occurs when the user has finished moving the selected columns. Your event
procedure can either accept the movement or cancel it altogether.
Syntax
object_ColMove (ByVal Position As Integer, Cancel As Integer)
Arguments
Position is an integer that specifies the target location of the selected columns.
Cancel is an integer that may be set to True to prohibit movement.
Remarks
The Position argument ranges from 0, which denotes the left edge, to the total number of columns, which
denotes the right edge.
To determine which columns are being moved, examine the SelStartCol and SelEndCol properties.
If you set the Cancel argument to True, no movement occurs. Selected columns always remain selected,
regardless of the Cancel setting.
Note
This event is only fired when the user moves the selected columns to a new location.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ColResize Event (TDBDropDown)

The ColResize event occurs after the user has finished resizing a column, but before columns to the right
are repositioned.
 DataSourceChanged Event (TDBDropDown) · 627

Syntax
object_ColResize (ByVal ColIndex As Integer, Cancel As Integer)
Arguments
ColIndex is an integer that identifies the column that was resized.
Cancel is an integer that may be set to True to undo resizing.
Remarks
Your event procedure can accept the change, alter the degree of change, or cancel the change completely.
If you set the Cancel argument to True, the previous column width is restored and no repainting occurs.
To alter the degree of change, set the Width property of the Column object specified by the ColIndex
argument to the desired value.
It is not necessary to execute the Refresh method within this event procedure. Doing so causes the grid to
be repainted even if the Cancel argument is True.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DataSourceChanged Event (TDBDropDown)

The DataSourceChanged event occurs when a bound data source is changed or requeried. This event
also fires when a bound grid control is first loaded.
Syntax
object_DataSourceChanged ( )
Arguments
None
Remarks
The DataSourceChanged event fires before the grid is filled with data. Therefore, you can use this event
to initialize the grid according to information obtained from the data source, if necessary.
This event does not fire in unbound or storage modes.
Note
With the OLE DB version of True DBGrid, you can use the DataSourceChanged event in conjunction
with the BookmarkType property to circumvent type mismatch errors that may occur when a grid-
supplied bookmark is passed to an ADO Recordset object (or vice versa). The workaround is as follows:
Sub TDBGrid1_DataSourceChanged()
TDBGrid1.BookmarkType = VarType(ADODC1.Recordset.Bookmark)
End Sub
This code ensures that any bookmarks returned by the grid are first converted to the appropriate type for
the bound data source. This workaround is only needed when using the grid in an HTML page; it is not
needed for Visual Basic 6.0.
628 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DblClick Event (TDBDropDown)

The DblClick event occurs when the user presses then releases a mouse button twice in rapid succession
over the grid.
Syntax
object_DblClick ( )
Arguments
None
Remarks
Double clicking a grid also generates MouseDown, MouseUp, and Click events in addition to the
DblClick event. The order of events for the TDBGrid control is MouseDown, MouseUp, Click,
DblClick, and MouseUp.
Note
When the MarqueeStyle property of a TDBGrid control is set to the default value of 6 - Floating Editor,
the DblClick event will not fire when the user double-clicks a noncurrent cell within the grid. This is
because the first click is used by the floating editor to begin editing, placing the cell into edit mode at the
character on which the click occurred. Double-clicking the current cell of the grid fires the DblClick event
normally, however.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

DropDownClose Event
The DropDownClose event is triggered when a TDBDropDown control is closed.
Syntax
TDBDropDown_DropDownClose ( )
Arguments
None
Remarks
The DropDownClose event is triggered when a TDBDropDown control is closed, which occurs when:
• The user selects an item from the dropdown.
• The user clicks the current cell's built-in button.
• The user presses ALT+DOWN ARROW.
• The dropdown loses focus.
 DropDownOpen Event · 629

The built-in button is enabled for a column when its DropDown property is set to the name of a valid
TDBDropDown control.
See Also
TDBDropDown Control (page 118)

DropDownOpen Event
The DropDownOpen event is triggered when a TDBDropDown control is opened.
Syntax
TDBDropDown_DropDownOpen ( )
Arguments
None
Remarks
The DropDownOpen event is triggered when a TDBDropDown control is opened, which occurs when:
• The user clicks the current cell's built-in button.
• The user presses ALT+DOWN ARROW.
The built-in button is enabled for a column when its DropDown property is set to the name of a valid
TDBDropDown control.
See Also
TDBDropDown Control (page 118)

Error Event (TDBDropDown)

The Error event occurs only as the result of a data access error that takes place when no Visual Basic code
is being executed.
Syntax
object_Error (DataError As Integer, Response As Integer)
Arguments
DataError is an integer that identifies the error that occurred.
Response is an integer that may be set to 0 to suppress error message display.
Remarks
Even if your application handles run time errors in code, errors can still occur when none of your code is
executing, as when the user clicks a Data control button or changes the current record by interacting with
a bound control. If a data access error results from such an action, the Error event is fired.
If you set the Response argument to 0, no error message will be displayed.
If the Response argument retains its default value of 1, or if you do not code an event procedure for the
Error event, the message associated with the error will be displayed.
Note
Use the ErrorText property to retrieve the error string that will be displayed.
630 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FetchCellStyle Event (TDBDropDown)

The FetchCellStyle event occurs when the grid is about to display cell data in a column whose FetchStyle
property is set to dbgFetchCellStyleColumn or dbgFetchCellStyleAddNewColumn.
Syntax
TDBGrid_FetchCellStyle (ByVal Condition As Integer, ByVal Split As Integer, Bookmark As Variant, ByVal Col
As Integer, ByVal CellStyle As TrueDBGrid80.StyleDisp)
TDBDropDown_FetchCellStyle (ByVal Condition As Integer, Bookmark As Variant, ByVal Col As Integer,
ByVal CellStyle As TrueDBGrid80.StyleDisp)
Arguments
Condition is the sum of one or more CellStyleConstants describing the disposition of the cell being
displayed.
Split is an integer that identifies the split containing the cell being displayed. This argument is omitted for
TDBDropDown controls.
Bookmark is a variant that identifies the row containing the cell being displayed.
Col is an integer that identifies the column containing the cell being displayed.
CellStyle is a Style object used to override the font and color characteristics of the cell being displayed.
Remarks
By setting one or more properties of the Style object passed in the CellStyle parameter, your application
can change the appearance of individual cells.
You can also set the ForegroundPicture property of the CellStyle parameter to display distinct bitmaps on
a per-cell basis.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FetchRowStyle Event (TDBDropDown)

The FetchRowStyle event is fired whenever the grid is about to display a row of data, but only if the
FetchRowStyle property is True for the grid or one of its splits.
Syntax
TDBGrid_FetchRowStyle (ByVal Split As Integer, Bookmark As Variant, ByVal RowStyle As
TrueDBGrid80.StyleDisp)
TDBDropDown_FetchRowStyle (Bookmark As Variant, ByVal RowStyle As TrueDBGrid80.StyleDisp)
 FetchScrollTips Event (TDBDropDown) · 631

Arguments
Split is the zero-based index of the split for which formatting information is being requested. This
argument is omitted for TDBDropDown controls.
Bookmark is a variant that uniquely identifies the row to be displayed.
RowStyle is a Style object used to convey font and color information to the grid.
Remarks
Use the FetchRowStyle event to control formatting on a per-row basis, as it is much more efficient than
coding the FetchCellStyle event to apply the same formatting to all columns.
Note
A common application of row-based formatting is to present rows in alternating colors to enhance their
readability. Although you could use the FetchRowStyle event to achieve this effect, the
AlternatingRowStyle property is easier to use, as it requires no coding.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FetchScrollTips Event (TDBDropDown)

If the ScrollTips property is True, the FetchScrollTips event will be fired whenever the grid has focus
and the scrollbar thumb is moved using the mouse.
Syntax
TDBGrid_FetchScrollTips (ByVal SplitIndex As Integer, ByVal ColIndex as Integer, Bookmark As Variant,
ByVal ScrollBar as ScrollBarsConstants, ScrollTip As String, ByVal TipStyle As TrueOleDBGrid80.StyleDisp)
TDBDropDown_FetchScrollTips (ByVal ColIndex as Integer, Bookmark As Variant, ByVal ScrollBar as
ScrollBarsConstants, ScrollTip As String, ByVal TipStyle As TrueOleDBGrid80.StyleDisp)
Arguments
SplitIndex is the zero-based index of the split that the scrollbar is associated with. This argument is
omitted for TDBDropDown controls.
ColIndex is the leftmost column in the current split.
Bookmark is a variant that uniquely identifies the topmost grid row.
ScrollBar identifies the scrollbar that was moved (dbgVertical or dbgHorizontal).
ScrollTip contains the text to be displayed in the pop-up text box.
TipStyle is a Style object used to override the font and color characteristics of the scroll tip text.
Description
By setting the properties of the TipStyle object, you can control the background color, text color, and font
of the pop-up text box. By default, the TipStyle object uses the system ToolTip colors and the font
attributes of the current split.
632 · Object Reference

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FirstRowChange Event (TDBDropDown)

The FirstRowChange event occurs when the first displayed row of a control or split is changed.
Syntax
TDBGrid_FirstRowChange (ByVal SplitIndex As Integer)
TDBDropDown_FirstRowChange ( )
Arguments
SplitIndex is the zero-based index of the split in which the row change occurred. This argument is omitted
for TDBDropDown controls.
Remarks
This event is triggered under several circumstances:
• When the grid is first displayed.
• When the user scrolls through the grid with the vertical scroll bar or navigation keys.
• When data in the grid is changed in a way that implicitly affects the first row, such as when the
first displayed record is deleted.
• When the FirstRow property is changed in code to a different value.
When multiple cell change events are sent, the order will be SplitChange, FirstRowChange,
LeftColChange, and RowColChange. None of these events will be sent until any modified data has been
validated with the BeforeColUpdate event.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FootClick Event (TDBDropDown)

The FootClick event occurs when the user clicks on the footer for a particular grid column.
Syntax
object_FootClick (ByVal ColIndex As Integer)
Event applies to TDBGrid and TDBDropDown controls.
Arguments
ColIndex is an integer that identifies the column footer that was clicked.
Remarks
One possible action for this event is to re-sort the Recordset object based on the selected column.
 FormatText Event (TDBDropDown) · 633

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

FormatText Event (TDBDropDown)

The FormatText event occurs when the grid is about to display cell data in a column whose
NumberFormat property is set to the string FormatText Event.
Syntax
object_FormatText (ByVal ColIndex As Integer, Value As Variant, Bookmark As Variant)
Arguments
ColIndex is an integer that identifies the column being displayed.
Value is a variant containing the underlying data value.
Bookmark is a variant that uniquely identifies the row from which the underlying data value was
obtained.
Remarks
The Value argument contains the underlying data value and also serves as a placeholder for the formatted
data to be displayed.
This event allows you to provide your own text formatting for cases where Visual Basic's intrinsic
formatting is either unavailable or does not suit your needs.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

HeadClick Event (TDBDropDown)

The HeadClick event occurs when the user clicks on the header for a particular grid column.
Syntax
object_HeadClick (ByVal ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column header that was clicked.
Remarks
One possible action for this event is to re-sort the Recordset object based on the selected column.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
634 · Object Reference

KeyDown Event (TDBDropDown)

The KeyDown event occurs when the user presses a key.
Syntax
object_KeyDown (KeyCode As Integer, Shift As Integer)
Arguments
KeyCode is an integer or constant representing a Windows key code. For example, the Visual Basic object
library provides the constants vbKeyF1 (the F1 key) and vbKeyHome (the HOME key).
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys at the time of the event.
The Shift argument is a bit field with the least-significant bits corresponding to the SHIFT key (bit 0), the
CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively.
Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For
example, if both CTRL and ALT are pressed, the value of Shift is 6.
Remarks
Although this event is fired for most keystrokes, it is most often used for:
• Extended character keys such as function keys.
• Navigation keys.
• Combinations of keys with standard keyboard modifiers.
• Distinguishing between the numeric keypad and regular number keys.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

KeyPress Event (TDBDropDown)

Occurs when an ANSI key is pressed and released.
Syntax
object_KeyPress (KeyAscii As Integer)
Arguments
KeyAscii is an integer representing an ANSI key code. KeyAscii is passed by reference; changing it sends a
different character to the grid. Changing KeyAscii to 0 cancels the keystroke so the grid receives no
character.
Remarks
The KeyPress event occurs when the user presses and releases one of the following kinds of keys:
• A printable keyboard character.
• The CTRL key combined with an alphabetic or special character.
• The ENTER or BACKSPACE key.
Use the KeyPress event to test keystrokes for validity or to format characters as they are typed.
 KeyUp Event (TDBDropDown) · 635

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

KeyUp Event (TDBDropDown)

The KeyUp event occurs when the user releases a key.
Syntax
object_KeyUp (KeyCode As Integer, Shift As Integer)
Arguments
KeyCode is an integer or constant representing a Windows key code. For example, the Visual Basic object
library provides the constants vbKeyF1 (the F1 key) and vbKeyHome (the HOME key).
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys at the time of the event.
The Shift argument is a bit field with the least-significant bits corresponding to the SHIFT key (bit 0), the
CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively.
Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For
example, if both CTRL and ALT are pressed, the value of Shift is 6.
Remarks
Although this event is fired for most keystrokes, it is most often used for:
• Extended character keys such as function keys.
• Navigation keys.
• Combinations of keys with standard keyboard modifiers.
• Distinguishing between the numeric keypad and regular number keys.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

LayoutReady Event (TDBDropDown)

The LayoutReady event fires when asynchronous downloading of a grid layout file has completed.
Syntax
object_LayoutReady ( )
Arguments
None
Remarks
The location of the layout file is determined by the LayoutURL property.
If you set the LayoutURL property to a nonempty string at design time (and LayoutFileName is empty),
the grid initiates asynchronous downloading at run time after it has been loaded. You can also initiate
636 · Object Reference

downloading by setting the LayoutURL property in code. This technique is particularly useful for
initializing a grid on an HTML page.
In either case, the grid fires the LayoutReady event when the download operation has completed. You
should write a handler for this event that loads the desired layout as follows:
TDBGrid1.LayoutName = "MyLayout"
TDBGrid1.LoadLayout
Note
You can create grid layout files at design time by setting the LayoutFileName and LayoutName
properties and using the layout commands on the grid's visual editing menu.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

LeftColChange Event (TDBDropDown)

The LeftColChange event occurs when the first visible column of a grid or split is changed.
Syntax
TDBGrid_LeftColChange (ByVal SplitIndex As Integer)
TDBDropDown_LeftColChange ( )
Arguments
SplitIndex is the zero-based index of the split in which the column change occurred. This argument is
omitted for TDBDropDown controls.
Remarks
This event is triggered under several circumstances:
• When the grid is first displayed.
• When the user scrolls through the grid with the horizontal scroll bar or navigation keys.
• When the LeftCol property is changed in code to a different value.
• When the Visible property of the current left column is set to False.
• When the Width property of the current left column is set to 0.
• When the user resizes the current left column so that it is no longer visible.
• When the user moves the current left column or moves another column into its place.
When multiple cell change events are sent, the order will be SplitChange, FirstRowChange,
LeftColChange, and RowColChange. None of these events will be sent until any modified data has been
validated with the BeforeColUpdate event.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
 MouseDown Event (TDBDropDown) · 637

MouseDown Event (TDBDropDown)

Use a MouseDown event procedure to specify actions that will occur when a given mouse button is
pressed.
Syntax
object_MouseDown (Button As Integer, Shift As Integer, X As Single, Y As Single)
Arguments
Button is an integer that identifies the button that was pressed or released to cause the event. The Button
argument is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle
button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set,
indicating the button that caused the event.
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys when the button specified
in the Button argument is pressed or released. A bit is set if the key is down. The Shift argument is a bit
field with the least-significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT
key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can
be set, indicating that some, all, or none of the keys are pressed. For example, if both CTRL and ALT are
pressed, the value of Shift is 6.
X and Y are single-precision numbers that specify the current location of the mouse pointer. They are
always expressed in terms of the coordinate system of the grid's container.
Remarks
Unlike the Click and DblClick events, MouseDown and MouseUp events enable you to distinguish
between the left, right, and middle mouse buttons. You can also write code for mouse/keyboard
combinations that use the SHIFT, CTRL, and ALT keyboard modifiers.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

MouseMove Event (TDBDropDown)

The MouseMove event is generated continually as the mouse pointer moves across the grid.
Syntax
object_MouseMove (Button As Integer, Shift As Integer, X As Single, Y As Single)
Arguments
Button is an integer that corresponds to the state of the mouse buttons in which a bit is set if the button is
down. The Button argument is a bit field with bits corresponding to the left button (bit 0), right button (bit
1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. The Button
argument indicates the complete state of the mouse buttons; some, all, or none of these three bits can be
set, indicating that some, all, or none of the buttons are pressed.
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys. A bit is set if the key is
down. The Shift argument is a bit field with the least-significant bits corresponding to the SHIFT key (bit
0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4,
respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are
pressed. For example, if both CTRL and ALT are pressed, the value of Shift is 6.
638 · Object Reference

X and Y are single-precision numbers that specify the current location of the mouse pointer. They are
always expressed in terms of the coordinate system of the grid's container.
Remarks
This event is primarily useful for implementing drag-and-drop behavior on a per-column basis.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

MouseUp Event (TDBDropDown)

Use a MouseUp event procedure to specify actions that will occur when a given mouse button is
released.
Syntax
object_MouseUp (Button As Integer, Shift As Integer, X As Single, Y As Single)
Arguments
Button is an integer that identifies the button that was pressed or released to cause the event. The Button
argument is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle
button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set,
indicating the button that caused the event.
Shift is an integer that corresponds to the state of the SHIFT, CTRL, and ALT keys when the button specified
in the Button argument is pressed or released. A bit is set if the key is down. The Shift argument is a bit
field with the least-significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT
key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can
be set, indicating that some, all, or none of the keys are pressed. For example, if both CTRL and ALT are
pressed, the value of Shift is 6.
X and Y are single-precision numbers that specify the current location of the mouse pointer. They are
always expressed in terms of the coordinate system of the grid's container.
Remarks
Unlike the Click and DblClick events, MouseDown and MouseUp events enable you to distinguish
between the left, right, and middle mouse buttons. You can also write code for mouse/keyboard
combinations that use the SHIFT, CTRL, and ALT keyboard modifiers.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Paint Event (TDBDropDown)

The Paint event is triggered whenever the grid repaints itself (that is, whenever it receives a WM_PAINT
message).
Syntax
object_Paint ( )
 PostEvent Event (TDBDropDown) · 639

Arguments
None
Remarks
This occurs frequently in the Windows environment and is generally useful only for special
circumstances. In this event, programmers familiar with the Windows API may use the grid's hWnd
property to paint special effects such as lines, bitmaps, and icons in appropriate cells of the grid.
Note
This event is included for backward compatibility with earlier versions of True DBGrid. New
applications should use the OwnerDrawCell event to draw directly into the grid's device context.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

PostEvent Event (TDBDropDown)

The PostEvent event is used in conjunction with the PostMsg method to postpone operations that are
illegal within the grid's events.
Syntax
object_PostEvent (ByVal MsgId As Integer)
Arguments
MsgId is an integer that identifies the message posted by the PostMsg method.
Remarks
If the PostMsg method is called, the grid will fire the PostEvent event with the MsgId of the
corresponding PostMsg invocation after all pending operations are completed. You can then safely
perform all desired operations in the PostEvent event.
For example, it is not possible to perform the Data control's Refresh method within the grid's
AfterUpdate event because database operations are still pending, and the refresh cannot be tolerated.
Instead of performing the refresh in the AfterUpdate event, you can call the PostMsg method (with a
MsgId value of 1, for instance). After all pending database operations are completed, the grid will fire the
PostEvent event. You can then perform the refresh operation safely in this event, after confirming that the
MsgId argument passed in is 1.
The special case where MsgId is zero is used to clear any pending PostMsg invocations that have not yet
been processed. A PostEvent event will fire for this case.
The following code illustrates a typical PostEvent handler:
Private Sub TDBGrid1_PostEvent(ByVal MsgId As Integer)
Select Case MsgId
Case 0
Exit Sub
Case 1
Data1.Refresh
Case 2
' Process other postponed operations
End Select
End Sub
640 · Object Reference

Note
Take care to avoid recursive situations when using PostMsg and PostEvent.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

RowChange Event
The RowChange event occurs when the current row changes to a different row.
Syntax
TDBDropDown_RowChange ( )
Arguments
None
Remarks
This event is triggered under several circumstances:
• When a dropdown is first displayed.
• When the user moves the current row by clicking on another row or using the navigation keys.
• During incremental searching.
The current row position is provided by the Bookmark property.
See Also
TDBDropDown Control (page 118)

RowResize Event (TDBDropDown)

The RowResize event occurs when the user has finished resizing a grid row.
Syntax
object_RowResize (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to undo resizing.
Remarks
Your event procedure can accept the change, alter the degree of change, or cancel the change completely.
The TDBGrid control's RowHeight property determines the height of all rows in the control.
If you set the Cancel argument to True, the previous row height is restored and no repainting occurs. To
alter the degree of change, set the RowHeight property to the desired value.
It is not necessary to execute the Refresh method within this event procedure. Doing so causes the grid to
be repainted even if the Cancel argument is True.
 Scroll Event (TDBDropDown) · 641

See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

Scroll Event (TDBDropDown)

The Scroll event occurs when the user scrolls the grid horizontally or vertically using the scroll bars.
Syntax
object_Scroll (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to prevent the scroll operation from occurring.
Remarks
This event is fired before the grid is repainted to display the results of the scroll operation. If you set the
Cancel argument to True, the scroll operation fails and no repainting occurs.
It is not necessary to execute the Refresh method within this event procedure. Doing so causes the grid to
be repainted even if the Cancel argument is True.
You can use this event to perform calculations or to manipulate controls that must be coordinated with
ongoing changes in the grid's scroll bars.
Note
Within this event procedure, the values of the FirstRow and LeftCol properties are not updated to reflect
the pending scroll operation. You cannot determine the orientation or magnitude of the pending scroll
operation by examining these properties.
Avoid using a MsgBox (Visual Basic) statement or function in this event.
This event only fires when the user operates the scroll bars; it will not fire in response to keyboard
navigation, data control notifications, or code.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

SelChange Event (TDBDropDown)

The SelChange event occurs when the user selects a different range of rows or columns.
Syntax
object_SelChange (Cancel As Integer)
Arguments
Cancel is an integer that may be set to True to undo the new selection.
Remarks
This event is triggered under several circumstances:
• When the user selects a single row by clicking its record selector.
642 · Object Reference

• When the user adds a row to the list of selected rows by clicking its record selector while holding
down the CTRL key.
• When the user selects a single column by clicking its header.
• When the user changes the range of selected columns by dragging to an adjacent column within
the header row.
• When the user extends the range of selected columns by holding down the SHIFT key and clicking
an unselected column header.
• When the user clears the current row or column selection by clicking an individual cell, in which
case this event precedes RowColChange.
The current range of selected columns is provided by the SelStartCol and SelEndCol properties. The
bookmarks of the selected rows are available in the SelBookmarks collection. Within this event
procedure, these properties and collections reflect the user's pending selection(s).
If your event procedure sets the Cancel argument to True, the previous row and column selections (if any)
are restored, and the aforementioned properties revert to their previous values.
This event is only triggered by user interaction with the grid. It cannot be triggered by code.
Note
When the user selects a column, any row selections are cleared. Similarly, when the user selects a row,
any column selections are cleared.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

UnboundColumnFetch Event (TDBDropDown)

The UnboundColumnFetch event is fired when a bound grid (one with its DataMode property set to 0 -
Bound) needs to display the value of a cell in an unbound column as specified by the Bookmark and Col
arguments.
Syntax
TDBGrid_UnboundColumnFetch (Bookmark As Variant, Col As Integer, Value As Variant)
Arguments
Bookmark is a variant that identifies the row being requested.
Col is an integer that identifies the column being requested.
Value is a variant used to transfer unbound column data to the grid.
Remarks
For a bound grid, any column with an empty DataField property and a non-empty Caption property is
considered an unbound column.
To return an unbound value to the grid, simply set the Value argument to the desired result. If you do not
assign a value, the cell will remain blank.
 UnboundFindData Event · 643

Use this event to implement calculated fields based on other columns or to display local data alongside
remote bound data.
Your application is responsible for storing data entered into an unbound column by the user. Use the
Column object's Text property to retrieve unbound values within the BeforeUpdate and BeforeInsert
events.
If an unbound column is used to display a calculated result based on other columns, then you do not
need to store the unbound values since they can always be calculated "on the fly" using either the
Column object's Text property or data access objects.
Note
Do not confuse unbound columns with unbound mode. The UnboundColumnFetch event is only fired
when a bound grid contains one or more unbound columns.
During the execution of this event, row movement is not permitted.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

UnboundFindData Event
When a dropdown control is activated, it will attempt to position to the record that matches the current
cell text of its parent grid.
Syntax
TDBDropDown_UnboundFindData (StartLocation As Variant, ByVal ReadPriorRows As Boolean, ByVal
IncludeCurrent As Boolean, ByVal Col As Integer, ByVal Value As Variant, ByVal SeekFlags As Integer,
NewLocation As Variant)
Arguments
StartLocation is a bookmark that specifies the starting row for the search.
ReadPriorRows indicates the direction in which the dropdown is searching for data. If False, you should
provide data in the forward direction starting with the row specified by StartLocation. If True, you should
provide data in the backward direction, starting with the row specified by StartLocation.
IncludeCurrent indicates the inclusion of StartLocation in the search. If False, you should not use
StartLocation when searching for data. If True, StartLocation should be included in the search.
Col is a column index that specifies the data column for the search.
Value is the value to be searched for.
SeekFlags is an UnboundFindConstants value that provides additional information about how the search
should be performed.
The NewLocation argument is initially Null. However, before returning from this event, you should set it
to a bookmark that uniquely identifies the row where the data was found. If you do not set the value of
NewLocation, it is assumed that no values match and the dropdown will be positioned at the first row.
Remarks
To do this, the dropdown will fire the UnboundFindData event, which allows you to set the current
record position within the dropdown.
644 · Object Reference

The SeekFlags argument specifies how to compare the Value argument to dropdown column data:
dbgSeekLT Find first column data less than Value
dbgSeekLE Find first column data less than or equal to Value
dbgSeekEQ Find first column data equal to Value
dbgSeekGE Find first column data greater than or equal to Value
dbgSeekGT Find first column data greater than Value
dbgSeekPartialEQ Find first column data that partially matches Value starting from
the first character position
Note
This event will not fire when DataMode is set to 0 - Bound.
See Also
TDBDropDown Control (page 118)

UnboundGetRelativeBookmark Event (TDBDropDown)

Fired when the dropdown needs a relative bookmark.
Syntax
object_UnboundGetRelativeBookmark (StartLocation As Variant, ByVal Offset As Long, NewLocation As
Variant, ApproximatePosition As Long)
Arguments
StartLocation is a bookmark that, together with Offset, specifies the row to be returned in NewLocation. A
StartLocation of Null indicates a request for a row from BOF or EOF.
Offset specifies the relative position (from StartLocation) of the row to be returned in NewLocation. A
positive number indicates a forward relative position; a negative number indicates a backward relative
position.
NewLocation is a variable that receives the bookmark of the row specified by StartLocation plus Offset. If
the row specified is beyond the first or the last row (that is, beyond BOF or EOF), then NewLocation
should be set to Null.
ApproximatePosition is a variable that optionally receives the ordinal position of NewLocation. Setting this
variable will enhance the ability of the grid to display its vertical scroll bar accurately. If the exact ordinal
position of NewLocation is not known, you can set it to a reasonable, approximate value, or just ignore this
parameter.
Remarks
This event is mandatory when the DataMode property is set to 3 - Application. For DataMode 1 -
Unbound, this event is optional. It is not used when the DataMode property is set to 2 - Unbound Extended.
This event is used in conjunction with the UnboundReadData or ClassicRead events when the grid
needs to obtain positional information about your underlying data. By coding this event for DataMode
setting 1 - Unbound, you can dramatically improve the performance of the grid. However, you do not
need to change existing applications; you can ignore this event and they will continue to function
properly.
 UnboundReadData Event (TDBDropDown) · 645

Before returning from this event, you must set NewLocation to a valid bookmark. For example, if Offset is 1
(or -1), then you must return in NewLocation the bookmark of the row that follows (or precedes)
StartLocation. However, if the requested row is beyond the first or last row, then you should return Null in
NewLocation to inform the grid of BOF/EOF conditions.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

UnboundReadData Event (TDBDropDown)

The UnboundReadData event is fired when an unbound grid (one with its DataMode property set to 1 -
Unbound) requires data for display, such as when it is first loaded or the user scrolls the grid display.
Syntax
object_UnboundReadData (ByVal RowBuf As TrueDBGrid80.RowBuffer, StartLocation As Variant, ByVal
ReadPriorRows As Boolean)
Arguments
RowBuf is a RowBuffer object used to transfer row data to the grid.
StartLocation is a variant bookmark that identifies the row to position to before fetching the next or
previous page of records. If Null, the grid is requesting the first or last page of records as determined by
the ReadPriorRows argument.
ReadPriorRows is a boolean that determines the direction in which rows are to be fetched. If True, the grid
is requesting records that precede StartLocation. If False, the grid is requesting records that follow
StartLocation.
Remarks
The RowBuf argument acts like a two-dimensional array of variants corresponding to the grid cells being
fetched. By populating its Value property with the appropriate data, your event procedure transfers rows
from the unbound dataset to the grid.
Use the row buffer's RowCount property to determine how many rows of data the grid is requesting. Use
its ColumnCount property to determine the number of columns to be populated.
The RowBuf argument is also used to store a set of variant bookmarks that uniquely identify rows in the
unbound dataset. The format of these bookmarks is determined solely by your application. For example,
they may be primary key fields, row numbers, or array indexes, depending upon the nature of the
unbound dataset.
Your event procedure supplies bookmarks to the grid by populating the row buffer's Bookmark property
for each row returned. Keep in mind that the bookmarks you provide in the UnboundReadData event
may be subsequently passed to the UnboundWriteData and UnboundDeleteRow events depending on
how the user interacts with the grid. In addition, bookmark-based TDBGrid properties and methods
such as Bookmark, FirstRow, GetBookmark, and RowBookmark are also designed to work with these
unbound bookmarks.
It is not necessary to fill the row buffer completely, and it is in fact acceptable to return no rows at all. The
row buffer's RowCount property can be set to indicate that fewer rows were returned than requested.
The grid interprets this to mean that there are no more rows to retrieve in the indicated direction. Thus, it
is only necessary to fill the row buffer completely if there are more valid rows to be retrieved.
646 · Object Reference

Note
True DBGrid is very conservative in its assumptions about row counts and BOF/EOF conditions. As a
result, it may seem that the UnboundReadData event fires "too often." This should not be interpreted as
a sign of inefficiency, but rather as an assurance that an unbound grid performs accurately with large
multiuser databases.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

UnboundReadDataEx Event (TDBDropDown)

The UnboundReadDataEx event is fired when an unbound grid (one with its DataMode property set to 2
- Unbound Extended) requires a bookmark for a specific row or data for display, such as when it is first
loaded or the user scrolls the grid display.
Syntax
object_UnboundReadDataEx (ByVal RowBuf As TrueDBGrid80.RowBuffer, StartLocation As Variant, ByVal
Offset As Long, ApproximatePosition As Long)
Arguments
RowBuf is a RowBuffer object used to transfer row data to the grid.
StartLocation is a bookmark that, together with Offset, specifies the starting row for data transfer. A
StartLocation of Null indicates a request for data from BOF or EOF. For example, if StartLocation is Null
and Offset is 2 (or -2), then you should retrieve data starting from the second (or second to last) row.
Offset specifies the relative position (from StartLocation) of the first row of data to be transferred. A
positive number indicates a forward relative position; a negative number indicates a backward relative
position.
ApproximatePosition is a variable that optionally receives the ordinal position of the first row of data to be
transferred. Setting this variable will enhance the ability of the grid to display its vertical scroll bar
accurately. If the exact ordinal position of the row is not known, you can set it to a reasonable,
approximate value, or just ignore this parameter.
Remarks
Before returning from the UnboundReadDataEx event, you must fill the Bookmark array of RowBuf with
unique row identifiers, and the Value array with the actual data. For example, if Offset is 1 (or -1), then
you must fill in RowBuf, starting from the row that follows (or precedes) StartLocation.
The RowBuf argument acts like a two-dimensional array of variants corresponding to the grid cells being
fetched. By populating its Value property with the appropriate data, your event procedure transfers rows
from the unbound dataset to the grid.
Use the row buffer's RowCount property to determine how many rows of data the grid is requesting. Use
its ColumnCount property to determine the number of columns to be populated, if any. If ColumnCount
is zero, the grid is requesting the bookmark of a single row; if ColumnCount is nonzero, the grid is
requesting RowCount rows of data and their corresponding bookmarks.
The ColumnIndex property specifies the grid column index corresponding to a row buffer column index;
you must fill in the Value property array with column data according to the column index specified by
the ColumnIndex property array.
 ValueItemError Event (TDBDropDown) · 647

The RowBuf argument is also used to store a set of variant bookmarks that uniquely identify rows in the
unbound dataset. The format of these bookmarks is determined solely by your application. For example,
they may be primary key fields, row numbers, or array indexes, depending upon the nature of the
unbound dataset.
Your event procedure supplies bookmarks to the grid by populating the row buffer's Bookmark property
for each row returned. Keep in mind that the bookmarks you provide in the UnboundReadDataEx event
may be subsequently passed to the UnboundWriteData and UnboundDeleteRow events depending on
how the user interacts with the grid. In addition, bookmark-based TDBGrid properties and methods
such as Bookmark, FirstRow, GetBookmark, and RowBookmark are also designed to work with these
unbound bookmarks.
It is not necessary to fill the row buffer completely, and it is in fact acceptable to return no rows at all. The
row buffer's RowCount property can be set to indicate that fewer rows were returned than requested.
The grid interprets this to mean that there are no more rows to retrieve in the indicated direction. Thus, it
is only necessary to fill the row buffer completely if there are more valid rows to be retrieved.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)

ValueItemError Event (TDBDropDown)

The ValueItemError event is triggered when the user attempts to enter invalid data into a column that is
using value lists.
Syntax
object_ValueItemError (ColIndex As Integer)
Arguments
ColIndex is an integer that identifies the column being edited.
Remarks
This event is only triggered when the associated ValueItems collection has its Validate property set to
True.
This event is useful even if the user is permitted to enter values not present in the ValueItems collection,
as you may want to add the new value to the collection in this event. It also allows you to control how
you want to respond to incorrect input.
See Also
TDBGrid Control (page 118)
TDBDropDown Control (page 118)
 AddNewMode Constants · 649

Constant Reference
AddNewMode Constants
Applies To
AddNewMode Property (page 362)
Values
Design Time Run Time
0 - No AddNew pending dbgNoAddNew
1 - Current cell in AddNew row dbgAddNewCurrent
2 - AddNew pending dbgAddNewPending

Alignment Constants
Applies To
Alignment Property (page 363)
FooterAlignment Property (page 425)
HeadAlignment Property (page 431)
Values
Design Time Run Time
0 - Left dbgLeft
1 - Right dbgRight
2 - Center dbgCenter
3 - General (default) dbgGeneral

AnimateWindow Constants
Applies To
AnimateWindow Property (page 370)
Values
Design Time Run Time
0 - No Animate (default) dbgNoAnimate
1 - Roll dbgRoll
2 - Slide dbgSlide
3 - Blend dbgBlend
650 · Constant Reference

AnimateWindowClose Constants
Applies To
AnimateWindowClose Property (page 371)
Values
Design Time Run Time
0 - No Animate Close (default) dbgNoAnimateClose
1 - Opposite Direction dbgOppositeDirection
2 - Same Direction dbgSameDirection

AnimateWindowDirection Constants
Applies To
AnimateWindowDirection Property (page 372)
Values
Design Time Run Time
0 - Default dbgDefaultDirection
1 - Top To Bottom dbgTopToBottom
2 - Bottom To Top dbgBottomToTop
3 - Left To Right dbgLeftToRight
4 - Right To Left dbgRightToLeft
5 - Top Left To Bottom Right dbgTopLeftToBottomRight
6 - Top Right To Bottom Left dbgTopRightToBottomLeft
7 - Bottom Left To Right dbgBottomLeftToTopRight
8 - Bottom Right To Top Left dbgBottomRightToTopLeft
9 - Center dbgAnimateCenter

Appearance Constants
Applies To
Appearance Property (page 374)
Values
Design Time Run Time
0 - Flat dbgFlat
1 - 3D (default) dbg3D

BackgroundPictureDrawMode Constants
Applies To
BackgroundPictureDrawMode Property (page 378)
 BorderStyle Constants · 651

Values
Design Time Run Time
0 - Center (default) dbgBPCenter
1 - Tile dbgBPTile
2 - Stretch dbgBPStretch

BorderStyle Constants
Applies To
BorderStyle Property (page 383)
Values
Design Time Run Time
0 - None dbgNoBorder
1 - Fixed Single (default) dbgFixedSingle

CellStyle Constants
Applies To
AddCellStyle Method (page 489)
AddRegexCellStyle Method (page 490)
ClearCellStyle Method (page 497)
ClearRegexCellStyle Method (page 498)
FetchCellStyle Event (page 541)
Values
Description Run Time
-1 - All Cells dbgAllCells
0 - Cells without status conditions dbgNormalCell
1 - Current cell dbgCurrentCell
2 - Cells in a highlighted row dbgMarqueeRow
4 - Cells that have been modified dbgUpdatedCell
8 - Cells in a selected row dbgSelectedRow

CellTip Constants
Applies To
FetchCellTips Event (page 542)
Values
Description Run Time
-1 - On Record Selector dbgOnRecordSelector
652 · Constant Reference

Description Run Time

-2 - On Empty Column dbgOnEmptyColumn
-1 - On Column Header dbgOnColumnHeader
-2 - On Split Header dbgOnSplitHeader
-3 - On Empty Row dbgOnEmptyRow
-4 - On Caption dbgOnCaption
-5 - On AddNew Row dbgOnAddNew
-6 - On Column Footer dbgOnColumnFooter

CellTipPresentation Constants
Applies To
CellTips Property (page 388)
Values
Design Time Run Time
0 - None (default) dbgNoCellTips
1 - Anchored dbgAnchored
2 - Floating dbgFloating

ConvertEmptyCell Constants
Applies To
ConvertEmptyCell Property (page 394)
Values
Design Time Run Time
0 - Write as is (default) dbgNoConversion
1 - Write as Null value dbgAsNull

DataMode Constants
Applies To
DataMode Property (page 398)
Values
Design Time Run Time
0 - Bound (default) dbgBound
1 - Unbound dbgUnbound
2 - Unbound Extended dbgUnboundEx
3 - Application dbgUnboundAp
4 - Storage dbgUnboundSt
 DataView Constants · 653

DataView Constants
Applies To
DataView Property (page 399)
Values
Design Time Run Time
0 - Normal (default) dbgNormalView
1 - Hierarchical dbgHierarchicalView
2 - Group dbgGroupView

DividerStyle Constants
Applies To
DividerStyle Property (page 408)
RowDividerStyle Property (page 465)
Values
Design Time Run Time
0 - No dividers (Split default) dbgNoDividers
1 - Black line dbgBlackLine
2 - Dark gray line (non-Split default) dbgDarkGrayLine
3 - Raised dbgRaised
4 - Inset dbgInset
5 - ForeColor dbgUseForeColor
6 - Light gray line dbgLightGrayLine
7 – Custom color dbgCustomColor
8 - Double line dbgDoubleLine

Error Constants
Applies To
Trappable errors for TDBGrid and TDBDropDown controls
Values
Description Run Time
4097 - Cannot initialize data bindings dbgBINDERROR
4098 - Invalid setting for name property dbgINVPROPVAL
6145 - Invalid column index dbgCOLINDEX
6146 - Control not properly initialized dbgNOTINIT
6147 - Column not found dbgCNOTFOUND
6148 - Invalid row number dbgINVROWNUM
654 · Constant Reference

Description Run Time

6149 - Invalid bookmark dbgINVBOOKMARK
6150 - Invalid selected row bookmark index dbgBADSELRIDX
6151 - Scroll arguments out of range dbgSCROLLRANGE
6152 - Invalid setting for ScrollBars property dbgINVSBSTYLE
6153 - Error occurred while trying to update record dbgUPDERROR
6154 - Error occurred while trying to add record dbgADDERROR
6155 - Error occurred while trying to delete record dbgDELERROR
6156 - Data type mismatch during field update dbgCOLDATA
6157 - Data type incompatible with column data dbgINCOMPAT
type
6158 - name is not a valid data field name dbgFIELDERR
6159 - Cannot delete multiple rows dbgDELMULTROWS
6160 - Data access error dbgDATAACCESS
6161 - Operation is invalid within the event name dbgBADEVENT
6162 - Property is not available in this context dbgNOPROPNOW
6163 - No current record dbgNOCURREC
6164 - Caption text is too long dbgCAPTOOLONG
6244 - Invalid split index dbgSPLITINDEX
6245 - Invalid value list index dbgVLINDEX
6246 - Error accessing value item dbgVITEMERR
6247 - Invalid style index dbgSTYLEINDEX
6248 - Duplicate style name dbgDUPSTYLE
6249 - Error accessing style dbgSTYLEERR
6250 - Error updating style dbgUPDSTYLE
6251 - Error removing style dbgREMSTYLE
6252 - Error adding cell condition dbgADDCELLCOND
6253 - Invalid style name dbgSTYLENAME
6254 - Error applying style dbgAPPLYSTYLE
6255 - Bitmap is too large dbgBMPTOOLARGE

ExposeCellMode Constants
Applies To
ExposeCellMode Property (page 418)
Values
Design Time Run Time
0 - Scroll on Select (default) dbgScrollOnSelect
 FetchCellStyle Constants · 655

Design Time Run Time

1 - Scroll on Edit dbgScrollOnEdit
2 - Never Scroll dbgScrollNever

FetchCellStyle Constants
Applies To
FetchStyle Property (page 421)
Values
Design Time Run Time
0 - None dbgFetchCellStyleNone
1 – Column dbgFetchCellStyleColumn
2 – Column and AddNew dbgFetchCellStyleAddNewColumn

ForegroundPicturePosition Constants
Applies To
ForegroundPicturePosition Property (page 429)
Values
Design Time Run Time
0 - Left (default) dbgFPLeft
1 - Right dbgFPRight
2 - Left of Text dbgFPLeftOfText
3 - Right of Text dbgFPRightOfText
4 - Top of Text dbgFPTopOfText
5 - Bottom of Text dbgFPBottomOfText
6 - Picture Only dbgFPPictureOnly
7 - Text Only dbgFPTextOnly

MarqueeStyle Constants
Applies To
MarqueeStyle Property (page 443)
Values
Design Time Run Time
0 - Dotted Cell Border dbgDottedCellBorder
1 - Solid Cell Border dbgSolidCellBorder
2 - Highlight Cell dbgHighlightCell
3 - Highlight Row dbgHighlightRow
656 · Constant Reference

Design Time Run Time

4 - Highlight Row, Raise Cell dbgHighlightRowRaiseCell
5 - No Marquee dbgNoMarquee
6 - Floating Editor (default) dbgFloatingEditor
7 - Dotted Row Border dbgDottedRowBorder

MergeCell Constants
Applies To
Merge Property (page 446)
Values
Design Time Run Time
0 - None dbgMergeNone
1 - Free dbgMergeFree
2 - Restricted dbgMergeRestricted

MousePointer Constants
Applies To
MousePointer Property (page 447)
Values
Design Time Run Time
0 - Default (default) dbgMPDefault
1 - Arrow dbgMPArrow
2 - Cross dbgMPCross
3 - I-beam dbgMPIbeam
4 - Icon dbgMPIcon
5 - Size dbgMPSize
6 - Size NE SW dbgMPSizeNESW
7 - Size NS dbgMPSizeNS
8 - Size NW SE dbgMPSizeNWSE
9 - Size EW dbgMPSizeEW
10 - Up Arrow dbgMPUpArrow
11 - Hourglass dbgMPHourglass
12 - No Drop dbgMPNoDrop
13 - Arrow Hourglass dbgMPArrowHourglass
14 - Arrow Question dbgMPArrowQuestion
15 - Size All dbgMPSizeAll
 MoveDirection Constants · 657

Design Time Run Time

99 - Custom dbgMPCustom

MoveDirection Constants
Applies To
DirectionAfterEnter Property (page 406)
DirectionAfterTab Property (page 406)
Values
Design Time Run Time
0 - None dbgMoveNone
1 - Right (default) dbgMoveRight
2 - Down dbgMoveDown
3 - Left dbgMoveLeft
4 - Up dbgMoveUp

MultipleLines Constants
Applies To
MultipleLines Property (page 448)
Values
Design Time Run Time
0 - Disabled (default) dbgMultipleDisabled
1 - Variable dbgMultipleVariable
2 - Fixed dbgMultipleFixed

MultiSelect Constants
Applies To
MultiSelect Property (page 449)
Values
Design Time Run Time
0 - None dbgMultiSelectNone
1 - Simple (default) dbgMultiSelectSimple
2 - Extended dbgMultiSelectExtended

OLEDragMode Constants
Applies To
OLEDragMode Property (page 453)
658 · Constant Reference

Values
Design Time Run Time
0 - Manual (default) dbgOLEDragManual
1 - Automatic dbgOLEDragAutomatic

OLEDropMode Constants
Applies To
OLEDropMode Property (page 454)
Values
Design Time Run Time
0 - None (default) dbgOLEDropNone
1 - Manual dbgOLEDropManual
2 - Automatic dbgOLEDropAutomatic

PointAt Constants
Applies To
PointAt Method (page 513)
Values
Description Run Time
0 - Not in Grid dbgNotInGrid
1 - At Grid Caption dbgAtCaption
2 - At Split Header dbgAtSplitHeader
3 - At Split Size Box dbgAtSplitSizeBox
4 - At Row Select dbgAtRowSelect
5 - At Row Size dbgAtRowSize
6 - At Column Header dbgAtColumnHeader
7 - At Column Footer dbgAtColumnFooter
8 - At Column Size dbgAtColumnSize
9 - At Data Area dbgAtDataArea
10 - At Group Area dbgAtGroupArea
11 - At Group Header dbgAtGroupHeader

Presentation Constants
Applies To
Presentation Property (page 460)
 PrintInfo_Menu Constants · 659

Values
Design Time Run Time
0 - Normal (default) dbgNormal
1 - Radio Button dbgRadioButton
2 - Combo Box dbgComboBox
3 - Sorted Combo Box dbgSortedComboBox
4 - Check Box dbgCheckBox

PrintInfo_Menu Constants
Applies To
GetMenuText Method (page 683)
SetMenuText Method (page 686)
Values
Constant Menu Command
0 - dbgpMenuFile File
1 - dbgpMenuPrint Print
2 - dbgpMenuExit Exit
3 - dbgpMenuView View
4 - dbgpMenuZoomIn Zoom In
5 - dbgpMenuZoomOut Zoom Out
6 - dbgpMenuFit Fit in Window
7 - dbgpMenuPgFirst First Page
8 - dbgpMenuPgPrev Previous Page
9 - dbgpMenuPgNext Next Page
10 - dbgpMenuPgLast Last Page
11 - dbgpMenuPrintSomePages Print Some Pages
12 - dbgpMenuPrintCurrPage Print Current Page
13 - dbgpDlgPagesCaption Print Some Pages dialog caption
14 - dbgpDlgPagesPrompt Print Some Pages dialog prompt
15 - dbgpDlgPagesOk Print Some Pages dialog OK button text
16 - dbgpDlgPagesCancel Print Some Pages Cancel button text
17 - dbgpTipPrint Print Document
18 - dbgpTipZoomIn Zoom In
19 - dbgpTipZoomOut Zoom Out
20 - dbgpTipFit Fit in Window
21 - dbgpTipZoom Zoom Factor
22 - dbgpTipPgFirst Go to First Page
660 · Constant Reference

Constant Menu Command

23 - dbgpTipPgPrev Go to Previous Page
24 - dbgpTipPgNext Go to Next Page
25 - dbgpTipPgLast Go to Last Page
26 - dbgpTipPageOf Current page number
27 - dbgpTipStop Stop Pagination
28 - dbgpMenuOpen Opens the Menu
29 - dbgpMenuSaveAs Save File As
30 - dbgpMenuPageSetup Page Setup
31 - dbgpTipOpen Open a Previously Saved Report
32 - dbgpTipSaveAs Save Current Report in a file
33 - dbgpTipPageSetup Show Page Setup Dialog
34 - dbgpFilemaskArx ComponentOne Report Files
35 - dbgpFilemaskAll All Files
36 – dbgpErrFileOpen Error Loading File
37 - dbgpErrFileSave Error Saving File
38 - dbgpErrFileFormat Not a Valid ComponentOne Report File
39 - dbgpApsCaption Adjust Page Settings
40 - dbgpApsText Contents Bigger Than Printable Area
41 - dbgpApsMargins Use Margins to Maximize Printable Area
42 - dbgpApsOrientation Select Best Orientation
43 - dbgpApsHorzText Horizontal Positioning of Printable Area
44 - dbgpApsHorzLeft Align to Left Margin
45 - dbgpApsHorzCenter Center Between Left and Right Margins
46 - dbgpApsHorzRight Align to Right Margin
47 - dbgpApsVerText Vertical Positioning of Printable Area
48 - dbgpApsVerTop Align to Top Margin
49 - dbgpApsVertCenter Center Between Top & Bottom Margins
50 - dbgpApsVertBottom Align to Bottom Margin
51 - dbgpApsPageSetup Page Setup
52 - dbgpMenuFileClose Close File Menu
53 - dbgpDlgExporting Preparing for Export
54 - dbgpDlgExportPage Exporting Page To
55 - dbgpTipFitWidth Fit Width
56 - dbgpTipActualSize Actual Size
57 - dbgpMenuFitWidth Fit Width
58 - dbgpMenuActualSize Actual Size
 RowSelector Constants · 661

Notes
All constants with Menu are menu items.
All constants with Tip are tool tips.
All constants with Aps are strings from the “adjust page settings” dialog (see below).
All constants with Err are error messages.
With the exception of 40 - dbgpApsText, all constants with Aps appear as part of a custom dialog
available after the page settings have been changed and the preview must determine how to show the
already generated pages.
With 40 - dbgpApsText, a dialog appears: “The contents is bigger than the printable area of the page.
Please review and/or change options below and click OK to adjust the page settings and scale down the
contents.”

RowSelector Constants
Applies To
ExportToDelimitedFile Method (page 504)
ExportToFile Method (page 505)
PrintData Method (page 685)
PrintPreview Method (page 685)
Values
Description Run Time
0 - All Rows dbgAllRows
1 - Selected Rows dbgSelectedRows
2 - Current Row dbgCurrentRow

ScrollBars Constants
Applies To
ScrollBars Property (page 466)
Values
Design Time Run Time
0 - None dbgNone
1 - Horizontal dbgHorizontal
2 - Vertical dbgVertical
3 - Both dbgBoth
4 - Automatic (default) dbgAutomatic
662 · Constant Reference

SplitSizeMode Constants
Applies To
SizeMode Property (page 473)
Values
Design Time Run Time
0 - Scalable (default) dbgScalable
1 - Exact dbgExact
2 - Number of Columns dbgNumberOfColumns

StyleBorderAppearance Constants
Applies To
BorderAppearance Property (page 381)
Values
Design Time Run Time
0 - Flat (default) dbgFlatStyle
1 - Raised dbg3DRaised
2 - Inset dbg3DInset
3 - Raise Bevel dbg3DRaiseBevel
4 - Inset Bevel dbg3DInsetBevel

StyleBorderType Constants
Applies To
BorderType Property (page 383)
Values
Design Time Run Time
0 - None (default) dbgBorderNone
1 - Left dbgBorderLeft
2 - Right dbgBorderRight
4 - Top dbgBorderTop
8 - Bottom dbgBorderBottom

TabAction Constants
Applies To
TabAction Property (page 477)
 UnboundFind Constants · 663

Values
Design Time Run Time
0 - Control Navigation (default) dbgControlNavigation
1 - Column Navigation dbgColumnNavigation
2 - Grid Navigation dbgGridNavigation
3 - Grid Column Navigation dbgGridColumnNavigation

UnboundFind Constants
Applies To
UnboundFindData Event (page 643)
Values
Description Run Time
-1 - Less Than dbgSeekLT
-2 - Less Than or Equal dbgSeekLE
-3 - Equal dbgSeekEQ
-4 - Greater Than or Equal dbgSeekGE
-5 - Greater Than dbgSeekGT
-6 - Partially Equal dbgSeekPartialEQ

VerticalAlignment Constants
Applies To
VerticalAlignment Property (page 484)
Values
Design Time Run Time
0 - Top (default) dbgTop
1 - Bottom dbgBottom
2 - Vertical Center dbgVertCenter
 PrintInfo All Members · 665

PrintInfo Reference
PrintInfo All Members
PrintInfo Object Properties
Collate Sets/returns whether printed output should be collated
Default Sets/returns default PrintInfo status
Draft Sets/returns whether output should be rendered faster at the cost of
lower quality
Name Index into the PrintInfos collection
NeedTotalPageCount Sets/returns whether total page count is required for owner drawn
page header or footer
NoClipping Sets/returns whether printed text is clipped to cell boundaries
NumberOfCopies Sets/returns the number of copies to print
PageFooter Sets/returns the page footer for a PrintInfo object
PageFooterFont Sets/returns the page footer font for a PrintInfo object
PageFooterHeight Sets/returns height of owner drawn page footer
PageFooterOwnerDraw Sets/returns whether page header is owner drawn
PageHeader Sets/returns the page header for a PrintInfo object
PageHeaderFont Sets/returns the page header font for a PrintInfo object
PageHeaderHeight Sets/returns height of owner drawn page header
PageHeaderOwnerDraw Sets/returns whether page header is owner drawn
PageSetupCancelled Returns true if the Page Setup dialog is cancelled by the user
PreviewAllowFileOps Sets/returns whether file load/save are allowed in preview
PreviewCaption Sets/returns the print preview window caption
PreviewInitHeight Sets/returns print preview window's initial height
PreviewInitPosX Sets/returns print preview window's initial X position
PreviewInitPosY Sets/returns print preview window's initial Y position
PreviewInitScreenFill sets/returns print preview window's initial screen fill
PreviewInitWidth Sets/returns print preview window's initial width
PreviewInitZoom Sets/returns print preview window's initial zoom factor
PreviewMaximize Sets/returns whether print preview window is initially maximized
PreviewPageOf Controls the PrintPreview window display of "Page x of y"
RangeOfPages Sets/returns the range of pages to be printed
RepeatColumnFooters Sets/returns whether column footers appear on each page
RepeatColumnHeaders Sets/returns whether column headers appear on each page
666 · PrintInfo Reference

RepeatGridHeader Sets/returns whether the grid caption appear on each page

RepeatSplitHeaders
Settings
SettingsDeviceName
SettingsMarginBottom
SettingsMarginLeft
SettingsMarginRight
SettingsMarginTop
SettingsOrientation
SettingsPaperBin
SettingsPaperHeight
SettingsPaperSize
SettingsPaperWidth
UnitsPerInch
VariableRowHeight
Sets/returns whether split captions appear on each page
Page setup and printer settings blob (run time only)
Provides access to the printing device name in the Settings blob
Provides access to the bottom margin (twips) in the Settings blob
Provides access to the left margin (twips) in the Settings blob
Provides access to the right margin (twips) in the Settings blob
Provides access to the top margin (twips) in the Settings blob
Provides access to the paper orientation in the Settings blob
Provides access to the paper bin in the Settings blob
Provides access to the paper height (twips) in the Settings blob
Provides access to the paper size in the Settings blob
Provides access to the paper width (twips) in the Settings blob
Returns the number of logical units per inch
Sets/returns whether row height can vary to fully print each cell

PrintInfo Object Methods

GetMenuText Retrieves the text of the specified PrintPreview menu item
GetSubstituteFont Retrieves a substitution font for printing
PageSetup Opens the page setup dialog for printing and PrintPreview
PrintData Sends the grid's contents directly to the printer
PrintPreview Opens the print preview window on the grid's contents
SetMenuText Overrides the default text for the specified PrintPreview menu item
SubstituteFont Adds a substitution font for printing

PrintInfo Properties
Collate Property (PrintInfo)
This property sets or returns a boolean that determines whether output should be collated when printing
multiple copies.
Syntax
PrintInfo.Collate = boolean
Remarks
Read/Write at run time and design time.
If True, each page is printed NumberOfCopies times before the next page is printed.
If False (the default), each page is printed once, and the process is repeated NumberOfCopies times.
 Default Property (PrintInfo) · 667

See Also
PrintInfo Object (page 121)

Default Property (PrintInfo)

This property sets or returns a boolean that determines whether the target object is the default PrintInfo
for the associated TDBGrid control.
Syntax
PrintInfo.Default = boolean
Read/Write at run time and design time.
Remarks
If True (the default), the PrintInfo property of the associated TDBGrid control returns the target object.
If False, the target object can only be accessed through the PrintInfos collection of the associated
TDBGrid control.
When a TDBGrid control is first created, its PrintInfos collection contains a single PrintInfo object whose
Default property is True.
See Also
PrintInfo Object (page 121)

Draft Property (PrintInfo)

The Draft property sets or returns a boolean that enables you to specify a lower output quality for screen
rendering or printing for the sake of enhanced performance.
Syntax
PrintInfo.Draft = boolean
Remarks
Read/Write at run time and design time.
If True, rendered or printed output is in draft quality.
If False (the default), rendered or printed output uses the default settings.
See Also
PrintInfo Object (page 121)

Name Property (PrintInfo)

This property sets or returns the string used to identify a PrintInfo object within a PrintInfos collection.
Syntax
PrintInfo.Name = string
Remarks
Read/Write at run time and design time.
668 · PrintInfo Reference

When a TDBGrid control is first created, its PrintInfos collection contains a single PrintInfo object
named DefaultPrintInfo.
See Also
PrintInfo Object (page 121)

NeedTotalPageCount Property (PrintInfo)

This property sets or returns a boolean that indicates whether the total page count is needed to render an
owner-drawn page header or footer.
Syntax
PrintInfo.NeedTotalPageCount = boolean
Remarks
Read/Write at run time and design time.
See Also
PrintInfo Object (page 121)

NoClipping Property (PrintInfo)

This property sets or returns a boolean that determines how cell text is clipped during print and print
preview operations.
Syntax
PrintInfo.NoClipping = boolean
Remarks
Read/Write at run time and design time.
If False (the default), text inside of grid cells is clipped to the cell boundaries, as it is in the normal grid
view.
If set to True, any text inside the grid cells will be drawn without clipping during print and print preview
operations only.
With some printer/font combinations, the size required to print certain text is sometimes reported
incorrectly, which can result in undesired clipping of letters (when there should be none). If this occurs, it
is necessary to set the NoClipping property to True. This will prevent the undesired clipping. This
property should be used with caution, as in certain cases, it can result in cells' contents overflowing into
other cells.
See Also
PrintInfo Object (page 121)

NumberOfCopies Property (PrintInfo)

This property sets or returns the number of copies to be printed by the PrintData method or from within
the PrintPreview window.
 PageFooter Property (PrintInfo) · 669

Syntax
PrintInfo.NumberOfCopies = integer
Remarks
Read/Write at run time and design time.
When NumberOfCopies is greater than 1, the order in which pages are printed is determined by the
Collate property.
See Also
PrintInfo Object (page 121)

PageFooter Property (PrintInfo)

This property sets or returns a string to be printed at the bottom of each page.
Syntax
PrintInfo.PageFooter = string
Remarks
Read/Write at run time and design time.
By default, this property returns an empty string, and no page footer is printed.
If specified, the page footer can consist of up to three substrings separated by the \t character sequence.
The first substring will be left-aligned, the second centered, and the third right-aligned on the printed
page. The \p sequence will be replaced by the current page number during printing.
For example, the following statement sets the PageFooter property of the default PrintInfo object so that
the word "CONFIDENTIAL" is centered at the bottom of each page:
TDBGrid1.PrintInfo.PageFooter = "\tCONFIDENTIAL"
In addition, the following characters provide even greater control over the appearance of the PageFooter
property, especially when the grid is so large that columns span more than one printed page.
\p Current page number. 1-based, and incremented by subpages (i.e., the group of
pages that hold all of the columns for a set of records).
\P Total number of pages; each sub-page is counted separately.
\g Current subpage group number. 1-based.
\G Total number of subpage groups
\s Current subpage number. 1-based.
\S Total number of subpages.
For example, the following statement sets the PageFooter property of the default PrintInfo object so that
the number of groups is on the left, the sub-page number is in the center, and the total number of pages is
on the right, preceded by the word "Page:"
TDBGrid1.PrintInfo.PageFooter = _
"\tPage: \g of group \G, \s of subpage \S, \p of page \P"
The page footer will look something like this:
Page: 1 of group 169, 1 of subpage 2, 1 of page 338
670 · PrintInfo Reference

Note
If Draft mode is True, the total pages and subpage group pages will not be calculated.
Use the PageHeader property to specify a string to be printed at the top of each page.
See Also
PrintInfo Object (page 121)

PageFooterFont Property (PrintInfo)

This property sets or returns the font used to display the PageFooter string.
Syntax
PrintInfo.PageFooterFont = font
Remarks
Read/Write at run time and design time.
By default, this is the same value returned by the grid's Font property.
See Also
PrintInfo Object (page 121)

PageFooterHeight Property (PrintInfo)

This property sets or returns the height of an owner-drawn page footer in twips.
Syntax
PrintInfo.PageFooterHeight = long
Remarks
Read/Write at run time and design time.
See Also
PrintInfo Object (page 121)

PageFooterOwnerDraw Property (PrintInfo)

This property sets or returns a boolean that determines whether the page footer is owner-drawn.
Syntax
PrintInfo.PageFooterOwnerDraw = boolean
Remarks
Read/Write at run time and design time.
By default, this property is False, and the string returned by the PageFooter property is used to format the
page footer.
If set to True, then the OwnerDrawPageFooter event is fired as needed to render the page footer to the
printer device context.
 PageHeader Property (PrintInfo) · 671

See Also
PrintInfo Object (page 121)

PageHeader Property (PrintInfo)

This property sets or returns a string to be printed at the top of each page.
Syntax
PrintInfo.PageHeader = string
Remarks
Read/Write at run time and design time.
By default, this property returns an empty string, and no page header is printed.
If specified, the page header can consist of up to three substrings separated by the \t character sequence.
The first substring will be left-aligned, the second centered, and the third right-aligned on the printed
page. The \p sequence will be replaced by the current page number during printing.
For example, the following statement sets the PageHeader property of the default PrintInfo object so that
the current date is on the left, and the page number is on the right, preceded by the word "Page."
TDBGrid1.PrintInfo.PageHeader = CStr(Now) & "\t\tPage \p"
In addition, the following characters provide even greater control over the appearance of the PageHeader
property when the grid is so large that columns span more than one printed page.
\p Current page number. 1-based, and incremented by subpages (i.e., the group of
pages that hold all of the columns for a set of records).
\P Total number of pages; each sub-page is counted separately.
\g Current subpage group number. 1-based.
\G Total number of subpage groups
\s Current subpage number. 1-based.
\S Total number of subpages.
For example, the following statement sets the PageHeader property of the default PrintInfo object so that
the number of groups is on the left, the sub-page number is in the center, and the total number of pages is
on the right, preceded by the word "Page:"
TDBGrid1.PrintInfo. PageHeader = _
"\tPage: \g of group \G, \s of subpage \S, \p of page \P"
The page header will look something like this:
Page: 1 of group 169, 1 of subpage 2, 1 of page 338
Note
If Draft mode is True, the total pages and subpage group pages will not be calculated.
Use the PageFooter property to specify a string to be printed at the bottom of each page.
See Also
PrintInfo Object (page 121)
672 · PrintInfo Reference

PageHeaderFont Property (PrintInfo)

This property sets or returns the font used to display the PageHeader string.
Syntax
PrintInfo.PageHeaderFont = font
Remarks
Read/Write at run time and design time.
By default, this is the same value returned by the grid's Font property.
See Also
PrintInfo Object (page 121)

PageHeaderHeight Property (PrintInfo)

This property sets or returns the height of an owner-drawn page header in twips.
Syntax
PrintInfo.PageHeaderHeight = long
Remarks
Read/Write at run time and design time.
See Also
PrintInfo Object (page 121)

PageHeaderOwnerDraw Property (PrintInfo)

This property sets or returns a boolean that determines whether the page header is owner-drawn.
Syntax
PrintInfo.PageHeaderOwnerDraw = boolean
Remarks
Read/Write at run time and design time.
By default, this property is False, and the string returned by the PageHeader property is used to format
the page header.
If set to True, then the OwnerDrawPageHeader event is fired as needed to render the page header to the
printer device context.
See Also
PrintInfo Object (page 121)

PageSetupCancelled Property (PrintInfo)

This property returns a boolean that determines whether the PageSetup dialog has been cancelled by the
user.
 PreviewAllowFileOps Property (PrintInfo) · 673

Syntax
PrintInfo.PageSetupCancelled
Remarks
Read-only at run time. Not available at design time.
If True, the PageSetup dialog most recently displayed was cancelled by the user (either the user pressed
Cancel command button or the small Close button in the upper right hand corner of the dialog was
pressed). This indicates that any user changes to the specified printer settings have been aborted, and that
the Settings property of the PrintInfo object has not been changed.
If False, the PageSetup dialog most recently displayed was closed by the user pressing the OK command
button on the lower right hand corner of the dialog. This indicates that user changes (if any) to the
specified printer settings have been stored in the Settings property of the PrintInfo object.
See Also
PrintInfo Object (page 121)

PreviewAllowFileOps Property (PrintInfo)

This property sets or returns a boolean that determines whether file loads or saves are allowed in
preview.
Syntax
PrintInfo.PreviewAllowPrintOps = boolean
Remarks
Read/Write at run time and design time.
This property is False by default. If True, file operations (open and save as) are enabled in print preview.
See Also
PrintInfo Object (page 121)

PreviewCaption Property (PrintInfo)

This property sets or returns a string that will be displayed in the title bar of the PrintPreview window.
Syntax
PrintInfo.PreviewCaption = string
Remarks
Read/Write at run time and design time.
By default, this property returns an empty string, and no window caption is displayed.
See Also
PrintInfo Object (page 121)
674 · PrintInfo Reference

PreviewInitHeight Property (PrintInfo)

This property specifies the preview window's initial height in pixels, if non-zero (and the
PreviewInitWidth property is also non-zero).
Syntax
PrintInfo.PreviewInitHeight = long
Remarks
Read/Write at run time and design time.
If either property is zero, then the window size is determined by the PreviewInitScreenFill property.
See Also
PrintInfo Object (page 121)

PreviewInitPosX Property (PrintInfo)

If the PreviewInitWidth and PreviewInitHeight properties are both non-zero, this property specifies the
initial X coordinate (in pixels) of the preview window's top left corner.
Syntax
PrintInfo.PreviewInitPosX = long
Remarks
Read/Write at run time and design time.
See Also
PrintInfo Object (page 121)

PreviewInitPosY Property (PrintInfo)

If the PreviewInitWidth and PreviewInitHeight properties are both non-zero, this property specifies the
initial Y coordinate (in pixels) of the preview window's top left corner.
Syntax
PrintInfo.PreviewInitPosY = long
Remarks
Read/Write at run time and design time.
See Also
PrintInfo Object (page 121)

PreviewInitScreenFill Property (PrintInfo)

If non-zero, and the PreviewInitWidth and PreviewInitHeight properties are both zero, this property
specifies the percentage of screen space allocated to the preview window (as an integer).
Syntax
PrintInfo.PreviewInitScreenFill = long
 PreviewInitWidth Property (PrintInfo) · 675

Remarks
Read/Write at run time and design time.
The default value (zero) is equivalent to 80%.
See Also
PrintInfo Object (page 121)

PreviewInitWidth Property (PrintInfo)

This property specifies the preview window's initial width in pixels, if non-zero (and the
PreviewInitHeight property is also non-zero).
Syntax
PrintInfo.PreviewInitWidth = long
Remarks
Read/Write at run time and design time.
If either property is zero, then the window size is determined by the PreviewInitScreenFill property.
See Also
PrintInfo Object (page 121)

PreviewInitZoom Property (PrintInfo)

Sets or returns the print preview window's initial zoom factor.
Syntax
PrintInfo.PreviewInitZoom = long
Remarks
Read/Write at run time and design time.
If non-zero, this property sets the initial zoom factor for the print preview window. If zero, the preview
window automatically selects the maximum zoom factor that shows the whole page.
See Also
PrintInfo Object (page 121)

PreviewMaximize Property (PrintInfo)

This property sets or returns a boolean that determines whether the PrintPreview dialog is initially
maximized when first displayed.
Syntax
PrintInfo.PreviewMaximize = boolean
Remarks
Read/Write at run time and design time.
676 · PrintInfo Reference

If True, the PrintPreview dialog will be maximized whenever it is shown. The user may resize the dialog
while it is shown, but the PrintPreview dialog will always be maximized again whenever it is next
displayed.
If False (the default), the PrintPreview dialog will not be maximized whenever it is displayed, and will be
displayed at the default size.
Regardless of the value of this property, it is always possible to maximize or restore the default window
size using the buttons in the upper right hand corner of the print preview dialog.
See Also
PrintInfo Object (page 121)

PreviewPageOf Property (PrintInfo)

The PreviewPageOf property sets or returns a string that controls how page number information is
displayed in the PrintPreview window.
Syntax
PrintInfo.PreviewPageOf = string
Remarks
Read/Write at run time and design time.
If specified, the string may contain two special substrings:
\p Current page (just as in the page header/footer).
\P Total number of pages.
Note
If the user presses Abort while print preview pages are being rendered, the "\P" substring is evaluated as
"\P?".
See Also
PrintInfo Object (page 121)

RangeOfPages Property (PrintInfo)

This property sets or returns a string that defines the range of pages to be printed when the PrintData
method is invoked.
Syntax
PrintInfo.RangeOfPages = string
Remarks
Read/Write at run time. Not available at design time.
This property is honored only be the PrintData method, and not by PrintPreview.
The syntax of the string accepted by this property is in a relatively free format, and is parsed using the
following rules:
• Any characters except digits and "-" are ignored.
 RepeatColumnFooters Property (PrintInfo) · 677

• Any numbers which are separated with "-" are treated as an inclusive range of pages.
• A "-" at the beginning of the string is treated as "1-".
• A "-" at the end of the string is treated as "to the end".
• All other numbers are treated as single page numbers.
• Sequence is not important, unless within a range. In this case, the smaller number must be given
first, or the range will be ignored. The string "4-8" indicates pages 4 to 8 (inclusive), but the string
"8-4" will not print any pages.
Example
For a grid containing 14 pages of data, the string "-3, 8-10, 7, 12-" will print pages 1, 2, 3, 7, 8, 9, 10, 12, 13,
and 14.
See Also
PrintInfo Object (page 121)

RepeatColumnFooters Property (PrintInfo)

This property sets or returns a boolean that determines whether column footers should appear on each
page.
Syntax
PrintInfo.RepeatColumnFooters = boolean
Remarks
Read/Write at run time and design time.
If True, column footers are printed at the bottom of each physical page.
If False (the default), column footers are printed on the last page only.
Note
If the ColumnFooters property of the associated TDBGrid control is False, then column footers are not
printed, regardless of the setting of this property.
See Also
PrintInfo Object (page 121)

RepeatColumnHeaders Property (PrintInfo)

This property sets or returns a boolean that determines whether column headers should appear on each
page.
Syntax
PrintInfo.RepeatColumnHeaders = boolean
Remarks
Read/Write at run time and design time.
If True, column headers are printed at the top of each physical page below the split headers and grid
header, if present.
678 · PrintInfo Reference

If False (the default), column headers are printed on the first page only.
Note
If the ColumnHeaders property of the associated TDBGrid control is False, then column headers are not
printed, regardless of the setting of this property.
See Also
PrintInfo Object (page 121)

RepeatGridHeader Property (PrintInfo)

This property sets or returns a boolean that determines whether the grid caption should appear on each
page.
Syntax
PrintInfo.RepeatGridHeader = boolean
Remarks
Read/Write at run time and design time.
If True, the grid caption is printed at the top of each physical page.
If False (the default), the grid caption is printed on the first page only.
Note
If the Caption property of the associated TDBGrid control is not set, then the grid header is not printed,
regardless of the setting of this property.
See Also
PrintInfo Object (page 121)

RepeatSplitHeaders Property (PrintInfo)

This property sets or returns a boolean that determines whether split captions should appear on each
page.
Syntax
PrintInfo.RepeatSplitHeaders = boolean
Remarks
Read/Write at run time and design time.
If True, split captions are printed at the top of each physical page below the grid header and above the
column headers, if present.
If False (the default), split captions are printed on the first page only.
Note
If split captions are not set within the associated TDBGrid control, then the split headers are not printed,
regardless of the setting of this property.
See Also
PrintInfo Object (page 121)
 Settings Property (PrintInfo) · 679

Settings Property (PrintInfo)

This property sets or returns a string containing binary data that specifies printer settings such as the
paper size and source, portrait or landscape orientation, margins, and the name of the output device.
Syntax
PrintInfo.Settings = string
Remarks
Read/Write at run time. Not available at design time.
By default, this property returns an empty string, and the current settings for the system default printer
are used.
When the PageSetup method is called, and the user selects OK to confirm the options in the page setup
dialog, the specified printer settings are stored in the Settings property as a string of binary data. This
string is used by the PrintData and PrintPreview methods during printer initialization.
You can use this property to save and restore user preferences specified in the page setup dialog. For
example, the following code saves the Settings property to a binary file:
Dim Settings() As Byte
Open "pagesetup.dat" For Random Access Write As #1 Len = 4096
Settings = TDBGrid1.PrintInfo.Settings
Put #1, , Settings
Close #1
Similarly, the following code reads the contents of the file into a byte array, which is then assigned to the
Settings property.
Dim Settings() As Byte
Open "pagesetup.dat" For Random Access Read As #1 Len = 4096
Get #1, , Settings
Close #1
TDBGrid1.PrintInfo.Settings = Settings
Assigning an empty string to the Settings property restores the default printer settings.
Note
The internal format used by the Settings string is not available. If you need to access an individual
attribute such as the printer name, use the additional Settings* properties.
See Also
PrintInfo Object (page 121)

SettingsDeviceName Property (PrintInfo)

Use this property to specify the printer device name in the print Settings blob.
Syntax
PrintInfo.SettingsDeviceName = string
Remarks
Read/Write at run time. Not available at design time.
680 · PrintInfo Reference

See Also
PrintInfo Object (page 121)

SettingsMarginBottom Property (PrintInfo)

This property provides access to the bottom margin in the print Settings blob, allowing you to control the
margin setting (in twips) at the bottom of the page.
Syntax
PrintInfo.SettingsMarginBottom = long
Remarks
Read/Write at run time. Not available at design time.
The following code will result in a one-inch margin at the bottom of the printed page:
TDBGrid1.PrintInfo.SettingsMarginBottom = 1440
See Also
PrintInfo Object (page 121)

SettingsMarginLeft Property (PrintInfo)

This property provides access to the left margin in the print Settings blob, allowing you to control the left
margin setting (in twips).
Syntax
PrintInfo.SettingsMarginLeft = long
Remarks
Read/Write at run time. Not available at design time.
The following code will result in a one-inch left margin on the printed page:
TDBGrid1.PrintInfo.SettingsMarginLeft = 1440
See Also
PrintInfo Object (page 121)

SettingsMarginRight Property (PrintInfo)

This property provides access to the right margin in the print Settings blob, allowing you to control the
right margin setting (in twips).
Syntax
PrintInfo.SettingsMarginRight = long
Remarks
Read/Write at run time. Not available at design time.
The following code will result in a one-inch right margin on the printed page:
TDBGrid1.PrintInfo.SettingsMarginRight = 1440
 SettingsMarginTop Property (PrintInfo) · 681

See Also
PrintInfo Object (page 121)

SettingsMarginTop Property (PrintInfo)

This property provides access to the top margin in the print Settings blob, allowing you to control the
margin setting (in twips) at the top of the page.
Syntax
PrintInfo.SettingsMarginTop = long
Remarks
Read/Write at run time. Not available at design time.
The following code will result in a one-inch margin at the top of the printed page:
TDBGrid1.PrintInfo.SettingsMarginTop = 1440
See Also
PrintInfo Object (page 121)

SettingsOrientation Property (PrintInfo)

This property provides access to the paper orientation in the print Settings blob, which allows you to
control whether the page will be printed in a 1 - Portrait or 2 - Landscape orientation.
Syntax
PrintInfo.SettingsOrientation = integer
Remarks
Read/Write at run time. Not available at design time.
See Also
PrintInfo Object (page 121)

SettingsPaperBin Property (PrintInfo)

Use this property to specify the paper bin to be used in the print Settings blob.
Syntax
PrintInfo.SettingsPaperBin = integer
Remarks
Read/Write at run time. Not available at design time.
See Also
PrintInfo Object (page 121)

SettingsPaperHeight Property (PrintInfo)

Use this property to specify the paper height ( in twips) in the print Settings blob.
682 · PrintInfo Reference

Syntax
PrintInfo.SettingsPaperHeight = long
Remarks
Read/Write at run time. Not available at design time.
See Also
PrintInfo Object (page 121)

SettingsPaperSize Property (PrintInfo)

Use this property to specify the paper size in the print Settings blob.
Syntax
PrintInfo.SettingsPaperSize = integer
Remarks
Read/Write at run time. Not available at design time.
This is a Windows-specific setting and a complete discussion of all possible values is beyond the scope of
this documentation. Please refer to the Visual Basic help for more information on the Printer.PaperSize
property.
See Also
PrintInfo Object (page 121)

SettingsPaperWidth Property (PrintInfo)

Use this property to specify the paper width (in twips) in the print Settings blob.
Syntax
PrintInfo.SettingsPaperWidth = long
Remarks
Read/Write at run time. Not available at design time.
See Also
PrintInfo Object (page 121)

UnitsPerInch Property (PrintInfo)

Returns the number of logical units per inch.
Syntax
PrintInfo.UnitsPerInch = long
Remarks
Read-only at run time. Not available at design time.
 VariableRowHeight Property (PrintInfo) · 683

Use the UnitsPerInch property to determine the logical resolution of a printer device context. You do not
need to use this property unless your application uses owner-drawn cells in conjunction with the
PrintData or PrintPreview methods.
When creating fonts for use in the OwnerDrawCellPrint event, you can use the value returned by the
UnitsPerInch property to calculate the appropriate font size. For example, the following code creates a
10-point bold Tahoma font suitable for printing:
Dim UPI As Long, lfHeight As Long
Dim NewPrinterFont As Long
UPI = TDBGrid1.PrintInfo.UnitsPerInch
lfHeight = -(10 * UPI / 72)
NewPrinterFont = CreateFont(lfHeight, 0, 0, 0, 700, _
0, 0, 0, 0, 0, 0, 0, 0, "Tahoma")
You can access the UnitsPerInch property anywhere in your application. Typically, this is done in the
Form_Load event.
See Also
PrintInfo Object (page 121)

VariableRowHeight Property (PrintInfo)

This property sets or returns a boolean that determines whether the height of individual rows can vary to
accommodate cell text that spans multiple lines.
Syntax
PrintInfo.VariableRowHeight = boolean
Remarks
Read/Write at run time and design time.
If True, then the height of each printed row will be adjusted to accommodate cell contents that do not fit
within the allotted column width, provided that the WrapText property of the corresponding Column
object is set to True.
If False (the default), then each printed row occupies a single line of text, and cell contents that do not fit
within the allotted column width are truncated in the printed output.
Note
If the WrapText property of a Column is False, then its printed contents will not span multiple lines, even
if VariableRowHeight is True.
See Also
PrintInfo Object (page 121)

PrintInfo Methods
GetMenuText Method (PrintInfo)
Retrieves the text of the specified PrintPreview menu item.
Syntax
PrintInfo.GetMenuText (index)
684 · PrintInfo Reference

Arguments
index is a constant that specifies a menu item in the PrintPreview window.
Return Value
A string containing the text of the specified menu item.
Remarks
Use the GetMenuText method to retrieve the text of the specified PrintPreview menu item. Note that
system menus cannot be retrieved with this method.
See the SetMenuText method for a list of the menu constants.
See Also
PrintInfo Object (page 121)

GetSubstituteFont Method (PrintInfo)

The GetSubstituteFont method retrieves the name of a replacement font specified in a prior call to the
SubstituteFont method.
Syntax
PrintInfo.GetSubstituteFont (UnavailableFont)
Arguments
UnavailableFont is a string that identifies the name of the font to be substituted.
Return Value
The name of the replacement font or an empty string if none was specified.
See Also
PrintInfo Object (page 121)

PageSetup Method (PrintInfo)

The PageSetup method opens the page setup dialog box for printing and print preview.
Syntax
PrintInfo.PageSetup
Arguments
None
Return Value
None
Remarks
This is a standard Windows dialog box from which end users can select the paper size and source,
portrait or landscape orientation, margins, and the name of the output device.
If the user selects OK in the page setup dialog, the specified printer settings are stored in the Settings
property as a string of binary data.
 PrintData Method (PrintInfo) · 685

See Also
PrintInfo Object (page 121)

PrintData Method (PrintInfo)

The PrintData method prints the specified rows in the associated grid using the currently selected
printer.
Syntax
PrintInfo.PrintData [selector]
Arguments
selector is an optional RowSelectorConstants value that specifies the rows to be printed.
Return Value
None
Remarks
Generally, the selected printer is the system default printer, although you can use the PageSetup method
to enable end users to select a different printer prior to calling the PrintData method.
The selector argument determines the rows to be printed. It can be one of the following constant values:
0 - dbgAllRows All available rows are printed. If the selector argument is omitted,
this value is assumed.
1 - dbgSelectedRows Only selected rows are printed. The grid's SelBookmarks
collection contains a bookmark for each selected row.
2 - dbgCurrentRow Only the current row is printed. The grid's Bookmark property
returns the bookmark of the current row.
The printed output preserves as much of the associated grid's original formatting as possible, including
colors, fonts, alignment, and relative column widths. If present, the grid caption, split captions, column
headers, and column footers are displayed on the first page. You can force these elements to be repeated
on each physical page by setting the RepeatGridHeader, RepeatSplitHeaders, RepeatColumnHeaders,
and RepeatColumnFooters properties to True.
Note
Use the PrintPreview method to enable end users to view and scale the output before optionally printing
it.
See Also
PrintInfo Object (page 121)

PrintPreview Method (PrintInfo)

Opens the print preview window on the grid's contents.
Syntax
PrintInfo.PrintPreview [selector]
686 · PrintInfo Reference

Arguments
selector is an optional RowSelectorConstants value that specifies the rows to be previewed.
Return Value
None
Remarks
The PrintPreview method opens a separate application window in which end users can preview the
output that would be generated by the PrintData method. If desired, end users can also print the data
before closing the preview window.
Generally, the output is formatted for the system default printer, although you can use the PageSetup
method to enable end users to select a different printer prior to calling the PrintPreview method.
The selector argument determines the rows to be previewed. It can be one of the following constant
values:
0 - dbgAllRows All available rows are previewed. If the selector argument is
omitted, this value is assumed.
1 - dbgSelectedRows Only selected rows are previewed. The grid's SelBookmarks
collection contains a bookmark for each selected row.
2 - dbgCurrentRow Only the current row is previewed. The grid's Bookmark property
returns the bookmark of the current row.
The printed output preserves as much of the associated grid's original formatting as possible, including
colors, fonts, alignment, and relative column widths. If present, the grid caption, split captions, column
headers, and column footers are displayed on the first page. You can force these elements to be repeated
on each physical page by setting the RepeatGridHeader, RepeatSplitHeaders, RepeatColumnHeaders,
and RepeatColumnFooters properties to True.
If you are developing a non-English application, or an international application, you can use the
SetMenuText method to change the names of the menu commands in the PrintPreview window.
Note
Use the PrintData method to send data directly to the printer without end user intervention.
See Also
PrintInfo Object (page 121)

SetMenuText Method (PrintInfo)

If you are developing an international application, you can use the SetMenuText method to change the
names of the menu commands in the PrintPreview window.
Syntax
PrintInfo.SetMenuText index, string
Arguments
index is a constant that specifies a menu item in the PrintPreview window.
string is the replacement text for the specified menu item.
 SetMenuText Method (PrintInfo) · 687

Return Value
None
Remarks
The index argument can be one of the following constants:
Constant Menu Command
0 - dbgpMenuFile File
1 - dbgpMenuPrint Print
2 - dbgpMenuExit Exit
3 - dbgpMenuView View
4 - dbgpMenuZoomIn Zoom In
5 - dbgpMenuZoomOut Zoom Out
6 - dbgpMenuFit Fit in Window
7 - dbgpMenuPgFirst First Page
8 - dbgpMenuPgPrev Previous Page
9 - dbgpMenuPgNext Next Page
10 - dbgpMenuPgLast Last Page
11 - dbgpMenuPrintSomePages Print Some Pages
12 - dbgpMenuPrintCurrPage Print Current Page
13 - dbgpDlgPagesCaption Print Some Pages dialog caption
14 - dbgpDlgPagesPrompt Print Some Pages dialog prompt
15 - dbgpDlgPagesOk Print Some Pages dialog OK button
text
16 - dbgpDlgPagesCancel Print Some Pages Cancel button text
17 - dbgpTipPrint Print Document
18 - dbgpTipZoomIn Zoom In
19 - dbgpTipZoomOut Zoom Out
20 - dbgpTipFit Fit in Window
21 - dbgpTipZoom Zoom Factor
22 - dbgpTipPgFirst First Page
23 - dbgpTipPgPrev Previous Page
24 - dbgpTipPgNext Next Page
25 - dbgpTipPgLast Last Page
26 - dbgpTipPageOf Current page number
27 - dbgpTipStop Stop Pagination
Use the GetMenuText method to retrieve the text for the specified item.
See Also
PrintInfo Object (page 121)
688 · PrintInfo Reference

SubstituteFont Method (PrintInfo)

This method sets the name of a substitute font to be used for printing if the specified font is unavailable.
Syntax
PrintInfo.SubstituteFont UnavailableFont, [AvailableFont]
Arguments
UnavailableFont is a string that identifies the name of the font to be substituted.
AvailableFont is an optional string that identifies the replacement font.
Return Value
None
Remarks
If the AvailableFont argument is omitted, any prior substitution is discarded.
See Also
PrintInfo Object (page 121)
 Count Property (XArrayDB) · 689

XArrayDB Reference
XArrayDB All Members
XArrayDB Object Properties
Count Returns the number of elements for a given dimension
DefaultColumnType Sets/returns the default data type for the specified column
LowerBound Returns the lower bound for a given dimension
Notify Controls notification of OLEDBSimpleProviderListener objects
Precision Sets/returns the floating point precision value
UpperBound Returns the upper bound for a given dimension
Value Sets/returns the value of an individual array element

XArrayDB Object Methods

AboutBox Displays a dialog box with information about the array object
AppendColumns Appends new columns to an array object
AppendRows Appends new rows to an array object
Clear Deallocates all data associated with an array object
Delete Deletes an index from a given dimension
DeleteColumns Deletes a range of columns from an array object
DeleteRows Deletes a range of rows from an array object
Find Searches for a given value within an array column
Get Returns the value of an array element
Insert Inserts a new index into a given dimension
InsertColumns Inserts new columns into an array object
InsertRows Inserts new rows into an array object
LoadRows Loads a VB array into an XArrayDB object
QuickSort Uses the quicksort method to sort an array
ReDim Sets the dimensions of an array object while preserving its data
Set Assigns a value to an array element

XArrayDB Properties
Count Property (XArrayDB)
This property returns a long integer that specifies the number of elements contained in a given dimension
of an XArrayDB object.
690 · XArrayDB Reference

Syntax
XArrayDB.Count (nDim)
Arguments
nDim is a one-based integer specifying an array dimension.
Remarks
Read-only at run time. Not available at design time.
The value returned is always equal to:
MyArray.UpperBound(nDim) - MyArray.LowerBound(nDim) + 1
The nDim argument should be 1 for rows and 2 for columns. A trappable error occurs if an invalid
dimension is specified.
Example
The following example uses one-based row indexes (the first dimension) and zero-based column indexes
(the second dimension):
MyArray.ReDim 1, 100, 0, 5
Dim N As Long
N = MyArray.Count(1) ' returns 100
N = MyArray.Count(2) ' returns 6
See Also
XArrayDB Object (page 123)

DefaultColumnType Property (XArrayDB)

This property sets or returns the default data type of a column in an XArrayDB object.
Syntax
XArrayDB.DefaultColumnType (column)
Arguments
column is a long integer specifying the index of the column whose default data type is being set or
returned.
Run Time
0 - Default XTYPE_DEFAULT
1 - Boolean XTYPE_BOOLEAN
2 - Byte XTYPE_BYTE
3 - Currency XTYPE_CURRENCY
4 - Date XTYPE_DATE
5 - Double XTYPE_DOUBLE
6 - Integer XTYPE_INTEGER
7 - Long XTYPE_LONG
8 - Single XTYPE_SINGLE
9 - String XTYPE_STRING
 LowerBound Property (XArrayDB) · 691

Remarks
Read-only at run time. Not available at design time.
By default, this property returns 0, which means that the column's data values are not automatically
translated to a specific data type.
When using XArrayDB as an OLEDBSimpleProvider data source, you can set the DefaultColumnType
property so that bound controls can determine the data type of individual columns.
You can also use this property to specify the default data type for a column when using the Find and
QuickSort methods.
See Also
XArrayDB Object (page 123)

LowerBound Property (XArrayDB)

This property returns a long integer that specifies the lower bound index for a given dimension of an
XArrayDB object.
Syntax
XArrayDB.LowerBound (nDim)
Arguments
nDim is a one-based integer specifying an array dimension.
Remarks
Read-only at run time. Not available at design time.
The nDim argument should be 1 for rows and 2 for columns. A trappable error occurs if an invalid
dimension is specified.
Example
The following example uses one-based row indexes (the first dimension) and zero-based column indexes
(the second dimension):
MyArray.ReDim 1, 100, 0, 5
Dim N As Long
N = MyArray.LowerBound(1) ' returns 1
N = MyArray.LowerBound(2) ' returns 0
See Also
XArrayDB Object (page 123)

Notify Property (XArrayDB)

This property sets or returns a boolean that determines whether notifications should be sent to all
OLEDBSimpleProviderListener objects associated with an XArrayDB object.
Syntax
XArrayDB.Notify = boolean
Remarks
Read-only at run time. Not available at design time.
692 · XArrayDB Reference

If True (the default), notifications are sent for row deletions, row insertions, and cell value changes.
If False, all notifications are suppressed.
When using XArrayDB as an OLEDBSimpleProvider data source, you can set the Notify property to
False to suppress notification during initialization or massive updates, then set it back to True to re-enable
listener notifications.
See Also
XArrayDB Object (page 123)

Precision Property (XArrayDB)

This property sets or returns a double that determines the precision used for floating point comparisons
performed during sorting and searching operations.
Syntax
XArrayDB.Precision = double
Remarks
Read-only at run time. Not available at design time.
By default, this property returns 0, and all floating point values stored within an XArrayDB object are
compared as is.
You can set the Precision property to a nonzero value to specify a tolerance for floating point values
processed by the Find and QuickSort methods. If the difference between two values is less than or equal
to the Precision value, then XArrayDB considers them to be equal for comparison purposes.
Example
The following example initializes a single-column XArrayDB object containing double-precision
numbers, then uses the Find method to demonstrate the effect of the Precision property:
MyArray.ReDim 1, 4, 1, 1
MyArray(1, 1) = 198#
MyArray(2, 1) = 150#
MyArray(3, 1) = 200#
MyArray(4, 1) = 250#

' find an exact match for 200#

Debug.Print MyArray.Find(1, 1, 200#) ' prints 3
' change the precision to plus or minus 5
MyArray.Precision = 5#

' find values between 195# and 205#

Debug.Print MyArray.Find(1, 1, 200#) ' prints 1
See Also
XArrayDB Object (page 123)

UpperBound Property (XArrayDB)

This property returns a long integer that specifies the upper bound index for a given dimension of an
XArrayDB object.
 Value Property (XArrayDB) · 693

Syntax
XArrayDB.UpperBound (nDim)
Arguments
nDim is a one-based integer specifying an array dimension.
Remarks
Read-only at run time. Not available at design time.
The nDim argument should be 1 for rows and 2 for columns. A trappable error occurs if an invalid
dimension is specified.
Example
The following example uses one-based row indexes (the first dimension) and zero-based column indexes
(the second dimension):
MyArray.ReDim 1, 100, 0, 5
Dim N As Long
N = MyArray.UpperBound(1) ' returns 100
N = MyArray.UpperBound(2) ' returns 5
See Also
XArrayDB Object (page 123)

Value Property (XArrayDB)

Sets or returns the value of an individual array element.
Syntax
XArrayDB.Value (row, column) = variant
Arguments
row and column are long integer indexes identifying a particular array element.
Remarks
Read/Write at run time. Not available at design time.
The Value property sets or returns the variant value of an individual XArrayDB element. For instance, if
x is a valid row index and y is a valid column index, the following statement assigns a string value to an
individual element:
MyArray.Value(x, y) = "Hello"
Similarly, the following statement retrieves it:
s$ = MyArray.Value(x, y)
Note that the Value property is the default property for XArrayDB. Therefore, the preceding statements
can be shortened to:
MyArray(x, y) = "Hello"
s$ = MyArray(x, y)
Example
Since the elements of an XArrayDB object are true variants, you can arbitrarily mix data types within a
row (or column), as in the following example:
694 · XArrayDB Reference

MyArray(1, 1) = "Hello" ' string

MyArray(1, 2) = 1.98 ' floating point
MyArray(1, 3) = 250000 ' long integer
MyArray(2, 2) = True ' boolean
MyArray(2, 3) = LoadPicture("xyz.bmp") ' bitmap
Note
Although XArrayDB can be used to store picture data, True DBGrid's storage mode (DataMode 4) only
accepts string and numeric data, and will not render XArrayDB picture data as an in-cell graphic.
However, you can use the FetchCellStyle event to display XArrayDB picture data on a per-cell basis.
See Also
XArrayDB Object (page 123)

XArrayDB Methods
AboutBox Method (XArrayDB)
This method displays the version number and copyright notice for XArrayDB.
Syntax
XArrayDB.AboutBox
Arguments
None
Return Value
None
See Also
XArrayDB Object (page 123)

AppendColumns Method (XArrayDB)

This method appends count columns to an XArrayDB object and returns the number of columns
successfully appended.
Syntax
XArrayDB.AppendColumns ([count])
Arguments
count is an optional long integer specifying the number of columns to be appended. If omitted, this
argument defaults to 1.
Return Value
A long integer specifying the number of columns successfully appended.
Remarks
This method is provided for convenience; the following statements are equivalent:
MyArray.AppendColumns n
MyArray.InsertColumns MyArray.UpperBound(2) + 1, n
 AppendRows Method (XArrayDB) · 695

See Also
XArrayDB Object (page 123)

AppendRows Method (XArrayDB)

This method appends count rows to an XArrayDB object and returns the number of rows successfully
appended.
Syntax
XArrayDB.AppendRows ([count])
Arguments
count is an optional long integer specifying the number of rows to be appended. If omitted, this argument
defaults to 1.
Return Value
A long integer specifying the number of rows successfully appended.
Remarks
This method is provided for convenience; the following statements are equivalent:
MyArray.AppendRows n
MyArray.InsertRows MyArray.UpperBound(1) + 1, n
See Also
XArrayDB Object (page 123)

Clear Method (XArrayDB)

This method deallocates all data associated with an XArrayDB object while preserving its dimensions.
Syntax
XArrayDB.Clear
Arguments
None
Return Value
None
Remarks
After the Clear method executes, all of the array elements contain empty variants, and both of the
following Visual Basic expressions evaluate to True for any element:
IsEmpty(element)
VarType(element) = 0
See Also
XArrayDB Object (page 123)
696 · XArrayDB Reference

Delete Method (XArrayDB)

This method deletes the element at position index from the dimension specified by nDim while preserving
data and shifting the indexes of the remaining elements appropriately.
Syntax
XArrayDB.Delete nDim, index
Arguments
nDim is a one-based integer specifying an array dimension.
index is a long integer specifying an element position within the dimension nDim.
Return Value
None
Remarks
The nDim argument should be 1 for rows and 2 for columns. A trappable error occurs if an invalid
dimension is specified.
Note
This method is provided for backward compatibility with the XArray object. Both of the following
statements delete the row whose index is n.
MyArray.Delete 1, n
MyArray.DeleteRows n
Similarly, both of the following statements delete the column whose index is n:
MyArray.Delete 2, n
MyArray.DeleteColumns n
Unlike Delete, the DeleteRows and DeleteColumns methods support the deletion of multiple
contiguous elements.
See Also
XArrayDB Object (page 123)

DeleteColumns Method (XArrayDB)

This method deletes count columns from an XArrayDB object starting at column index and returns the
number of columns successfully deleted.
Syntax
XArrayDB.DeleteColumns (index, [count])
Arguments
index is a long integer specifying the index of the first column to be deleted.
count is an optional long integer specifying the number of columns to be deleted. If omitted, this
argument defaults to 1.
Return Value
A long integer specifying the number of columns successfully deleted.
 DeleteRows Method (XArrayDB) · 697

Example
The following example initializes an XArrayDB object with 10 rows and 6 columns, then removes the
fourth and fifth columns:
MyArray.ReDim 1, 10, 1, 6
Dim i, j As Integer
For i = 1 To 10
For j = 1 To 6
MyArray(i, j) = "Row " & i & ", Col " & j
Next j
Next i
Debug.Print MyArray(1, 4) ' prints Row 1, Col 4
Debug.Print MyArray(1, 5) ' prints Row 1, Col 5
' remove two columns starting at index 4
Dim result As Long
result = MyArray.DeleteColumns(4, 2)
Debug.Print result ' prints 2
Debug.Print MyArray.Count(2) ' prints 4
Debug.Print MyArray(1, 4) ' prints Row 1, Col 6
' the next line now gives a "Subscript out of range" error
Debug.Print MyArray(1, 5)
See Also
XArrayDB Object (page 123)

DeleteRows Method (XArrayDB)

This method deletes count rows from an XArrayDB object starting at row index and returns the number of
rows successfully deleted.
Syntax
XArrayDB.DeleteRows (index, [count])
Arguments
index is a long integer specifying the index of the first row to be deleted.
count is an optional long integer specifying the number of rows to be deleted. If omitted, this argument
defaults to 1.
Return Value
A long integer specifying the number of rows successfully deleted.
Example
The following example initializes an XArrayDB object with 10 rows and 6 columns, then removes the first
three rows:
MyArray.ReDim 1, 10, 1, 6
Dim i, j As Integer
For i = 1 To 10
For j = 1 To 6
MyArray(i, j) = "Row " & i & ", Col " & j
Next j
Next i
Debug.Print MyArray(1, 1) ' prints Row 1, Col 1
Debug.Print MyArray(2, 1) ' prints Row 2, Col 1
Debug.Print MyArray(8, 1) ' prints Row 8, Col 1
698 · XArrayDB Reference

' remove three rows starting at index 1

Dim result As Long
result = MyArray.DeleteRows(1, 3)
Debug.Print result ' prints 3
Debug.Print MyArray.Count(1) ' prints 7
Debug.Print MyArray(1, 1) ' prints Row 4, Col 1
Debug.Print MyArray(2, 1) ' prints Row 5, Col 1
' the next line now gives a "Subscript out of range" error
Debug.Print MyArray(8, 1)
See Also
XArrayDB Object (page 123)

Find Method (XArrayDB)

The Find method searches for a specified value within a column of an XArrayDB object, starting at a
particular row.
Syntax
XArrayDB.Find (row, column, value, [order], [comparison], [type])
Arguments
row is a long integer specifying the starting row of the search.
column is a long integer specifying the column to be searched.
value is a variant specifying the value to search for.
order is an XORDER constant that specifies the direction of the search. If omitted, XORDER_ASCEND is
assumed.
comparison is an XCOMP constant that specifies the kind of comparison to be performed. If omitted,
XCOMP_EQ is assumed.
type is an XTYPE constant that specifies the data type used to coerce column values during comparison. If
omitted, XTYPE_DEFAULT is assumed, which means that the data type of the value argument is used.
Return Value
A long integer corresponding to the index of the next row that contains a matching value. If no match is
found, the value returned is one less than the lower bound for rows specified in the previous call to the
ReDim method.
Remarks
If a match is found, this method returns the corresponding row index; otherwise, the value returned is
equal to:
LowerBound(1) - 1
Example
The following example demonstrates the use of the Find method on a single-column XArrayDB object
containing long integers:
MyArray.ReDim 1, 4, 1, 1
MyArray(1, 1) = 198
MyArray(2, 1) = 150
MyArray(3, 1) = 200
 Get Method (XArrayDB) · 699

MyArray(4, 1) = 250
' search for the value 200
Debug.Print MyArray.Find(1, 1, 200) ' prints 3
' search for a value less than 200
Debug.Print MyArray.Find(1, 1, 200, , XCOMP_LT) ' prints 1
See Also
XArrayDB Object (page 123)

Get Method (XArrayDB)

The Get method provides an alternate way of retrieving a value from an XArrayDB element.
Syntax
XArrayDB.Get row, column, var
Arguments
row and column are long integer indexes identifying a particular array element.
var is a variable that receives a variant value from the specified array element.
Return Value
None
Remarks
You can use this method in scripting engines that do not properly resolve the default Value property of
XArrayDB.
The var argument receives the variant value of the XArrayDB element specified by the row and column
indexes.
Example
The three statements following the variable declaration are all equivalent:
Dim var As Variant
MyArray.Get x, y, var
var = MyArray.Value(x, y)
var = MyArray(x, y)
See Also
XArrayDB Object (page 123)

Insert Method (XArrayDB)

This method inserts a new element at position index into the dimension specified by nDim while
preserving data and shifting the indexes of the existing elements appropriately.
Syntax
XArrayDB.Insert nDim, index
Arguments
nDim is a one-based integer specifying an array dimension.
700 · XArrayDB Reference

index is a long integer specifying an element position within the dimension nDim.
Return Value
None
Remarks
The nDim argument should be 1 for rows and 2 for columns. A trappable error occurs if an invalid
dimension is specified.
If index is greater than the value of the UpperBound property for dimension nDim, then UpperBound is
adjusted to the new index.
Note
This method is provided for backward compatibility with the XArray object. Both of the following
statements insert a new row at index position n.
MyArray.Insert 1, n
MyArray.InsertRows n
Similarly, both of the following statements insert a new column at index position n:
MyArray.Insert 2, n
MyArray.InsertColumns n
Unlike Insert, the InsertRows and InsertColumns methods support the insertion of multiple contiguous
elements.
See Also
XArrayDB Object (page 123)

InsertColumns Method (XArrayDB)

Inserts new columns into an array object.
Syntax
XArrayDB.InsertColumns (index, [count])
Arguments
index is a long integer specifying the index of the first column to be inserted.
count is an optional long integer specifying the number of columns to be inserted. If omitted, this
argument defaults to 1.
Return Value
A long integer specifying the number of columns successfully inserted.
Remarks
This method inserts count columns into an XArrayDB object starting at column index and returns the
number of columns successfully inserted.
Example
The following example initializes an XArrayDB object with 10 rows and 6 columns, then inserts a new
column before the fourth column:
MyArray.ReDim 1, 10, 1, 6
Dim i, j As Integer
 InsertRows Method (XArrayDB) · 701

For i = 1 To 10
For j = 1 To 6
MyArray(i, j) = "Row " & i & ", Col " & j
Next j
Next i
Debug.Print MyArray(1, 4) ' prints Row 1, Col 4
Debug.Print MyArray(1, 5) ' prints Row 1, Col 5
' insert a new column at index 4
Dim result As Long
result = MyArray.InsertColumns(4)
Debug.Print result ' prints 1
Debug.Print MyArray.Count(2) ' prints 7
Debug.Print IsEmpty(MyArray(1, 4)) ' prints True
Debug.Print MyArray(1, 5) ' prints Row 1, Col 4
Debug.Print MyArray(1, 6) ' prints Row 1, Col 5
See Also
XArrayDB Object (page 123)

InsertRows Method (XArrayDB)

This method inserts count rows into an XArrayDB object starting at row index and returns the number of
rows successfully inserted.
Syntax
XArrayDB.InsertRows (index, [count])
Arguments
index is a long integer specifying the index of the first row to be inserted.
count is an optional long integer specifying the number of rows to be inserted. If omitted, this argument
defaults to 1.
Return Value
A long integer specifying the number of rows successfully inserted.
Example
The following example initializes an XArrayDB object with 10 rows and 6 columns, then inserts three
new rows before the first row:
MyArray.ReDim 1, 10, 1, 6
Dim i, j As Integer
For i = 1 To 10
For j = 1 To 6
MyArray(i, j) = "Row " & i & ", Col " & j
Next j
Next i
Debug.Print MyArray(1, 1) ' prints Row 1, Col 1
Debug.Print MyArray(2, 1) ' prints Row 2, Col 1
Debug.Print MyArray(10, 1) ' prints Row 10, Col 1
' insert three new rows at index 1
Dim result As Long
result = MyArray.InsertRows(1, 3)
Debug.Print result ' prints 3
Debug.Print MyArray.Count(1) ' prints 13
Debug.Print IsEmpty(MyArray(1, 1)) ' prints True
Debug.Print MyArray(4, 1) ' prints Row 1, Col 1
702 · XArrayDB Reference

Debug.Print MyArray(5, 1) ' prints Row 2, Col 1

Debug.Print MyArray(13, 1) ' prints Row 10, Col 1
See Also
XArrayDB Object (page 123)

LoadRows Method (XArrayDB)

This method populates an XArrayDB object from a two-dimensional variant array.
Syntax
XArrayDB.LoadRows array, [transpose]
Arguments
array is a variant array containing the data to be loaded.
transpose is an optional boolean argument that determines whether the array data should be transposed.
Return Value
None
Remarks
Typically, the array is derived from a data provider such as ADO or RDO, but it can also be a standard
Visual Basic array..
If the transpose argument is True (default), the array elements are copied in row-major order. If transpose
is False, or omitted, the array elements are copied in column-major order. The argument should be False if
you are using the GetRows method (of the ADO Recordset), and True if you are using a standard Visual
Basic array.
Example
The following example copies ten rows of data from a DAO Recordset to an XArrayDB object in column-
major order, then associates the XArrayDB object with a TDBGrid control. Note that it is not necessary to
invoke the ReDim method when using LoadRows:
Dim MyArray As New XArrayDB
Data1.Recordset.MoveFirst
MyArray.LoadRows Data1.Recordset.GetRows(10)
Set TDBGrid1.Array = MyArray
TDBGrid1.ReBind
See Also
XArrayDB Object (page 123)

QuickSort Method (XArrayDB)

Uses the quicksort method to sort an array.
Syntax
XArrayDB.QuickSort rowstart, rowend, column1, order1, type1 [, …, column10, order10, type10]
 ReDim Method (XArrayDB) · 703

Arguments
rowstart is a long integer specifying the first row to be sorted.
rowend is a long integer specifying the last row to be sorted.
column1 through column10 are long integers specifying the indexes of the columns to be sorted, in the
order in which they are applied.
order1 through order10 are XORDER constants specifying the sort order of the columns.
type1 through type10 are XTYPE constants specifying the data type used to coerce column values during
comparison.
Return Value
None
Remarks
The QuickSort method sorts a range of rows in an XArrayDB object according to the specified column(s).
The optional arguments must be specified in groups of three. That is, if you supply a column argument,
you must supply its order and type arguments as well. You must provide at least one argument triplet,
otherwise a trappable error will occur.
Example
The following example initializes a single-column XArrayDB object containing date values in a variety of
formats, then uses the QuickSort method to reorder the array in ascending order:
MyArray.ReDim 1, 4, 1, 1
MyArray(1, 1) = DateSerial(1998, 2, 11) ' date
MyArray(2, 1) = "January 22, 1998" ' string
MyArray(3, 1) = #10/4/1998# ' date literal
MyArray(4, 1) = CLng(#1/27/1998#) ' long integer

' sort all rows of the array

MyArray.QuickSort 1, 4, 1, XORDER_ASCEND, XTYPE_DATE

' print the results

Debug.Print MyArray(1, 1) ' prints January 22, 1998
Debug.Print MyArray(2, 1) ' prints 35822
Debug.Print MyArray(3, 1) ' prints 2/11/98
Debug.Print MyArray(4, 1) ' prints 10/4/98
See Also
XArrayDB Object (page 123)

ReDim Method (XArrayDB)

Sets the dimensions of an array object while preserving its data.
Syntax
XArrayDB.ReDim rowLB, rowUB, columnLB, columnUB
Arguments
rowLB and rowUB are long integers specifying the lower and upper bounds for row indexes.
columnLB and columnUB are long integers specifying the lower and upper bounds for column indexes.
704 · XArrayDB Reference

Return Value
None
Remarks
This method is used to set or reset the dimensions of an XArrayDB object while preserving any existing
data. Since a newly created XArrayDB object does not have any default dimensions, you must use the
ReDim method before you can assign or access array elements.
Example
The following example creates and initializes a two-dimensional XArrayDB object. The first dimension
has 100 elements, with indexes starting at 1 and ending at 100. The second dimension has 6 elements,
with indexes starting at 0 and ending at 5.
Dim MyArray As New XArrayDB
MyArray.ReDim 1, 100, 0, 5
See Also
XArrayDB Object (page 123)

Set Method (XArrayDB)

The Set method provides an alternate way of assigning a value to an XArrayDB element.
Syntax
XArrayDB.Set row, column, value
Arguments
row and column are long integer indexes identifying a particular array element.
value is a variant to be assigned to the specified array element.
Return Value
None
Remarks
You can use this method in scripting engines that do not properly resolve the default Value property of
XArrayDB.
The value argument is the variant value to be assigned to the XArrayDB element specified by the row and
column indexes.
Example
The following three statements are equivalent:
MyArray.Set x, y, "Hello"
MyArray.Value(x, y) = "Hello"
MyArray(x, y) = "Hello"
See Also
XArrayDB Object (page 123)
 XArrayDB Object Constants · 705

XArrayDB Object Constants

XCOMP
Description Run Time
1 - Equal XCOMP_EQ
2 - Less Than XCOMP_LT
3 - Less Than or Equal To XCOMP_LE
4 - Greater Than XCOMP_GT
5 - Greater Than or Equal To XCOMP_GE
6 - Not Equal To XCOMP_NE
The XCOMP constants are used to specify a comparison operator for the Find method.
XORDER
Description Run Time
0 - Ascending XORDER_ASCEND
1 - Descending XORDER_DESCEND
The XORDER constants are used to specify a search direction for the Find method and a sort order for the
QuickSort method.
XTYPE
Description Run Time
0 - Default XTYPE_DEFAULT
1 - Boolean XTYPE_BOOLEAN
2 - Byte XTYPE_BYTE
3 - Currency XTYPE_CURRENCY
4 - Date XTYPE_DATE
5 - Double XTYPE_DOUBLE
6 - Integer XTYPE_INTEGER
7 - Long XTYPE_LONG
8 - Single XTYPE_SINGLE
9 - String XTYPE_STRING
10 - Case-sensitive Find or QuickSort XTYPE_STRINGCASESENSITIVE
11 - Numeric Find or QuickSort XTYPE_NUMBER
The XTYPE constants are used to specify the data type of a column for the Find and QuickSort methods
and the DefaultColumnType property.

Index
A
AboutBox method 489, 614, 696
of TDBDropDown 614
of TDBGrid 489
of XArrayDB 696
Add method 489
AddCellStyle method 490, 614
of TDBDropDown 614
Adding 21, 190
columns 21
records 190
AddNewMode constants 651
AddNewMode property 363
AddRegexCellStyle method 491, 615
of TDBDropDown 615
AfterColEdit event 527
AfterColUpdate event 527
AfterDelete event 528
AfterInsert event 528
AfterUpdate event 529
Alignment 260
Alignment constants 651
Alignment property 364
AllowAddNew property 364
AllowArrows property 365
AllowColMove property 365, 579
of TDBDropDown 579
AllowColSelect property 366, 579
of TDBDropDown 579
AllowDelete property 366
AllowFocus property 367
AllowRowSelect property 368
AllowRowSizing property 368, 580
of TDBDropDown 580
AllowSizing property 369
AllowUpdate property 369
Alternating row colors 259
AlternatingRowStyle property 370, 581
of TDBDropDown 581
AnchorRightColumn property 370, 581
of TDBDropDown 581
AnimateWindow constants 651
AnimateWindow property 371
AnimateWindowClose constants 652
AnimateWindowClose property 372
AnimateWindowDirection constants 652
Index · 707
AnimateWindowDirection property 373
AnimateWindowTime property 374
Animation 261
AnnotatePicture property 374
Appearance 247, 249
Appearance constants 652
Appearance property 375, 582
of TDBDropDown 582
AppendColumns method 696
of XArrayDB 696
AppendRows method 697
of XArrayDB 697
application mode 16, 211, 212, 214, 215, 216, 217
adding records 216
bookmarks 212
deleting records 216, 217
events 214
example of 217
refreshing the display 216
reinitializing the grid 217
supplying bookmarks 214
supplying data 215
updating records 215, 217
ApproxCount property 375, 582
of TDBDropDown 582
Array property 376, 583
of TDBDropDown 583
ASCII text file 505
AutoCompletion property 376
AutoDropDown property 377
AutoSize method 493
B
BackColor property 377, 583
of TDBDropDown 583
BackgroundPicture property 378
BackgroundPictureDrawMode constants 652
BackgroundPictureDrawMode property 378
Bands property 379
BatchUpdates property 379
BeforeColEdit event 529
BeforeColUpdate event 530
BeforeDelete event 530
BeforeInsert event 531
BeforeOpen event 531
BeforeRowColChange event 532
BeforeUpdate event 532
708 · Index
Bitmaps 269, 326, 327, 329
and styles 326, 327, 329
and text 269
BOF 236
BOF property 380
Bookmark property 380, 381, 584
of RowBuffer 380
of TDBDropDown 584
bookmarks 23, 212, 213, 221, 235, 237
in application mode 212
in True DBGrid 213
in unbound mode 221
in Visual Basic 213
retrieving 237
BookmarkType property 381, 584
of TDBDropDown 584
BorderAppearance property 382
BorderColor property 383
Borders 251
BorderSize property 383
BorderStyle constants 653
BorderStyle property 383, 585
of TDBDropDown 585
BorderType property 383
Bound mode 15, 195, 196, 197, 198
Recordset changes in 197
Built-in controls 336, 341, 342
combo box 341, 342
drop-down text editor 336
Button property 384
ButtonAlways property 385
ButtonClick event 533
ButtonFooter property 385
ButtonHeader property 386
ButtonPicture property 386
Buttons 273, 339, 340, 345
bitmaps 340
detecting clicks 340
in-cell 339, 340, 345
ButtonText property 387
C
Caption property 387
Captions 247, 248, 249
multiline 248
of columns 247
of grids 247
of splits 249
CaptionStyle property 388
CaptureImage method 494, 617
of TDBDropDown 617
Cell status values 322
Cell styles 321, 322, 323, 324, 326
by contents 323
by custom criteria 324
by status 322
evaluation order 326
Cell tips 274
CellContaining method 494
Cells 184, 190, 236, 237, 254, 255, 333, 334, 335, 336
contents of 334
editing 190, 333, 334, 335, 336
highlighting 254, 255
merged 276
modification status 333
owner-drawn 285
reading data 236
reading data from non-current records 236
restricting navigation 184
validating data 237
writing data 236
CellStyle constants 653
CellText method 495
CellTip constants 653
CellTipPresentation constants 654
CellTips property 388
CellTipsDelay property 389
CellTipsWidth property 390
CellTop property 390
CellValue method 495
Change event 533
Child grids 281
ChildGrid property 391
ClassicAdd event 534
ClassicDelete event 534
ClassicRead event 535, 626
of TDBDropDown 626
ClassicWrite event 535
Clear method 496, 497, 697
of DataObject 496
of Errors 497
of ValueItems 496
of XArrayDB 697
ClearCellStyle method 497, 618
of TDBDropDown 618
ClearFields method 498, 618
of TDBDropDown 618
ClearRegexCellStyle method 498, 619
of TDBDropDown 619
ClearSelCols method 499, 619
of TDBDropDown 619
Click event 536, 627
 Index · 709

of TDBDropDown 627 removing 21

Close method 499 rightmost 182, 252
Col property 391, 586 selecting 132, 184
of TDBDropDown 586 setting properties of 19, 20, 22
ColContaining method 500, 620 sizing 131, 188
of TDBDropDown 620 split-specific properties 298
ColEdit event 537 Columns collection 119
ColIndex property 392 Columns property 394, 587
Collapse event 537 of TDBDropDown 587
CollapseBand method 501 Combo box 341, 342
CollapseChild method 501 built-in 341
CollapseColor property 391 detecting selections 342
Collate property 668 ComboSelect event 539
of PrintInfo 668 Constants 651, 707
Collections 119, 120, 121, 122, 123 of XArrayDB 707
Columns 119 Context menu 129
Errors 120 Context-sensitive help 274
GroupColumns 120 ConvertEmptyCell constants 654
Layouts 121 ConvertEmptyCell property 394
PrintInfos 121 Count property 395, 692
SelBookmarks 121 of collection 395
Splits 122 of XArrayDB 692
Styles 122 Creating splits 131
ValueItems 123 CurrentCellModified property 395
working with 123 CurrentCellVisible property 396, 587
ColMove event 538, 627 of TDBDropDown 587
of TDBDropDown 627 CycleOnClick property 396
ColResize event 538, 628
of TDBDropDown 628
D
Column bindings 19
Column layouts 16 Data binding 195, 196
Column object 119, 297, 298 ICursor 196
global properties 297 OLE DB 196
split-specific properties 298 Data control 196, 197, 198
ColumnCount property 392 on another form 198
ColumnFooters property 392, 586 Data modes 15, 16
of TDBDropDown 586 application 16
ColumnHeaders property 393, 586 bound 15
of TDBDropDown 586 storage 16
ColumnIndex property 393 unbound 16
ColumnName property 393 Data presentations 263, 265, 269, 272, 273
Columns 16, 17, 19, 20, 21, 22, 131, 132, 182, 184, 185, 188, check boxes 272
251, 252, 297, 298, 305 graphics and text 269
adding 21 merged cells 276
configuring at design time 17 radio buttons 273
configuring at run time 20 Data sources 15, 279, 281
dividing lines 251 Data translations 265, 266, 268
fixed 305 text-to-picture 268
global properties 297 text-to-text 266
moving 132, 185 Data validation 239
nonscrolling 305 Data views 278, 279, 281, 284
referencing 22 form 284
710 · Index

group 278 removing layouts 180

hierarchical 279, 281 saving layouts 179
inverted 284 TDBDropDown control 180
Database fields 19 visual editing 130
Database programming 235 DestinationCol property 404
DataChanged property 397 DestinationRow property 404
DataField property 397, 588 DestinationSplit property 405
of Column 397 DirectionAfterEnter property 406
of TDBDropDown 588 DirectionAfterTab property 406
DataMember property 398, 588 DisplayAlignment property 407
of TDBDropDown 588 DisplayValue property 408
DataMode constants 654 DividerColor property 408
DataMode property 398, 589 Dividers 251
of TDBDropDown 589 DividerStyle constants 655
DataObject object 119 DividerStyle property 408
DataSource property 399, 589 Draft property 669
of TDBDropDown 589 of PrintInfo 669
DataSourceChanged event 539, 628 Drag-and-drop 191
of TDBDropDown 628 DragCell event 540
DataView constants 655 Drop-down controls 118, 341, 342, 343, 344
DataView property 399 DropDown property 409
DataWidth property 400 DropDownClose event 629
Date masks 338 DropDownList property 410
DblClick event 540, 629 DropDownOpen event 630
of TDBDropDown 629
DeadAreaBackColor property 401, 590
E
of TDBDropDown 590
Default property 669 Edit masks 264, 337, 338
of PrintInfo 669 date fields 338
DefaultColumnType property 692 formatting with 338
of XArrayDB 692 updating 338
DefaultItem property 401 EditActive property 410
DefaultValue property 402 EditBackColor property 410
DefColWidth property 403, 590 EditDropDown property 411
of TDBDropDown 590 EditForeColor property 411
Delete method 502, 698 editing 190, 333, 334, 337
of TDBGrid 502 EditMask property 412
of XArrayDB 698 EditMaskRight property 413
DeleteColumns method 698 EditMaskUpdate property 413
of XArrayDB 698 Editor 256, 336
DeleteRows method 699 drop-down 336
of XArrayDB 699 floating 256
Deleting 21, 191, 241 EditorStyle property 414
columns 21 EllipsisText property 414
records 191, 241 EmptyRows property 415, 591
Delimited text file 505 of TDBDropDown 591
Description property 403 Enabled property 415, 592
Design time 129, 130, 147, 154, 155, 162, 166, 168, 171, 175, of TDBDropDown 592
178, 179, 180 EOF 236
context menu 129 EOF property 415
loading layouts 179 Error constants 655
property pages 147, 154, 155, 162, 166, 168, 171, 175, 178 Error event 541, 630
 Index · 711

of TDBDropDown 630 of XArrayDB 700

Errors 243, 244, 655
Errors property 416
ErrorText property 416, 592
of TDBDropDown 592
EvenRowStyle property 417, 592
of TDBDropDown 592
Events 245, 334, 335
editing 334, 335
keystroke 334
posting 245
Expand event 541
ExpandBand method 502
ExpandChild method 503
ExpandColor property 417
ExportBegin method 503
ExportEnd method 504
ExportEOF property 417
ExportNextBookmark property 418
ExportRows method 504
ExportToDelimitedFile method 505
ExportToFile method 506
ExposeCellMode constants 656
ExposeCellMode property 418
ExtendRightColumn property 419, 593
of TDBDropDown 593
ExternalEditor property 419
F
FetchCellStyle constants 657
FetchCellStyle event 542, 631
of TDBDropDown 631
FetchCellTips event 542
FetchRowStyle event 544, 632
of TDBDropDown 632
FetchRowStyle property 420, 593
of TDBDropDown 593
FetchScrollTips event 544, 632
of TDBDropDown 632
FetchStyle property 420
Files property 421
Filter bar 288
FilterActive property 422
FilterBar property 422
FilterBarStyle property 422
FilterButton property 423
FilterButtonClick event 546
FilterButtonPicture property 423
FilterChange event 546
FilterText property 423
Find method 700
FirstRow property 424, 594
of TDBDropDown 594
FirstRowChange event 545, 633
of TDBDropDown 633
Fix method 507
fixed columns 305
Flat displays 249
Floating editor 256
Font property 424, 594
of TDBDropDown 594
FootClick event 546, 633
of TDBDropDown 633
FooterAlignment property 425
FooterBackColor property 425, 595
of TDBDropDown 595
FooterDivider property 426
FooterFont property 426, 595
of TDBDropDown 595
FooterForeColor property 426, 596
of TDBDropDown 596
Footers 247, 248
FooterStyle property 427, 596
of TDBDropDown 596
FooterText property 427
FootLines property 428, 597
of TDBDropDown 597
ForeColor property 428, 597
of TDBDropDown 597
ForegroundPicture property 429
ForegroundPicturePosition constants 657
ForegroundPicturePosition property 429
Form view 284
FormatText event 546, 634
of TDBDropDown 634
Formatting text 263, 264, 265, 338
using an event handler 265
using input masks 338
G
Get method 701
of XArrayDB 701
GetBand method 507
GetBookmark method 508, 621
of TDBDropDown 621
GetData method 508
GetFormat method 509
GetMenuText method 685
of PrintInfo 685
GetSubstituteFont method 686
of PrintInfo 686
712 · Index

Graphics and text 269 Input validation 237

Group property 430 Insert method 702
GroupByCaption property 430 of XArrayDB 702
GroupColMove event 547 InsertColumns method 702
GroupColumns property 430 of XArrayDB 702
GroupHeadClick event 548 Insertion mode 337
Grouping 278 InsertMode property 438
InsertRows method 703
of XArrayDB 703
H
IntegralHeight property 601
HeadAlignment property 431 IntelliMouse 182
HeadBackColor property 431, 598 Inverted view 284
of TDBDropDown 598 IsSelected method 510
HeadClick event 548, 634 Item method 510
of TDBDropDown 634
HeaderDivider property 432
Headers 247, 248 K
HeadFont property 432, 598 KeyDown event 548, 635
of TDBDropDown 598 of TDBDropDown 635
HeadForeColor property 433, 599 KeyPress event 549, 635
of TDBDropDown 599 of TDBDropDown 635
HeadingStyle property 433, 599 KeyUp event 550, 636
of TDBDropDown 599 of TDBDropDown 636
HeadLines property 433, 599
of TDBDropDown 599
L
HelpContext property 434
HelpFile property 434 LayoutFileName property 439, 601
Hierarchical data display 279, 281 of TDBDropDown 601
HighlightRowStyle property 435, 600 LayoutName property 439, 602
of TDBDropDown 600 of TDBDropDown 602
HoldFields method 509, 621 LayoutReady event 550, 636
of TDBDropDown 621 of TDBDropDown 636
Horizontal alignment 260 Layouts 16, 17, 179, 180
HScrollHeight property 435 automatic 16
hWnd property 436, 600 customized 17
of TDBDropDown 600 design-time 179
hWndEditor property 436 loading 179
removing 180
run-time 17, 179
I saving 179
ICursor 196 switching between types 17
InactiveBackColor property 437 Layouts collection 121
InactiveForeColor property 437 Layouts property 440, 602
InactiveStyle property 438 of TDBDropDown 602
In-cell buttons 339, 340, 345 LayoutURL property 440, 602
bitmaps 340 of TDBDropDown 602
detecting clicks 340 Left property 441
Index property 438 LeftCol property 441, 603
Input masks 264, 337, 338 of TDBDropDown 603
date fields 338 LeftColChange event 551, 637
formatting with 338 of TDBDropDown 637
updating 338 ListField property 604
 Index · 713

LoadLayout method 511 MultiSelect property 449

LoadRows method 704
of XArrayDB 704
N
Locked property 442
LowerBound property 693 Name property 449, 450, 669
of XArrayDB 693 of Column 449
of PrintInfo 669
of Style 450
M NativeError property 450
Marquee 254, 255, 256, 257 Navigation 181, 182, 183, 184, 235, 306
disabling 256 across splits 306
dotted cell 254 at row boundaries 183
dotted row 257 at split boundaries 184
floating editor 256 IntelliMouse 182
highlight cell 255 keyboard 182
highlight row 255 mouse 181
solid cell 254 restricting 184
MarqueeStyle constants 657 NeedTotalPageCount property 670
MarqueeStyle property 442 of PrintInfo 670
MarqueeUnique property 444 NoClipping property 670
Master-detail relationships 242, 279, 281 of PrintInfo 670
MatchCase property 444 Nonscrolling columns 305
MaxComboItems property 445 Notify property 694
MaxRows property 445 of XArrayDB 694
Menu constants 685, 687, 688 Number property 450
Menus 129, 132 NumberFormat property 451
context 129 NumberOfCopies property 670
visual editing 132 of PrintInfo 670
Merge property 445
MergeCell constants 658
O
Merged cells 276
MinWidth property 446 Object model 117, 140
MouseDown event 551, 638 Objects 118, 119, 120, 121, 122, 123
of TDBDropDown 638 Column 119
MouseIcon property 446 DataObject 119
MouseMove event 552, 638 Error 120
of TDBDropDown 638 PrintInfo 121
MousePointer constants 658 RowBuffer 121
MousePointer property 447 Split 122
MouseUp event 553, 639 Style 122
of TDBDropDown 639 TDBDropDown 118
MoveDirection constants 659 TDBGrid 118
MoveFirst method 511 ValueItem 123
MoveLast method 512 working with 123
MoveNext method 512 XArrayDB 123
MovePrevious method 512 OddRowStyle property 452, 604
MoveRelative method 513 of TDBDropDown 604
Moving columns 132 OLE DB 196, 381, 398, 399, 539
Multiline displays 257, 258, 259 OLECompleteDrag event 553
MultipleLines constants 659 OLEDrag method 513
MultipleLines property 447 OLEDragDrop event 554
MultiSelect constants 659 OLEDragMode constants 659
714 · Index
OLEDragMode property 453
OLEDragOver event 555
OLEDropMode constants 660
OLEDropMode property 453
OLEGiveFeedback event 556
OLESetData event 557
OLEStartDrag event 557
OnAddNew event 558
OnInit event 558
Option buttons 273
Order property 454
Outlook-style grouping 278
Overviews 15
OwnerDraw property 454
OwnerDrawCell event 559
OwnerDrawCellPrint event 560
Owner-drawn cells 285
OwnerDrawPageFooter event 560
OwnerDrawPageHeader event 561
P
PageFooter property 671
of PrintInfo 671
PageFooterFont property 672
of PrintInfo 672
PageFooterHeight property 672
of PrintInfo 672
PageFooterOwnerDraw property 672
of PrintInfo 672
PageHeader property 673
of PrintInfo 673
PageHeaderFont property 674
of PrintInfo 674
PageHeaderHeight property 674
of PrintInfo 674
PageHeaderOwnerDraw property 674
of PrintInfo 674
PageSetup method 686
of PrintInfo 686
PageSetupCancelled property 674
of PrintInfo 674
Paint event 562, 640
of TDBDropDown 640
Parent property 455
PartialRightColumn property 455, 605
of TDBDropDown 605
PictureAddNewRow property 456
PictureCurrentRow property 456
PictureFilterBar property 457
PictureFooterRow property 457
PictureHeaderRow property 458
PictureModifiedRow property 458
Pictures 269, 326, 327, 329
and styles 326, 327, 329
and text 269
PictureStandardRow property 459
PointAt constants 660
PointAt method 514
Posted events 245
PostEvent event 563, 640
of TDBDropDown 640
PostMsg method 514, 622
of TDBDropDown 622
Precision property 694
of XArrayDB 694
Presentation constants 660
Presentation property 459
PreviewAllowFileOps property 675
of PrintInfo 675
PreviewCaption property 675
of PrintInfo 675
PreviewInitHeight property 676
of PrintInfo 676
PreviewInitPosX property 676
of PrintInfo 676
PreviewInitPosY property 676
of PrintInfo 676
PreviewInitScreenFill property 676
of PrintInfo 676
PreviewInitWidth property 677
of PrintInfo 677
PreviewInitZoom property 677
of PrintInfo 677
PreviewMaximize property 677
of PrintInfo 677
PreviewPageOf property 678
of PrintInfo 678
PrintData method 687
of PrintInfo 687
PrintInfo object 121
PrintInfo property 460
PrintInfo_Menu constants 661
PrintInfos collection 121
PrintInfos property 460
PrintPreview menu text 661, 685, 688
PrintPreview method 687
of PrintInfo 687
Property pages 135, 147, 154, 155, 162, 166, 168, 171, 175, 178
TDBDropDown control 171
TDBGrid control 147
Property trees 136, 141, 142, 144
editing 137, 138, 139, 140
 Index · 715

Q of TDBDropDown 606
RowBookmark method 522, 624
QuickSort method 705
of TDBDropDown 624
of XArrayDB 705
RowBuffer object 121, 221
using 221
R RowChange event 641
Radio buttons 273 RowColChange event 563
RangeOfPages property 678 RowContaining method 523, 625
of PrintInfo 678 of TDBDropDown 625
ReBind method 515, 622 RowCount property 463
of TDBDropDown 622 RowDividerColor property 463, 606
Records 187, 190, 191, 235, 240, 241 of TDBDropDown 606
adding 190 RowDividerStyle property 464, 607
deleting 191, 241 of TDBDropDown 607
positioning 235 RowExpanded method 523
selecting 187, 240 RowHeight property 464, 607
updating 241 of TDBDropDown 607
RecordSelectors property 460 RowResize event 564, 641
RecordSelectorStyle property 461 of TDBDropDown 641
RecordSelectorWidth property 461 Rows 131, 187, 188, 190, 191, 240, 241, 251, 252, 253, 254, 255,
ReDim method 705 257, 258, 259
of XArrayDB 705 adding 190
Reference 651, 667, 691 alternating colors 259
Refetch method 516 deleting 191, 241
RefetchCell method 517 dividing lines 251
RefetchCol method 517 height of 257
Refetching data 242 highlighting 254, 255
RefetchRow method 518 multiple lines in 257, 258
Refresh method 518, 623 selecting 187, 240
of TDBDropDown 623 sizing 131, 188
RefreshCell method 519 unused 252, 253
RefreshCol method 519 updating 241
Refreshing the display 241 RowSelector constants 506, 663, 687
RefreshRow method 520 RowSubDividerColor property 465
Remove method 520 RowTop method 524, 625
Removing 21, 296 of TDBDropDown 625
columns 21 RowTracking property 608
splits 296 Run time 181, 184, 188, 190, 192
ReOpen method 521
RepeatColumnFooters property 679 S
of PrintInfo 679
Scroll bars 234, 276, 304
RepeatColumnHeaders property 679
Scroll event 565, 642
of PrintInfo 679
of TDBDropDown 642
RepeatGridHeader property 680
Scroll method 524, 626
of PrintInfo 680
of TDBDropDown 626
RepeatSplitHeaders property 680
ScrollBars constants 663
of PrintInfo 680
ScrollBars property 465, 608
Reset method 522
of TDBDropDown 608
RightToLeft property 462, 605
ScrollGroup property 466
of TDBDropDown 605
Scrolling 181, 276
Row property 462, 606
ScrollTips property 466, 609
716 · Index
of TDBDropDown 609
ScrollTrack property 467, 609
of TDBDropDown 609
Searching 81, 700
in storage mode 81, 700
SelBookmarks collection 121
SelBookmarks property 467
SelChange event 565, 642
of TDBDropDown 642
SelectedBackColor property 467
SelectedForeColor property 468
SelectedItem property 610
SelectedStyle property 468
Selecting 132, 184, 187, 240, 337
columns 132, 184
records 187, 240
rows 187, 240
text 337
SelEndCol property 468, 610
of TDBDropDown 610
SelLength property 469
SelRange property 469
SelStart property 469
SelStartCol property 470, 611
of TDBDropDown 611
SelText property 470
Set method 706
of XArrayDB 706
SetData method 525
SetMenuText method 688
of PrintInfo 688
Settings property 681
of PrintInfo 681
SettingsDeviceName property 681
of PrintInfo 681
SettingsMarginBottom property 682
of PrintInfo 682
SettingsMarginLeft property 682
of PrintInfo 682
SettingsMarginRight property 682
of PrintInfo 682
SettingsMarginTop property 683
of PrintInfo 683
SettingsOrientation property 683
of PrintInfo 683
SettingsPaperBin property 683
of PrintInfo 683
SettingsPaperHeight property 683
of PrintInfo 683
SettingsPaperSize property 684
of PrintInfo 684
SettingsPaperWidth property 684
of PrintInfo 684
ShowCollapseExpandIcons property 471
Size property 471
SizeMode property 472
Sizing 131, 188, 189, 299
columns 131, 188
rows 131, 188
splits 131, 189, 299
Sorting 81, 705
in storage mode 81, 705
Source property 473
Split groups 304
Split object 122, 294, 295
properties in common with TDBGrid 294
properties not supported by TDBGrid 295
Split property 473
SplitChange event 566
SplitContaining method 525
Splits 131, 189, 293, 294, 295, 296, 297, 298, 299, 302, 304, 305,
306
columns in 296
creating 131, 296, 302
fixed columns in 305
grouping 304
horizontal scrolling 305
navigation 306
properties common to TDBGrid 294
properties not supported by TDBGrid 295
referencing 293
removing 296
scaling 299
sizing 131, 189, 299, 302
user interaction with 302
using 293
vertical scrolling 304
Splits collection 122
Splits property 473
SplitSizeMode constants 663
SpringMode property 473
SQL 198
SQLState property 474
Storage mode 16, 205, 209
examples of 209
Style object 122
Style properties 311, 312, 313, 320
Style property 474, 611
of TDBDropDown 611
StyleBorderAppearance constants 664
StyleBorderType constants 664
Styles 307, 308, 309, 310, 311, 312, 313, 315, 317, 320, 321, 322,
323, 324, 326, 327, 329
 Index · 717

anonymous 315, 317 refreshing the display 232, 233

built-in 307 reinitializing the grid 233
displaying pictures with 326, 327, 329 supplying bookmarks 226, 229
evaluation order 326 supplying data 223, 226, 229
inheritance 309, 317 updating records 231, 233
modifying 310, 312 using the RowBuffer object 221
named 307, 308, 309, 315 UnboundAddData event 567
Styles collection 122 UnboundColumnFetch event 568, 643
Styles property 475, 611 of TDBDropDown 643
of TDBDropDown 611 UnboundDeleteRow event 568
SubstituteFont method 689 UnboundFind constants 665
of PrintInfo 689 UnboundFindData event 644
UnboundGetRelativeBookmark event 569, 645
of TDBDropDown 645
T
UnboundReadData event 570, 646
TabAcrossSplits property 475 of TDBDropDown 646
TabAction constants 664 UnboundReadDataEx event 571, 647
TabAction property 476 of TDBDropDown 647
TableName property 477 UnboundWriteData event 572
Tag property 477 UnitsPerInch property 684
TDBDropDown control 118, 342, 343 of PrintInfo 684
TDBGrid control 118 Update method 526
Text 263, 264, 265, 269, 336, 337 updating records 241
and pictures 269 UpperBound property 695
formatting 263, 264, 265 of XArrayDB 695
selecting and replacing 337
working with 336
Text property 477, 612 V
of TDBDropDown 612 Validate property 480
Three-dimensional displays 249 Validating cell data 237, 239
Top property 478 Value property 480, 481, 482, 695
Translate property 479 of Column 480
TransparentForegroundPicture property 479 of RowBuffer 481
TransparentRowPictures property 479 of Style 481
Tutorials 27, 29, 32, 33, 37, 38, 42, 44, 46, 48, 51, 53, 55, 61, 63, of ValueItem 482
64, 70, 75, 79, 81, 84, 86, 88, 91, 96, 100, 103, 105, 108, 111 of XArrayDB 695
ValueItem object 123
U ValueItemError event 573, 648
of TDBDropDown 648
Unbound columns 198, 199, 200, 201, 202, 203
ValueItems collection 123
creating 199
ValueItems property 482
editing 203
ValueTranslate property 613
implementing 200, 201
VariableRowHeight property 685
updating 202
of PrintInfo 685
Unbound mode 16, 219, 220, 221, 223, 226, 229, 231, 232, 233,
Vertical alignment 260
234
VerticalAlignment constants 665
adding records 231, 233
VerticalAlignment property 483
bookmarks 221
ViewColumnCaptionWidth property 482
calibrating the vertical scroll bar 234
ViewColumnWidth property 483
deleting records 232, 233
Visible property 484
events 223
VisibleCols property 484, 613
examples of 234
of TDBDropDown 613
718 · Index

VisibleRows property 484, 614

of TDBDropDown 614
Visual Basic 196, 206, 213
bookmarks in 213
Data control 196
using XArrayDB with 206
Visual editing 18, 130, 132
menu 132
VScrollWidth property 485

W
Width property 485
Window animation 261
Wordwrap 258, 333
WrapCellPointer property 486
WrapRowPointer property 486
WrapText property 486

X
XArrayDB object 123, 205, 206, 207, 208, 209, 707
adding to a Visual Basic project 206
attaching to a True DBGrid control 207
constants 707
creating 206
initializing 206
inserting columns 209
inserting rows 208
interactions with True DBGrid 207
populating 206
redimensioning 206
removing columns 209
removing rows 208
updating elements 208
using 205