ComponentOne True DBGrid Pro 8.0

* The Basics

* Tutorials

* Object Model

* Object Reference

Overview

Product Profile

Installation

Adding the True DBGrid Pro 8.0 Components to the Toolbox

Upgrading

End-User License Agreement for ComponentOne Software

Redistributable Files

Technical Support


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.
Excel-like splits | 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.
Fixed, nonscrolling columns | Splits can also be used to create nonscrolling columns anywhere in the grid (at the left or right edges, or in the middle).
In-cell objects | The grid supports a variety of in-cell objects for data display and editing, including bitmaps, command buttons, check boxes, and radio buttons.
Drop-down objects | 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.
Automatic data translation | 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.
Data-sensitive display | 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.
Drag-and-drop features | Programmers can implement drag-and-drop interfaces that are sensitive to the grid's rows, columns, or individual cells.
Interactive visual editing | 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.
Flexible unbound modes | 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.
Unbound columns | The grid supports unbound columns while other columns are bound to a data control.
Array-based storage mode | 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!
Reusable grid layouts | 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 masking | Input templates similar to Visual Basic format strings can be assigned to columns in order to reduce end-user data entry errors.
Multiline displays | The cells in a single record can now span multiple lines, making all columns visible.
Run-time CellTips | Provides context-sensitive help for end users.
Alternating row colors | Enhances the readability of the grid's display.
Excellent documentation | True DBGrid Pro 8.0 includes an extensive manual and online help with plenty of tutorials and examples.
Responsive technical support | 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/.
Free run-time distribution | 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.

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.

· 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 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. "Network Server CPU License" means that a separate End User License must be purchased for each CPU operating the computer software at issue in the reference.

“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.

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 a single install of the SOFTWARE for use in designing, testing and creating Developed Software by a single Developer on a single computer with a single set of input devices, so long as such computer is used only by one Developer. 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. If the SOFTWARE is used to create Developed Web Server Software, then you may perform a single install of the SOFTWARE for use in designing, testing and creating Developed Web Server Software by a single Developer on a single computer or Network Server, either with a single CPU only. An additional Network Server CPU License is required for each additional CPU on the single computer or Network Server, as the case may be, upon which the SOFTWARE and/or the Developed Web Server Software is installed and a separate license for each separate computer. That is, for Developed Web Server Software, if the computer or Network Server operating the SOFTWARE has 2 CPU's, then you would need to purchase one additional Network Server CPU License (beyond the one Developer Seat License granted in this EULA).

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.

a. License to Distribute Developed Legacy Software. Subject to the terms and conditions in this EULA, you are granted the license to use and to distribute Developed Legacy Software on a royalty-free basis, provided that the Developed Legacy 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 Legacy Software only.

b. License to Distribute Developed Web Server Software. Subject to the terms and conditions in this EULA, you are granted the license to use and to distribute Developed Web Server Software, provided that you must purchase one Network CPU License for each CPU operating the Developed Web Server Software (and/or Redistributable Files called or otherwise used directly by the Developed Web Server Software). You may purchase an additional Network CPU License by purchasing an additional separate End User License for the SOFTWARE; one Network CPU License is included in this EULA. Notwithstanding the foregoing, however, you may distribute or transfer, free of royalties, the Redistributable Files (and/or any Developed Legacy Software) to the extent that they are used separately on a single CPU on the client/workstation side of the network served by the Web Server.

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.

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. VSForum. VSForum 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 discussion forum (the database hereinafter referred to as the "Forum"). You may use the SOFTWARE to create one Forum on one Network Server only, which server may be connected at any point to an unlimited number of workstations or computers operating on one or more networks. You are specifically NOT LICENSED to create or operate multiple Forums. To create or to operate more than one FORUM, you must purchase one additional SOFTWARE license for each additional Forum.

d. 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.

e. 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.

f. 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 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 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 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 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.

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.

NOTE: A distribution license must be obtained for each server CPU on which your Developed Web Server Application is installed. If your Developed Web Server Application is installed on a server for which a license has already been purchased, and only one CPU is operating the application, it is not necessary to purchase an additional license. However, additional licenses must be purchased for each additional CPU on the network that is operating the Developed Web Server Application.

For a more detailed account of your rights to distribute your Developed Web Server Software, please see the End-User License Agreement for ComponentOne Software.

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.


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

Choosing a Column Layout

Configuring Columns at Design Time

Configuring Columns at Run Time

Understanding 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?

What is storage mode?

What is application mode?

What is unbound mode?


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.


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.


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.


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.


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

Customized layouts

Run-time layouts

Switching between layout types


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 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.


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.

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.


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.

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.


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.


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 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.


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

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 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

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.


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

Apptbook | This sample illustrates how to implement a drag-and-drop operation in the grid, how to interactively set the grid's color, and also how to use Unbound Extended mode. This sample uses the TDBGrid control.
GENLEDGR | This sample illustrates a number of important points about how splits can be used effectively, and how several additional features (such as outlining and updating unbound columns) can be used. This sample uses the TDBGrid control.
Invntry | This sample illustrates how styles can be used effectively. It uses the grid's AddRegexCellStyle method and FetchRowStyle event. This sample uses the TDBGrid and TDBDropDown controls.
OwnrDraw | This is a small sample that shows how you can use GDI calls in grid's OwnerDraw event. This sample uses the TDBGrid control.
TRUBRWSE | This sample illustrates a number of useful database application techniques, including 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.
APIToX | This sample shows how you can populate XArrayDB from an ODBC database. The advantage is that there is no overhead of DAO, ADO or RDO. This sample uses the TDBGrid control.
DAOToX | This sample dumps everything from a recordset to an XArrayDB. The difference between this sample and the RDOToXarray is only the redimensioning of the 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.
Odbc7 | This sample shows how you can use ODBC API to populate the list in Unbound extended mode. This sample uses the TDBGrid control.
OwnerDraw | This is a small sample that shows how you can use GDI calls in grid's OwnerDraw event. This sample uses the TDBGrid control.
RDOToX | 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. The obvious disadvantage is the concurrency issues. This sample uses the TDBGrid control.
Transaction | 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 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.
Ub1DAO | 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 applications should use the UnboundExtended mode. This sample uses the TDBGrid control.
Ub2ADO | This sample shows how you can populate the grid in Unbound extended mode from an ADO recordset. This sample uses the TDBGrid control.
Ub2ARR | This sample uses a generic data class. For small data sets you should use DataMode 4 - Storage with XArrayDB. This sample uses the TDBGrid control.
Ub2DAO | This sample populates the list with the DAO recordset in Unbound extended mode. This sample uses the TDBGrid control.
Ub2RDO | This sample populates the list with the RDO Resultset in Unbound extended mode. This sample uses the TDBGrid control.


Tutorials

Introduction

Tutorial 1 - Binding True DBGrid to a Data Control

Tutorial 2 - Using True DBGrid with SQL Query Results

Tutorial 3 - Linking Multiple True DBGrid Controls

Tutorial 4 - Interacting with Code and Other Bound Controls

Tutorial 5 - Selecting Multiple Rows Using Bookmarks

Tutorial 6 - Defining Unbound Columns in a Bound Grid

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

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

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

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

Tutorial 11 - Using Styles to Highlight Related Data

Tutorial 12 - Displaying Rows in Alternating Colors

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

Tutorial 14 - OLE Drag-and-Drop

Tutorial 15 - Creating a Grid with Fixed, Nonscrolling Columns

Tutorial 16 - Displaying Array Data in Unbound Mode

Tutorial 17 - Displaying Array Data in Unbound Extended Mode

Tutorial 18 - Displaying Array Data in Unbound Application Mode

Tutorial 19 - Displaying Array Data in Unbound Storage Mode

Tutorial 20 - Sorting and Searching

Tutorial 21 - Displaying Arbitrary Bitmaps

Tutorial 22 - Reusable Layouts

Tutorial 23 - Printing, Print Preview, and Export

Tutorial 24 - Displaying Hierarchical Data

Tutorial 25 - Outlook-Style Grouping

Tutorial 26 - Value Translation

Tutorial 27 - Range Selection

Tutorial 28 - Transposed Views

Tutorial 29 - Filter Bar

Tutorial 30 - Cell Bordering and Scroll Tips/Tracking


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.

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 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:

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.

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

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.

