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

Corporate Headquarters ComponentOne LLC 4516 Henry Street Suite 500 Pittsburgh, PA 15213 USA

Internet: info@ComponentOne.com Web site: http://www.componentone.com

Sales E-mail: sales@componentone.com Telephone: 1.800.858.2739 or 1.412.681.4343 (Pittsburgh, PA USA Office)

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

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

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

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

· iii

Table of Contents Table of Contents ....................................................................................................................... iii Overview........................................................................................................................................ 1

Product Profile ........................................................................................................................ 1 Installation............................................................................................................................... 3 Adding the True DBGrid Pro 8.0 Components to the Toolbox........................................ 3 Upgrading ............................................................................................................................... 4 END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE.............. 5 Redistributable Files............................................................................................................. 12 Technical Support................................................................................................................. 13

The Basics..................................................................................................................................... 15 Specifying a Data Source ..................................................................................................... 15 Choosing a Column Layout ................................................................................................ 16 Configuring Columns at Design Time .............................................................................. 17 Configuring Columns at Run Time ................................................................................... 20 Understanding Bookmarks ................................................................................................. 23

True DBGrid Samples ............................................................................................................... 25 ICursor and OLEDB Samples ............................................................................................. 25 True DBGrid Extra Samples................................................................................................ 25

Tutorials ....................................................................................................................................... 27 Introduction .......................................................................................................................... 27 Tutorial 1 - Binding True DBGrid to a Data Control ....................................................... 27 Tutorial 2 - Using True DBGrid with SQL Query Results .............................................. 29 Tutorial 3 - Linking Multiple True DBGrid Controls ...................................................... 32 Tutorial 4 - Interacting with Code and Other Bound Controls ...................................... 33 Tutorial 5 - Selecting Multiple Rows Using Bookmarks ................................................. 37 Tutorial 6 - Defining Unbound Columns in a Bound Grid............................................. 38 Tutorial 7 - Displaying Translated Data with the Built-in Combo ................................ 42 Tutorial 8 - Attaching a True DBDropDown Control to a Grid Cell ............................. 44 Tutorial 9 - Attaching an Arbitrary Drop-down Control to a Grid Cell ....................... 46 Tutorial 10 - Enhancing the User Interface with In-Cell Bitmaps.................................. 49 Tutorial 11 - Using Styles to Highlight Related Data ...................................................... 51 Tutorial 12 - Displaying Rows in Alternating Colors...................................................... 54 Tutorial 13 - Implementing Drag-and-Drop in True DBGrid......................................... 56 Tutorial 14 - OLE Drag-and-Drop...................................................................................... 61 Tutorial 15 - Creating a Grid with Fixed, Nonscrolling Columns ................................. 63 Tutorial 16 - Displaying Array Data in Unbound Mode................................................. 64 Tutorial 17 - Displaying Array Data in Unbound Extended Mode............................... 70 Tutorial 18 - Displaying Array Data in Unbound Application Mode........................... 75 Tutorial 19 - Displaying Array Data in Unbound Storage Mode .................................. 79 Tutorial 20 - Sorting and Searching ................................................................................... 81 Tutorial 21 - Displaying Arbitrary Bitmaps...................................................................... 84 Tutorial 22 - Reusable Layouts ........................................................................................... 86 Tutorial 23 - Printing, Print Preview, and Export ............................................................ 88 Tutorial 24 - Displaying Hierarchical Data ....................................................................... 91 Tutorial 25 - Outlook-Style Grouping................................................................................ 97

iv ·

Tutorial 26 - Value Translation ......................................................................................... 100 Tutorial 27 - Range Selection............................................................................................. 103 Tutorial 28 - Transposed Views........................................................................................ 105 Tutorial 29 - Filter Bar ........................................................................................................ 108 Tutorial 30 - Cell Bordering and Scroll Tips/Tracking ................................................. 111

Object Model............................................................................................................................. 117 True DBGrid Objects and Collections.............................................................................. 117 TDBGrid Control ................................................................................................................ 118 TDBDropDown Control .................................................................................................... 118 Column Object, Columns Collection ............................................................................... 119 DataObject Object, DataObjectFiles Collection............................................................... 119 Error Object, Errors Collection ......................................................................................... 120 GroupColumns Collection ................................................................................................ 120 Layouts Collection.............................................................................................................. 121 PrintInfo Object, PrintInfos Collection ............................................................................ 121 RowBuffer Object................................................................................................................ 121 SelBookmarks Collection................................................................................................... 121 Split Object, Splits Collection............................................................................................ 122 Style Object, Styles Collection........................................................................................... 122 ValueItem Object, ValueItems Collection ....................................................................... 123 XArrayDB Object ................................................................................................................ 123 Working with Objects and Collections ............................................................................ 123

Design Time Interaction.......................................................................................................... 129 Context Menu...................................................................................................................... 129 Visual Editing Mode .......................................................................................................... 130 Property Page Overview ................................................................................................... 135 TDBGrid Property Pages ................................................................................................... 147 TDBDropDown Property Pages ....................................................................................... 171 Reusable Layouts................................................................................................................ 178 TDBDropDown at Design Time ....................................................................................... 179

Run Time Interaction............................................................................................................... 181 Navigation and Scrolling................................................................................................... 181 Selection and Movement ................................................................................................... 184 Sizing and Splitting ............................................................................................................ 188 Database Operations .......................................................................................................... 190 Drag-and-Drop Behavior................................................................................................... 191 Additional User Interaction Features .............................................................................. 193