This concludes Tutorial 2.


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$

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).

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

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

' 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 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

' 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.

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.

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.

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.

16. Click the OK button at the bottom of the property page dialog to accept the changes. You have now finished configuring the grid.

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.

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 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.

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.

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.

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, 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.

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.

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.

· 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.

· 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.

2. Add a ListBox control (List1) to the form (Form1) as shown in the figure.

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.

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 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.

· 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.

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.

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.

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.

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

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.

· 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.

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.

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.

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, 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.


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 and Design Time Interaction 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.

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.

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

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.

· 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.

· 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, 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.

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.

· 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 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:

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.

· 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.

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), application mode (Tutorial 18), or storage mode (Tutorial 19) instead. For detailed instructions on how to use unbound mode 1, see Unbound Mode.

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).

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

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( _

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.

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

' 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

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. 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.

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).

Configuring the grid at design time

We shall configure the grid as in Tutorial 16.

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, 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

' 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)

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

' 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)

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.

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.

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 15, 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.

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

' 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

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.

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.

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.

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).

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)

' 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.

· 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.

Adding XArrayDB to the project

As in Tutorial 19, 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)

' 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.

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.

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.

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

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.

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.

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

' 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.

· 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.

· 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 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.)

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 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.

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.

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

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

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 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.

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.

· 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.

· 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.

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:

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:

· 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

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

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

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.

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.

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:

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:

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

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 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

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:

· 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.

Congratulations, you have successfully completed all 30 tutorials!


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, 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

TDBGrid Control

TDBDropDown Control

Column Object, Columns Collection

DataObject Object, DataObjectFiles Collection

Error Object, Errors Collection

GroupColumns Collection

Layouts Collection

PrintInfo Object, PrintInfos Collection

RowBuffer Object

SelBookmarks Collection

Split Object, Splits Collection

Style Object, Styles Collection

ValueItem Object, ValueItems Collection

XArrayDB Object

Working with 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.
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
Run Time Interaction
Bound Mode
Storage Mode
Application Mode
Unbound Mode

Reference Topics


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.

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
Using the TDBDropDown Control

Reference Topics


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

Reference Topics

Column Object Properties

Column Object Methods


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

Reference Topics

DataObject Object Properties

DataObject Object Methods


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


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

Reference Topics


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

Reference Topics


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


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

Reference Topics

RowBuffer Object Properties


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 programmatically using its Add and Remove methods. This collection is accessed using the SelBookmarks property.

See Also

Selecting and Highlighting Records

Reference Topics


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

Reference Topics


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

Reference Topics


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
Automatic Data Translation with TDBDropdown

Reference Topics


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

Reference Topics


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.

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

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)

' 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.

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.


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

Visual Editing Mode

Property Page Overview

TDBGrid Property Pages

TDBDropDown Property Pages

Reusable Layouts

TDBDropDown at Design Time


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 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.

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.

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.

· 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

Creating and sizing splits

Selecting and highlighting columns

Moving selected columns

Using the visual editing menu


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.

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 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.

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

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

Working with property trees

Changing values in property trees

Understanding the object model

Using the property tree context menu


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.

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.

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

String properties

String selection properties

Numeric properties

Enumerated properties

Font properties

Color properties

Picture properties

Style properties

Layout properties


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.


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.


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.


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.

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.

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.

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.

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 or TDBDropDown Property Pages 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.

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.

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

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

Columns property page

Splits property page

Style Factory property page

Print Info property page

Values property page


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.


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
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
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
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
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
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.

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.


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
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.

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.

Split properties by alphabet

Split properties by category

Split-specific Column properties by alphabet

Split-specific Column properties by category


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
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


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
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
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
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

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.


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.

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
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 | Sets/returns a style's background picture
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


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.

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
PreviewInitZoom | Sets/returns print preview window's initial zoom factor
PreviewMaximize | Controls whether the PrintPreview window is initially maximized when shown
PreviewPageOf | Controls the PrintPreview window display of "Page x of y"
RepeatColumnFooters | Sets/returns whether column footers should appear on each page
RepeatColumnHeaders | Sets/returns whether column headers should appear on each page
RepeatGridHeader | Sets/returns whether the grid caption should appear on each page
RepeatSplitHeaders | Sets/returns whether split captions should appear on each page
VariableRowHeight | 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:

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 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

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)

Columns property page (TDBDropDown)

Style Factory property page (TDBDropDown)

Values property page (TDBDropDown)


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.


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
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

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

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.


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


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

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.


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.


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.

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.

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.


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

Selection and Movement

Sizing and Splitting

Database Operations

Drag-and-Drop Behavior

Additional User Interaction Features


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

Clicking the rightmost column

IntelliMouse support

Keyboard navigation

Navigation at row boundaries

Navigation at split boundaries

Restricting cell navigation


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.


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.
 | 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. 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.

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.

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.


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.

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.

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.


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.


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.

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.

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 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.


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

Scroll Tracking and ScrollTips

Hierarchical Data Display

Dropdown Hierarchical Data Display

Filtering Data in Recordsets

Outlook-Style Grouping


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.

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.

· 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

Interactions between True DBGrid and the Data control

Using True DBGrid with a Data control on a different form

Using True DBGrid to display SQL query results


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:

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.
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 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. 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.

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

Implementing unbound columns using Recordset clones

Implementing unbound columns using cell access methods

Implementing multiple unbound columns

Updating unbound columns

Editing unbound columns


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.


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

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.

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.

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.


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

Using the XArrayDB Object

Interactions between True DBGrid and XArrayDB

Storage Mode Examples


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.

Adding XArrayDB to a Visual Basic project

Creating an XArrayDB object

Redimensioning an XArrayDB object

Populating an XArrayDB object

Attaching an XArrayDB object to a True DBGrid control


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)

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:

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.

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 or examine the UNBOUND4.VBP sample, which can be found in the TUTORIAL\UNBOUND4 subdirectory of the True DBGrid installation directory. Tutorial 20 demonstrates the searching and sorting features of XArrayDB.


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

How Application Mode Works

Application Mode Bookmarks

Application Mode Events

Application Mode Programming Considerations

Application Mode Example


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.

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.

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.


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

Handling the ClassicRead event in mode 3

Handling the ClassicWrite event in mode 3

Handling the ClassicAdd event in mode 3

Handling the ClassicDelete event in mode 3


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.

' 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.


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:

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.


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 or examine the UNBOUND3.VBP sample, which can be found in the TUTORIAL\UNBOUND3 subdirectory of the True DBGrid installation directory.


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

How Unbound Mode Works

Unbound Mode Bookmarks

Using the RowBuffer Object

Unbound Mode Events

Unbound Mode Programming Considerations

Unbound Mode Examples


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 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 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.


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 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

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

Handling the UnboundGetRelativeBookmark event in mode 1

Handling the UnboundReadDataEx event in mode 2

UnboundReadDataEx event examples

Handling the UnboundWriteData event in modes 1 and 2

Handling the UnboundAddData event in modes 1 and 2

Handling the UnboundDeleteRow event in modes 1 and 2


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.

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.

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

' 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.


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.

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 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.

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

...

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:

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.

· 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

Refreshing the display in mode 2

Reinitializing the grid in modes 1 and 2

Updating and deleting rows in modes 1 and 2

Adding rows in modes 1 and 2

Calibrating the vertical scroll bar in modes 1 and 2


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.


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 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 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 or examine the UNBOUND2.VBP sample, which can be found in the TUTORIAL\UNBOUND2 subdirectory of the True DBGrid installation directory.


Database Programming Techniques

As Tutorial 1 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, 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

Accessing and Manipulating Cell Data

Validating Cell Data

Selecting and Highlighting Records

Updating and Deleting the Current Record

Refreshing the Display

Refetching Data from the Data Source

Coordinating with Other Controls

Handling Database Errors

Postponing Illegal Operations in Grid Events


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


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.

Reading and writing cell data within the current record

Reading cell data from non-current records

Retrieving a bookmark relative to the current record

Retrieving a bookmark relative to a displayed row


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)

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)

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.

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

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)

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.


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 demonstrates how to use the SelBookmarks collection to select records that satisfy specific criteria.


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).
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.

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 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.

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 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

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.


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

Three-dimensional versus Flat Display

Borders and Dividing Lines

Unpopulated Regions

Highlighting the Current Row or Cell

Row Height and Multiple-line Displays

Alternating Row Colors

Horizontal and Vertical Alignment

Window Animation


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

Column footers

Multiple-line headers and footers

Split captions


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.

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.


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.

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.

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

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.

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.

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.

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

MarqueeStyle 1 - Solid Cell Border

MarqueeStyle 2 - Highlight Cell

MarqueeStyle 3 - Highlight Row

MarqueeStyle 4 - Highlight Row, Raise Cell

MarqueeStyle 5 - No Marquee

MarqueeStyle 6 - Floating Editor

MarqueeStyle 7 - Dotted Row Border


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).


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.


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.

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. 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 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.

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

Enabling wordwrap in cells

Displaying a single record on multiple lines

Implications of multiple-line mode


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.

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.


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 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.

Tutorial 12 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 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.


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.


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.

Text Formatting

Automatic Data Translation with ValueItems

Context-sensitive Help with CellTips

Scroll Tracking and ScrollTips

Data-sensitive Cell Merging

Outlook-Style Grouping

Hierarchical Data Display

Dropdown Hierarchical Data Display

Form Data Display

Inverted Data Display

Owner-drawn Cells

Filtering Data in Recordsets


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

Input validation with built-in formatting

Formatting with an input mask

Formatting with a custom event handler


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.
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.


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 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.

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?

Specifying text-to-text translations

Specifying text-to-picture translations

Displaying both text and pictures in a cell

Displaying boolean values as check boxes

Displaying allowable values as radio buttons


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 and Tutorial 10 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.

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"

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.

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.

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.

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 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.

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.


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.

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.

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.

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 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 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.

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

.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. The section Applying Pictures to Grid Elements 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.

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 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.

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.

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.

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.

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:

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 source, you can set the DataMode property to 1 - Hierarchical. For more information, see Hierarchical Data Display.


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

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

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

' 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.


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

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.

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.

For more information, see Tutorial 29.


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

Creating and Removing Splits

Working with Columns in Splits

Sizing and Scaling Splits

Creating and Resizing Splits through User Interaction

Vertical Scrolling and Split Groups

Horizontal Scrolling and Fixed Columns

Navigation across Splits


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

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
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


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 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

' 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
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
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.

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

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.

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.

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 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.

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

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.


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

Working with Style Properties

Applying Styles to Cells

Applying Pictures to Grid Elements


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
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:

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.

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.

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
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

Assigning a value to a style property

Named styles versus anonymous styles

Anonymous style inheritance

Shortcut style properties


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.

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.

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:

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.

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.

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

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

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 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
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.

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.

Specifying cell status values

Applying cell styles by status

Applying cell styles by contents

Applying cell styles by custom criteria

Cell style evaluation order


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 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 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.

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)

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
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.

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).

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.

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.

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.

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. 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 demonstrates how to use styles to display arbitrary bitmaps within data cells.


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

Handling Editing Events

Working with Text

Input Masking

In-cell Buttons

Drop-down Controls


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.

Initiating cell editing

Color and wordwrap

Determining modification status

Determining cell contents

Terminating cell editing


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.

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.

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

' 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 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

Providing a drop-down edit control for long fields

Changing the insertion mode

Selecting and replacing text


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

.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

Specifying a date mask for a column

Using an input mask for formatting

Controlling how masked input is updated


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 ">"

? 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 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

Rendering cells as command buttons

Detecting in-cell button clicks

Customizing the in-cell button bitmap


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.


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.


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")

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

Detecting built-in combo box selections

Using the TDBDropDown control

Automatic data translation with TDBDropDown

Using an arbitrary drop-down control

Using the built-in column button


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, 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 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.


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.

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 and Tutorial 26.


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.

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 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. An example of dropping down a Visual Basic ListBox control from a grid cell is given in Tutorial 9.


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.


Object Reference

True DBGrid All Members

True DBGrid Properties

True DBGrid Methods

True DBGrid Events

TDBDropDown All Members

TDBDropDown Properties

TDBDropDown Methods

TDBDropDown Events

True DBGrid Methods

True DBGrid Events

TDBDropDown All Members

TDBDropDown Properties

TDBDropDown Methods

TDBDropDown Events


True DBGrid All Members

TDBGrid Control Properties

TDBGrid Control Methods

TDBGrid Control Events

Column Object Properties

Column Object Methods

Columns Collection Properties

Columns Collection Methods

DataObject Object Properties

DataObject Object Methods

Error Object Properties

Errors Collection Properties

Errors Collection Methods

GroupColumns Collection Properties

GroupColumns Collection Methods

Layouts Collection Properties

Layouts Collection Methods

PrintInfos Collection Properties

PrintInfos Collection Methods

RowBuffer Object Properties

SelBookmarks Collection Properties

SelBookmarks Collection Methods

Split Object Properties

Split Object Methods

Splits Collection Properties

Splits Collection Methods

Style Object Properties

Style Object Methods

Styles Collection Properties

Styles Collection Methods

ValueItem Object Properties

ValueItems Collection Properties

ValueItems Collection Methods


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
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
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
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
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
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
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
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


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
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


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
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


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
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


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
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

Alignment Property

AllowAddNew Property

AllowArrows Property

AllowColMove Property

AllowColSelect Property

AllowDelete Property

AllowFocus Property

AllowRowSelect Property

AllowRowSizing Property

AllowSizing Property

AllowUpdate Property

AlternatingRowStyle Property

AnchorRightColumn Property

AnimateWindow Property

AnimateWindowClose Property

AnimateWindowDirection Property

AnimateWindowTime Property

AnnotatePicture Property

Appearance Property

ApproxCount Property

Array Property

AutoCompletion Property

AutoDropDown Property

BackColor Property

BackgroundPicture Property

BackgroundPictureDrawMode Property

Bands Property

BatchUpdates Property

BOF Property

Bookmark Property (RowBuffer)

Bookmark Property

BookmarkType Property

BorderAppearance Property

BorderColor Property

BorderSize Property

BorderStyle Property

BorderType Property

Button Property

ButtonAlways Property

ButtonFooter Property

ButtonHeader Property

ButtonPicture Property

ButtonText Property

Caption Property

CaptionStyle Property

CellTips Property

CellTipsDelay Property

CellTipsWidth Property

CellTop Property

ChildGrid Property

Col Property

CollapseColor Property

ColIndex Property

ColumnCount Property

ColumnFooters Property

ColumnHeaders Property

ColumnIndex Property

ColumnName Property

Columns Property

ConvertEmptyCell Property

Count Property

CurrentCellModified Property

CurrentCellVisible Property

CycleOnClick Property

DataChanged Property

DataField Property (Column)

DataMember Property

DataMode Property

DataSource Property

DataView Property

DataWidth Property

DeadAreaBackColor Property

DefaultItem Property

DefaultValue Property

DefColWidth Property

Description Property

DestinationCol Property

DestinationRow Property

DestinationSplit Property

DirectionAfterEnter Property

DirectionAfterTab Property

DisplayAlignment Property

DisplayValue Property

DividerColor Property

DividerStyle Property

DropDown Property

DropDownList Property

EditActive Property

EditBackColor Property

EditDropDown Property

EditForeColor Property

EditMask Property

EditMaskRight Property

EditMaskUpdate Property

EditorStyle Property

EllipsisText Property

EmptyRows Property

Enabled Property

EOF Property

Errors Property

ErrorText Property

EvenRowStyle Property

ExpandColor Property

ExportEOF Property

ExportNextBookmark Property

ExposeCellMode Property

ExtendRightColumn Property

ExternalEditor Property

FetchRowStyle Property

FetchStyle Property

Files Property

FilterActive Property

FilterBar Property

FilterBarStyle Property

FilterButton Property

FilterButtonPicture Property

FilterText Property

FirstRow Property

Font Property

FooterAlignment Property

FooterBackColor Property

FooterDivider Property

FooterFont Property

FooterForeColor Property

FooterStyle Property

FooterText Property

FootLines Property

ForeColor Property

ForegroundPicture Property

ForegroundPicturePosition Property

Group Property

GroupByCaption Property

GroupColumns Property

HeadAlignment Property