Bound Mode .............................................................................................................................. 195 Binding True DBGrid to a Data Source ........................................................................... 195 Visual Basic Data Control Considerations ...................................................................... 196 Unbound Columns............................................................................................................. 198

Storage Mode............................................................................................................................. 205 When to Use Storage Mode............................................................................................... 205 Using the XArrayDB Object .............................................................................................. 205 Interactions between True DBGrid and XArrayDB ....................................................... 207 Storage Mode Examples .................................................................................................... 209

Application Mode..................................................................................................................... 211 When to Use Application Mode ....................................................................................... 211 How Application Mode Works ........................................................................................ 211

· v

Application Mode Bookmarks.......................................................................................... 212 Application Mode Events.................................................................................................. 214 Application Mode Programming Considerations ......................................................... 216 Application Mode Example .............................................................................................. 217

Unbound Mode......................................................................................................................... 219 When to Use Unbound Mode........................................................................................... 219 How Unbound Mode Works ............................................................................................ 220 Unbound Mode Bookmarks.............................................................................................. 221 Using the RowBuffer Object ............................................................................................. 221 Unbound Mode Events...................................................................................................... 223 Unbound Mode Programming Considerations ............................................................. 232 Unbound Mode Examples ................................................................................................ 234

Database Programming Techniques ..................................................................................... 235 Changing the Current Record Position ........................................................................... 235 Accessing and Manipulating Cell Data ........................................................................... 236 Validating Cell Data........................................................................................................... 237 Selecting and Highlighting Records ................................................................................ 240 Updating and Deleting the Current Record ................................................................... 241 Refreshing the Display....................................................................................................... 241 Refetching Data from the Data Source ............................................................................ 242 Coordinating with Other Controls................................................................................... 242 Handling Database Errors................................................................................................. 243 Postponing Illegal Operations in Grid Events................................................................ 245

Customizing the Grid's Appearance..................................................................................... 247 Captions, Headers, and Footers ....................................................................................... 247 Three-dimensional versus Flat Display........................................................................... 249 Borders and Dividing Lines .............................................................................................. 251 Unpopulated Regions ........................................................................................................ 252 Highlighting the Current Row or Cell............................................................................. 254 Row Height and Multiple-line Displays ......................................................................... 257 Alternating Row Colors..................................................................................................... 259 Horizontal and Vertical Alignment ................................................................................. 260 Window Animation ........................................................................................................... 261

Data Presentation Techniques ............................................................................................... 263 Text Formatting .................................................................................................................. 263 Automatic Data Translation with ValueItems................................................................ 265 Context-sensitive Help with CellTips.............................................................................. 274 Scroll Tracking and ScrollTips.......................................................................................... 276 Data-sensitive Cell Merging.............................................................................................. 276 Outlook-Style Grouping.................................................................................................... 278 Hierarchical Data Display ................................................................................................. 279 Dropdown Hierarchical Data Display............................................................................. 281 Form Data Display ............................................................................................................. 284 Inverted Data Display........................................................................................................ 284 Owner-drawn Cells............................................................................................................ 285 Filtering Data in Recordsets.............................................................................................. 288

How to Use Splits ..................................................................................................................... 293 Referencing Splits and their Properties ........................................................................... 293 Creating and Removing Splits.......................................................................................... 296

vi ·

Working with Columns in Splits ...................................................................................... 296 Sizing and Scaling Splits.................................................................................................... 299 Creating and Resizing Splits through User Interaction................................................. 302 Vertical Scrolling and Split Groups.................................................................................. 304 Horizontal Scrolling and Fixed Columns........................................................................ 305 Navigation across Splits .................................................................................................... 306

How to Use Styles..................................................................................................................... 307 Built-in Named Styles ........................................................................................................ 307 Working with Style Properties.......................................................................................... 311 Applying Styles to Cells .................................................................................................... 321 Applying Pictures to Grid Elements ................................................................................ 326

Cell Editing Techniques.......................................................................................................... 333 How Cell Editing Works ................................................................................................... 333 Handling Editing Events ................................................................................................... 334 Working with Text ............................................................................................................. 336 Input Masking..................................................................................................................... 337 In-cell Buttons ..................................................................................................................... 339 Drop-down Controls .......................................................................................................... 341

Object Reference....................................................................................................................... 347 True DBGrid All Members ................................................................................................ 347 True DBGrid Properties..................................................................................................... 362 True DBGrid Methods ....................................................................................................... 488 True DBGrid Events ........................................................................................................... 526 TDBDropDown All Members........................................................................................... 573 TDBDropDown Properties................................................................................................ 577 TDBDropDown Methods .................................................................................................. 612 TDBDropDown Events ...................................................................................................... 625

Constant Reference................................................................................................................... 649 PrintInfo Reference .................................................................................................................. 665

PrintInfo All Members ....................................................................................................... 665 PrintInfo Properties ............................................................................................................ 666 PrintInfo Methods .............................................................................................................. 683

XArrayDB Reference................................................................................................................ 689 XArrayDB All Members .................................................................................................... 689 XArrayDB Properties ......................................................................................................... 689 XArrayDB Methods............................................................................................................ 694 XArrayDB Object Constants.............................................................................................. 705

Index............................................................................................................................................ 707

Product Profile · 1

Overview Welcome to ComponentOne True DBGrid® Pro 8. True DBGrid Pro 8.0 is a powerful, versatile, and easy-to-use data presentation tool. Novice programmers can use True DBGrid Pro 8.0 to create a fully functional database browser without writing a single line of code. Professional developers can use the grid control's many properties and events to create sophisticated and user-friendly database front-end applications.