HeadBackColor Property

HeaderDivider Property

HeadFont Property

HeadForeColor Property

HeadingStyle Property

HeadLines Property

HelpContext Property

HelpFile Property

HighlightRowStyle Property

HScrollHeight Property

hWnd Property

hWndEditor Property

InactiveBackColor Property

InactiveForeColor Property

InactiveStyle Property

Index Property

InsertMode Property

LayoutFileName Property

LayoutName Property

Layouts Property

LayoutURL Property

Left Property

LeftCol Property

Locked Property

MarqueeStyle Property

MarqueeUnique Property

MatchCase Property

MaxComboItems Property

MaxRows Property

Merge Property

MinWidth Property

MouseIcon Property

MousePointer Property

MultipleLines Property

MultiSelect Property

Name Property (Column)

Name Property (Style)

NativeError Property

Number Property

NumberFormat Property

OddRowStyle Property

OLEDragMode Property

OLEDropMode Property

Order Property

OwnerDraw Property

Parent Property

PartialRightColumn Property

PictureAddNewRow Property

PictureCurrentRow Property

PictureFilterBar Property

PictureFooterRow Property

PictureHeaderRow Property

PictureModifiedRow Property

PictureStandardRow Property

Presentation Property

PrintInfo Property

PrintInfos Property

RecordSelectors Property

RecordSelectorStyle Property

RecordSelectorWidth Property

RightToLeft Property

Row Property

RowCount Property

RowDividerColor Property

RowDividerStyle Property

RowHeight Property

RowSubDividerColor Property

ScrollBars Property

ScrollGroup Property

ScrollTips Property

ScrollTrack Property

SelBookmarks Property

SelectedBackColor Property

SelectedForeColor Property

SelectedStyle Property

SelEndCol Property

SelLength Property

SelRange Property

SelStart Property

SelStartCol Property

SelText Property

ShowCollapseExpandIcons Property

Size Property

SizeMode Property

Source Property

Split Property

Splits Property

SpringMode Property

SQLState Property

Style Property

Styles Property

TabAcrossSplits Property

TabAction Property

TableName Property

Tag Property

Text Property

Top Property

Translate Property

TransparentForegroundPicture Property

TransparentRowPictures Property

Validate Property

Value Property (Column)

Value Property (RowBuffer)

Value Property (Style)

Value Property (ValueItem)

ValueItems Property

ViewColumnCaptionWidth Property

ViewColumnWidth Property

VerticalAlignment Property

Visible Property

VisibleCols Property

VisibleRows Property

VScrollWidth Property

Width Property

WrapCellPointer Property

WrapRowPointer Property

WrapText Property


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.

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


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.

See Also

Column Object

Style Object


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


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


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 for more information.

Note

The AllowColSelect property must also be True in order for the user to move selected columns.

See Also

TDBGrid Control

TDBDropDown Control

Split Object


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.

See Also

TDBGrid Control

TDBDropDown Control

Split Object


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


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.

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

Split Object


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

Split Object


AllowRowSizing Property

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

TDBDropDown Control

Split Object


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.

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

Split Object


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


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.

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

TDBDropDown Control

Split Object


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

TDBDropDown Control

Split Object


AnimateWindow Property

Controls the object's animation style.

Syntax

TDBGrid.AnimateWindow = value

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 for more information.

See Also

TDBGrid Control


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

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


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
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


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


AnnotatePicture Property

This property determines whether the column associated with a ValueItems collection can display both text and graphics in a single cell.

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.

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


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.

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

TDBDropDown Control


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

TDBDropDown Control


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.

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

TDBDropDown Control


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


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


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

TDBDropDown Control

Column Object

Style Object

Split Object


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


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


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

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


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 for more information.

Note

This property is only supported by the OLE DB version of True DBGrid Pro.

See Also

TDBGrid Control


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.

If the data source contains no records, then BOF will always return True.

See Also

TDBGrid Control


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


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


BorderAppearance Property

Controls the appearance (3D effects) of the cell borders.

Syntax

object.BorderAppearance = value

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


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


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


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

TDBDropDown Control


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.

See Also

Style Object


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


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.

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


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


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.

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


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


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

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


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

Column Object

Split Object


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

Split Object


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.

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


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


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


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


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.

See Also

TDBGrid Control


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

TDBDropDown Control


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


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.

See Also

Column Object


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


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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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


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


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

TDBDropDown Control

Split Object


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


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.

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

Error Object, Errors Collection

GroupColumns Collection

Layouts Collection

PrintInfo Object, PrintInfos Collection

SelBookmarks Collection

Split Object, Splits Collection

Style Object, Styles Collection

ValueItem Object, ValueItems Collection


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


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.

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

TDBDropDown Control

Split Object


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


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.

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

Column Object


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

Column Object


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.

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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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.

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

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 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.

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.

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


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.

See Also

Column Object


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

TDBDropDown Control


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.

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 DefaultItemproperty 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


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


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

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

TDBDropDown Control


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


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


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).

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


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.

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


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


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
4 - Up | dbgMoveUp

Remarks

Read/Write at run time and design time.

See Also

TDBGrid Control


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


DisplayValue Property

This property returns or sets the translated data value for a member of a ValueItems collection.

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


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

Split Object


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
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.

See Also

Column Object

Split Object


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


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


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


EditBackColor Property

This property controls the background color of an object's editing window when editing is in progress.

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

Column Object

Split Object


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


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

Column Object

Split Object


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

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


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


EditMaskUpdate Property

Controls whether masked data is used for updates.

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


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

Column Object

Split Object


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.

See Also

Style Object


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

TDBDropDown Control


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

TDBDropDown Control


EOF Property

Returns end-of-file status.

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


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


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control

Split Object


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


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.

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


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


ExposeCellMode Property

This property controls how the rightmost column reacts when clicked by the user.

Syntax

TDBGrid.ExposeCellMode = value

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


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.

See Also

TDBGrid Control

TDBDropDown Control

Split Object


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


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.

See Also

TDBGrid Control

TDBDropDown Control

Split Object


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


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.

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


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

Split Object


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.

See Also

TDBGrid Control

Split Object


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

Split Object


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


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.

· The Presentation property of the column's ValueItems collection is set to 2 - Combo Box or 3 - Sorted Combo Box.

See Also

Column Object


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


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

TDBDropDown Control

Split Object


Font Property

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

TDBDropDown Control

Column Object

Split Object

Style Object


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


FooterBackColor Property

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.

See Also

TDBGrid Control

TDBDropDown Control

Column Object

Split Object


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


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.

See Also

TDBGrid Control

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Column Object

Split Object


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


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

TDBDropDown Control


ForeColor Property

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

TDBDropDown Control

Column Object

Split Object

Style Object


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


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

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


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 for more information.

See Also

Column Object


GroupByCaption Property

This property sets or returns the text displayed in the grouping area when no group is defined.

Syntax

TDBGrid.GroupByCaption = string

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 for more information.

See Also

TDBGrid Control


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 for more information.

See Also

TDBGrid Control


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

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


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

TDBDropDown Control

Column Object

Split Object


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.

See Also

Column Object


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control


HelpContext Property

Returns or sets a context ID for a topic in a Help file.

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


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


HighlightRowStyle Property

This property sets or returns the Style object that controls the appearance of a highlighted row or cell marquee.

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

TDBDropDown Control

Split Object


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

Split Object


hWnd Property

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

TDBDropDown Control


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


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.

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

Split Object


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


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.

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

Split Object


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


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


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.

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

TDBDropDown Control


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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


Left Property

This property returns the position of a column's left edge in terms of the coordinate system of the grid's container.

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


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

TDBDropDown Control

Split Object


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.

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

Split Object

Style Object


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.

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

Split Object


MarqueeUnique Property

This property controls the display of the current cell marquee when there is more than one split.

Syntax

TDBGrid.MarqueeUnique = boolean

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


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


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.

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


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


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.

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


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


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


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

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


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

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


MultiSelect Property

Sets or returns the type of selection allowed in the grid.

Syntax

TDBGrid.MultiSelect = value

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


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


Name Property (Style)

This property returns the name of a Style object.

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


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


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.

Note

This property applies to Error object (OLE DB only).

See Also

Error Object


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.
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


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

TDBDropDown Control