If you like True DBGrid Pro 8.0, you can check out our other products by visiting our web site at http://www.componentone.com. ComponentOne has a user-friendly distribution policy. We want every programmer to obtain a copy of True DBGrid Pro 8.0 to try for as long as they wish. Those who like the product and find it useful may buy a license for a reasonable price. The only restriction is that unlicensed copies of True DBGrid Pro 8.0 will display a ComponentOne banner every time they are loaded to remind developers to license the product.

We are confident that you'll like True DBGrid Pro 8.0. If you have any suggestions or ideas for new features or tools that you'd like to see included in a future version please call us or write:

Corporate Headquarters

ComponentOne LLC 4516 Henry Street Suite 500 Pittsburgh, PA 15213 USA 412.681.4343 412.681.4384 (Fax)

http://www.componentone.com

Product Profile True DBGrid Pro 8.0 is a data-aware ActiveX grid control for Microsoft Visual Studio. Developed by ComponentOne LLC, True DBGrid Pro 8.0 is the upgrade to the DBGrid control included in this product, as well as earlier versions of Microsoft Visual Basic and Visual C++.

True DBGrid Pro 8.0 allows end users to browse, edit, add, and delete data in a tabular format. Using the latest data-binding technologies built into Visual Studio, including OLE DB, True DBGrid Pro 8.0 completely manages the database interface, allowing developers to concentrate on important application-specific tasks. True DBGrid Pro 8.0 can also be used in unbound or storage mode with a programmer's own data source.

In addition to being the fastest database grid on the market, True DBGrid Pro 8.0 includes dozens of advanced data access, data presentation, and user interface features that enable developers to build intuitive, professional-looking applications:

100% DBGrid compatibility True DBGrid Pro 8.0 supports all of the features of the Microsoft Data Bound Grid control (DBGrid).

Excel and Word-like styles Style objects encapsulate font, color, picture, and formatting information, facilitating easy customization of grid components at design time and run time.

http://www.componentone.com/http://www.componentone.com/

2 · Overview

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.

Installation · 3

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.

http://www.componentone.com/

4 · Overview

To use the True DBGrid components, they must be added to the Visual Studio Toolbox:

Open the Visual Basic IDE (Microsoft's Integrated Development Environment). Make sure the Toolbox is visible (if necessary, select Toolbox in the View menu).

To set up the True DBGrid components to appear on their own tab, right-click anywhere in the Toolbox and select Add Tab from the context menu. Enter a tab name, for example, “True DBGrid 8”, in the dialog box. Select the new tab. Right-click the gray area under that tab and select Components from the context menu. The Components dialog box opens.

In the Components dialog box, find and select ComponentOne True DBGrid Pro 8.0. Click OK.

Note that the class names are the same regardless of which control is used. However, the type library name used to qualify object references is TrueDBGrid80 for the legacy control, and TrueOleDBGrid80 for the OLE DB control.

Also note that the OLE DB control can only be used with Visual Basic 6.0 or higher.

Upgrading If you have projects which use versions of True DBGrid other than True DBGrid Pro 8.0, you can easily convert them to use True DBGrid Pro 8.0 by running the add-in migration utility.

The True DBGrid Pro 8.0 Migration Utility is copied to your system during installation. A single add-in is provided for both Visual Basic 5.0 and 6.0. To activate the add-in within the design-time environment, follow these instructions:

• Run Visual Basic and select Add-In Manager… from the Add-Ins menu. The Add-In Manager dialog will appear.

• If you are using Visual Basic 6.0, select the list item labeled True DBGrid Pro 8.0 Migration Utility, then check the Loaded/Unloaded box.

• If you are using Visual Basic 5.0, check the box labeled True DBGrid Pro 8.0 Migration Utility.

END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 5

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

After you have added the True DBGrid Pro 8.0 Migration Utility to the list of available add-ins, follow these steps to convert your projects:

• Make backup copies of any projects that you plan to convert.

• Open a project that contains one of the controls listed in the From column in the migration chart.

• Click the migration utility icon on the toolbar.

• Choose the type of migration that applies to your project (for example, from DBGrid 1.0 to True DBGrid Pro 8.0, or from True DBGrid Pro 7.0 to True DBGrid Pro 8.0 OLE DB), then click OK.

If the conversion succeeds, a message box will appear to inform you that "The current project was converted successfully." To avoid conflict, the migration utility also removes the From control from the Visual Basic Toolbox.

Please note that the migration utility may also need to modify your source code. Whenever source code is modified, the original code will be commented out and the modification will be tagged with the following comment:

*** ComponentOne Migration Utility Code Change ***

END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE

IMPORTANT-READ CAREFULLY: This End User License Agreement (this "EULA") contains the terms and conditions regarding your use of the SOFTWARE (as defined below). This EULA contains material limitations to your rights in that regard. You should read this EULA carefully and treat it as valuable property.

I. THIS EULA.

1. Software Covered by this EULA. This EULA governs your use of the ComponentOne, LLC ("C1") software product(s) enclosed or otherwise accompanied herewith (individually and collectively, the "SOFTWARE"). The term "SOFTWARE" includes, to the extent provided by C1: 1) any revisions, updates and/or upgrades thereto; 2) any data, image or executable files, databases, data engines, computer software, or similar items customarily used or distributed with computer software products; 3) anything in any form whatsoever intended to be used with or in conjunction with the SOFTWARE; and 4) any associated media, documentation (including physical, electronic and on-line) and printed materials (the "Documentation").