Split Object


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

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


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


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


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.

See Also

Column Object


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


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.

See Also

TDBGrid Control

TDBDropDown Control

Split Object


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


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")

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


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


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


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


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


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


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.

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


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


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


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.

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

Split Object


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

Split Object


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

Split Object


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

TDBDropDown Control


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.

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

TDBDropDown Control


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


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

TDBDropDown Control


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

TDBDropDown Control


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

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

TDBDropDown Control


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


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.

See Also

TDBGrid Control

TDBDropDown Control

Split Object


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


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

TDBDropDown Control


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

TDBDropDown Control


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


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

Split Object


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

Split Object


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

Split Object


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.

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

TDBDropDown Control

Split Object


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


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


SelStart Property

This property returns or sets the starting point of the text selection within the grid's editing window.

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


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

TDBDropDown Control

Split Object


SelText Property

This property returns or sets the string containing the currently selected text within the grid's editing window.

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


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


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.

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


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 remove all but one, the SizeMode and Size properties of the remaining split automatically revert to 0 and 1, respectively.

See Also

Split Object


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


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


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


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

Split Object


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


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.

Remarks

By default, this is the built-in Normal style.

See Also

TDBGrid Control

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control


TabAcrossSplits Property

This property controls the behavior of the tab and arrow keys at split borders.

Syntax

TDBGrid.TabAcrossSplits = boolean

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


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.

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


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


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


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.

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

TDBDropDown Control

Column Object


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 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


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


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


TransparentRowPictures Property

This property determines whether custom record selector bitmaps are rendered so that a particular color is used as a transparent color.

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


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


Value Property (Column)

This property returns or sets the underlying data value in a column for the current row.

Syntax

column.Value = variant

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


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


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 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


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


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


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.

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


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


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.

See Also

Style Object


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


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

TDBDropDown Control


VisibleRows Property

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

TDBDropDown Control


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

Split Object


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.

See Also

Column Object


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


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


WrapText Property

This property returns or sets a value indicating whether an object wordwraps text at cell boundaries.

Syntax

object.WrapText = boolean

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

Style Object


True DBGrid Methods

AboutBox Method

Add Method

AddCellStyle Method

AddRegexCellStyle Method

AutoSize Method

CaptureImage Method

CellContaining Method

CellText Method

CellValue Method

Clear Method

Clear Method (DataObject)

Clear Method (Errors)

ClearCellStyle Method

ClearFields Method

ClearRegexCellStyle Method

ClearSelCols Method

Close Method

ColContaining Method

CollapseBand Method

CollapseChild Method

Delete Method

ExpandBand Method

ExpandChild Method

ExportBegin Method

ExportEnd Method

ExportRows Method

ExportToDelimitedFile Method

ExportToFile Method

Fix Method

GetBand Method

GetBookmark Method

GetData Method

GetFormat Method

HoldFields Method

IsSelected Method

Item Method

LoadLayout Method

MoveFirst Method

MoveLast Method

MoveNext Method

MovePrevious Method

MoveRelative Method

OLEDrag Method

PointAt Method

PostMsg Method

ReBind Method

Refetch Method

RefetchCell Method

RefetchCol Method

RefetchRow Method

Refresh Method

RefreshCell Method

RefreshCol Method

RefreshRow Method

Remove Method

ReOpen Method

Reset Method

RowBookmark Method

RowContaining Method

RowExpanded Method

RowTop Method

Scroll Method

SetData Method

SplitContaining Method

Update Method


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

TDBDropDown Control


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.

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

Split Object, Splits Collection

Style Object, Styles Collection

GroupColumns Collection

PrintInfo Object, PrintInfos Collection

Layouts Collection

SelBookmarks Collection

ValueItem Object, ValueItems Collection


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.

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

TDBDropDown Control

Column Object

Split Object


AddRegexCellStyle Method

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.
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"

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

TDBDropDown Control

Column Object

Split Object


AutoSize Method

Automatically sizes the column width.

Syntax

column.AutoSize

Arguments

None

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 for more information.

See Also

Column Object


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

TDBDropDown Control


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.

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


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


CellValue Method

Returns displayed column text for any row.

Syntax

column.CellValue (bookmark)

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


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

PrintInfo Object, PrintInfos Collection

SelBookmarks Collection

ValueItem Object, ValueItems Collection


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


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


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control


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

TDBDropDown Control

Column Object

Split Object


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.

Use the SelStartCol and SelEndCol properties to determine the current column selection range for a split.

See Also

TDBGrid Control

TDBDropDown Control

Split Object


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

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


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

TDBDropDown Control


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.

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


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


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.

See Also

TDBGrid Control


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


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


ExportBegin Method

The ExportBegin method prepares the grid for export to an HTML file by creating an internal clone of the current recordset.

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


ExportEnd Method

The ExportEnd method releases the internal recordset clone created by the previous call to the ExportBegin method.

Syntax

TDBGrid.ExportEnd

Arguments

None

Return Value

None

See Also

TDBGrid Control


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


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.

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


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.

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


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


GetBand Method

The GetBand method returns the band number corresponding to a grid column.

Syntax

TDBGrid.GetBand (columnindex)

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


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.

See Also

TDBGrid Control

TDBDropDown Control


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


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.

See Also

DataObject Object


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

TDBDropDown Control


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


Item Method

Use the Item method to access a specific member of a True DBGrid collection.

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

Error Object, Errors Collection

Split Object, Splits Collection

Style Object, Styles Collection

GroupColumns Collection

PrintInfo Object, PrintInfos Collection

Layouts Collection

SelBookmarks Collection

ValueItem Object, ValueItems Collection


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

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


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


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


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


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


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

See Also

TDBGrid Control


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


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
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


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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


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.

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


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


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

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


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

TDBDropDown Control

Column Object


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


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


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


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

Split Object, Splits Collection

Style Object, Styles Collection

GroupColumns Collection

PrintInfo Object, PrintInfos Collection

Layouts Collection

SelBookmarks Collection

ValueItem Object, ValueItems Collection


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


Reset Method

This method causes a style to inherit all of its properties from its parent style.

Syntax

style.Reset

Arguments

None

Return Value

None

See Also

Style Object


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

TDBDropDown Control


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.

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

TDBDropDown Control


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


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)

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

TDBDropDown Control


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

TDBDropDown Control


SetData Method

This method inserts data into a DataObject object using the specified data format.

Syntax

dataobject.SetData [value], [format]

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


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


Update Method

This methods forces data from the current row to be updated to the underlying database.

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


True DBGrid Events

AfterColEdit Event

AfterColUpdate Event

AfterDelete Event

AfterInsert Event

AfterUpdate Event

BeforeColEdit Event

BeforeColUpdate Event

BeforeDelete Event

BeforeInsert Event

BeforeOpen Event

BeforeRowColChange Event

BeforeUpdate Event

ButtonClick Event

Change Event

ClassicAdd Event

ClassicDelete Event

ClassicRead Event

ClassicWrite Event

Click Event

ColEdit Event

Collapse Event

ColMove Event

ColResize Event

ComboSelect Event

DataSourceChanged Event

DblClick Event

DragCell Event

Error Event

Expand Event

FetchCellStyle Event

FetchCellTips Event

FetchRowStyle Event

FetchScrollTips Event

FirstRowChange Event

FilterButtonClick Event

FilterChange Event

FootClick Event

FormatText Event

GroupColMove Event

GroupHeadClick Event

HeadClick Event

KeyDown Event

KeyPress Event

KeyUp Event

LayoutReady Event

LeftColChange Event

MouseDown Event

MouseMove Event

MouseUp Event

OLECompleteDrag Event

OLEDragDrop Event

OLEDragOver Event

OLEGiveFeedback Event

OLESetData Event

OLEStartDrag Event

OnAddNew Event

OnInit Event

OwnerDrawCell Event

OwnerDrawCellPrint Event

OwnerDrawPageFooter Event

OwnerDrawPageHeader Event

Paint Event

PostEvent Event

RowColChange Event

RowResize Event

Scroll Event

SelChange Event

SplitChange Event

UnboundAddData Event

UnboundColumnFetch Event

UnboundDeleteRow Event

UnboundGetRelativeBookmark Event

UnboundReadData Event

UnboundReadDataEx Event