2. This EULA is a Legally Binding Agreement Between You and C1. If you are acting as an agent of a company or another legal person, such as an officer or other employee acting for your employer, then "you" and "your" mean your principal, the entity or other legal person for whom you are acting. However, importantly, even if you are acting as an agent for another, you may still be personally liable for violation of federal and State laws, such as copyright infringement.

This EULA is a legally binding agreement between you and C1. You intend to be legally bound to this EULA to the same extent as if C1 and you physically signed this EULA. By installing, copying, or otherwise using the SOFTWARE, you agree to be bound by the terms and conditions contained in this EULA. If you do not agree to all of the terms and conditions contained in this EULA, you may not install or use the SOFTWARE. If, for whatever reason, installation has

6 · Overview

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

II. YOUR LICENSE TO DEVELOP AND TO DISTRIBUTE.

As provided in more detail below, this EULA grants you two licenses: 1) a license to use the SOFTWARE to develop other software products (the "Development License"); and 2) a license to use and/or distribute the Developed Software (the "Distribution License"). Both of these licenses (individually and collectively, the "Licenses") are explained and defined in more detail below.

1. Definitions. The following terms have the respective meanings as used in this EULA:

"Network Server" means a computer with one or more computer central processing units (CPU's) that operates for the purpose of serving other computers logically or physically connected to it, including, but not limited to, other computers connected to it on an internal network, intranet or the Internet. "Web Server" means a type of Network Server that serves other computers more particularly connected to it over an intranet or the Internet.

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

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

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

END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 7

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

The SOFTWARE is licensed to you on a Developer Seat License basis.

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

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

3. Your Distribution License.

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

4. Specific Product Limitations. Notwithstanding anything in this EULA to the contrary, if the license you have purchased is for any of the following products, then the following additional limitations will apply:

a. ComponentOne Reports for .NET Designer Edition. ComponentOne Reports for .NET Designer Edition includes at least: 1) one dynamic link library (c1.win.c1reportdesigner.dll) file known as C1ReportDesigner Component, 2) one executable (ReportDesigner.exe) file known as C1ReportDesigner Application and, 3) the Source Code of the C1ReportDesigner Application. The C1ReportDesigner Component is subject to the general terms and restrictions set forth in this EULA. The C1ReportDesigner Application is an executable file used to design and prepare reports; the C1ReportDesigner Application may be distributed, free of royalties, only in conjunction with the Developed Software.

8 · Overview

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

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

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

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

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

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

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

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

5. Updates/Upgrades; Studio Subscription. Subject to the terms and conditions of this EULA, the Licenses are perpetual. Updates and upgrades to the SOFTWARE may be provided by C1 from time-to-time, and, if so provided by C1, are provided upon the terms and conditions offered at that time by C1 in its sole discretion. C1 may provide updates and upgrades to the SOFTWARE for free or for any charge, at any time or never, and through its chosen manner of access and distribution, all in C1's sole and complete discretion.

C1 licenses certain of its separately-licensed products bundled together in a product suite, called the C1 "Studio" product line (the "Studio Products"). The exact separately-licensed products that

END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 9

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

6. Serial Number. Within the packaging of the SOFTWARE, a unique serial number (the "Serial Number") is included, which allows for the registration of the SOFTWARE. The Serial Number is subject to the restrictions set forth in this EULA and may not be disclosed or distributed either with your Developed Software or in any other way. The disclosure or distribution of the Serial Number shall constitute a breach of this EULA, the effect of which shall be the automatic termination and revocation of all the rights granted herein.

7. Evaluation Copy. If you are using an "evaluation copy" or similar version, specifically designated as such by C1 on its website or otherwise, then the Licenses are limited as follows: a) you are granted a license to use the SOFTWARE for a period of thirty (30) days counted from the day of installation (the "Evaluation Period"); b) upon completion of the Evaluation Period, you shall either i) delete the SOFTWARE from the computer containing the installation, or you may ii) contact C1 or one of its authorized dealers to purchase a license of the SOFTWARE, which is subject to the terms and limitations contained herein; and c) any Developed Software may not be distributed or used for any commercial purpose.

III. INTELLECTUAL PROPERTY.

1. Copyright. You agree that all right, title, and interest in and to the SOFTWARE (including, but not limited to, any images, photographs, animations, video, audio, music, text, and “applets” incorporated into the SOFTWARE), and any copies of the SOFTWARE, and any copyrights and other intellectual properties therein or related thereto are owned exclusively by C1, except to the limited extent that C1 may be the rightful license holder of certain third-party technologies incorporated into the SOFTWARE. The SOFTWARE is protected by copyright laws and international treaty provisions. The SOFTWARE is licensed to you, not sold to you. C1 reserves all rights not otherwise expressly and specifically granted to you in this EULA.

2. Backups. You may either: (a) copy the SOFTWARE solely for backup or archival purposes; or (b) install the SOFTWARE on a single computer, provided you keep the original solely for backup or archival purposes. Notwithstanding the foregoing, you may not copy the Documentation.

3. General Limitations. You may not reverse engineer, decompile, or disassemble the SOFTWARE, except and only to the extent that applicable law expressly permits such activity notwithstanding this limitation.

4. Software Transfers. You may not rent or lease the SOFTWARE. You may transfer the SOFTWARE to another computer, provided that it is completely removed from the computer from which it was transferred. You may permanently transfer all of your rights under the EULA, provided that you retain no copies, that you transfer all the SOFTWARE (including all component parts, the media and printed materials, any dates, upgrades, this EULA and, if applicable, the Certificate of Authenticity), and that the recipient agrees to the terms and