UnboundWriteData Event

ValueItemError Event


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


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.

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


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


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

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


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


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.

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


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


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


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


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


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


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.

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


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.

See Also

TDBGrid Control


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


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.

Note

If the add operation fails in the underlying data source, then you should set NewRowBookmark to Null.

See Also

TDBGrid Control


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


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.

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

TDBDropDown Control


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


Click Event

The Click event occurs when the user presses then releases a mouse button over the grid.

Syntax

object_Click ( )

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

TDBDropDown Control


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


Collapse Event

The Collapse event is fired when a user clicks on the collapse row icon ("–") in an expanded hierarchical grid row.

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


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

TDBDropDown Control


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

TDBDropDown Control


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


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.

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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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.

Note

Use the ErrorText property to retrieve the error string that will be displayed.

See Also

TDBGrid Control

TDBDropDown Control


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


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.

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

TDBDropDown Control


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

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


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.

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

TDBDropDown Control


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

TDBDropDown Control


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 ( )

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

TDBDropDown Control


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


FilterChange Event

This event is fired when a user types in the filter cell.

Syntax

TDBGrid_FilterChange ( )

Arguments

None

See Also

TDBGrid Control


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

TDBDropDown Control


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

TDBDropDown Control


GroupColMove Event

The GroupColMove event occurs before a selected column is moved to or from the grouping area.

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 for more information.

See Also

TDBGrid Control


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 for more information.

See Also

TDBGrid Control


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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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:

· 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

TDBDropDown Control


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

TDBDropDown Control


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 ( )

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

TDBDropDown Control


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.

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

TDBDropDown Control


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

TDBDropDown Control


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)

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

TDBDropDown Control


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.

See Also

TDBGrid Control


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


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.

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


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


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)

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


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 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


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


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


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


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.

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


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.

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


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.

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


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

TDBDropDown Control


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.

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

TDBDropDown Control


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.

· 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


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

TDBDropDown Control


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.

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

TDBDropDown Control


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.

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

TDBDropDown Control


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


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)

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


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.

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

TDBDropDown Control


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


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

TDBDropDown Control


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)

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

TDBDropDown Control


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.

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.

See Also

TDBGrid Control

TDBDropDown Control


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


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

TDBDropDown Control


TDBDropDown All Members

TDBDropDown Control Properties

TDBDropDown Control Methods

TDBDropDown Control Events


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
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
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
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
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)

AllowColSelect Property (TDBDropDown)

AllowRowSizing Property (TDBDropDown)

AlternatingRowStyle Property (TDBDropDown)

AnchorRightColumn Property (TDBDropDown)

Appearance Property (TDBDropDown)

ApproxCount Property (TDBDropDown)

Array Property (TDBDropDown)

BackColor Property (TDBDropDown)

Bookmark Property (TDBDropDown)

BookmarkType Property (TDBDropDown)

BorderStyle Property (TDBDropDown)

Col Property (TDBDropDown)

ColumnFooters Property (TDBDropDown)

ColumnHeaders Property (TDBDropDown)

Columns Property (TDBDropDown)

CurrentCellVisible Property (TDBDropDown)

DataField Property (TDBDropDown)

DataMember Property (TDBDropDown)

DataMode Property (TDBDropDown)

DataSource Property (TDBDropDown)

DeadAreaBackColor Property (TDBDropDown)

DefColWidth Property (TDBDropDown)

EmptyRows Property (TDBDropDown)

Enabled Property (TDBDropDown)

ErrorText Property (TDBDropDown)

EvenRowStyle Property (TDBDropDown)

ExtendRightColumn Property (TDBDropDown)

FetchRowStyle Property (TDBDropDown)

FirstRow Property (TDBDropDown)

Font Property (TDBDropDown)

FooterBackColor Property (TDBDropDown)

FooterFont Property (TDBDropDown)

FooterForeColor Property (TDBDropDown)

FooterStyle Property (TDBDropDown)

FootLines Property (TDBDropDown)

ForeColor Property (TDBDropDown)

HeadBackColor Property (TDBDropDown)

HeadFont Property (TDBDropDown)

HeadForeColor Property (TDBDropDown)

HeadingStyle Property (TDBDropDown)

HeadLines Property (TDBDropDown)

HighlightRowStyle Property (TDBDropDown)

hWnd Property (TDBDropDown)

IntegralHeight Property

LayoutFileName Property (TDBDropDown)

LayoutName Property (TDBDropDown)

Layouts Property (TDBDropDown)

LayoutURL Property (TDBDropDown)

LeftCol Property (TDBDropDown)

ListField Property

OddRowStyle Property (TDBDropDown)

PartialRightColumn Property (TDBDropDown)

RightToLeft Property (TDBDropDown)

Row Property (TDBDropDown)

RowDividerColor Property (TDBDropDown)

RowDividerStyle Property (TDBDropDown)

RowHeight Property (TDBDropDown)

RowTracking Property

ScrollBars Property (TDBDropDown)

ScrollTips Property (TDBDropDown)

ScrollTrack Property (TDBDropDown)

SelectedItem Property

SelEndCol Property (TDBDropDown)

SelStartCol Property (TDBDropDown)

Style Property (TDBDropDown)

Styles Property (TDBDropDown)

Text Property (TDBDropDown)

ValueTranslate Property

VisibleCols Property (TDBDropDown)

VisibleRows Property (TDBDropDown)


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 for more information.

Note

The AllowColSelect property must also be True in order for the user to move selected columns.

See Also

TDBGrid Control

TDBDropDown Control

Split Object


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.

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

TDBDropDown Control

Split Object


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

TDBDropDown Control

Split Object


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

TDBDropDown Control

Split Object


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.

See Also

TDBGrid Control

TDBDropDown Control

Split Object


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

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control


BackColor Property (TDBDropDown)

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

TDBDropDown Control

Column Object

Style Object

Split Object


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

TDBDropDown Control


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

TDBDropDown Control


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

Remarks

Read/Write at run time and design time.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control

Split Object


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.

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

TDBDropDown Control

Split Object


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

Column Object


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.

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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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

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

TDBDropDown Control


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

TDBDropDown Control


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.

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

TDBDropDown Control


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

TDBDropDown Control

Split Object


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.

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

TDBDropDown Control

Split Object


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

TDBDropDown Control

Split Object


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.

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

TDBDropDown Control

Split Object


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

TDBDropDown Control

Column Object

Split Object

Style Object


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.

See Also

TDBGrid Control

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control


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

TDBDropDown Control

Column Object

Split Object

Style Object


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Column Object

Split Object


HeadingStyle Property (TDBDropDown)

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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control


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

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

TDBDropDown Control

Split Object


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

TDBDropDown Control


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.

See Also

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control


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 procedure is to set the LayoutName property in the LayoutReady handler, immediately before calling the LoadLayout method.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control

Split Object


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.

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


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

TDBDropDown Control

Split Object


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

TDBDropDown Control

Split Object


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

TDBDropDown Control


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.

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

TDBDropDown Control


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

TDBDropDown Control


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.

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

TDBDropDown Control


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

TDBDropDown Control


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.

See Also

TDBDropDown Control


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

TDBDropDown Control

Split Object


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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


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

TDBDropDown Control

Split Object


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

TDBDropDown Control

Split Object


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

TDBDropDown Control

Column Object

Split Object


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control

Column Object


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.

When this property is set to True, the grid will automatically display the ListField values in the associated column.

See Also

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control


TDBDropDown Methods

AboutBox Method (TDBDropDown)

AddCellStyle Method (TDBDropDown)

AddRegexCellStyle Method (TDBDropDown)

CaptureImage Method (TDBDropDown)

ClearCellStyle Method (TDBDropDown)

ClearFields Method (TDBDropDown)

ClearRegexCellStyle Method (TDBDropDown)

ClearSelCols Method (TDBDropDown)

ColContaining Method (TDBDropDown)

GetBookmark Method (TDBDropDown)

HoldFields Method (TDBDropDown)

PostMsg Method (TDBDropDown)

ReBind Method (TDBDropDown)

Refresh Method (TDBDropDown)

RowBookmark Method (TDBDropDown)

RowContaining Method (TDBDropDown)

RowTop Method (TDBDropDown)

Scroll Method (TDBDropDown)