10 · Overview

conditions of this EULA as provided herein. If the SOFTWARE is an update or upgrade, any transfer must include all prior versions of the SOFTWARE.

5. Termination. Without prejudice to any other rights it may have, C1 may terminate this EULA and the Licenses if you fail to comply with the terms and conditions contained herein. In such an event, you must destroy all copies of the SOFTWARE and all of its component parts.

6. Export Restrictions. You acknowledge that the SOFTWARE is of U.S. origin. You acknowledge that the license and distribution of the SOFTWARE is subject to the export control laws and regulations of the United States of America, and any amendments thereof, which restrict exports and re-exports of software, technical data, and direct products of technical data, including services and Developed Software. You agree that you will not export or re-export the SOFTWARE or any Developed Software, or any information, documentation and/or printed materials related thereto, directly or indirectly, without first obtaining permission to do so as required from the United States of America Department of Commerce's Bureau of Export Administration ("BXA"), or other appropriate governmental agencies, to any countries, end-users, or for any end-uses that are restricted by U.S. export laws and regulations, and any amendments thereof, which include, but are not limited to, the following:

Restricted Countries: Restricted Countries currently include, but are not necessarily limited to Cuba, Iran, Iraq, Libya, Montenegro, North Korea, Serbia, Sudan, and Syria.

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

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

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

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

http://www.bxa.doc.gov/

END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 11

SOFTWARE, and any license agreement used in connection with the distribution of the SOFTWARE. Manufacturer is ComponentOne, LLC, 4516 Henry Street, Suite 501, Pittsburgh, Pennsylvania 15213 USA. For solicitations issued by the Government on or after December 1, 1995 and the Department of Defense on or after September 29, 1995, the only rights provided in the software and documentation provided herein shall be those contained in this EULA. Under no circumstances shall C1 be obligated to comply with any Governmental requirements regarding the submission of or the request for exemption from submission of cost or pricing data or cost accounting requirements. For any distribution of the SOFTWARE that would require compliance by C1 with the Government's requirements relating to cost or pricing data or cost accounting requirements, you must obtain an appropriate waiver or exemption from such requirements for the benefit of C1 from the appropriate Government authority before the distribution and/or license of the SOFTWARE to the Government.

IV. WARRANTIES AND REMEDIES.

1. Limited Warranty. C1 warrants that the original media, if any, are free from defects for ninety (90) days from the date of delivery of the SOFTWARE. EXCEPT AS OTHERWISE PROVIDED IN THE PRECEDING SENTENCE, AND TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, C1 EXPRESSLY DISCLAIMS ANY WARRANTY FOR THE SOFTWARE, DOCUMENTATION AND ANYTHING ELSE PROVIDED BY C1 HEREBY AND C1 PROVIDES THE SAME IN “AS IS” CONDITION WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK ARISING OUT OF USE OR PERFORMANCE OF THE SOFTWARE AND DOCUMENTATION REMAINS WITH YOU. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS WHICH VARY FROM STATE TO STATE.

2. Limited Remedy. C1's entire liability and your exclusive remedy under this EULA shall be, at C1's sole option, either (a) return of the price paid for the SOFTWARE; (b) repair the SOFTWARE through updates distributed online or otherwise in C1's discretion; or (c) replace the SOFTWARE with SOFTWARE that substantially performs as described in the SOFTWARE documentation, provided that you return the SOFTWARE in the same manner as provided in Section I.2 for return of the SOFTWARE for non-acceptance of this EULA. Any media for any repaired or replacement SOFTWARE will be warranted for the remainder of the original warranty period or thirty (30) days, whichever is longer. THESE REMEDIES ARE NOT AVAILABLE OUTSIDE OF THE UNITED STATES OF AMERICA. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL C1 BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFIT, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF C1 HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES/JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES IN CERTAIN CASES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.

V. MISCELLANEOUS.

1. This is the Entire Agreement. This EULA (including any addendum or amendment to this EULA included with the SOFTWARE) is the final, complete and exclusive statement of the entire agreement between you and C1 relating to the SOFTWARE. This EULA supersedes any prior and contemporaneous proposals, purchase orders, advertisements, and all other communications in relation to the subject matter of this EULA, whether oral or written. No terms or conditions, other than those contained in this EULA, and no other understanding or agreement which in any

12 · Overview

way modifies these terms and conditions, shall be binding upon the parties unless entered into in writing executed between the parties, or by other non-oral manner of agreement whereby the parties objectively and definitively act in a manner to be bound (such as by continuing with an installation of the SOFTWARE, "clicking-through" a questionnaire, etc.) Employees, agents and other representatives of C1 are not permitted to orally modify this EULA.

2. You Indemnify C1. . You agree to indemnify, hold harmless, and defend C1 and its suppliers and resellers from and against any and all claims or lawsuits, including attorney's fees, which arise out of or result from your breach of any of the terms and conditions of this EULA.