AboutBox Method (TDBDropDown)

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

TDBDropDown Control


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.

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

TDBDropDown Control

Column Object

Split Object


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.
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"

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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control


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.

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

TDBDropDown Control

Column Object

Split Object


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

TDBDropDown Control

Split Object


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)

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

TDBDropDown Control


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.

Note

Do not confuse the GetBookmark method with the RowBookmark method, which can only return bookmarks for visible rows.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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.

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

TDBDropDown Control


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.

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

TDBDropDown Control


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

TDBDropDown Control

Column Object


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

TDBDropDown Control


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.

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

TDBDropDown Control


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

TDBDropDown Control


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

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

TDBDropDown Control


TDBDropDown Events

ClassicRead Event (TDBDropDown)

Click Event (TDBDropDown)

ColMove Event (TDBDropDown)

ColResize Event (TDBDropDown)

DataSourceChanged Event (TDBDropDown)

DblClick Event (TDBDropDown)

DropDownClose Event

DropDownOpen Event

Error Event (TDBDropDown)

FetchCellStyle Event (TDBDropDown)

FetchRowStyle Event (TDBDropDown)

FetchScrollTips Event (TDBDropDown)

FirstRowChange Event (TDBDropDown)

FootClick Event (TDBDropDown)

FormatText Event (TDBDropDown)

HeadClick Event (TDBDropDown)

KeyDown Event (TDBDropDown)

KeyPress Event (TDBDropDown)

KeyUp Event (TDBDropDown)

LayoutReady Event (TDBDropDown)

LeftColChange Event (TDBDropDown)

MouseDown Event (TDBDropDown)

MouseMove Event (TDBDropDown)

MouseUp Event (TDBDropDown)

Paint Event (TDBDropDown)

PostEvent Event (TDBDropDown)

RowChange Event

RowResize Event (TDBDropDown)

Scroll Event (TDBDropDown)

SelChange Event (TDBDropDown)

UnboundColumnFetch Event (TDBDropDown)

UnboundFindData Event

UnboundGetRelativeBookmark Event (TDBDropDown)

UnboundReadData Event (TDBDropDown)

UnboundReadDataEx Event (TDBDropDown)

ValueItemError Event (TDBDropDown)


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

TDBDropDown Control


Click Event (TDBDropDown)

The Click event occurs when the user presses then releases a mouse button over the grid.

Syntax

object_Click ( )

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

TDBDropDown Control


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

TDBDropDown Control


ColResize Event (TDBDropDown)

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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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.

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


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


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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)

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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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 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

TDBDropDown Control


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

TDBDropDown Control


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

TDBDropDown Control


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.

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

TDBDropDown Control


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

TDBDropDown Control


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 ( )

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

TDBDropDown Control


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

Note

Take care to avoid recursive situations when using PostMsg and PostEvent.

See Also

TDBGrid Control

TDBDropDown Control


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


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.

See Also

TDBGrid Control

TDBDropDown Control


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

TDBDropDown Control


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.

· 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

TDBDropDown Control


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.

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

TDBDropDown Control


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.

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


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.

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

TDBDropDown Control


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.

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

TDBDropDown Control


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.

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

TDBDropDown Control


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

TDBDropDown Control


Constant Reference

AddNewMode Constants

Alignment Constants

AnimateWindow Constants

AnimateWindowClose Constants

AnimateWindowDirection Constants

Appearance Constants

BackgroundPictureDrawMode Constants

BorderStyle Constants

CellStyle Constants

CellTip Constants

CellTipPresentation Constants

ConvertEmptyCell Constants

DataMode Constants

DataView Constants

DividerStyle Constants

Error Constants

ExposeCellMode Constants

FetchCellStyle Constants

ForegroundPicturePosition Constants

MarqueeStyle Constants

MergeCell Constants

MousePointer Constants

MoveDirection Constants

MultipleLines Constants

MultiSelect Constants

OLEDragMode Constants

OLEDropMode Constants

PointAt Constants

Presentation Constants

PrintInfo_Menu Constants

RowSelector Constants

ScrollBars Constants

SplitSizeMode Constants

StyleBorderAppearance Constants

StyleBorderType Constants

TabAction Constants

UnboundFind Constants

VerticalAlignment Constants


AddNewMode Constants

Applies To

AddNewMode Property

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

FooterAlignment Property

HeadAlignment Property

Values

Design Time | Run Time
0 - Left | dbgLeft
1 - Right | dbgRight
2 - Center | dbgCenter
3 - General (default) | dbgGeneral


AnimateWindow Constants

Applies To

AnimateWindow Property

Values

Design Time | Run Time
0 - No Animate (default) | dbgNoAnimate
1 - Roll | dbgRoll
2 - Slide | dbgSlide
3 - Blend | dbgBlend


AnimateWindowClose Constants

Applies To

AnimateWindowClose Property

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

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

Values

Design Time | Run Time
0 - Flat | dbgFlat
1 - 3D (default) | dbg3D


BackgroundPictureDrawMode Constants

Applies To

BackgroundPictureDrawMode Property

Values

Design Time | Run Time
0 - Center (default) | dbgBPCenter
1 - Tile | dbgBPTile
2 - Stretch | dbgBPStretch


BorderStyle Constants

Applies To

BorderStyle Property

Values

Design Time | Run Time
0 - None | dbgNoBorder
1 - Fixed Single (default) | dbgFixedSingle


CellStyle Constants

Applies To

AddCellStyle Method

AddRegexCellStyle Method

ClearCellStyle Method

ClearRegexCellStyle Method

FetchCellStyle Event

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

Values

Description | Run Time
-1 - On Record Selector | dbgOnRecordSelector
-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

Values

Design Time | Run Time
0 - None (default) | dbgNoCellTips
1 - Anchored | dbgAnchored
2 - Floating | dbgFloating


ConvertEmptyCell Constants

Applies To

ConvertEmptyCell Property

Values

Design Time | Run Time
0 - Write as is (default) | dbgNoConversion
1 - Write as Null value | dbgAsNull


DataMode Constants

Applies To

DataMode Property

Values

Design Time | Run Time
0 - Bound (default) | dbgBound
1 - Unbound | dbgUnbound
2 - Unbound Extended | dbgUnboundEx
3 - Application | dbgUnboundAp
4 - Storage | dbgUnboundSt


DataView Constants

Applies To

DataView Property

Values

Design Time | Run Time
0 - Normal (default) | dbgNormalView
1 - Hierarchical | dbgHierarchicalView
2 - Group | dbgGroupView


DividerStyle Constants

Applies To

DividerStyle Property

RowDividerStyle Property

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
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 type | dbgINCOMPAT
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

Values

Design Time | Run Time
0 - Scroll on Select (default) | dbgScrollOnSelect
1 - Scroll on Edit | dbgScrollOnEdit
2 - Never Scroll | dbgScrollNever


FetchCellStyle Constants

Applies To

FetchStyle Property

Values

Design Time | Run Time
0 - None | dbgFetchCellStyleNone
1 – Column | dbgFetchCellStyleColumn
2 – Column and AddNew | dbgFetchCellStyleAddNewColumn


ForegroundPicturePosition Constants

Applies To

ForegroundPicturePosition Property

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

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


MergeCell Constants

Applies To

Merge Property

Values

Design Time | Run Time
0 - None | dbgMergeNone
1 - Free | dbgMergeFree
2 - Restricted | dbgMergeRestricted


MousePointer Constants

Applies To

MousePointer Property

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


MoveDirection Constants

Applies To

DirectionAfterEnter Property

DirectionAfterTab Property

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

Values

Design Time | Run Time
0 - Disabled (default) | dbgMultipleDisabled
1 - Variable | dbgMultipleVariable
2 - Fixed | dbgMultipleFixed


MultiSelect Constants

Applies To

MultiSelect Property

Values

Design Time | Run Time
0 - None | dbgMultiSelectNone
1 - Simple (default) | dbgMultiSelectSimple
2 - Extended | dbgMultiSelectExtended


OLEDragMode Constants

Applies To

OLEDragMode Property

Values

Design Time | Run Time
0 - Manual (default) | dbgOLEDragManual
1 - Automatic | dbgOLEDragAutomatic


OLEDropMode Constants

Applies To

OLEDropMode Property