3. Interpretation of this EULA. If for any reason a court of competent jurisdiction finds any provision of this EULA, or any portion thereof, to be unenforceable, that provision of this EULA will be enforced to the maximum extent permissible so as to effect the intent of the parties, and the remainder of this EULA will continue in full force and effect. Formatives of defined terms shall have the same meaning of the defined term. Failure by either party to enforce any provision of this EULA will not be deemed a waiver of future enforcement of that or any other provision. Except as otherwise required or superseded by law, this EULA is governed by the laws of the Commonwealth of Pennsylvania, without regard to its conflict of laws principles. The parties consent to the personal jurisdiction and venue of the Commonwealth of Pennsylvania, in the County of Allegheny, and agree that any legal proceedings arising out of this EULA shall be conducted solely in such Commonwealth. If the SOFTWARE was acquired outside the United States, then local law may apply.

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

TDBG8.OCX ComponentOne True DBGrid Pro 8.0. This is an ICursor-based control compatible with the intrinsic data control of Visual Basic and the Microsoft Remote Data Control.

TODG8.OCX ComponentOne True DBGrid Pro 8.0 (OLE DB). This control is compatible with OLE DB and ADO (ActiveX Data Objects) data sources, such as the Microsoft ADO Data Control and the Data Environment of Visual Basic 6.0.

TODGUB8.DLL Unbound mode support DLL for use with TODG8.OCX. This file is not used by TDBG8.OCX, which contains built-in unbound mode support.

TDBGPP8.DLL Printing, print preview, and export support DLL for use with TDBG8.OCX and TODG8.OCX. Note: The TDGBPP8.DLL module uses the zlib data compression library written by Jean-loup Gailly and Mark Adler.

XADB8.OCX ComponentOne XArrayDB Object. This is the enhanced version that supports sorting and searching.

NOTE: If you use the OLE DB grid (TODG8.OCX) with the DataView property set to 1 - Hierarchical, then you must also distribute XADB8.OCX, even if you do not use the XArrayDB object explicitly in code.

End users of your applications are not licensed to use True DBGrid for development, and may not redistribute any of the above control files.

Technical Support · 13

You are not licensed to distribute any True DBGrid file to users for development purposes. You are not allowed to add or transfer the True DBGrid license key to the registry of your users' computer(s).

In particular, if you create a control using a True DBGrid component as a constituent control, you are not licensed to distribute the control you created with the True DBGrid component to users for development purposes.

It is your responsibility to make such restrictions clear to your users.

Site licenses are available for groups of multiple developers. Please contact Sales@ComponentOne.com for details.

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

ComponentOne Web site The ComponentOne Web site at www.componentone.com provides a wealth of information and software downloads for True DBGrid users:

• Descriptions of the various support options available through the ComponentOne Service Team.

• Answers to frequently asked questions (FAQ's) about True DBGrid, organized by functionality. Please consult the FAQ's before contacting us directly, as this can save you time and also introduce you to other useful information pertaining to True DBGrid.

• Free product updates, which provide you with bug fixes and new features.

Internet e-mail For technical support through the Internet, e-mail us at:

support.tdbgrid@componentone.com

To help us provide you with the best support, please include the following information when contacting ComponentOne:

• Your ComponentOne product serial number.

• The version and name of your operating system.

• Your development environment and its version.

For more information on technical support, go to:

www.componentone.com/support

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

mailto:sales@componentone.comhttp://www.componentone.com/mailto:support.tdbgrid@componentone.comhttp://www.componentone.com/supporthttp://www.componentone.com/newsgroups

Specifying a Data Source · 15

The Basics This section explains the three fundamental concepts that you need to master in order to use True DBGrid effectively:

1. Data sources

2. Column layouts

3. Bookmarks

Specifying a Data Source True DBGrid offers unprecedented flexibility in choosing a data source. You can bind directly to Visual Basic's intrinsic Data control, OLE DB data sources such as Microsoft's ADO Data Control and Remote Data Services (RDS), or a third-party data control such as ComponentOne's True DataControl. Using True DBGrid in bound mode greatly simplifies database development by enabling you to focus on your application's interface instead of data access details.

However, there are times when binding to a data control is neither practical nor desirable, and an unbound mode of operation is necessary. By their nature, data controls add layers of overhead, which may result in performance degradation for large datasets. Bound mode is not an option if you are using a proprietary database format or one that is not supported by the standard data controls. You may even need to display a simple two-dimensional array within a grid—why bother with a database?

True DBGrid provides a sensible strategy for handling all of these situations. Regardless of which data access strategy you choose, you won't be penalized for switching to another one at a later date, as True DBGrid provides a clean separation between the data source and the grid's programmatic interface. In other words, if you write data validation or record manipulation code that works in bound mode, it will continue to work if you switch to unbound mode.

True DBGrid supports the following data access modes:

Bound The grid receives data and notifications from an intrinsic or external data control according to the Microsoft data binding specifications.

Storage The grid receives data from a ComponentOne XArrayDB object, which can be redimensioned and populated in code much like a standard Visual Basic array.

Application The grid fires data retrieval and update events for individual grid cells.

Unbound The grid fires data retrieval and update events for a small set of records all at once.

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

For more information on using True DBGrid in bound mode, see Bound Mode (page 195).

16 · The Basics

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

For more information on using True DBGrid in storage mode, see Storage Mode (page 205).

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

For more information on using True DBGrid in application mode, see Application Mode (page 211).

What is unbound mode? If you are working with a database API that supports multiple-row fetches (such as ODBC), or are converting applications that use unbound DBGrid controls, then the row-based unbound mode should be used. Although unbound mode is the most difficult data access mode to implement, it tends to be more efficient than application mode, since fewer events need to be fired.

DataMode setting 2 - Unbound Extended is the preferred method. Setting 1 - Unbound is a remnant of the original DBGrid control and is included for backward compatibility.

For more information on using True DBGrid in unbound mode, see Unbound Mode (page 219).

Choosing a Column Layout In a True DBGrid display, each column represents a single field of data. For each column, the grid needs to know the field name associated with the data, and optionally a heading to be displayed above the data column.

True DBGrid gets information about field names and headings in one of three ways:

1. Automatic layouts, derived at run time from the Data control's Recordset.

2. Customized layouts, derived at design time from the Data control's Recordset and optionally tailored using the control's property pages.

3. Run-time layouts, created or modified in code by manipulating the Columns collection and its Column object members.

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

Configuring Columns at Design Time · 17

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

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

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

Switching between layout types If you define a design-time column layout, the grid will not automatically change the layout at run time, as it assumes that you want total control of the display. The grid considers you to have defined a design-time column layout if you chose the Retrieve Fields option from the grid's context menu or modified any properties in either the Columns or Splits property pages.

You can clear the design-time layout by choosing the Clear Fields option of the grid's context menu or by invoking the grid's ClearFields method in code:

TDBGrid1.ClearFields ' Clear column layout

After this statement is executed, the grid will again respond automatically to layout changes at run time.

Conversely, you can cancel the grid's automatic layout behavior by invoking the grid's HoldFields method in code:

TDBGrid1.HoldFields ' Cancel automatic layout

After this statement is executed, the grid will stop automatically changing the layout at run time, and uses the current column layout for all subsequent Recordset display. This is especially useful if you need to refresh the data control the grid is bound to while maintaining the current grid layout.

By using the ClearFields and HoldFields methods, you can alternate the grid's display between automatic layout and customized layout.

Configuring Columns at Design Time True DBGrid provides unique visual editing capabilities that streamline design-time column configuration. Instead of adding and removing columns with command buttons on a property page, you manipulate the grid directly on the form with the mouse. You can even copy columns to the Clipboard and paste them into another grid on a different form!

Once you have created and resized columns to your liking, you can use the Columns and Splits property pages to further refine their appearance and behavior.

18 · The Basics

Visual editing At design time, you can use True DBGrid's visual editing mode to perform the following tasks:

• Add and remove columns.

• Copy columns to and from the Clipboard.

• Move and resize columns.

• Adjust the grid's row height.

• Retrieve field layouts from a bound data source.

• Split the grid into separate vertical scrolling regions.

• Save the current grid layout to a file.

• Load an existing grid layout from a file.

• Access the grid's property pages.

To enter visual editing mode, click anywhere on the grid with the right mouse button to display the grid's context menu, then choose the Edit command.

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

This indicates that the column you are pointing to is ready to be resized. If you drag the dividing line to a different position, the column will change its width accordingly, and the grid will reposition any adjacent columns.

Similarly, if you point to a column header, the mouse pointer changes again.

Configuring Columns at Design Time · 19

This symbol indicates that the column is ready to be selected. If you click its header, the entire column is highlighted. You can also drag the mouse pointer within the column header area to extend the selection to other adjacent columns. To cancel the selection and return the columns to their normal, unhighlighted state, click any cell within the grid's data area.

Column selection serves two purposes in visual editing mode:

1. Selected columns can be moved to a different position within the grid by dragging within the column header (provided that AllowColMove is True for the current split).

2. Selected columns act as arguments for some visual editing menu commands.

If the grid is already in visual editing mode, right-clicking it again displays a different context menu. This is the visual editing menu, which provides commands for manipulating columns, splits, and layouts.

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

Specifying database fields At design time, the easiest way to bind database fields to grid columns is with the Retrieve Fields command. However, if the grid is not bound at design time, this command has no effect. Fortunately, you can still set column properties manually using the grid's property pages, but you must first create blank columns using the Insert or Append commands of visual editing mode.

To associate a database field with a grid column, choose Properties… from the visual editing menu (or context menu) to display the Property Pages dialog, then click the Columns tab to display the Columns property page. Expand a numbered column node in the property tree on the left, then select the DataField property.

20 · The Basics

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

When you are done specifying column properties, click the OK button.

Specifying other column properties Not all column properties can be set from the Columns property page. This is because some properties, such as Width, may differ from split to split. In True DBGrid, a split is similar to the split window features of products such as Microsoft Excel and Word, and is often used to present data in multiple vertical panes. Two common applications of splits in True DBGrid are:

1. Independent vertical scrolling panes

2. Fixed nonscrolling columns

If you are just getting started with True DBGrid, you don't need to learn about splits right away, but you should know that the Splits property page is used to specify split-specific column properties. For more information, see Columns in property trees (page 142).

Configuring Columns at Run Time True DBGrid provides complete control over column layouts at run time. Regardless of which data access mode you are using, you can always add, remove, and manipulate columns in code.

The techniques used to configure columns in code follow the conventions for collection objects in Visual Basic.

Configuring Columns at Run Time · 21

Adding and removing columns By manipulating the Columns collection, you can add or remove columns from the grid at run time. You can even perform complete grid configurations in code, rather than using the visual editing features.

Here is an example of how a column can be added to the grid using the Columns collection: ' Create a new Column 0 Dim C As TrueDBGrid80.Column Set C = TDBGrid1.Columns.Add(0) ' Initialize the new Column 0 With C .Visible = True ' Make it visible .DataField = "LAST" ' Set the column's database field .Caption = "Last Name" ' Set the column's caption End With ' Make Column 0 as wide as Column 1 C.Width = TDBGrid1.Columns(1).Width

Several key points should be noted in this example:

• The Columns collection is referenced as TDBGrid1.Columns, while an individual Column object is referenced with a numeric index, TDBGrid1.Columns(1). All indexes for a collection are zero-based, so index position 1 refers to the second column. This is the general syntax for referencing a collection and its individual elements.

• You can add a new Column object to the Columns collection using the collection's Add method, which accepts a numeric index and returns the newly created object. This is the general technique used to add an item to a collection.

• The Visual Basic Set statement is needed to store the new column object in the variable C. Without it, the run-time error "Object variable or With block variable not set" will occur.

• The newly added column is Column 0 of the grid. The previous Column 0 becomes Column 1, the previous Column 1 becomes Column 2, and so on.

You can insert a new column at any position. For example: Set C = TDBGrid1.Columns.Add(3)

After this statement executes, the new column will be Column 3. The previous Column 3 becomes Column 4, the previous Column 4 becomes Column 5, and so on.

After a new column is added, the Count property of the Columns collection will be automatically incremented by one. You cannot create a column with an index larger than the current value of the Count property. The Count property is read-only, so you cannot append columns by setting it to a larger value.

To delete a member of the Columns collection and remove it from the grid's display, use the Remove method. This is the general technique to remove an item from a collection:

TDBGrid1.Columns.Remove 1

Or, to remove all columns from a grid: While TDBGrid1.Columns.Count 0 TDBGrid1.Columns.Remove 0 Wend

At run time, a newly created column is made invisible to avoid unnecessary flicker when multiple columns are created. Therefore, you must explicitly set its Visible property to True. Also, you must set

22 · The Basics

the column's DataField and Caption properties, otherwise the grid will display a blank column with no heading.

Note that when you set the DataField property of a column in code, you must ReBind the grid to the data source in order for the new column binding to take effect.

Referencing column objects When a column is added to or removed from a grid, the associated Column object is added to or removed from the grid's Columns collection. This may cause a change in the index numbers of the existing columns, making it very inconvenient to reference columns numerically. For this reason, True DBGrid also allows you to reference columns using either the DataField or Caption strings. Thus, the following references are identical:

TDBGrid1.Columns(n) ' Reference by the Column index TDBGrid1.Columns("LAST") ' Reference by the DataField name TDBGrid1.Columns("Last Name") ' Reference by the Caption string

Referencing column objects by DataField or Caption is not case-sensitive. TDBGrid1.Columns("LAST") refers to the same column as TDBGrid1.Columns("last").

When you reference a Column object and its properties at run time, Visual Basic creates an instance of the object. For example, if you duplicate certain properties of a column:

TDBGrid1.Columns("First").Width = _ TDBGrid1.Columns("Last").Width TDBGrid1.Columns("First").Alignment = _ TDBGrid1.Columns("Last").Alignment TDBGrid1.Columns("First").AllowSizing = _ TDBGrid1.Columns("Last").AllowSizing

The Columns("First") and Columns("Last") objects will each be created and discarded three times in the preceding example. The same results are achieved more efficiently by creating object variables that refer to these columns:

' Declare Column objects Dim FirstCol As TrueDBGrid80.Column Dim LastCol As TrueDBGrid80.Column ' Reference First and Last Column objects Set FirstCol = TDBGrid1.Columns("First") Set LastCol = TDBGrid1.Columns("Last") ' Copy properties from Last to First FirstCol.Width = LastCol.Width FirstCol.Alignment = LastCol.Alignment FirstCol.AllowSizing = LastCol.AllowSizing

The same technique can be applied to other objects in Visual Basic. For more details, see Object Model (page 117).

Adjusting column properties in code Properties of the Column object can be changed at run time using Visual Basic code. For example, changing the DataField property can be done as follows:

With TDBGrid1.Columns(0) .DataField = "New DataField" TDBGrid1.ReBind .Caption = "New Caption" End With

Understanding Bookmarks · 23

Note that after changing the DataField property, you must ReBind the grid columns so that the new data will appear in the column. You should also change the caption to describe the new field.

Other Column object properties can be changed in a similar fashion. Please refer to Column Object Properties (page 355) for a complete listing.

Understanding Bookmarks Both True DBGrid and Microsoft ActiveX Data Objects (ADO) use bookmarks to identify records and navigate through the database. A bookmark is a variant that uniquely identifies a particular row in a database. As such, it is a generalization of the concept of row numbers.

Programmers who are accustomed to using row numbers to reference a record (as with dBASE databases) may need to adjust conceptually. In a relational database, the ordinal position of a record (that is, its row number) is irrelevant, since the total number of rows in the database or in a query result set is generally not available. After performing certain operations such as Find, the current record moves an unspecified number of rows forward and there is no efficient way to determine how many. To avoid time-consuming counting operations, most relational database systems have abandoned the practice of using row numbers and have adopted the bookmark approach.

Bookmarks are actually quite simple to use. The following are the basic rules to remember when using bookmarks in True DBGrid and in Visual Basic:

• Each record, or row, has a unique bookmark.

• You can move to a specific record by setting the Bookmark property of either the grid or the Data control: TDBGrid1.Bookmark = SomeBookmark Data1.Recordset.Bookmark = SomeBookmark

SomeBookmark is usually a bookmark you have obtained from the Data control, a clone, or a collection of bookmarks, such as True DBGrid's SelBookmarks collection. The Bookmark property of the grid and the Data control will always contain the bookmark of the current record.

• You navigate through the database by moving to the first or last record, or by moving relative (next or previous) to the current bookmark: Data1.Recordset.Move