Values

Design Time | Run Time
0 - None (default) | dbgOLEDropNone
1 - Manual | dbgOLEDropManual
2 - Automatic | dbgOLEDropAutomatic


PointAt Constants

Applies To

PointAt Method

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

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

SetMenuText Method

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
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

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

ExportToFile Method

PrintData Method

PrintPreview Method

Values

Description | Run Time
0 - All Rows | dbgAllRows
1 - Selected Rows | dbgSelectedRows
2 - Current Row | dbgCurrentRow


ScrollBars Constants

Applies To

ScrollBars Property

Values

Design Time | Run Time
0 - None | dbgNone
1 - Horizontal | dbgHorizontal
2 - Vertical | dbgVertical
3 - Both | dbgBoth
4 - Automatic (default) | dbgAutomatic


SplitSizeMode Constants

Applies To

SizeMode Property

Values

Design Time | Run Time
0 - Scalable (default) | dbgScalable
1 - Exact | dbgExact
2 - Number of Columns | dbgNumberOfColumns


StyleBorderAppearance Constants

Applies To

BorderAppearance Property

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

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

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

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

Values

Design Time | Run Time
0 - Top (default) | dbgTop
1 - Bottom | dbgBottom
2 - Vertical Center | dbgVertCenter


PrintInfo Reference

PrintInfo All Members

PrintInfo Properties

PrintInfo Methods


PrintInfo All Members

PrintInfo Object Properties

PrintInfo Object Methods


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
RepeatGridHeader | Sets/returns whether the grid caption appear on each page
RepeatSplitHeaders | Sets/returns whether split captions appear on each page
Settings | Page setup and printer settings blob (run time only)
SettingsDeviceName | Provides access to the printing device name in the Settings blob
SettingsMarginBottom | Provides access to the bottom margin (twips) in the Settings blob
SettingsMarginLeft | Provides access to the left margin (twips) in the Settings blob
SettingsMarginRight | Provides access to the right margin (twips) in the Settings blob
SettingsMarginTop | Provides access to the top margin (twips) in the Settings blob
SettingsOrientation | Provides access to the paper orientation in the Settings blob
SettingsPaperBin | Provides access to the paper bin in the Settings blob
SettingsPaperHeight | Provides access to the paper height (twips) in the Settings blob
SettingsPaperSize | Provides access to the paper size in the Settings blob
SettingsPaperWidth | Provides access to the paper width (twips) in the Settings blob
UnitsPerInch | Returns the number of logical units per inch
VariableRowHeight | 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)

Default Property (PrintInfo)

Draft Property (PrintInfo)

Name Property (PrintInfo)

NeedTotalPageCount Property (PrintInfo)

NoClipping Property (PrintInfo)

NumberOfCopies Property (PrintInfo)

PageFooter Property (PrintInfo)

PageFooterFont Property (PrintInfo)

PageFooterHeight Property (PrintInfo)

PageFooterOwnerDraw Property (PrintInfo)

PageHeader Property (PrintInfo)

PageHeaderFont Property (PrintInfo)

PageHeaderHeight Property (PrintInfo)

PageHeaderOwnerDraw Property (PrintInfo)

PageSetupCancelled Property (PrintInfo)

PreviewAllowFileOps Property (PrintInfo)

PreviewCaption Property (PrintInfo)

PreviewInitHeight Property (PrintInfo)

PreviewInitPosX Property (PrintInfo)

PreviewInitPosY Property (PrintInfo)

PreviewInitScreenFill Property (PrintInfo)

PreviewInitWidth Property (PrintInfo)

PreviewInitZoom Property (PrintInfo)

PreviewMaximize Property (PrintInfo)

PreviewPageOf Property (PrintInfo)

RangeOfPages Property (PrintInfo)

RepeatColumnFooters Property (PrintInfo)

RepeatColumnHeaders Property (PrintInfo)

RepeatGridHeader Property (PrintInfo)

RepeatSplitHeaders Property (PrintInfo)

Settings Property (PrintInfo)

SettingsDeviceName Property (PrintInfo)

SettingsMarginBottom Property (PrintInfo)

SettingsMarginLeft Property (PrintInfo)

SettingsMarginRight Property (PrintInfo)

SettingsMarginTop Property (PrintInfo)

SettingsOrientation Property (PrintInfo)

SettingsPaperBin Property (PrintInfo)

SettingsPaperHeight Property (PrintInfo)

SettingsPaperSize Property (PrintInfo)

SettingsPaperWidth Property (PrintInfo)

UnitsPerInch Property (PrintInfo)

VariableRowHeight Property (PrintInfo)


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.

See Also

PrintInfo Object


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


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


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.

When a TDBGrid control is first created, its PrintInfos collection contains a single PrintInfo object named DefaultPrintInfo.

See Also

PrintInfo Object


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


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


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.

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


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

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


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


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


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.

See Also

PrintInfo Object


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


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


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


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


PageSetupCancelled Property (PrintInfo)

This property returns a boolean that determines whether the PageSetup dialog has been cancelled by the user.

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


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


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


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


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


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


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

Remarks

Read/Write at run time and design time.

The default value (zero) is equivalent to 80%.

See Also

PrintInfo Object


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


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


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.

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


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


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.

· 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


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


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.

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


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


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


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


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.

See Also

PrintInfo Object


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


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


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

See Also

PrintInfo Object


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


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


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


SettingsPaperHeight Property (PrintInfo)

Use this property to specify the paper height ( in twips) in the print Settings blob.

Syntax

PrintInfo.SettingsPaperHeight = long

Remarks

Read/Write at run time. Not available at design time.

See Also

PrintInfo Object


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


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


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.

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


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


PrintInfo Methods

GetMenuText Method (PrintInfo)

GetSubstituteFont Method (PrintInfo)

PageSetup Method (PrintInfo)

PrintData Method (PrintInfo)

PrintPreview Method (PrintInfo)

SetMenuText Method (PrintInfo)

SubstituteFont Method (PrintInfo)


GetMenuText Method (PrintInfo)

Retrieves the text of the specified PrintPreview menu item.

Syntax

PrintInfo.GetMenuText (index)

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


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


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.

See Also

PrintInfo Object


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


PrintPreview Method (PrintInfo)

Opens the print preview window on the grid's contents.

Syntax

PrintInfo.PrintPreview [selector]

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


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.

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


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


XArrayDB Reference

XArrayDB All Members

XArrayDB Properties

XArrayDB Methods

XArrayDB Object Constants


XArrayDB All Members

XArrayDB Object Properties

XArrayDB Object Methods


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)

DefaultColumnType Property (XArrayDB)

LowerBound Property (XArrayDB)

Notify Property (XArrayDB)

Precision Property (XArrayDB)

UpperBound Property (XArrayDB)

Value Property (XArrayDB)


Count Property (XArrayDB)

This property returns a long integer that specifies the number of elements contained in a given dimension of an XArrayDB object.

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


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

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


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


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.

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


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


UpperBound Property (XArrayDB)

This property returns a long integer that specifies the upper bound index for a given dimension of an XArrayDB object.

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


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:

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


XArrayDB Methods

AboutBox Method (XArrayDB)

AppendColumns Method (XArrayDB)

AppendRows Method (XArrayDB)

Clear Method (XArrayDB)

Delete Method (XArrayDB)

DeleteColumns Method (XArrayDB)

DeleteRows Method (XArrayDB)

Find Method (XArrayDB)

Get Method (XArrayDB)

Insert Method (XArrayDB)

InsertColumns Method (XArrayDB)

InsertRows Method (XArrayDB)

LoadRows Method (XArrayDB)

QuickSort Method (XArrayDB)

ReDim Method (XArrayDB)

Set Method (XArrayDB)


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


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

See Also

XArrayDB Object


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


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


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


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.

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


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

' 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


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

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


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


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.

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


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

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


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

Debug.Print MyArray(5, 1) ' prints Row 2, Col 1

Debug.Print MyArray(13, 1) ' prints Row 10, Col 1

See Also

XArrayDB Object


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


QuickSort Method (XArrayDB)

Uses the quicksort method to sort an array.

Syntax

XArrayDB.QuickSort rowstart, rowend, column1, order1, type1 [, …, column10, order10, type10]

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


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.

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


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


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.