ComponentOne True DBList Pro 8.0

Product Profile

True DBList Reference

TDBCombo Reference

Tutorials


Overview

Welcome to ComponentOne True DBList 8.0, a customizable set of data-aware ActiveX list and combo controls for Visual Studio. ComponentOne True DBList Pro 8.0 adds dozens of data presentation and user interface features for unbeatable power and flexibility. If you like True DBList 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 DBList 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 DBList 8.0 for .NET will display a ComponentOne banner every time they are loaded to remind developers to license the product.

We hope you'll like True DBList 8.0. If you have suggestions or ideas for new features or new tools, 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

ComponentOne True DBList 8.0 includes two data-aware ActiveX controls for Microsoft Visual Studio: TDBList, a data-aware multicolumn list box, and TDBCombo, a data-aware multicolumn combo box. Patterned after the DBList and DBCombo controls of Visual Basic, both TDBList and TDBCombo are automatically populated from one or more fields in an attached Data control, and can optionally update a field in a related table of another Data control. With the exception of the text box portion of the TDBCombo control, both controls are identical.

Unlike the DBList and DBCombo controls of Visual Basic, True DBList 8.0 is based on the same underlying technology as ComponentOne's award-winning True DBGrid Pro 8.0, making it a robust, versatile, and easy-to-use data presentation tool. Novice programmers can use True DBList 8.0 to easily implement multicolumn lookup tables with incremental search. Professional developers can take full advantage of the many properties and events of True DBList 8.0 to create sophisticated and user-friendly database front-end applications.

Using the latest data binding technologies built into Visual Basic, True DBList 8.0 completely manages the database interface, allowing developers to concentrate on important application-specific tasks. True DBList 8.0 can also be used in unbound mode with a programmer's own data source without binding to the Visual Basic Data control.

In addition to providing the most flexible data-aware list and combo controls on the market, True DBList 8.0 includes dozens of advanced data access, data presentation, and user interface features that enable developers to build intuitive, professional-looking applications:

Incremental search

End-users can quickly locate list items by typing. Supports both single-character matching and an incremental search mode that concatenates typed characters to further refine the search.

Automatic field completion

Works in concert with incremental search to fill the text portion of a combo with matching field data as characters are typed.

Excel and Word-like styles

Style objects encapsulate font, color, and formatting information, facilitating easy customization of list components at design time and run time.

Excel-like splits

Developers and end-users can divide the list 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 list (at the left or right edges, or in the middle).

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

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.

Interactive visual editing

Programmers can create columns, retrieve field layouts from a bound data source, resize list components, and configure all aspects of the list 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 list supports unbound columns while other columns are bound to a data control.

Array-based storage mode

The XArrayDB object included with True DBList Pro 8.0 works just like a Visual Basic array, but also acts as a data source for the list. No unbound events to code!

Alternating row colors

Enhances the readability of the list's display.

Reusable list layouts

List layouts can be saved to a file, then reused in other projects. Multiple layouts can be stored in a single list or combo control 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.

Run-time CellTips

Provides context-sensitive help for end-users.

Excellent documentation

True DBList Pro 8.0 includes an extensive manual and on-line 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 DBList, use the SETUP.EXE 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.

The following files will be installed into your Windows\Help directory:

tdbl8.chm

Contains the True DBList 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 DBList in your Visual Basic projects, you must include these files in the project:

tdbl8.ocx | Contains the TDBList and TDBCombo control.
todl8.ocx | Contains the OLEDB versions of the control.
xadb8.ocx | Contains the XArrayDB control.

The following folders will be created by the setup utility:

ComponentOne Studio

Directory used to store ComponentOne control information.

ComponentOne\True DBList Pro 8.0

Contains sample projects and a README.TXT file with information about True DBList.


Adding the True DBList Components to the Toolbox

TDBList and TDBCombo are the components used to create customizable lists and combo boxes to enhance data presentation and user interface.

True DBList includes two separate list 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 list depending upon the type of data source used, as the following table illustrates.

To use the True DBList 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 TDBList 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, “List8”, 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 the ComponentOne True DBList Pro 8.0 Control. Click OK.

NOTE: The class names are the same regardless of which control is used. However, the type library name used to qualify object references is TrueDBList70 for the legacy control, and TrueOleDBList70 for the OLE DB control.


Upgrading

If you have projects which use versions of True DBList other than True DBList 8.0, you can easily convert them to use True DBList 8.0 by running the add-in migration utility, which handles the following conversions:

The True DBList 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 DBList Pro 8.0 Migration Utility, then check the Loaded/Unloaded box.

•

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

•

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

After you have added the True DBList 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 True DBList Pro 5.0 to True DBList Pro 8.0 OLE DB, or from an evaluation copy to the full version), 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

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. C1 ReportDesigner. C1ReportDesigner 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. VS View Reporting Edition. VS View Reporting Edition includes at least one executable file listed as “VSRpt7.exe”, known as “Designer.” The file "VSRpt7.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. 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.

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 its reasonable, 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, that arise or result from 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 DBList Pro 8.0 is developed and published by ComponentOne LLC. You may use it for development with Microsoft Visual Studio or any other programming environment. You may also distribute the following control files, royalty free, with any application you develop:

TDBL8.OCX

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

TODL8.OCX

ComponentOne True DBList 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 TODL7.OCX. This file is not used by TDBL7.OCX, which contains built-in unbound mode support. This file is shared with True DBGrid 8.0.

TDBGPP.DLL

Printing, print preview, and export support DLL for use with TDBL7.OCX and TODL7.OCX. This file is shared with True DBGrid 8.0.

XARRAYDB.OCX

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

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

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

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

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


Technical Support

ComponentOne Product 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 DBList 8.0 users, including:

•

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

•

Answers to frequently asked questions (FAQ's) about our products, 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 our products.

•

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.tdblist@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 peer-to-peer newsgroups for 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 our products. However, ComponentOne may monitor the newsgroups 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.


Getting Started


Syntax Changes

If you are using True DBList Pro 6.0, you should be aware of the following changes in syntax that may require modifications to your existing code.

In version 8.0, the allowable values for these properties are as follows:

Appearance

0 – Flat

1 – 3D (default)

2 – Mixed Flat

DataMode

0 – Bound (default)

1 – Unbound

2 – Unbound Extended

3 – Application

4 – Storage

5 – AddItem

MultiSelect

0 – None (default)

1 – Simple

2 – Extended

3 – Checkbox


Terminology

The True DBList and True DBCombo controls are usually referred to by their object names: TDBList and TDBCombo.

For the sake of brevity, the documentation often substitutes the term "list" for:

•

a True DBList or True DBCombo control, or

•

the list portion of a True DBList or True DBCombo control, or

•

a TDBList or TDBCombo object.

The documentation also substitutes the term "combo" for:

•

a True DBCombo control, or

•

the list portion of a True DBCombo control, or

•

a TDBCombo object.


Using the True DBList and True DBCombo Controls

Generally, you will use the True DBList and True DBCombo controls with two Data controls: one to fill the list as designated by the RowSource property, and one to update a field in a database as designated by the DataSource and DataField properties. True DBList and True DBCombo will never modify the data obtained from the RowSource property.

The BoundColumn property specifies which RowSource field supplies the data value to be used for the update. You can use the following pseudo-code to help you remember how to configure a list or combo control at design time:

DataSource.DataField = RowSource.BoundColumn

The left side of the assignment statement specifies the field to be updated; the right side specifies the set of allowable values.

At run time, when the user selects an item from the list, the BoundText property contains a string representation of the data value to be used for the update. You can also set the BoundText property in code to position the list to a specific item.

The optional ListField property specifies which RowSource field should be used for incremental search. If not specified, the first column in the list is used. For TDBList controls, the MatchEntry property determines how the list is searched as the user types characters at run time.

A Simple Example

Populating the List

Updating Another Data Source

Selecting List Items

Searching the List

Controlling the Display

Differences Between True DBList and True DBCombo


A Simple Example

Consider the following form, which displays records from the Titles table of the familiar Biblio database supplied with Visual Basic.

Note that the PubID field of the Titles table corresponds to the PubID field of the Publishers table, which contains name and contact information. Therefore, you can enhance the interface of this form by using a TDBCombo control to provide a multicolumn drop-down list of publisher names.

At design time, delete the PubID text box and replace it with a TDBCombo control. To view items in the combobox, set the MaxComboItems property of the TDBCombo1 to 6. Note that the height of the text portion of the combo does not change. Add a new Data control (Data2) to the form and set its Visible property to False, since this control exists only to populate the combo box. When you are finished, the form should look something like this.

Connect Data2 to the Publishers table by setting its DatabaseName (Data control) property to Biblio.mdb and its RecordSource (Data control)property to the following SQL query:

Select PubID, Name From Publishers

Set the RowSource property of TDBCombo1 to Data2. At run time, this will populate the combo with the PubID and Name fields from the Publishers table. Set the BoundColumn property of TDBCombo1 to PubID. Note that because you have already specified a RowSource, the drop-down list in the Visual Basic properties window shows all available fields (PubID and Name).

Next, set the DataSource property of TDBCombo1 to Data1 and the DataField property of TDBCombo1 to PubID. This specifies that the PubID field of the Titles table will be updated when the user selects an item from the combo box.

Finally, to provide more room for the list portion of the combo, set the DropdownWidth property of TDBCombo1 equal to the Width property of the Title text box.

Run the program and open the combo by clicking its drop-down button. The form will look something like this:

Note that the appropriate record in the Publishers table is automatically highlighted in the combo's drop-down list. As you type characters, the highlighted item changes accordingly. For example, typing the numbers 1, 2, and 3 in succession positions the selected item to PubID 1, 12, and 123.


Populating the List

The following properties are used to populate a TDBList control and the list portion of a TDBCombo control:

DataMode

Specifies bound or unbound mode

RowSource

Specifies source of control data

Note that the DataMode setting specifies the data access mode for RowSource, not DataSource. This differs from other bound controls such as DBGrid, which use the DataSource property to populate the control.

In True DBList, the DataSource property specifies the data source that will be updated when the user selects an item in a TDBList or TDBCombo control. The next section describes how to set up a list or combo control to update another data source automatically.

If you specify a valid RowSource, the list will be filled with data from the associated Recordset (Data control). The list will not track current record movement within this Recordset (Data control), nor will it notify the Recordset (Data control) when the user selects a different item in the list.

Unlike the DBList and DBCombo controls of Visual Basic, which can only display a single column of data (as specified by the ListField property), the TDBList and TDBCombo controls support multiple columns, which can be derived automatically from the underlying RowSource. For more information, see Choosing a Column Layout.

If you do not specify a valid RowSource, the list will not display any data, even if you specify a valid DataSource.

If the DataMode property is not set to its default value of 0 - Bound, then the RowSource property is not used and the control obtains data from unbound events or an XArrayDB object, depending upon the DataMode value. For more information on these other data modes, see Specifying a Data Source.


Updating Another Data Source

The following properties determine how a TDBList or TDBCombo control updates another data source:

BoundColumn

Name of the RowSource field used to update DataField

BoundText

Text value of the BoundColumn field

DataField

Name of the DataSource field to be updated by user selection

DataSource

Source of data to be updated once a selection is made

In True DBList, the DataSource property is not used to populate the control, but specifies the data source that will be updated when the user selects an item in a TDBList or TDBCombo control. If specified, the DataSource property must be set to a bound data source such as a Visual Basic Data control.

For obvious reasons, the DataSource and RowSource properties should be bound to different Data controls.

As with a simple bound control such as a Visual Basic text box, the DataSource and DataField properties uniquely define the field to be updated when the user selects an item from a TDBList or TDBCombo control. Similarly, the RowSource and BoundColumn properties determine the new value used during the update.

When the user selects an item from the list, the BoundText property receives the data value to be used for the update, and the Data control specified by the DataSource property receives notification that an update has been requested. The new value is not actually written to the database until the current record is repositioned or the Data control's UpdateRecord method is executed.


Selecting List Items

The following properties are used to set or get the current list item for a TDBList or TDBCombo control:

BoundText

Text value of the BoundColumn field

SelectedItem

Sets/returns the bookmark of the currently selected item

The BoundText property always reflects the value of the BoundColumn field within the list portion of the control. As the current record within the Recordset (Data control) associated with the DataSource property changes, the BoundText property receives the value specified by DataField. The list or combo control then searches the records in its list to see if the BoundText value matches any BoundColumn field. If a match is found, the record is highlighted in the list or placed in the text box portion of the combo control. If no match is found, the list selection is cancelled and BoundText returns an empty string.

You can use the SelectedItem property to retrieve the bookmark of the current list item. Setting this property to a valid RowSource bookmark highlights the corresponding list item or places the appropriate value in the text box portion of a combo control.

TDBList controls also support a multiple selection mode:

MultiSelect

Controls whether users can select multiple rows

SelBookmarks

Contains a collection of selected row bookmarks

If the MultiSelect property is 0 - None, only one item in the list can be selected at any time. This is the default behavior.

If the MultiSelect property is 1 - Simple and the user clicks a row, that row is selected and the SelectedItem property returns a bookmark for that row. If more than one row is selected, the SelectedItem property returns the bookmark of the most recently selected row, and the SelBookmarks collection contains the bookmarks for all selected rows.

If the MultiSelect property is 2 - Extended, pressing Shift and clicking the mouse or pressing Shift and one of the arrow keys (Up Arrow, Down Arrow, Left Arrow, or Right Arrow) extends the selection from the previously selected item to the current item. Pressing Ctrl and clicking the mouse selects or deselects an item in the list. 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.

If the MultiSelect property is 3 - Checkbox, the user can select or unselect rows by clicking checkboxes.

When one of the multiple selection modes is in effect, no updates will occur.


Searching the List

The following properties determine the search behavior of TDBList and TDBCombo controls:

ListField

Sets/returns the RowSource field used for incremental search

MatchEntry

Sets/returns the type of incremental search (TDBList only)

MatchCol

Sets the search column when the MatchEntry property is not 0

MatchCompare

Sets/returns the comparing mode for search

Additionally, the Find method allows you to locate the bookmark for a given row. For more information on the Find method, see Searching Bookmarks Using the Find Method.

The optional ListField property specifies which RowSource field should be used for incremental search. If not specified, the first column in the list is used. For instance, consider the example presented earlier. If you set the ListField property of TDBCombo1 to Name, the text portion of the combo displays the Name field instead of PubID. Typing the letter "m" selects M & T; typing the letter "a" selects MACMILLAN COMPUTER.

TDBCombo controls always search incrementally as in this example. TDBList controls support a MatchEntry property, which determines how the list is searched as the user types characters at run time.

If you set MatchEntry to 2 - Extended, the behavior is almost identical to that of a TDBCombo control except that the search argument is cleared when a TDBList control gains focus, or when the user presses Backspace or hesitates for a few seconds. If you set MatchEntry to 1 - Standard, the search argument is limited to one character. You can also disable searching altogether by setting MatchEntry to 0 - None.

By setting the MatchCol, you can allow the end user to perform searches in various columns (depending on which MatchCol option is chosen). Note: MatchCol is functional only when MatchEntry is NOT set to 0 (None). You can set MatchCol to the following options:

ListField (default)

The search column is the current ListField. If the ListField is not set, the search column will be the first column.

Current Mouse Position

The search column is the column where the mouse cursor is active.

Current Selected Col

The search column is the current selected column. If there is more than one selected column, the search column is the left most selected column.

Left Visible Col

The search column is the left most visible column.

Right Visible Col

The search column is the right most visible column.

All Cols

The search columns are all the visible columns.

By setting the MatchCompare, you can allow the end user access to various search modes, not just the standard incremental search. Note: MatchCompare is functional only when MatchEntry is NOT set to 0 (None). You can set MatchCompare to the following options:

Partially Equal (Default)

This is the same as an incremental search.

Less Than

Matches strings less than the search value.

Less Than or Equal

Matches strings less than or equal to the search value.

Equal

Matches strings equal to the search value.

Greater Than or Equal

Matches strings greater than or equal to the search value.

Greater Than

Matches strings greater than the search value.

Include Equal (OLEDB)

Matches the search value within the string. For example, if the search value is “put”, Include Equal will match “computer” because “put” is contained within the string.


Controlling the Display

These properties can be used to customize the appearance of TDBList and TDBCombo controls:

DropdownPosition

Sets/returns the position of the drop-down portion of the combo

DropdownWidth

Sets/returns the width of a combo's drop-down portion

IntegralHeight

Sets/returns a value that indicates the display of partial rows

By default, the text and list portions of a TDBCombo control have the same width. You can use the DropdownWidth property to make the drop-down portion wider than the text box. Use it with the DropdownPosition property to control the behavior of the drop-down portion.

If the number of items exceeds the number that can be displayed, a scroll bar is automatically added to the control. Use the IntegralHeight property to specify whether partial rows are displayed. You can find out the number of visible items in the list by examining the VisibleRows property.


Differences Between True DBList and True DBCombo

The following properties are supported by TDBList but not TDBCombo:

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

MatchCol

Sets the search column when the MatchEntry property is not 0

MatchCompare

Sets/returns the comparing mode for search

MatchEntry

Sets/returns the type of incremental search

MultiSelect

Controls whether users can select multiple rows

LayoutURL

Sets/returns the URL used for downloading control layouts

PrintInfo

Returns the default printer information object

PrintInfos

Contains a collection of printer information objects

SelBookmarks

Contains a collection of selected row bookmarks

SelectedStyle

Controls the selected row and column style for an object

SpringMode

Sets/returns how the control columns are resized

The following properties are supported by TDBCombo but not TDBList:

AutoCompletion

True if the combo's text box auto fills with the matched entry

AutoDropdown

True if typing a character automatically opens the combo's list

AutoSize

When True, the height of the edit box is set to the font height

ComboStyle

Sets/returns the display type of a combo box

DropdownPosition

Sets/returns the position of the drop-down portion of the control

DropdownWidth

Sets/returns the width of a combo's drop-down portion

EditBackColor

Sets/returns the background color of a combo's text portion

EditFont

Specifies the font used for a combo's text portion

EditForeColor

Sets/returns the foreground color of a combo's text portion

EditHeight

Sets/returns the height for the edit portion of the combo box

GapHeight

Sets/returns the distance between the edit portion and the dropdown portion of the combo box

LimitToList

True if the NotInList event is fired when an item is not found

MaxComboItems

Sets the number of items to display in the dropdown portion of the combo box

OLEDragMode

Sets/returns OLE Drag Source action

OLEDropMode

Sets/returns OLE Drop Target action

RowTracking

True if rows are highlighted as the mouse moves over them

SelLength

Sets/returns length of selected text

SelStart

Sets/returns start of selected text

SelText

Sets/returns the selected text


The Basics

This chapter explains the three fundamental concepts that you need to master in order to use True DBList 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 DBList 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 DBWizard. Using True DBList 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 list—why bother with a database?

True DBList 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 DBList provides a clean separation between the data source and the list'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 DBList supports the following data access modes:

Bound

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

Storage

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

Application

The list fires data retrieval and update events for individual list cells.

Unbound

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

AddItem

The list control is populated with data manually.

What is Bound Mode?

What is Storage Mode?

What is Application Mode?

What is Unbound Mode?

What is Additem Mode?


What is Bound Mode?

When the DataMode property of a TDBList or TDBCombo control is set to the default value of 0 - Bound, the control 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 RowSource property of a TDBList or TDBCombo 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.

Note that the DataSource property is used to specify the data source that will be updated when the user selects an item from the list. It is not used to populate the control itself.

For more information on using True DBList in bound mode, see Bound Mode.


What is Storage Mode?

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

For more information on using True DBList 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 TDBList or TDBCombo 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 list requests a value to be displayed in a particular cell; the latter is fired whenever the list needs to determine the bookmark used to identify a particular row.

For more information on using True DBList 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 DBList 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 DBList in unbound mode, see Unbound Mode.


What is Additem Mode?

When in AddItem mode, True DBList allows you to populate the list control (TDBList or TDBCombo) manually by using the AddItem, RemoveItem and Clear methods. In this mode, your application determines what data is contained within the list control.

For more information on using True DBList in AddItem mode, see AddItem Mode.


Choosing a Column Layout

In a TDBList or TDBCombo display, each column represents a single field of data. For each column, the list needs to know the field name associated with the data, and optionally a heading to be displayed above the data column.

True DBList 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 (Data control).

2.

Customized layouts, derived at design time from the Data control's Recordset (Data control), 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 DBList will automatically create one based upon the database used when you run your program. All fields from the Data control's Recordset (Data control) 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 (Data control), Recordset (Data control), or Recordset (Data control) properties of the Data control, resulting in a different Recordset (Data control). When the new Recordset (Data control) is created the list 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 list's automatic layout behavior by invoking the list's HoldFields method in code.


Customized Layouts

At design time, you can cause True DBList to configure to the Data control's Recordset by selecting Retrieve Fields from the list's context menu. The list will create a column for each field in the Recordset (Data control), 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 list's context menu, or by invoking the list's ClearFields method in code.


Run-time Layouts

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


Switching Between Layout Types

If you define a design-time column layout, the list will not automatically change the layout at run time, as it assumes that you want total control of the display. The list considers you to have defined a design-time column layout if you chose the Retrieve Fields option from the list'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 list's context menu, or by invoking the list's ClearFields method in code:

TDBList1.ClearFields ' Clear column layout

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

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

TDBList1.HoldFields ' Cancel automatic layout

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

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


Configuring Columns at Design Time

True DBList 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 list directly on the form with the mouse. You can even copy columns to the Clipboard and paste them into another list 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 DBList'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 list's row height.

•

Retrieve field layouts from a bound data source.

•

Split the list into separate vertical scrolling regions.

•

Save the current list layout to a file.

•

Load an existing list layout from a file.

•

Access the list's property pages.

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

The list 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 list 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 list's data area.

Column selection serves two purposes in visual editing mode:

1.

Selected columns can be moved to a different position within the list 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 list 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 list columns is with the Retrieve Fields command. However, if the list is not bound at design time, this command has no effect. Fortunately, you can still set column properties manually using the list'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 list 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 list 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 DBList, 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 DBList are:

1.

Independent vertical scrolling panes

2.

Fixed nonscrolling columns

If you are just getting started with True DBList, 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 DBList 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 list at run time. You can even perform complete list configurations in code, rather than using the visual editing features.

Here is an example of how a column can be added to the list using the Columns collection:

' Create a new Column 0

Dim C As TrueDBList80.Column

Set C = TDBList1.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 = TDBList1.Columns(1).Width

Several key points should be noted in this example:

•

The Columns collection is referenced as TDBList1.Columns, while an individual Column object is referenced with a numeric index, TDBList1.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 list. 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 = TDBList1.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 list's display, use the Remove method. This is the general technique to remove an item from a collection:

TDBList1.Columns.Remove 1

Or, to remove all columns from a list:

While TDBList1.Columns.Count <> 0

TDBList1.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 list 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 list 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 list, the associated Column object is added to or removed from the list'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 DBList also allows you to reference columns using either the DataField or Caption strings. Thus, the following references are identical:

TDBList1.Columns(n) ' Reference by the Column index

TDBList1.Columns("LAST") ' Reference by the DataField name

TDBList1.Columns("Last Name") ' Reference by the Caption string

Referencing column objects by DataField or Caption is not case-sensitive. TDBList1.Columns("LAST") refers to the same column as TDBList1.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:

TDBList1.Columns("First").Width = _

TDBList1.Columns("Last").Width

TDBList1.Columns("First").Alignment = _

TDBList1.Columns("Last").Alignment

TDBList1.Columns("First").AllowSizing = _

TDBList1.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 TrueDBList80.Column

Dim LastCol As TrueDBList80.Column

' Reference First and Last Column objects

Set FirstCol = TDBList1.Columns("First")

Set LastCol = TDBList1.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 TDBList1.Columns(0)

.DataField = "New DataField"

TDBList1.ReBind

.Caption = "New Caption"

End With

Note that after changing the DataField property, you must ReBind the list 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 DBList and the Microsoft Data Access Objects (DAO) library 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 FindFirst (Recordset) or FindFirst (Recordset), 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 DBList 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 list or the Data control:

TDBList1.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 DBList's SelBookmarks collection. The Bookmark property of the list 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.


Tutorials

Twenty-three 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 DBList is needed. By following the steps outlined in the tutorials, you will be able to create projects demonstrating a variety of True DBList features, and get a good sense of what the True DBList and True DBCombo controls can do and how to do it. Source code for the tutorial projects is provided during installation.

The tutorials use an Access database, TDBLDemo.mdb. The database files TDBLDemo.mdb, TDBLDemo.sav, and the tutorial projects are in the TUTORIAL subdirectory of the True DBList installation directory. TDBLDemo.sav is a backup copy of TDBLDemo.mdb. If you want to restore TDBLDemo.mdb after editing, adding, or deleting records while using the tutorials, make a new copy of TDBLDemo.mdb from TDBLDemo.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 DBList. You will find that True DBList is very easy to use, and it enables you to create powerful database applications.

The tutorials assume that the database file TDBLDemo.mdb is in the C:PROGRAM FILES\TDBL8\TUTORIALS\ directory, and refer to it by filename instead of the full pathname for the sake of brevity.

NOTE: Because the user has the option of changing True DBList program location, i.e. the source path may be changed at install time, our tutorial projects are written to automatically use a relative path for database access, while our online tutorials are written utilizing design-time construction. This method is advantageous for two reasons. First, it allows the developer to change the installation location of True DBList without losing the functionality of the tutorial projects. Second, it gives the developer examples of two methods for completing the same task (run-time and design-time).

Tutorial 1 - Binding True DBList to a Data Control

Tutorial 2 - Incremental Search and Auto Completion with True DBCombo

Tutorial 3 - Lookup Combo Update with Two Data Controls

Tutorial 4 - Displaying Master-Detail Relationships

Tutorial 5 - Using True DBList with SQL Query Results

Tutorial 6 - Selecting Multiple Rows Using Bookmarks

Tutorial 7 - Defining Unbound Columns in a Bound List

Tutorial 8 - Displaying Translated Data

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

Tutorial 10 - Using Styles to Highlight Related Data

Tutorial 11 - Displaying Rows in Alternating Colors

Tutorial 12 - Creating a List with Fixed, Nonscrolling Columns

Tutorial 13 - Displaying Array Data in Unbound Mode

Tutorial 14 - Displaying Array Data in Unbound Extended Mode

Tutorial 15 - Displaying Array Data in Unbound Application Mode

Tutorial 16 - Displaying Array Data in Unbound Storage Mode

Tutorial 17 - Sorting and Searching

Tutorial 18 - Displaying Arbitrary Bitmaps

Tutorial 19 - Reusable Layouts

Tutorial 20 - Printing, Print Preview, and Export

Tutorial 21 - Cell Bordering and Scroll Tips/Tracking

Tutorial 22 - Performing a List Search Using the Find Method

Tutorial 23 - Outlook-Style Grouping (OLEDB Only)


Tutorial 1 - Binding True DBList to a Data Control

In this tutorial, you will learn how to bind a True DBList control to a Visual Basic Data control and create a fully functional database browser. You will also learn about the basic properties associated with the Data control and True DBList. You will then be able to run the program and observe the run-time features of the list.

1.

Start a new project.

2.

From the Visual Basic Project menu, select Components, then check the box labeled ComponentOne True DBList 8.0. Click OK to add the TDBList (and TDBCombo) control icons to the toolbox. The TDBList icon looks like this:

3.

Place a Data control (Data1) and a True DBList control (TDBList1) on the form (Form1) as shown in the following figure.

4.

Set the DatabaseName (Data control) property of Data1 to TDBLDemo.mdb, and the RecordSource (Data control) property to Composer.

5.

Set the RowSource property of TDBList1 to Data1.

Run the program and observe the following:

•

The True DBList control 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.

•

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 and configuring the list at run time.

To end the program, press the End button on the Visual Basic toolbar.

OLE DB support:

True DBList 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 DBList 8.0 (OLEDB) and Microsoft ADO Data Control 6.0 (OLEDB). Click OK to add the selected control icons to the toolbox. The TDBList icon looks like this:

3.

Place an ADO Data control (Adodc1) and a True DBList control (TDBList1) 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\TDBL7\TUTORIALS\TDBLDEMO.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 (Data control) property to 2 - adCmdTable.

6.

Set the RecordSource (Data control) property to Composer.

7.

Set the RowSource property of TDBList1 to Adodc1.

8.

Congratulations, you have successfully completed Tutorial 1!


Tutorial 2 - Incremental Search and Auto Completion with True DBCombo

This tutorial demonstrates the incremental search facility of the True DBCombo control. When the control receives focus, any keys the user types are concatenated into a search argument, and the list portion of the control instantly highlights the next matching entry, if found. You can also enable the AutoCompletion property to cause the remainder of the matching entry to be appended to the combo's text box.

1.

Start a new project.

2.

Place a Data control (Data1) and a True DBCombo control (TDBCombo1) on the form (Form1) as shown in the following figure.

3.

Set the DatabaseName (Data control) property of Data1 to TDBLDemo.mdb, and the RecordSource (Data control) property to Composer.

4.

Set the RowSource property of TDBCombo1 to Data1, the ListField property to Last and the MaxComboItems property to 8.

Run the program and observe the following:

•

The True DBCombo control 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 displayed in the text box portion is the one specified by the ListField property.

•

Click the combo's drop-down button or press Alt + Down Arrow to open the list portion of TDBCombo1. The last name of the first composer in the table remains selected in the text box portion. Type the letter b. Note that the b replaces the selected text, and the current row in the list portion moves to the first last name that begins with b: in this case Bach. Type e and the list will reposition to Beethoven, type r and the list will jump to Berg. At this point, if you press the Enter key or click the highlighted row, the list portion of the combo will close and a complete last name (Berg) will appear in the text box. This value is also used to fill the BoundText property, as described in the next tutorial.

5.

Press the End button on the Visual Basic toolbar to end the program. In design mode, select TDBCombo1 and in the Visual Basic Properties window change the AutoCompletion property to True.

Run the program again and observe the following:

•

Open the list portion of TDBCombo1 as described earlier. Note that with each letter you type, TDBCombo1 now fills in the text box with the rest of the matching last name, if any. Also, the part that was filled in is selected. For example, if you type be, the letters ethoven will be added and selected. Experiment by pressing the Del and Backspace keys.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 2.


Tutorial 3 - Lookup Combo Update with Two Data Controls

This tutorial illustrates the most common use of the True DBCombo control: to provide a list of choices from one database that can be used to update a field in another database. When the user selects an item from the combo's list portion, it becomes available to the updatable data source, and also appears in the text box portion of the combo where it can be edited. Likewise, when the user enters a value in the text box, the list portion of the control attempts to position to a matching item. If a match is found, the BoundText property is set based on the field specified by the BoundColumn property.

1.

Start a new project.

2.

Place two Data controls (Data1, Data2), a True DBCombo control (TDBCombo1), and a Microsoft Data Bound Grid Control 5.0 (DBGrid1) on the form (Form1) as shown in this figure.

3.

Set the DatabaseName (Data control) property of Data1 and Data2 to TDBLDemo.mdb, the RecordSource (Data control) property of Data1 to CustType, and the RecordSource (Data control) property of Data2 to the following SQL statement:

SELECT FirstName, LastName, CustType FROM Customers

4.

Set the following properties of TDBCombo1: RowSource = Data1, ListField = TypeDesc, DataSource = Data2, DataField = CustType, MaxComboItems = 5 and BoundColumn = TypeId.

5.

Set the DataSource property of DBGrid1 to Data2.

Run the program and observe the following:

•

TDBCombo1 retrieves the database schema information from the Data control specified by the RowSource property. The contents of the text box portion of TDBCombo1 (Normal) match the CustType field of the current row from Data2 (2). Note that the field names are used as the default column headings.

•

Change the current record in DBGrid1 and notice that the combo's text box portion shows the appropriate CustType. For example, if the second row (Gordon) is current, the combo displays Distributor, which corresponds to 4 in the grid's CustType column. If the third row is current, the combo displays Prospective.

•

Click the combo's drop-down button to show its list portion. Note that when you click on a row in the list, the value specified by the ListField column will be entered into the text box portion of the combo. Also, the combo will update the current record of the data control specified by the DataSource property with the TypeId corresponding to the TypeDesc column. The update does not take place immediately, but occurs when you move the current row in DBGrid1 or Data1.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 3.


Tutorial 4 - Displaying Master-Detail Relationships

This tutorial demonstrates how you can link multiple True DBList and True DBCombo controls using the ItemChange 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), a True DBCombo control (TDBCombo1), and a True DBList control (TDBList1) on the form (Form1) as shown in this figure.

3.

Set the DatabaseName (Data control) property of Data1 to TDBLDemo.mdb and the RecordSource (Data control) property to the following SQL statement:

SELECT Last FROM Composer

4.

Set the DatabaseName (Data control) property of Data2 to TDBLDemo.mdb and the RecordSource (Data control) property to Opus.

5.

Set the RowSource property of TDBCombo1 and TDBList1 to Data1 and Data2, respectively. Set the ListField and BoundColumn properties of TDBCombo1 to Last and the MaxComboItems property to 9.

6.

Add the following code to the ItemChange event of TDBCombo1:

Private Sub TDBCombo1_ItemChange()

Dim strSQL As String

' A query is performed by taking the BoundText property

' which corresponds to the "LAST" name field from

' the Data1 control and building an SQL query on the LAST

' name field in the Data2 (Opus) table.

strSQL = "SELECT * FROM Opus WHERE Last='"

strSQL = strSQL & TDBCombo1.BoundText & "'"

Data2.RecordSource = strSQL

Data2.Refresh

End Sub

Run the program and observe the following:

•

When Form1 is loaded, TDBCombo1 retrieves the database schema information from Data1 and automatically configures itself to display all of the last names in the Composer table. Similarly, TDBList1 displays all fields from the Opus table.

•

Change the current record position of TDBCombo1 by selecting a different composer. Observe that TDBList1 (the detail list) displays a new set of compositions each time the row changes in TDBCombo1 (the master list).

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 4.


Tutorial 5 - Using True DBList with SQL Query Results

An important feature of True DBList is its ability to automatically sense changes to the database at run time. In this tutorial, you will learn how to use True DBList to display the results of ad-hoc SQL queries. Note that no code is necessary to tell the list what to do---the list will automatically change its field layout to match the new configuration of the query result. Also note that in order for the list 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 list's Clear Fields context menu command to remove it. This will allow the list to configure itself automatically.

1.

Start a new project.

2.

Place a Data control (Data1), a True DBList control (TDBList1), a command button (Command1), and a TextBox control (Text1) on the form (Form1) as shown in this figure.

3.

Set the DatabaseName (Data control) property of Data1 to TDBLDemo.mdb, and the RecordSource (Data control) property to Customer.

4.

Set the RowSource property of TDBList1 to Data1.

5.

Set the Caption property of Command1 to Execute SQL and the MultiLine (TextBox control) property of Text1 to True. Set the Text (TextBox control) property to Enter SQL statement here.

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

TDBList1.SetFocus

Exit Sub

SQLErr:

MsgBox "Error Executing SQL Statement"

Exit Sub

End Sub

Run the program and observe the following:

•

As in Tutorial 1, the True DBList control 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 list 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 list 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(*), to return the total number of records in the Customer table. Even though the SQL result is not a set of records, the list 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 list 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.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 5.


Tutorial 6 - 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 DBList. When manipulating a group of items in True DBList, 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 DBList control (TDBList1), and two command buttons (Command1 and Command2).

3.

Set the DatabaseName (Data control) property of Data1 to TDBLDemo.mdb, and the RecordSource (Data control) property to the following SQL statement:

select * from composer, opus, composer inner join opus on composer.last = opus.last

This will create a RecordSource (Data control) containing all records from Composer joined with Opus having the same values of the data field Last.

4.

Set the RowSource property of TDBList1 to Data1 and the MultiSelect property to 1 - Simple.

5.

Set the Caption properties of Command1 and Command2 to Select and Clear, respectively.

6.

You can easily select and deselect rows in True DBList 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 DAO.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 list. The list 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 TrueDBList80.SelBookmarks

Set SelBks = TDBList1.SelBookmarks

Dim Criteria As String

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

Set SelBks = TDBList1.SelBookmarks

While SelBks.Count <> 0

SelBks.Remove 0

Wend

End Sub

Run the program and observe the following:

•

The True DBList control 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 list 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.

NOTE: Multiple selection is only supported by True DBList, not True DBCombo.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 6.


Tutorial 7 - Defining Unbound Columns in a Bound List

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 8 through 11.

1.

Start a new project.

2.

Place a Data control (Data1) and a True DBList control (TDBList1) on the form (Form1).

3.

Set the DatabaseName (Data control) property of Data1 to TDBLDemo.mdb, and the RecordSource (Data control) 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 RowSource property of TDBList1 to Data1.

Configuring the list at design time

We shall configure the list using its context menus and property pages. For more details, see Design Time Interaction.

6.

Right-click the list to display its context menu.

7.

Choose Edit from the context menu. The list will enter its visual editing mode, enabling you to interactively change the list's row and column layout.

8.

By default, the list contains two columns. We are going to create three more. Right-click anywhere in the list to display the visual editing menu. Choose the Append command to add a new column at the end of the list. Execute this command two more times to create two more columns. A total of five columns are now in the list.

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 DBList 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 list'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 list looks like the one in the following figure.

14.

Click Form1 anywhere outside TDBList1 to exit visual editing mode. You have now finished configuring the list.

Displaying data in the unbound column

In step 9, Column0 of the list was configured as an unbound column, so you must supply its data using the UnboundColumnFetch event. When the list needs to display data in an unbound column, it calls 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 on unbound columns, see Unbound Columns.

15.

Declare RSClone as a Recordset (Data control) in the General section of Form1 so that the RSClone variable will be available in all procedures in Form1:

Dim RSClone As DAO.Recordset

16.

In the Form_Load (Visual Basic) 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 (Data control).

Private Sub Form_Load()

Data1.Refresh

DoEvents

Set RSClone = Data1.Recordset.Clone

End Sub

Finally, define data in the unbound column by combining the FirstName and LastName fields of the Recordset (Data control) in the list's UnboundColumnFetch event:

Private Sub TDBList1_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 list. Note that Bookmark does not usually refer to the current row, since the list displays more than one row at a time. Hence we use a clone (RSClone) to get data from the Recordset (Data control) 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:

•

The True DBList control 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.

•

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 (8, 9, and 10), we will illustrate techniques to improve both the display and the user interface.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 7.


Tutorial 8 - Displaying Translated Data

In this tutorial, you will learn how to use the ValueItems collection to display translated text without writing a single line of code.

1.

Start with the project created in Tutorial 7.

2.

Right-click TDBList1 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 list to translate the data in Column1 before displaying it. Note that the list at the bottom of the property page now displays two columns labeled Value and DisplayValue.

6.

Now enter the Value - DisplayValue pairs in the list 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 list treats the Value property as a string. Entries in the DisplayValue column are translated values to be displayed in the CustType column of the list. 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.

7.

Click the OK button at the bottom of the Property Pages dialog to accept the changes.

Run the program and observe the following:

•

TDBList1 displays data from the joined tables as in Tutorial 7.

•

The CustType column now displays the translated text instead of numeric values.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 8.


Tutorial 9 - 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 8.

2.

First, we will change the captions of the ContactType and Callback columns. Right-click TDBList1 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. Place a check next to the Split’s AllowRowSizing property to make it True.

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 list to translate the data in Column2 before displaying it. Note that the list 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 list to display.

8.

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

9.

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.

10.

Drop down the Presentation combo box and select 4 – Check Box. True DBList will automatically translate 0 and –1 to a check box.

11.

Click the OK button at the bottom of the Property Pages dialog to accept the changes. You should see the column captions on the list modified according to the changes you made in step 3.

12.

Display the primary context menu again as in step 2, but this time choose the Edit option to enter the list's visual editing mode, which enables you to interactively change the list's row height and column layout.

13.

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.

14.

Now place the mouse cursor over the left most part of the left column, changing it to a vertical double-arrow resizing cursor. Drag the divider downward to increase the row size to about double the current height.

15.

Click Form1 anywhere outside TDBList1 to exit visual editing mode. You have now completed reconfiguring the list, which should look like the figure below.

Run the program and observe the following:

•

TDBList1 displays data from the joined table as in Tutorials 7 and 8.

•

The How and Call? columns now display bitmaps instead of numeric values as shown in the following figure.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 9.


Tutorial 10 - Using Styles to Highlight Related Data

In this tutorial, you will learn how to change the list's display to highlight rows by defining new styles at run time. True DBList uses Style objects to apply font and color characteristics to rows, columns, and individual cells.

1.

Start with the project used in Tutorial 9.

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 List 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 TrueDBList80.Style

Dim Distributors As New TrueDBList80.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

TDBList1.FetchRowStyle = True

Case 1

ButtonFlag = 1

TDBList1.FetchRowStyle = True

Case 2

TDBList1.FetchRowStyle = False

End Select

TDBList1.Refresh

End Sub

5.

Enter the following code in the Form_Load (Visual Basic) event:

Private Sub Form_Load()

Set Prospective = TDBList1.Styles.Add("Prospective")

Prospective.Font.Italic = True

Prospective.Font.Bold = True

Prospective.ForeColor = vbBlue

Set Distributors = TDBList1.Styles.Add("Distributors")

Distributors.BackColor = vbRed

Distributors.ForeColor = vbWhite

End Sub

6.

Enter the following code in the FetchRowStyle event of TDBList1:

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:

•

TDBList1 displays data as in Tutorial 9.

•

Click the Prospective Customers button. The list should appear as follows.

•

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

•

Finally, click the Reset the list button. The list should now appear as follows.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 10.


Tutorial 11 - 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 list rows to improve their readability.

1.

Start with the project used in Tutorial 9.

2.

Right-click the list 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 list has default settings for both the EvenRow and OddRow styles. We will use the default settings first then change the settings for the EvenRow style.

Run the program and observe the following:

•

TDBList1 displays data as in Tutorial 9, except that even-numbered rows have a light cyan background.

3.

Right-click the list 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:

•

TDBList1 displays data as in the previous figure, except that even-numbered rows now have a light gray background.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 11.


Tutorial 12 - Creating a List 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 DBList 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 list 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 True DBList control bound to a Data control.

2.

In the Form_Load (Visual Basic) 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 list's properties, make sure the

' list is initialized by refreshing the Data control.

Data1.Refresh

' Create an additional split:

Dim S As TrueDBList80.Split

Set S = TDBList1.Splits.Add(0)

' Hide all columns in the leftmost split, Splits(0),

' except for columns 0 and 1

Dim C As TrueDBList80.Column

Dim Cols As TrueDBList80.Columns

Set Cols = TDBList1.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 TDBList1.Splits(0)

.SizeMode = dblNumberOfColumns

.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 = TDBList1.Splits(1).Columns

Cols(0).Visible = False

Cols(1).Visible = False

End Sub

Run the program and observe the following:

•

The True DBList control 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.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 12.

You can use splits to create fixed, nonscrolling columns anywhere within the list---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.


Tutorial 13 - 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 DBList to display an array of strings.

NOTE: This unbound mode has been retained for backward compatibility with the original DBGrid control. ComponentOne recommends using unbound extended mode (Tutorial 14), application mode (Tutorial 15), or storage mode (Tutorial 16) instead. For detailed instructions on how to use unbound mode 1, see Unbound Mode.

1.

Start a new project.

2.

Place a True DBCombo control (TDBCombo1) on the form (Form1).

3.

Set the DataMode property of TDBCombo1 to 1 - Unbound (the default value of this property is 0 - Bound) and the MaxComboItems property to 14.

Configuring the combo at design time

This example displays a two-column array within the list portion of a True DBCombo control. Since the control displays two columns by default, you do not have to add or delete columns at design time.

4.

Right-click TDBCombo1 to display its context menu. Choose Properties... to display the Property Pages dialog.

5.

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. The combo should look like this.

Initializing the array data

We first create and initialize a two-dimensional array to hold the data to be displayed in the list.

6.

Add the CLASS1.CLS file from the TUTOR13 directory to the project. This class module will be responsible for storing data and responding to the combo's events.

Displaying data in the unbound combo

When using the ListBox control in Visual Basic, you store all of the data in the control using its AddItem (ListBox control) 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 DBList's unbound modes do not store your data. You manage the data while the list handles all display and end-user interactions. Whenever the list 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 list generally asks for only what it needs to display, but may cache some data for efficiency considerations. You cannot predict when the list will ask for data, nor can you assume data will be requested in any particular order. Furthermore, since the list does not store the data, any data that has been requested once may be requested again.

7.

This example shows how data is provided to the combo via the RowBuffer object. The class module CLASS1.CLS declares a private variable using the WithEvents (Visual Basic) keyword:

Private WithEvents TDBC As TrueDBList80.TDBCombo

This provides a convenient mechanism for encapsulating all of the unbound combo events into a self-contained class. NOTE: Since the WithEvents (Visual Basic) keyword is not supported by Visual Basic 4.0, the control's event handlers need to delegate the work to the appropriate subroutine in CLASS1.CLS.

' Called when the Combo needs data

Private Sub TDBC_UnboundReadData( _

ByVal RowBuf As TrueDBList80.RowBuffer, _

StartLocation As Variant, ByVal ReadPriorRows As Boolean)

' UnboundReadData is fired by a combo control whenever

' it requires data for display. This event will fire

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

' is used and when the list is scrolled. The

' list fetches data in "chunks", and the number of rows

' the list 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 list is requesting

' to display. It will also hold the number of rows that

' were successfully supplied to the list.

' 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 list wants is the row after

' StartLocation, and if we are reading rows before

' StartLocation (ReadPriorRows = True) then the first

' row of data the list 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 RowsFetched As Integer

Dim I As Integer, J As Integer, RelPos As Integer

Dim CurRow As Long

RowsFetched = 0

If ReadPriorRows Then

' Requesting data in rows prior to StartLocation

RelPos = -1

Else

' Requesting data in rows after StartLocation

RelPos = 1

End If

If IsNull(StartLocation) Then

If ReadPriorRows Then

' StartLocation refers to EOF.

CurRow = MaxRow - 1

Else

' StartLocation refers to BOF.

CurRow = 0

End If

Else

CurRow = Val(StartLocation) + RelPos

End If

For I = 0 To RowBuf.RowCount - 1

' If the next row is BOF or EOF, then stop

' fetching and return any rows fetched up to this

' point.

If CurRow < 0 Or CurRow >= MaxRow Then Exit For

' Place the record data into the row buffer

For J = 0 To RowBuf.ColumnCount - 1

RowBuf.Value(I, J) = ComboArray(J, CurRow)

Next J

' Set the bookmark for the row

RowBuf.Bookmark(I) = CurRow

CurRow = CurRow + RelPos

' Increment the count of fetched rows

RowsFetched = RowsFetched + 1

Next I

RowBuf.RowCount = RowsFetched

End Sub

8.

The following implementation of the UnboundGetRelativeBookmark event demonstrates how to provide bookmarks to the unbound combo. Although it is not required for DataMode 1 - Unbound, it will greatly improve speed and efficiency:

Private Sub TDBC_UnboundGetRelativeBookmark( _

StartLocation As Variant, ByVal OffSet As Long, _

NewLocation As Variant, ApproximatePosition As Long)

Dim Index As Long

' TDBCombo calls this routine each time it needs to

' reposition itself. StartLocation is a bookmark

' supplied by the combo 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.

If IsNull(StartLocation) Then

If OffSet < 0 Then

Index = MaxRow + OffSet

Else

Index = -1 + OffSet

End If

Else

Index = Val(StartLocation) + OffSet

End If

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

If Index >= 0 And Index < MaxRow Then

ApproximatePosition = Index

NewLocation = Index

Else

NewLocation = Null

End If

End Sub

9.

In the General section of Form1, insert the following declarations:

Option Explicit

Dim Sink As New Class1

10.

In the Form_Load (Visual Basic) event, initialize the elements of the Class1 instance and set the ApproxCount property of the combo accordingly. The ApproxCount property is optional, but setting this value will enable the list to position the vertical scroll bar accurately.

Private Sub Form_Load()

Dim Row As Long, Col As Integer

Row = 100

Col = 2

' Initialize storage

Sink.SetDims Row, Col

' Fill with values

For Row = 0 To Sink.RowCount - 1

For Col = 0 To Sink.ColCount - 1

Sink.Value(Row, Col) = _

"Row " & Row & ", Col " & Col

Next Col

Next Row

' Initialize the class

Sink.Attach TDBCombo1

' Calibrate the VScroll bar

TDBCombo1.ApproxCount = Sink.RowCount

End Sub

Run the program and observe the following:

•

The combo displays the data generated in the Form_Load (Visual Basic) event and otherwise behaves as if it were bound to a Data control.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 13.


Tutorial 14 - 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 DBList to display an array of strings. As its name implies, the unbound extended mode is an extension of the unbound mode introduced in Tutorial 13. 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.

The TUTOR14.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\TUTOR14 subdirectory of the True DBList installation directory.

1.

Start a new project.

2.

Place a True DBCombo control (TDBCombo1) on the form (Form1).

3.

Set the DataMode property of TDBCombo1 to 2 - Unbound Extended (the default value of this property is 0 - Bound) and the MaxComboItems property to 14.

Configuring the combo at design time

We shall configure the combo as in Tutorial 13.

4.

Right-click TDBCombo1 to display its context menu. Choose Properties... to display the Property Pages dialog.

5.

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

We first create and initialize a two-dimensional array to hold the data to be displayed in the list. As in Tutorial 13, we will use a class module to encapsulate the unbound events.

6.

Add the CLASS1.CLS file from the TUTOR14 directory to the project. This class module will be responsible for storing data and responding to the combo's events.

Displaying data in the unbound combo

As explained in Tutorial 13, True DBList does not store your data in any of its unbound modes. In unbound mode 2, whenever the list needs to display more rows of data, it will fire the UnboundReadDataEx event (instead of UnboundReadData) to ask for data from your data source.

7.

Study the following implementation of the UnboundReadDataEx event from CLASS1.CLS. This example shows how data and the row's ordinal position are provided to the list via the RowBuffer object and the ApproximatePosition arguments, respectively:

' Fired when the Combo needs a bookmark or data

Private Sub TDBC_UnboundReadDataEx( _

ByVal RowBuf As TrueDBList80.RowBuffer, _

StartLocation As Variant, ByVal offset As Long, _

ApproximatePosition As Long)

' UnboundReadDataEx is fired by an unbound combo whenever

' it requires data for display. This event will fire

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

' is used and when the combo is scrolled. The

' combo fetches data in "chunks", and the number of rows

' the combo 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 combo is

' requesting to display. It will also hold the number

' of rows that were successfully supplied to the combo.

' 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 combo, for instance, the new

' top row of the combo will have an index greater than

' the StartLocation (Offset > 0). If you page up on

' the combo, the new index is less than that of

' StartLocation, so Offset < 0. If StartLocation is

' a bookmark to row N, the combo 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

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

If IsNull(StartLocation) Then

If offset < 0 Then

' StartLocation refers to EOF

Bookmark = MaxRow + offset

Else

' StartLocation referrs to BOF

Bookmark = offset - 1

End If

Else

' StartLocation is a valid or invalid row

Bookmark = StartLocation + offset + I

' If the next row is BOF or EOF, stop fetching

' and return any rows fetched up to this point.

If Bookmark < 0 Or Bookmark >= MaxRow _

Then Exit For

End If

' Fill the RowBuffer with data

For J = 0 To RowBuf.ColumnCount - 1

ColIndex = RowBuf.ColumnIndex(I, J)

' Place the record data into the row buffer

RowBuf.Value(I, J) = _

ComboArray(ColIndex, Bookmark)

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 list how many rows were fetched

RowBuf.RowCount = RowsFetched

' Set the approximate scroll bar position. Only

' nonnegative values are valid.

If Bookmark >= 0 Or Bookmark < MaxRow _

Then ApproximatePosition = Bookmark - I

End Sub

8.

In the General section of Form1, insert the following declarations:

Option Explicit

Dim Sink As New Class1

9.

In the Form_Load (Visual Basic) event, initialize the elements of the Class1 instance and set the ApproxCount property of the combo accordingly. The ApproxCount property is optional, but setting this value will enable the combo to position the vertical scroll bar accurately.

Private Sub Form_Load()

Dim Row As Long, Col As Integer

Row = 100

Col = 2

' Initialize storage

Sink.SetDims Row, Col

' Fill with values

For Row = 0 To Sink.RowCount - 1

For Col = 0 To Sink.ColCount - 1

Sink.Value(Row, Col) = _

"Row " & Row & ", Col " & Col

Next Col

Next Row

' Initialize the class

Sink.Attach TDBCombo1

' Calibrate the VScroll bar

TDBCombo1.ApproxCount = Sink.RowCount

End Sub

Run the program and observe the following:

•

The combo displays the data generated in the Form_Load (Visual Basic) event and otherwise behaves as if it were bound to a Data control.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 14.


Tutorial 15 - 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 DBList 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 list fetches data one cell at a time, and you must program the UnboundGetRelativeBookmark event in order for the list to obtain the bookmark of a row. For detailed instructions on how to use unbound mode 3, see Application Mode.

The TUTORIAL15.VBP project provides a complete sample that you can use as a template for implementing application mode. This project is located in the TUTORIAL\TUTORIAL15 subdirectory of the True DBList installation directory.

1.

Start a new project.

2.

Place a True DBCombo control (TDBCombo1) on the form (Form1).

3.

Set the DataMode property of TDBCombo1 to 3 - Application (the default value of this property is 0 - Bound) and the MaxComboItems property to 14.

Configuring the combo at design time

We shall configure the combo as in Tutorial 14.

4.

Right-click TDBCombo1 to display its context menu. Choose Properties... to display the Property Pages dialog.

5.

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

We first create and initialize a two-dimensional array to hold the data to be displayed in the list. As in Tutorial 14, we will use a class module to encapsulate the unbound events.

6.

Add the CLASS1.CLS file from TUTOR15 directory to the project. This class module will be responsible for storing data and responding to the combo's events.

Displaying data in the unbound combo

As explained in Tutorial 14, True DBList does not store your data in any of its unbound modes. In unbound mode 3, whenever the list 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 list to obtain the bookmark of a row.

7.

Study the following implementation of the UnboundGetRelativeBookmark and ClassicRead events. These events show how to provide bookmarks and data to the unbound combo. Note that the code in the UnboundGetRelativeBookmark event is identical to the one used in Tutorial 13:

' Fired when the Combo needs to reposition itself

Private Sub TDBC_UnboundGetRelativeBookmark( _

StartLocation As Variant, ByVal OffSet As Long, _

NewLocation As Variant, ApproximatePosition As Long)

' TDBCombo1 calls this routine each time it needs to

' reposition itself. StartLocation is a bookmark

' supplied by the list 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.

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

Dim Index As Long

If IsNull(StartLocation) Then

If OffSet < 0 Then

Index = MaxRow + OffSet

Else

Index = -1 + OffSet

End If

Else

Index = Val(StartLocation) + OffSet

End If

If Index >= 0 And Index < MaxRow Then

ApproximatePosition = Index

NewLocation = Index

Else

NewLocation = Null

End If

End Sub

' Called when the Combo needs data

Private Sub TDBC_ClassicRead(Bookmark As Variant, _

ByVal Col As Integer, Value As Variant)

' When the list needs data in DataMode 3, it fires a

' ClassicRead event for each visible cell on the list

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

Value = ComboArray(Col, Bookmark)

End Sub

8.

In the General section of Form1, insert the following declarations:

Option Explicit

Dim Sink As New Class1

9.

In the Form_Load (Visual Basic) event, initialize the elements of the Class1 instance and set the ApproxCount property of the combo accordingly. The ApproxCount property is optional, but setting this value will enable the combo to position the vertical scroll bar accurately.

Private Sub Form_Load()

Dim Row As Long, Col As Integer

Row = 100

Col = 2

' Initialize storage

Sink.SetDims Row, Col

' Fill with values

For Row = 0 To Sink.RowCount - 1

For Col = 0 To Sink.ColCount - 1

Sink.Value(Row, Col) = _

"Row " & Row & ", Col " & Col

Next Col

Next Row

' Initialize the class

Sink.Attach TDBCombo1

' Calibrate the VScroll bar

TDBCombo1.ApproxCount = Sink.RowCount

End Sub

Run the program and observe the following:

•

The combo displays the data generated in the Form_Load (Visual Basic) event and otherwise behaves as if it were bound to a Data control.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 15.


Tutorial 16 - 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 DBList 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, re-dimension, 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 list or combo. The data will then be maintained and exchanged between the list 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 DBCombo control (TDBCombo1) on the form (Form1).

3.

Set the DataMode property of TDBCombo1 to 4 - Storage (the default value of this property is 0 - Bound) and the MaxComboItems property to 14.

Configuring the combo at design time

We shall configure the combo to display four columns.

4.

Right-click TDBCombo1 to display its context menu, and choose the Edit option. The combo will enter its visual editing mode, enabling you to interactively change the combo's row and column layout.

5.

By default, the combo contains two columns. We are going to create two more. Right-click anywhere in the combo to display the visual editing menu. Choose the Append command to add a new column at the end of the combo. Execute this command again to get a total of four columns.

6.

Right-click TDBCombo1 to display its context menu. Choose Properties... to display the Property Pages dialog.

7.

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.

Adding XArrayDB to the project

Before writing the code, we need to add the ComponentOne XArrayDB Object to the project.

8.

Select References… from the Project menu to display a list of available type library references. Select the check box labeled ComponentOne XArrayDB Object (XARRAYDB.OCX), then press the OK button.

Initializing the array data

Next, we create the XArrayDB object in code.

9.

In the General section of Form1, insert the following declarations:

' General declarations

Option Explicit

Dim Sink As New XArrayDB

10.

In the Form_Load (Visual Basic) event, we ReDim the XArrayDB to contain 100 rows and 4 columns. After populating the XArrayDB, we assign it to the combo's Array property.

Private Sub Form_Load()

' Allocate space for 100 rows, 4 columns

Sink.ReDim 0, 99, 0, 3

Dim row, col As Long

' 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 = Sink.LowerBound(1) To Sink.UpperBound(1)

For col = Sink.LowerBound(2) To Sink.UpperBound(2)

Sink(row, col) = "Row " & row & ", Col " & col

Next col

Next row

' Bind TDBCombo Control to this XArray instance

Set TDBCombo1.Array = Sink

End Sub

Run the program and observe the following:

•

The combo displays the data assigned to the XArrayDB and appears as follows.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 16.


Tutorial 17 - 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 a new project.

2.

Add the following controls on the form (Form1) as shown in the following figure: two text box controls (Text1 and Text2), a command button (Command1), two labels (Label1 and Label2), and a TDBList control (TDBList1).

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 (Visual Basic) 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 DBList Control to this XArrayDB instance

Set TDBList1.Array = x

' Enable footers

TDBList1.ColumnFooters = True

' Display headers and footers as buttons

Dim obcol As TrueDBList80.Column

For Each obcol In TDBList1.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

If RowFound >= 0 Then TDBList1.Bookmark = RowFound

TDBList1.SetFocus

End Sub

5.

Add the following code to the HeadClick and FootClick events:

Private Sub TDBList1_HeadClick(ByVal ColIndex As Integer)

' Ascending sort

x.QuickSort x.LowerBound(1), x.UpperBound(1), ColIndex, _

XORDER_ASCEND, XTYPE_INTEGER

TDBList1.Refresh

End Sub

Private Sub TDBList1_FootClick(ByVal ColIndex As Integer)

' Descending sort

x.QuickSort x.LowerBound(1), x.UpperBound(1), ColIndex, _

XORDER_DESCEND, XTYPE_INTEGER

TDBList1.Refresh

End Sub

Run the program and observe the following:

•

The list 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 list makes the specified row current.

•

Type a three-digit number into the Find text box, then click the Find button again. Since no matching value exists, the current row does not change.

This concludes Tutorial 17.


Tutorial 18 - Displaying Arbitrary Bitmaps

In this tutorial, you will learn how to use Style objects to display arbitrary bitmaps within list 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 DBList control (TDBList1), a command button (Command1), and a TextBox control (Text1) on the form (Form1)

3.

Set the DataMode property of TDBList1 to 4 - Storage (the default value of this property is 0 - Bound).

4.

Right-click TDBList1 to display its context menu and choose Properties… to display the Property Pages dialog.

5.

Click on the RowHeight property on the General Properties page, and enter the desired row height.

6.

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.

7.

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.

8.

Set the Caption (Visual Basic)property of Command1 to Display. Your form should now look like this:

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.

9.

Select References… from the Project menu to display a list of available type library references. Select the check box labeled ComponentOne XArrayDB Object (XARRAYDB.OCX), then press the OK button.

10.

Enter the path of the \Bitmaps\Flags directory in the Text property of Text1.

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 (Visual Basic) event:

Private Sub Form_Load()

' Initially we resize the XArrayDB

' to 0 rows and 2 columns

x.ReDim 0, -1, 0, 1

Set TDBList1.Array = x

' Enable FetchCellStyle Event

TDBList1.Columns(0).FetchStyle = True

End Sub

13.

Add the following code to the Click (Visual Basic) 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 list

TDBList1.Bookmark = Null

TDBList1.ReBind

End Sub

14.

Enter the following code in the FetchCellStyle event:

Private Sub TDBList1_FetchCellStyle( _

ByVal Condition As Integer, ByVal Split As Integer, _

Bookmark As Variant, ByVal Col As Integer, _

ByVal CellStyle As TrueDBList80.StyleDisp)

Dim PathFileName As String

' Full Path file name of a picture

PathFileName = Text1.Text & "\" & _

TDBList1.Columns(1).CellText(Bookmark)

' Load the picture

CellStyle.BackgroundPicture = LoadPicture(PathFileName)

End Sub

Run the program and observe the following:

•

True DBList 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 list 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 List Elements.

This concludes Tutorial 18.


Tutorial 19 - Reusable Layouts

In True DBList, a layout comprises the complete set of properties that define the appearance and behavior of a list, its splits, and its columns. You can save a list 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 DBList download it asynchronously, an ideal technique for initializing a list 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 ComponentOne 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 Click (Visual Basic) property of Command1, Command2, and Command3 to Retrieve Layout, Save Layout, and Retrieve Layout, respectively. Your form should now look like this.

4.

Right-click TDBList1 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 (Visual Basic) event of Command1, Command2 and Command3:

Private Sub Command1_Click()

On Error GoTo Err:

' Load the layout

TDBList1.LayoutName = "TestLayout"

TDBList1.LayoutFileName = App.Path & "\Tutor19.grx"

TDBList1.LoadLayout

Exit Sub

Err:

MsgBox Err.Description

End Sub

Private Sub Command2_Click()

' Save current layout

TDBList1.LayoutFileName = App.Path & "\Tutor19.grx"

TDBList1.Layouts.Add "TestLayout"

End Sub

Private Sub Command3_Click()

' Load layout from ComponentOne

TDBList1.LayoutName = "ComponentOne"

' Start the download

TDBList1.LayoutUrl = _

"ftp://ftp.componentone.com/pub/files/tutor19.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 TDBList1:

Private Sub TDBList1_LayoutReady()

' Load layout as soon as it is available

TDBList1.LoadLayout

End Sub

Run the program and observe the following:

•

As in Tutorial 1, True DBList 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 list 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 list will display the default layout as before. Now, click the Retrieve Layout button. The list will display the layout that you saved previously.

•

If your computer is connected to the Internet, click the Retrieve ComponentOne Layout button. The list will be configured according to a layout file stored on the ComponentOne server.

For more information, see Reusable Layouts.

This concludes Tutorial 19.


Tutorial 20 - Printing, Print Preview, and Export

In this tutorial, you will learn how to use the printing and exporting capabilities of True DBList.

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 Click (Visual Basic) property of Command1, Command2, and Check1 to Print Preview, Export HTML, and Export Selected Rows, respectively. Your form should now look like this:

NOTE: If you wish to select more than one row, you must also change the MultiSelect property (from the Properties window or the General tab on the Properties Pages dialog) from the default 0 - None to 2 - Extended.

4.

Enter the following code in the Form_Load (Visual Basic) event:

Private Sub Form_Load()

' Initialize the Data control

Data1.Refresh

' Allow user to change the column order

TDBList1.AllowColMove = True

' Change the presentation of the list

With TDBList1.Columns

.Item("Country").BackColor = vbCyan

.Item("Country").Font.Name = "Times New Roman"

.Item("Last").NumberFormat = ">"

.Item("Last").ForeColor = vbRed

End With

With TDBList1.HeadingStyle

.Font.Bold = True

.BackColor = vbBlue

.ForeColor = vbYellow

End With

End Sub

5.

Add the following code to Command1 and Command2:

Private Sub Command1_Click()

With TDBList1.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 list will export all or just selected rows

TDBList1.ExportToFile App.Path & _

"\Tutor20.html", False, Check1.Value

End Sub

Run the program and observe the following:

•

True DBList 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 list.

•

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 TUTOR20.HTML in the TUTOR20 directory. Load this file into your browser and note that the generated HTML table mirrors the format of the list.

•

Go back to Form1 and select one or more records in the list. 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 21 - Cell Bordering and Scroll Tips/Tracking

In this tutorial you will utilize the Cell Border, Scroll Tips and Scroll Tracking features in True DBList. 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 DBList control (TDBList1), an Data control (Data1), a Common Dialog control (Cdlg).

Next, below the 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 Data1 to the TDBLDemo database in code by adding the following code:

Private Sub Form_Load()

Dim path As String

On Error Resume Next

path = App.path & "\..\..\TDBLDemo.mdb" 'database path

'use run time connection

With Data1

.DatabaseName = path

.RecordSource = "composer"

.Refresh

End With

cdlg.Color = vbGreen

cboBorderAppearance.ListIndex = 3

cboBorderSize.ListIndex = 5

With TDBList1

.RowHeight = 400

.RowDividerStyle = 7 'custom style

.RowDividerColor = vbGreen

End With

End Sub

4.

Set the TDBList1 RowSource to Data1.

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 6 and add the following code:

Private Sub cboBorderSize_Click()

Call setStyle

End Sub

7.

Add the following code to cmdColor:

Private Sub cmdColor_Click()

cdlg.ShowColor

Call setStyle

End Sub

8.

Add the following code to chkSTracking:

Private Sub chkSTracking_Click()

TDBList1.ScrollTrack = chkSTracking.Value

End Sub

9.

Add the following code to chkSTips:

Private Sub chkSTips_Click()

TDBList1.ScrollTips = chkSTips.Value

End Sub

10.

Add the following code:

Option Explicit

Dim recset As Recordset

Dim border As TrueDBList70.BorderStyleConstants

Private Sub chkBorderType_Click(Index As Integer)

Dim chk As CheckBox

border = dblBorderNone

For Each chk In chkBorderType

If chk.Value Then

Select Case chk.Index

Case 0:

border = border Or dblBorderTop

Case 1:

border = border Or dblBorderLeft

Case 2:

border = border Or dblBorderBottom

Case 3:

border = border Or dblBorderRight

End Select

End If

Next chk

Call setStyle

End Sub

Private Sub Form_Activate()

'set the recordset in Active event instead of Load event

Set recset = Data1.Recordset

End Sub

Private Sub setStyle()

cmdColor.BackColor = cdlg.Color

With TDBList1.Columns(TDBList1.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 TDBList1_FetchScrollTips(ByVal ColIndex As Integer, Bookmark As Variant, ByVal ScrollBar As TrueDBList70.ScrollBarsConstants, ScrollTip As String, ByVal TipStyle As TrueDBList70.StyleDisp)

' Set the ScrollTip depending on which

' scroll bar was moved

Select Case ScrollBar

Case dblVertical:

recset.Bookmark = Bookmark

ScrollTip = "Record: " & CStr(recset.AbsolutePosition) & " of " & _

CStr(recset.RecordCount) & vbCrLf & "Last Name: " & _

recset("Last") & vbCrLf & "First Name: " & recset("First")

Case dblHorizontal:

ScrollTip = TDBList1.Columns(ColIndex).Caption

End Select

TipStyle.ForeColor = vbBlue

End Sub

11.

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.


Tutorial 22 - Performing a List Search Using the Find Method

Tutorial 22 – Performing a List Search Using the Find Method

In this tutorial you will utilize the Find method in True DBList. The Find method allows you to perform custom searches within the control.

1.

Start a new project.

2.

Based on the following illustration, place one list control (TDBList1), 3 combo boxes (TDBCombo1, 2 and 3), a text box (Text2), a data control (Data1), a command button (Command1) and four labels on the form as shown in the illustration below.

Set the RowSource of TDBList1 to Data1.

Set the DataMode property of the three TDBCombo controls to 4 – Storage.

Define X1, X2 and X3 as New XarrayDB corresponding to the three TDBCombo Boxes. These variables will hold the values for the TDBCombo Boxes.

Option Explicit

Dim X1 As New XArrayDB 'corresponding to 3 TDBComboboxes

Dim X2 As New XArrayDB

Dim X3 As New XArrayDB

3.

To connect Data1 to the datasource and fill the three TDBCombo Boxes with values at runtime, add the following code:

Private Sub Form_Load()

'put the form in the middle

Me.Left = (Screen.Width - Me.Width) \ 2

Me.Top = (Screen.Height - Me.Height) \ 2

Data1.Visible = False

Dim path As String

On Error Resume Next

path = App.path & "\..\..\TDBLDemo.mdb" 'database path

'use run time connection

With Data1

.DatabaseName = path

.RecordSource = "Customers"

.Refresh

End With

'fill combo1

X1.ReDim 0, 3, 0, 0

X1(0, 0) = "Partial Include"

X1(1, 0) = "Equal"

X1(2, 0) = "Less Than"

X1(3, 0) = "Greater Than"

With TDBCombo1

.ColumnHeaders = False

.Array = X1

.BoundText = "Partial Include"

End With

'fill combo2

X2.ReDim 0, 1, 0, 0

X2(0, 0) = "Start From Beginning"

X2(1, 0) = "Start After Current Row"

With TDBCombo2

.ColumnHeaders = False

.Array = X2

.BoundText = "Start From Beginning"

End With

'fill combo3

X3.ReDim 0, 6, 0, 0

X3(0, 0) = "UserCode"

X3(1, 0) = "LastName"

X3(2, 0) = "FirstName"

X3(3, 0) = "Company"

X3(4, 0) = "Contacted"

X3(5, 0) = "Phone"

X3(6, 0) = "CustType"

With TDBCombo3

.ColumnHeaders = False

.Array = X3

.BoundText = "UserCode"

End With

Text2.Text = ""

End Sub

4.

To handle the Command1 click event, add the following code:

Private Sub Command1_Click()

On Error GoTo Err_Handle

Dim matchCompare As Integer

Dim searchPos As Integer

Dim bk As Variant

If Text2.Text = "" Then

Exit Sub

End If

Select Case TDBCombo1.BoundText

Case "Partial Include"

matchCompare = dblSeekPartialEQ

Case "Equal"

matchCompare = dblSeekEQ

Case "Less Than"

matchCompare = dblSeekLT

Case "Greater Than"

matchCompare = dblSeekGT

End Select

Select Case TDBCombo2.BoundText

Case "Start From Beginning"

searchPos = 1

Case "Start After Current Row"

searchPos = 2

End Select

If searchPos = 1 Then

bk = TDBList1.Columns(CStr(TDBCombo3.BoundText)).Find(Text2.Text, matchCompare, True)

Else

If IsNull(TDBList1.Bookmark) Then

MsgBox "There is no current row"

Exit Sub

End If

bk = TDBList1.Columns(CStr(TDBCombo3.BoundText)).Find(Text2.Text, matchCompare, False, TDBList1.Bookmark)

End If

If Not IsNull(bk) Then

TDBList1.Bookmark = bk

Else

MsgBox "Can not find this value!"

End If

Exit Sub

Err_Handle:

MsgBox Err.Description

End Sub

5.

Finally, add the code below to clear the memory:

Private Sub Form_Unload(Cancel As Integer)

Set X1 = Nothing

Set X2 = Nothing

Set X3 = Nothing

End Sub

6.

Run the program and you should have a form that looks like this:

•

Set the Column Combo Box to LastName and the Compare Mode Combo Box to Partial Include. Then place a letter in the Search String(number) Text Box and press the Find button. Notice how the first item in the LastName column beginning with the letter you entered is found.

•

Next, set the Search Pos Combo Box to Start After Current Row and press the Find button. Notice how the next item in the LastName column beginning with the letter you entered is found.

•

The Find method will also let you search numeric strings. Set the Column Combo Box to Contacted and the Compare Mode Combo Box to Partial Include. Then place a date from the Contacted column in the Search String(Number) Text Box and press the Find button. Notice how the first item in the Contacted column with the date you entered is found.

NOTE: When using ICursor, the Find method can include wildcards (*) to allow for searches containing certain letters or numbers (such as *86 to search for any date ending in the year 1986). OleDB does not allow for wildcards so the OleDB Tutorial 22 includes a Inside Include option in Compare Mode which will search for values inside strings.


Tutorial 23 - Outlook-Style Grouping (OLEDB Only)

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 list columns into a new split for enhanced data display capabilities. When in Group mode, a "grouping area" is added to the list, providing an intuitive interface for creating a columns group.

When DataView is set to 2 - Group, and AllowColMove is set to True, the list 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 DBList.

1.

Start a new project.

2.

From the Visual Basic Project menu, select Components, then check the boxes labeled ComponentOne True DBList Pro 8.0 (OLEDB) and Microsoft ADO Data Control 6.0 (OLEDB).

3.

Place an ADO Data control (Adodc1) and a True DBList control (TDBList1) 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 Jet 3.51 Provider" option should be highlighted. Click Next>>. Enter the datasource name (C:PROGRAM FILES\TDBL7\TUTORIALS\TDBLDEMO.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 (Data control) property to 2 - adCmdTable.

6.

Set the RecordSource (Data control) property to Composer.

7.

Set the RowSource property of TDBList1 to Adodc1.

8.

Set the RowDividerStyle to 2 - Dark gray line.

9.

Set the DataView property of TDBList1 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 list. The list should look like the one in the following figure.

11.

Add the following code to GroupColMove event of TDBList1:

Private Sub TDBList1_GroupColMove(ByVal Position As Integer, ByVal ColIndex As Integer, Cancel As Integer)

Dim strSort As String

Dim Col As TrueOleDBList80.Column

' Loop through GroupColumns collection and construct

' the sort string for the Sort property of the Recordset

For Each Col In TDBList1.GroupColumns

If strSort <> vbNullString Then

strSort = strSort & ", "

End If

strSort = strSort & "[" & Col.DataField & "]"

Next Col

TDBList1.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 list's appearance. The rows are now sorted by the "Country" field. In addition, the list 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 list'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.

Congratulations, you have successfully completed all 23 tutorials!


Object Model

True DBList was developed using the latest ActiveX and data binding technologies. The True DBList 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 DBList.

If you are new to Visual Basic, please read Working with Objects and Collections, which illustrates how to manipulate True DBList 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 DBList objects and collections.

True DBList Pro Objects and Collections

TDBList and TDBCombo Controls

Column Object, Columns Collection

DataObject Object, DataObjectFiles Collection

GroupColumns Object

Layouts Object

PrintInfo Object, PrintInfos Collection

RowBuffer Object

SelBookmarks Object

Split Object, Splits Collection

Style Object, Styles Collection

ValueItem Object, ValueItems Collection

XArrayDB Object

Working with Objects and Collections


True DBList Pro Objects and Collections

True DBList provides a rich set of properties, methods, and events that enable you to develop sophisticated database applications. The organization imposed by True DBList'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 DBList to a Visual Basic project, the following controls are added to the toolbox:

TDBList

True DBList ActiveX control.

TDBCombo

True DBCombo ActiveX control.

The type library for True DBList also contains definitions for the following objects:

Column

Represents a column of data within a list 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 list columns. In general, a group of similar items in True DBList 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 DBList contains definitions for the following collections:

Columns

Contains zero or more Column objects in a list or split.

GroupColumns

Contains zero or more Column objects in the grouping area.

Layouts

Contains zero or more named list layouts.

PrintInfos

Contains one or more PrintInfo objects in a list.

SelBookmarks

Contains zero or more selected row bookmarks.

Splits

Contains one or more Split objects in a list.

Styles

Contains built-in and user-defined Style objects for a list.

ValueItems

Contains zero or more ValueItem objects for a column.

When using True DBList'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 DBList's objects and collections.


TDBList and TDBCombo Controls

The TDBList and TDBCombo controls are the primary objects of True DBList. Both controls implement multicolumn data-aware lists and are automatically populated from one or more fields in an attached Data control. Both controls can also optionally update a field in a related table of another Data control.

The TDBCombo control contains a text box portion for editing the selected field. The list portions of both controls are identical in functionality.

When you place a True DBList control on a Visual Basic form at design time, an instance of the list control object is created. List objects created in Visual Basic will be given default names of TDBList1, TDBList2, and so forth. Similarly, when you place a True DBCombo control on a Visual Basic form at design time, an instance of the TDBCombo control object is created. TDBCombo objects created in Visual Basic will be given default names of TDBCombo1, TDBCombo2, and so forth. You can change the object name of either control in the Visual Basic Properties window at design time.

See Also

Design Time Interaction

Run Time Interaction

Bound Mode

Storage Mode

Application Mode

Unbound Mode

AddItem Mode

Reference Topics

TDBList Control Properties

TDBList Control Methods

TDBList Control Events


Column Object, Columns Collection

Each column within a TDBList control, TDBCombo control, or Split object is represented by a Column object. When a list or combo control is bound to a database, each Column object is usually associated with a database field, although True DBList also supports unbound columns in bound mode. When a control is first created, it contains two Column objects by default.

The TDBList control, the TDBCombo 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 TDBCombo control supplies an argument of type DataObject when it fires the following events: OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.

The DataObjectFiles (Visual Basic) collection is not supported by True DBList. However, it is defined in the type library because it is referenced by the DataObject object.

Reference Topics

DataObject Object Properties

DataObject Object Methods


GroupColumns Object

When the DataView property is set to 2 - Group, a grouping area is created above the list; columns may be added to this area to form a group, creating a new split in the list. 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 list; it is not deleted.

The OLE DB TDBList control 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

GroupColumns Collection Properties

GroupColumns Collection Methods


Layouts Object

In True DBList, the term layout refers to the complete set of persistent properties for a TDBList or TDBCombo control, including its design-time collections. You can store one or more list 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 TDBList and TDBCombo controls support this collection.

See Also

Reusable Layouts

Reference Topics

Layouts Collection Properties

Layouts Collection Methods


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 TDBList control is first created, its PrintInfos collection contains a single PrintInfo object representing the system default printer.

The PrintInfo property of a TDBList control returns the default member of its PrintInfos collection.

The PrintInfos collection is persistent, which means that you can define multiple print layouts at design time, then recall them in code at run time.

Reference Topics

PrintInfo Object Properties

PrintInfo Object Methods


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 list in the row-based unbound mode events. You cannot create a standalone RowBuffer object.

See Also

Unbound Mode

Reference Topics

RowBuffer Object Properties


SelBookmarks Object

When the user selects and highlights one or more rows of a TDBList 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

SelBookmarks Collection Properties

SelBookmarks Collection Methods


Split Object, Splits Collection

True DBList supports Excel-like splits that divide the list 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 TDBList control is created, it contains one Split object by default. Many of the properties of the Split object also apply to the list or combo 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 TDBList and TDBCombo controls maintains a Splits collection to hold and manipulate Split objects. A list or combo control 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

Split Object Properties

Split Object Methods

Splits Collection Properties

Splits Collection Methods


Style Object, Styles Collection

Style objects encapsulate font, color, picture, and formatting information for a TDBList, TDBCombo, 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 list's display.

When a TDBList or TDBCombo control is created, it contains eight 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 TDBList and TDBCombo 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 list, 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

Style Object Properties

Style Object Methods

Styles Collection Properties

Styles Collection Methods


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 TDBList or TDBCombo control stores these items, if specified, in a ValueItems collection, which is accessed using the ValueItems property.

See Also

Automatic Data Translation with ValueItems

Reference Topics

ValueItem Object Properties

ValueItems Collection Properties

ValueItems Collection Methods


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 DBList, as it is packaged as a separate file, XARRAYDB.OCX, which is not dependent upon any of the list .OCX files.

The XArrayDB object is used as a data source for a TDBList or TDBCombo 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.

NOTE: Version 5.0 introduced the XArray object (without the DB), which supports up to ten dimensions but does not provide any methods for searching and sorting. For backward compatibility, version 6.0 and newer also supports the XArray object in storage mode. However, XArrayDB is preferred, since it is optimized for the two-dimensional case and supports sorting and searching.

See Also

Storage Mode

Reference Topics

XArrayDB Object Properties

XArrayDB Object Methods


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 DBList objects and collections, you can apply the same fundamentals to all Visual Basic objects and collections.

A TDBList object is created when you place a True DBList control on a Visual Basic form. TDBList objects created in Visual Basic will have default names of TDBList1, TDBList2, 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 TDBList 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 eight default Style objects: Normal, Heading, Footing, Selected, Caption, HighlightRow, EvenRow, and OddRow. 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 list has an index value of 0. You can read or set the Split object's properties as follows:

' Read a Split object property

variable = TDBList1.Splits(0).Property

' Set a Split object property

TDBList1.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 list's default Split object:

' Declare Split0 as a Split object

Dim Split0 As TrueDBList80.Split

' Set Split0 to reference the first Split in the collection

Set Split0 = TDBList1.Splits.Item(0)

Note the use of the type library qualifier TrueDBList80 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 TrueDBList80 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 DBList, the type library qualifier is TrueOleDBList instead of TrueDBList80. 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 TrueDBList80.Split

' Set Split0 to reference the first Split in the collection

Set Split0 = TDBList1.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 = TDBList1.Splits(0).Property1

variable2 = TDBList1.Splits(0).Property2

' Set a Split object's properties

TDBList1.Splits(0).Property1 = variable1

TDBList1.Splits(0).Property2 = variable2

This code is very inefficient because each time the object TDBList1.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 TrueDBList80.Split

' Set Split0 to reference the first Split in the collection

Set Split0 = TDBList1.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 DBList, and of Visual Basic in general. Of particular importance to the list are the Column object and Columns collection:

' Declare Cols as a Columns collection object, then set it to

' reference TDBList1's Columns collection object.

Dim Cols As TrueDBList80.Columns

Set Cols = TDBList1.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 list (recall that collections are zero-based):

With TDBList1.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 TrueDBList80.Column

' Reference by numeric index

Set Col0 = TDBList1.Columns.Item(0)

' Reference by numeric index (Item method is implicit)

Set Col0 = TDBList1.Columns(0)

' Reference by database field name

Set Col0 = TDBList1.Columns("LAST")

' Reference by column header text (Caption property)

Set Col0 = TDBList1.Columns("Last Name")

A True DBList Style object can also be referenced by name:

' Declare S as a Style object

Dim S As TrueDBList80.Style

' Set S to the list's built-in Normal style

Set S = TDBList1.Styles("Normal")

' Set S to the programmer-defined style MyStyle

Set S = TDBList1.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 list by adding new Split objects to the Splits collection:

' Create a Split object with index 0

Dim S As TrueDBList80.Split

Set S = TDBList1.Splits.Add(0)

This code adds a Split object with index 0 to the Splits collection of TDBList1. 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 TrueDBList80.Split

Set S = TDBList1.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 DBList, 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 TDBList control:

TDBList1.SelBookmarks.Add TDBList1.Bookmark

Since the SelBookmarks collection manages a list of variants corresponding to selected list rows, its Add method does not return a value, and no assignment statement is needed. This example could also be coded as:

With TDBList1

.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

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

variable = TDBList1.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 list:

For n = 0 To TDBList1.Columns.Count - 1

Debug.Print TDBList1.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 = TDBList1.Columns.Count

' Append a column to the end of the Columns collection

Dim C As TrueDBList80.Column

Set C = TDBList1.Columns.Add(NumCols)

' Make the new column visible, since columns created

' at run time are invisible by default

TDBList1.Columns(NumCols).Visible = True

' The following loop removes all columns from the list

While TDBList1.Columns.Count

TDBList1.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 TrueDBList80.Column

For Each C In TDBList1.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 DBList at design time using its context menu, visual editing mode, property pages, and reusable layout facility. These features enable you to see the list'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 DBList's design-time environment to configure the TDBList control. Most of the following material also applies to the TDBCombo control since it is a subset of TDBList. Specific differences between the two controls are discussed at the end of this chapter.

Context Menu

Visual Editing Mode

Property Page Overview

True DBList Property Pages

Reusable Layouts


Context Menu

Right-click anywhere on the list to display the True DBList 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 DBList. 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 list from the Visual Basic form to the Clipboard. Copy (Ctrl+C) moves a copy of the list to the Clipboard while leaving the list on the form intact. Paste (Ctrl+V) copies the list from the Clipboard to the form. Delete (the Del key) removes the list 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 list relative to the other objects on the Visual Basic form. Bring To Front (Ctrl+J) places the list 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 list's code window, which enables you to view and edit the list's event handling code.

Align to List

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

Edit

This command switches to True DBList's visual editing mode, in which you can interactively change the list's column layout and row height. Within visual editing mode, you can right-click anywhere on the list 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 list. 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 list's property pages, which enable you to customize the layout and appearance of the list 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 list's columns according to the schema information obtained from the Data control's Recordset (Data control). If you have already changed the list's default layout, True DBList will ask for confirmation before discarding your changes. By default, the list 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 list, a horizontal scroll bar will appear. The scroll bar is usable only when the list is in visual editing mode as described in the next section.

NOTE: The retrieved fields are taken from the Data control specified in the RowSource property, not DataSource. The latter is used for update operations, not for populating the list.

Clear Fields

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


Visual Editing Mode

To enter True DBList's visual editing mode, right-click anywhere on the list to display the context menu, then click Edit. The appearance of the list 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.

For TDBCombo controls with ComboStyle set to 0 - Dropdown Combo or 2 - Dropdown List, the list portion of the control will drop down upon entering visual editing mode, and will close upon exiting this mode.

To exit visual editing mode, select another control or click anywhere on the form outside the list. The next time you right-click the list, 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 list.

•

Move columns to and from the Clipboard.

•

Adjust the list's row height.

•

Save the current list layout to a file.

•

Load and remove list 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 list rows, move the pointer over a row divider at the left edge of the list. 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 list 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 list'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 list is in visual editing mode, right-click anywhere on the list to display the visual editing menu. The visual editing menu contains several commands that are also present in the list's context menu. However, while the context menu operates on the list as a whole, the visual editing menu is used to manipulate the list'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 list'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 list. Using the Cut, Copy, and Paste commands, you can move columns to the Clipboard and paste them to another list, or within the same list. The ability to copy columns to the Clipboard provides an easy way to set up list 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 list on another form.

Cut moves the selected columns from the list to the Clipboard. Copy moves a copy of the selected columns to the Clipboard while leaving the list 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 list.

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 list's property pages, which enable you to customize the list's layout and appearance.

Retrieve Fields

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

NOTE: The retrieved fields are taken from the Data control specified in the RowSource property, not DataSource. The latter is used for update operations, not for populating the list.

Clear Fields

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

Load Layout

This command loads the list 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 list, 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 list 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 list 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 DBList Pro utilizes a 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 TDBList or TDBCombo, 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 list 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 AlternatingRowStyle, 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 list'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 list 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 list 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 subobjects with their own set of editable properties. To expand a subobject 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 list 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 list 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 list 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 list'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 DBList supports a rich object model that reflects the organization of its visual components. Therefore, in order to customize a list'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 list contains a single split comprising all of its columns.


Splits in property trees

In the list'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 list as a whole.

Conversely, the term global is used to describe properties that apply to the list 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 list. 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 list'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 Caption.

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 True DBList 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 list 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 list 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 list 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 list 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 list 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 list 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 list immediately.


True DBList Property Pages

The TDBList and TDBCombo controls 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 and Splits pages, as it provides access to control properties in addition to those of the Columns and Splits collections.

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. Only column properties that are global to all splits appear on this page.

Splits

This page contains the properties of the control'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 control and its constituent objects.

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 check boxes and radio buttons.

The TDBList control also includes the following property page:

Print Info

This page manages a collection of PrintInfo objects, which encapsulate page setup and print job settings.

General property page (TDBList)

General property page (TDBCombo)

Columns property page

Splits property page

Style Factory property page

Values property page

Print Info property page


General property page (TDBList)

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


General properties by alphabet

The following TDBList control properties are available on the General property page:

AddItemSeparator

Determines the separator string for columns

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

BackColor

Sets/returns the background color

BorderStyle

Sets/returns style for control border

BoundColumn

Name of the RowSource field used to update DataField

BoundText

Text value of the BoundColumn field

Caption

Sets/returns caption for an object

CaptionStyle

Controls the caption style for an object

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

ColumnFooters

Turns column footings on or off

ColumnHeaders

Turns column headings on or off

Columns

Contains a collection of list columns

DataMode

Specifies bound or unbound mode

DefColWidth

Specifies column width for auto-created columns

EmptyRows

Enables empty rows in an underpopulated control

Enabled

Enables or disables user interaction

EvenRowStyle

Controls the row style for even-numbered rows

ExposeCellMode

Controls behavior of clicked rightmost visible cell

FetchRowStyle

Controls whether the FetchRowStyle event will be fired

Font

Specifies the overall font for a control

FooterStyle

Controls the footing style for an object

FootLines

Number of lines allocated for footing text

ForeColor

Sets/returns the foreground color

HeadingStyle

Controls the heading style for a control

HeadLines

Number of lines allocated for heading text

HighlightRowStyle

Controls the style of the current row

IntegralHeight

Sets/returns a value that indicates the display of partial rows

LayoutFileName

Sets/returns the name of a file containing list layouts

LayoutName

Sets/returns the name of the current list layout

LayoutURL

Sets/returns the URL used for downloading list layouts

ListField

Sets/returns the RowSource field used for incremental search

MatchCol

Sets the search column when the MatchEntry property is not 0

MatchCompare

Sets/returns the comparing mode for search

MatchEntry

Sets/returns the type of incremental search

MatchEntryTimeout

Sets/returns the incremental search timeout value

MouseIcon

Sets/returns a custom mouse icon

MousePointer

Sets/returns the mouse pointer type

MultipleLines

Controls whether individual records span multiple lines

MultiSelect

Controls whether users can select multiple rows

OddRowStyle

Controls the row style for odd-numbered rows

PrintInfos

Contains a collection of printer information objects

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

RowSubDividerColor

Controls the row subdivider color

ScrollTips

Determines whether the list displays a pop-up window

ScrollTrack

Controls whether the scrollbar thumb causes the control’s display to update with new data

SelectedStyle

Controls the selected row and column style for an object

Splits

Contains a collection list splits

Style

Controls the normal style for a control


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

BorderAppearance

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

BorderColor

Specifies the color for the border

BorderSize

Specifies the size of cell border

BorderStyle

Sets/returns style for list border

Caption

Sets/returns list 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 list

FootLines

Number of lines allocated for footing text

HeadLines

Number of lines allocated for heading text

IntegralHeight

Sets/returns a value that indicates the display of partial rows

MultipleLines

Controls whether individual records span multiple lines

RowDividerColor

Controls the row divider color

RowDividerStyle

Selects style of row divider lines

RowHeight

Specifies height of all list rows

RowSubDividerColor

Controls the row subdivider color

Behavior properties

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

Enabled

Enables or disables user interaction

ExposeCellMode

Controls behavior of clicked rightmost visible cell

FetchRowStyle

Controls whether the FetchRowStyle event will be fired

ListField

Sets/returns the RowSource field used for incremental search

MatchCompare

Sets/returns the comparing mode for search

MatchEntry

Sets/returns the type of incremental search

MatchEntryTimeout

Sets/returns the incremental search timeout value

MouseIcon

Sets/returns a custom mouse icon

MousePointer

Sets/returns the mouse pointer type

MultiSelect

Sets/returns the type of selection allowed in the list

PrintInfos

Contains a collection of printer information objects

RightToLeft

When True, applies right to left text functionality

ScrollTips

Determines whether the list displays a pop-up window

ScrollTrack

Controls whether the scrollbar thumb causes the control’s display to update with new data

Color properties

BackColor

Sets/returns the background color

ForeColor

Sets/returns the foreground color

Data properties

BoundColumn

Name of the RowSource field used to update DataField

BoundText

Text value of the BoundColumn field

DataMember

Sets/returns a data member offered by an OLE DB provider

DataMode

Specifies bound or unbound mode

MatchCol

Sets the search column when the MatchEntry property is not 0

Font properties

Font

Specifies the overall font for a list

Layout properties

LayoutFileName

Sets/returns the name of a file containing list layouts

LayoutName

Sets/returns the name of the current list layout

LayoutURL

Sets/returns the URL used for downloading list layouts

Style properties

CaptionStyle

Controls the caption style for a list

EvenRowStyle

Controls the row style for even-numbered rows

FooterStyle

Controls the footing style for a list

HeadingStyle

Controls the heading style for a list

HighlightRowStyle

Controls the style of the current row

InactiveStyle

Controls the inactive heading style for a list

OddRowStyle

Controls the row style for odd-numbered rows

SelectedStyle

Controls the selected row and column style for a list

Style

Controls the normal style for a list


General property page (TDBCombo)

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 TDBCombo object). You can also use this page to specify a layout file containing one or more named layouts.


General properties by alphabet (TDBCombo)

The following TDBCombo control properties are available on the General property page:

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

AutoCompletion

True if the combo's text box auto fills with the matched entry

AutoDropdown

True if typing a character automatically opens the combo's list

AutoSize

When True, the height of the edit box is set to the font height

BackColor

Sets/returns the background color

BorderStyle

Sets/returns style for control border

BoundColumn

Name of the RowSource field used to update DataField

BoundText

Text value of the BoundColumn field

Caption

Sets/returns caption for an object

CaptionStyle

Controls the caption style for an object

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

ColumnFooters

Turns column footers on or off

ColumnHeaders

Turns column headings on or off

Columns

Contains a collection of TrueDBList columns

ComboStyle

Sets/returns the display type of a combo box

DataMode

Specifies bound or unbound mode

DefColWidth

Specifies column width for auto-created columns

DropdownPosition

Sets/returns the position of the drop-down portion of the control

DropdownWidth

Sets/returns the width of the drop-down portion of the control

EditBackColor

Sets/returns the background color of the text box portion

EditFont

Specifies the font used for the text box portion

EditForeColor

Sets/returns the foreground color of the text box portion

EditHeight

Sets/returns the height for the edit portion of the combo box

EmptyRows

Enables empty rows in an underpopulated control

Enabled

Enables or disables user interaction

EvenRowStyle

Controls the row style for even-numbered rows

ExtendRightColumn

Returns current split extend column setting, sets all splits

FetchRowStyle

Controls whether the FetchRowStyle event will be fired

Font

Specifies the overall font for a control

FooterStyle

Controls the footing style for an object

FootLines

Number of lines allocated for footing text

ForeColor

Sets/returns the foreground color

GapHeight

Sets/returns the distance between the edit portion and the dropdown portion of the combo box

HeadingStyle

Controls the heading style for a control

HeadLines

Number of lines allocated for heading text

HighlightRowStyle

Controls the style of the current row

IntegralHeight

Sets/returns a value that indicates the display of partial rows

LayoutFileName

Sets/returns the name of a file containing list layouts

LayoutName

Sets/returns the name of the current list layout

LimitToList

True if the NotInList event is fired when an item is not found

ListField

Sets/returns the RowSource field used for incremental search

MatchEntryTimeout

Sets/returns the incremental search timeout value

MaxComboItems

Sets the number of items to display in the dropdown portion of the combo box

MouseIcon

Sets/returns a custom mouse icon

MousePointer

Sets/returns the mouse pointer type

MultipleLines

Controls whether individual records span multiple lines

OddRowStyle

Controls the row style for odd-numbered rows

OLEDragMode

Sets/returns OLE Drag Source action

OLEDropMode

Sets/returns OLE Drop Target action

PartialRightColumn

True if rightmost column can be clipped to edge of split

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

RowSubDividerColor

Controls the row subdivider color

RowTracking

True if rows are highlighted as the mouse moves over them

ScrollTips

Determines whether the list displays a pop-up window

ScrollTrack

Controls whether the scrollbar thumb causes the control’s display to update with new data

Splits

Contains a collection of TrueDBList splits

Style

Controls the normal style for a control


General properties by category (TDBCombo)

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

BorderStyle

Sets/returns style for drop-down border

Caption

Sets/returns caption for an object

ColumnFooters

Turns column footings on or off

ColumnHeaders

Turns column headings on or off

DefColWidth

Specifies column width for auto-created columns

EditHeight

Sets/returns the height for the edit portion of the combo box

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

GapHeight

Sets/returns the distance between the edit portion and the dropdown portion of the combo box

HeadLines

Number of lines allocated for heading text

IntegralHeight

Controls whether partial rows are displayed

MaxComboItems

Sets the number of items to display in the dropdown portion of the combo box

PartialRightColumn

True if rightmost column can be clipped to edge of split

RowDividerColor

Controls the row divider color

RowDividerStyle

Selects style of row divider lines

RowHeight

Specifies height of all drop-down rows

RowSubDividerColor

Controls the row subdivider color

Behavior properties

AutoCompletion

True if the combo's text box auto fills with the matched entry

AutoDropdown

True if typing a character automatically opens the combo's list

AutoSize

When True, the height of the edit box is set to the font height

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

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

ListField

Sets/returns the RowSource field used for incremental search

MatchEntryTimeout

Sets/returns the incremental search timeout value

MouseIcon

Sets/returns a custom mouse icon

MousePointer

Sets/returns the mouse pointer type

OLEDragMode

Sets/returns OLE Drag Source action

OLEDropMode

Sets/returns OLE Drop Target action

PartialRightColumn

True if rightmost column can be clipped to edge of split

RightToLeft

When True, applies right to left text functionality

RowTracking

True if rows are highlighted as the mouse moves over them

ScrollBars

Sets/returns scroll bar style for the drop-down

ScrollTips

Determines whether the list displays a pop-up window

ScrollTrack

Controls whether the scrollbar thumb causes the control’s display to update with new data

Color properties

BackColor

Sets/returns the background color

EditBackColor

Sets/returns the background color of the text box portion

EditForeColor

Sets/returns the foreground color of the text box portion

ForeColor

Sets/returns the foreground color

Data properties

BoundColumn

Name of the RowSource field used to update DataField

BoundText

Text value of the BoundColumn field

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

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

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 style of the current row

OddRowStyle

Controls the row style for odd-numbered rows

Style

Controls the normal style for a drop-down


Columns property page

The splits of a TDBList or TDBCombo control 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 control:

Caption

Sets/returns column heading text

DataField

Data table field name for a column

FooterText

Column footing text

NumberFormat

Data formatting string for a column


Column properties by category

Appearance properties

Caption

Sets/returns column heading text

FooterText

Column footing text

Data properties

DataField

Data table field name for a column

NumberFormat

Data formatting string for a column


Splits property page

The Splits property page defines the appearance and behavior of the splits in a TDBList or TDBCombo control. The control has one split by default, so even if you do not create a control with multiple splits, you may still need to set properties on this page in order to configure the control'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 TDBList and TDBCombo controls:

AllowColMove

Enables interactive column movement

AllowColSelect

Enables interactive column 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

Caption

Sets/returns split caption text

CaptionStyle

Controls the caption style for a split

Columns

Returns a collection of column objects for a split

DividerStyle

Divider style for right split border

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

FooterStyle

Controls the footing style for a split

HeadingStyle

Controls the heading style for a split

HighlightRowStyle

Controls the style of the current row

InactiveStyle

Controls the inactive heading 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

ScrollBars

Sets/returns scroll bar style for a split

ScrollGroup

Used to synchronize vertical scrolling between splits

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

Style

Controls the normal style for an object


Split properties by category

Appearance properties

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

PartialRightColumn

True if rightmost column can be clipped to edge of split

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

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

PartialRightColumn

True if rightmost column can be clipped to edge of split

ScrollBars

Sets/returns scroll bar style for a split

ScrollGroup

Used to synchronize vertical scrolling between splits

Style properties

AlternatingRowStyle

Controls whether even/odd row styles are applied to a split

CaptionStyle

Controls the caption 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 style of the current 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 TDBList and TDBCombo controls. To access individual columns, expand the Columns property node.

Alignment

Specifies horizontal text alignment

AllowSizing

Enables interactive resizing for a column

ButtonFooter

Controls whether a column footer acts like a standard button

ButtonHeader

Controls whether a column header acts like a standard button

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

FooterStyle

Controls the footing style for a column

HeadAlignment

Specifies column heading alignment

HeaderDivider

Controls display of dividing line in column header

HeadingStyle

Controls the heading style 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


Split-specific Column properties by category

Appearance properties

Alignment

Specifies horizontal text alignment

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

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

Behavior properties

AllowSizing

Enables interactive resizing for a column

ButtonFooter

Controls whether a column footer acts like a standard button

ButtonHeader

Controls whether a column header acts like a standard button

Style properties

FooterStyle

Controls the footing 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 TDBList or TDBCombo control and its constituent objects. By default, each control contains eight built-in styles: Normal, Heading, Footing, Selected, Caption, HighlightRow, EvenRow, and OddRow.


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 list 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 TDBList and TDBCombo 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

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

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

BorderColor

Specifies the color for the border

BorderSize

Specifies the size of cell border

BorderType

Controls which, if any, cell borders are displayed

VerticalAlignment

Specifies vertical text alignment

WrapText

Word wraps cell text when true

Behavior properties

Parent

Sets/returns the object from which a style inherits

Color properties

BackColor

Controls the background color

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


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

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

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 list. 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 TDBList control:

AnnotatePicture

True to show both underlying data and display value graphics

Presentation

Specifies how value items are displayed

Translate

True to translate data values to display values


ValueItem properties

The following ValueItem object properties are available on the Values property page of the TDBList control:

DisplayValue

Sets/returns displayed text or graphics

Value

Sets/returns untranslated data value


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 TDBList 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 list automatically creates a new one named DefaultPrintInfo.


PrintInfo properties

The following PrintInfo object properties are available on the Print Info property page of the TDBList 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

Name of the PrintInfo object

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

PageHeader

Sets/returns the page header for a PrintInfo object

PageHeaderFont

Sets/returns the page header font for a PrintInfo object

PreviewCaption

Sets/returns the print preview window caption

PreviewMaximize

Sets/returns whether print preview window is initially maximized

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

RepeatListHeader

Sets/returns whether the list caption 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


Reusable Layouts

True DBList provides a reusable layout facility that enables you to store one or more list layouts in a binary file, then recall them as needed at design time or run time. With this feature, you can:

•

Create repositories of list layouts that you can reuse in future projects.

•

Reduce the number of lists on a form by associating multiple layouts with a single list 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 list 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 TDBList or TDBCombo 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 list 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 list layout to a file at design time, do the following:

1.

Configure the list 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 list 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 list 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.


Run Time Interaction

This chapter describes how users of your application interact with True DBList at run time. You can give your users the ability to perform any or all of the following:

•

Navigate within the list using the mouse or keyboard.

•

Search for list items by first letter or incremental match.

•

Select rows or columns.

•

Configure the list's layout.

In the following sections, the properties and events associated with a particular user action are noted where applicable.

Navigation and Scrolling

Searching and Field Completion

Selection and Movement

Sizing and Splitting

Drag-and-Drop Behavior

Additional User Interaction Features


Navigation and Scrolling

The following sections describe the list'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

Row tracking (TDBCombo only)

Clicking the rightmost column

IntelliMouse support

Keyboard navigation


Mouse navigation

When the user clicks a row, that row becomes current, and the RowChange event is fired.

The user can also use the mouse to manipulate the list's scroll bars, bringing cells that lie outside the list'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.


Row tracking (TDBCombo only)

If the RowTracking property is set to True, rows are automatically highlighted as the mouse is moved over the drop-down portion of a TDBCombo control.

When RowTracking is True and the user highlights a different row by moving the mouse, the ItemChange event will not fire.


Clicking the rightmost column

The list 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 list'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 list will scroll to the left to display this column in its entirety. This may be less desirable for users who commonly click on the list to begin editing, as the list 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 list will not scroll when the rightmost visible column is clicked. However, if the user attempts to edit the cell, then the list 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 list 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 list 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 list's Col property) or by keyboard navigation, then the list will always scroll to make it totally visible.


IntelliMouse support

True DBList responds to Microsoft IntelliMouse activity as follows:

•

If the user turns the wheel, the list scrolls vertically by one row for each click of the wheel.

•

If the user holds down the Shift key while turning the wheel, the list 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 list 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 list 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 list scrolls by one page.


Keyboard navigation

By default, the user can navigate the list with the arrow keys, 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

These keys move the list in the horizontal direction.

Tab

The Tab key moves focus to the next control on the form, as determined by the tab order.

PgUp, PgDn

These keys scroll the list 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 list'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 list 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.


Searching and Field Completion

The following sections describe how the TDBList and TDBCombo controls locate list items in response to keyboard input.

Searching in TDBList

Searching in TDBCombo

Field completion (TDBCombo only)

Search Mismatch (TDBCombo only)


Searching in TDBList

The MatchEntry property determines how a TDBList control performs searches based on user input.

When set to 0 - None (the default), the control does not perform any incremental searches.

When set to 1 - Standard, the search argument is limited to one character, and the control attempts to find a match for the character entered using the first letter of entries in the list. Repeatedly typing the same letter cycles through all of the entries in the list beginning with that letter.

When set to 2 - Extended, the control searches for an entry matching all characters entered. The search is performed incrementally as characters are typed. This behavior is almost identical to that of a TDBCombo control except that the search argument is cleared when a TDBList control gains focus, or when the user presses Backspace or hesitates for a few seconds. Use the MatchEntryTimeout property to specify the timeout value; the next characters entered by the user after hesitating for the specified time will begin a new search through the list.


Searching in TDBCombo

Incremental searching is always "on" for TDBCombo controls, which search for an entry matching all characters entered, and perform the search incrementally as characters are typed. This behavior is almost identical to that of a TDBList control with its MatchEntry property set to 2 - Extended except that the search argument is not cleared when the user presses Backspace or hesitates for a few seconds. If the ComboStyle property is set to 2 - Dropdown, you can use the MatchEntryTimeout property to specify the timeout value. After the user hesitates for the specified amount of time, the combo text entry box will clear and the next characters entered will begin a new search.


Field completion (TDBCombo only)

The AutoCompletion property controls whether matching incremental search values are automatically copied to the text portion of a combo during editing.

If True, when the user enters one or more characters that match a value in the combo's 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), automatic completion does not occur, and the text portion of the control contains only the characters entered by the user.


Search Mismatch (TDBCombo only)

The Mismatch event is triggered whenever the user enters a value in the text portion of a combo box that is not found in the list portion. By default, Reposition is 0 - True, which resets the current row back to the top of the list portion when the event is fired.

If you set Reposition to 1 - False, and the combo cannot locate NewEntry, the current row remains unchanged when this event is fired.

NOTE: This event is only fired when the LimitToList property is True and the ComboStyle property is set to 0- Dropdown Combo or 1- Simple Combo .


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 list'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 small box at its lower right corner, and the divider at the left edge of the column being pointed to will be enlarged and highlighted.

The user specifies the desired location of the selected columns by dragging the enlarged divider, 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 divider. The moved columns remain selected.

If the user drags the divider 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 (TDBList only)

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 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 first row in the range, then holding down the Shift key and clicking 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.

If MultiSelect is set to 0 - None, multiple selection is disabled but single selection is permitted. When the user clicks an unselected row, 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.

Regardless of the value of MultiSelect, the user can deselect all rows by clicking a data cell or selecting columns. In code, setting the BoundText property to an empty string also deselects all rows.

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 list'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 places the mouse pointer over a row divider at the left edge of the list, 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 list will be resized to the same height; it is not possible to resize individual rows.

The RowHeight property of the list 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 list 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 list 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 list'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.

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 list, the user can also create a new split. For details, see Creating and sizing splits.


Drag-and-Drop Behavior

Typically, implementing a drag-and-drop interface using a list 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 DBList 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.

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 TDBList1_DragCell(ByVal SplitIndex As Integer, _

RowBookmark As Variant, ByVal ColIndex As Integer)

' Set the current cell to the one being dragged

TDBList1.Col = ColIndex

TDBList1.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 TDBList1 into drag mode)

TDBList1.Drag vbBeginDrag

End Sub

Note that the Col and Bookmark properties of the list 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 DBList 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 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 list 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 lists is that, given the mouse location, it is difficult to find out which cell, row, or column you are about to drop into. True DBList solves this problem by providing the SplitContaining, ColContaining, and RowContaining methods, which translate mouse coordinates into a list 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.

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 event, which fires as the mouse moves over the destination list. Here's how you would set the current cell pointer so that it tracks the dragging object:

Private Sub TDBList2_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 = TDBList2.ColContaining(X)

overRow = TDBList2.RowContaining(Y)

If overCol >= 0 Then TDBList2.Col = overCol

If overRow >= 0 Then TDBList2.Row = overRow

End Sub

When the drop occurs (detected in the DragDrop event), you can move the appropriate data into the destination list, 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 list:

Private Sub TDBList2_DragDrop(Source As Control, _

X As Single, Y As Single)

TDBList2.Columns(TDBList2.Col).Value = _

TDBList1.Columns(TDBList1.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.

True DBList also supports OLE drag-and-drop.


Additional User Interaction Features

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

Scroll Tracking and ScrollTips

Outlook-Style Grouping


Bound Mode

The easiest way to use True DBList 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 DBList 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), or ComponentOne's True DBWizard.

To use bound mode, set the DataMode property of the list to 0 - Bound at design time, then set the RowSource property of the list 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 DBList 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.

NOTE: Unlike other bound controls such as DBGrid, the primary data source for a TDBList or TDBCombo control is specified by the RowSource property, not DataSource. The latter is used for update operations, not for populating the list portion of the control.

Binding True DBList Pro Controls to a Data Source

Visual Basic Data Control Considerations

Remote Data Control (RDC) Considerations

Unbound Columns


Binding True DBList Pro Controls to a Data Source

True DBList includes two separate list 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 list depending upon the type of data source used, as the following table illustrates.

These two controls are functionally equivalent; they differ only in how they access data.


Binding to an ICursor data source

To associate a True DBList control (TDBL8.OCX) with a Visual Basic Data control, set the RowSource property of the list to the name of a Data control on the same form. This is all that is required to make True DBList fully aware of the database in your application.

Once such a link exists, True DBList and the Data control automatically notify and respond to all operations performed by the other, simplifying your application development:

•

Once the list 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 list. For more information, see Design Time Interaction.

•

When you run your application, True DBList 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. However, the list is read-only.

True DBList will automatically update its display to reflect any changes made to the Data control. However, True DBList 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. Use this property to update source data.


Binding to an OLE DB data source

To associate a True DBList control (TODL7.OCX) with an OLE DB data source, set the RowSource property of the list to the name of an available data source, then 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 (TDBL8.OCX), the OLE DB version of True DBList supports assignment to the RowSource property at run time. The following code sample demonstrates how to bind the list to a Data Environment command:

With TDBList1

Set .RowSource = DataEnvironment1

.DataMember = "Command1"

End With


Visual Basic Data Control Considerations

This section gives an overview of how True DBList interacts with the built-in Data control of Visual Basic. Generally speaking, True DBList 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 DBList reacts to Recordset changes

Interactions between True DBList and the Data control

Using True DBList with a Data control on a different form

Using True DBList to display SQL query results


How True DBList reacts to Recordset changes

When you bind a list to a Data control, you are actually linking the list 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.

NOTE: As of Visual Basic 4.0, the Data control does not support the outdated Dynaset object. You can create either a Table, Snapshot, or Dynaset-type Recordset using the Data control's RecordsetType property. By default, the Data control creates a Dynaset-type Recordset that is completely compatible with the Dynaset object, so you should not have to modify any existing code. Consult the Visual Basic Help for more information.

Here is how the list responds to various operations performed on the Recordset associated with the Data control:

Positioning

The list's current row will change in response to a successful invocation of any of the following Recordset methods: Seek, Move, MoveFirst, MoveLast, MoveNext, MovePrevious, FindFirst, FindLast, FindNext, and FindPrevious. If necessary, the list will scroll to make the current row visible. The list optimizes its response to these messages. For example, if your code performs a MoveFirst followed by 20 consecutive MoveNext calls, the list will position only once, to the 21st row. Consult the Visual Basic Help for more information on the Recordset object's methods.

Delete

True DBList reacts to the Recordset object's Delete method by removing the current row from the list display. However, the Delete method does not change the current record, therefore the Bookmark property of both the list and the Recordset still refers to the record that was just deleted. At this point, there is no current row in the list, and its Row property returns -1.

Requery

This method causes the list to refetch and redisplay all data. 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 list.


Interactions between True DBList and the Data control

If Recordset data has been edited, moving the record pointer using the Data control will automatically trigger an update to the database.

The list responds to the Data control's Refresh, UpdateRecord, and UpdateControls methods as follows:

Refresh

The list refetches and redisplays all data. 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 list.

UpdateControls

Any DataField modifications that have not been updated to the database will be discarded and data will be refreshed from the database. The current cell and the list display are not changed. This method can be used to cancel an AddNew or Edit operation.


Using True DBList with a Data control on a different form

Using the Data control's Recordset property, you can effectively bind True DBList or any other bound control on one form to a Data control on another form. Strictly speaking, you cannot directly bind a list to a Data control on another form. For example, assume you have a list 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 list 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 list on Form2 will work as if it were directly bound to Form1.Data1. When you move or update records through Form1.Data1, the list on Form2 will respond accordingly. Conversely, if you move or update records in the list, all controls on Form1 that are bound to Form1.Data1 will respond.


Using True DBList to display SQL query results

True DBList 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 list 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 list what to do. You can create very powerful user interfaces using these automatic features of the list. Tutorial 5 describes this feature in detail and also illustrates a few interesting and useful SQL statements.


Remote Data Control (RDC) Considerations

The Remote Data Control (RDC), which is used to connect to ODBC-compliant data sources, can also be used in True DBList's bound mode. Alternatively, you can work with the Remote Data Objects (RDO), and use the rdoResultset object to populate a True DBList control in one of the unbound modes.

ComponentOne provides several sample programs that demonstrate how to use RDC and RDO with True DBList. You can download these programs from the ComponentOne Web site at http://www.componentone.com/.


Unbound Columns

Normally, True DBList 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 list, but is not tied directly to a database field. A bound list has its DataMode property set to 0 - Bound, and its RowSource property set to a valid data source as described in Binding True DBList Pro Controls 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 list 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 list for these columns will not be cached by the list, 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


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

Dim Col As TrueDBList70.Column

With TDBList1

Set Col = .Columns.Add(1)

Col.Visible = True

Col.Caption = "Unbound"

.HoldFields

.ReBind

End With

When the list 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 list 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 TDBList1_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 list 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 list 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 list vertically or horizontally. To update the display, the list will need to fetch the new data that is scrolled into view for all rows and columns on the face of the list. However, changing the current row would cause an unwanted update to occur. For this reason, the list will not allow the current row of the list 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 TDBList1_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 list 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 TDBList1_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 TDBList1_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 TDBList1_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 TDBList1_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 list 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 TDBList1_UnboundColumnFetch(Bookmark As Variant, _

ByVal Col As Integer, Value As Variant)

Value = TDBList1.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 list), 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 list 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 list 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 TDBList1_UnboundColumnFetch(Bookmark As Variant, _

ByVal Col As Integer, Value As Variant)

ucfClone.Bookmark = Bookmark

Select Case TDBList1.Columns(Col).Caption

Case "Area"

' Calculate "Area" column of list

Value = ucfLength * ucfWidth

Case "Perimeter"

' Calculate "Perimeter" column of list

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.


Storage Mode

True DBList 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 an ComponentOne XArrayDB object as a data source. XArrayDB, which is included with True DBList Pro 8.0, is packaged as a separate file, XARRAYDB.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 list 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 list. The data will then be maintained and exchanged between the list 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 DBList. 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 list'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.

Storage mode is only used for populating a control with data. If you are using True DBList to update another data source, you must set the DataSource property to the name of a bound data control at design time.

NOTE: Version 5.0 introduced the XArray object (without the DB), which supports up to ten dimensions but does not provide any methods for searching and sorting. For backward compatibility, version 6.0 and newer also supports the XArray object in storage mode. However, XArrayDB is preferred, since it is optimized for the two-dimensional case and supports sorting and searching.

When to Use Storage Mode

Using the XArrayDB Object

Interactions between True DBList 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 DBList to a mature application that already manages intrinsic Visual Basic arrays, application mode is recommended, since you can easily wrap the ClassicRead event 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 DBList, 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 TDBList or TDBCombo control via the list'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 lists 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 DBList 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 (XARRAYDB.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 TDBList or TDBCombo control, its first dimension always specifies the row index from the list'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 list's perspective. Or, to put it another way, the list 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 list 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 DBList Control

Since XArrayDB objects can only exist at run time, you must write code to associate them with a TDBList or TDBCombo control. This is done by setting the Array property:

TDBList1.Array = MyArray

Once this association is made, the list 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 list also determines the number of rows (the first dimension) in an XArrayDB object and calibrates the vertical scroll bar accordingly.

However, the list 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 list, then create a new one for each XArrayDB column:

Dim C As TrueDBList80.Column

With TDBList1.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 DBList and XArrayDB

If you insert or delete XArrayDB rows or columns directly in code, or even change the value of a single element, the list does not receive any notifications from the XArrayDB. Therefore, you must either Refresh or ReBind the list 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 list's ReBind 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 list's Refresh method.


Updating XArrayDB Elements

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 list, 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 list row, then sets focus to the list:

Private Sub Command1_Click()

Dim row As Long, col As Integer

With TDBList1

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 list 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 list'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 list requests data for the current row.


Inserting and Removing XArrayDB Rows

When inserting or deleting rows, you must ReBind the list afterwards, since it does not receive any notifications from the XArrayDB object. Note that a list 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 list row, then sets focus to the list:

Private Sub Command1_Click()

With TDBList1

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

NOTE: For backward compatibility, the Insert and Delete methods of the original XArray object were retained in XArrayDB.


Inserting and Removing XArrayDB Columns

When you insert or delete XArrayDB columns, the list 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 TrueDBList80.Column

With TDBList1

MyArray.InsertColumns .Col

Set C = .Columns.Add(.Col)

C.Visible = True

.ReBind

.SetFocus

End With

End Sub

Note the use of the list'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 DBList in storage mode (DataMode 4) using an XArrayDB object as the data source, see Tutorial 16 or examine the UNBOUND4.VBP sample, which can be found in the TUTORIAL\UNBOUND4 subdirectory of the True DBList installation directory. Tutorial 17 demonstrates the searching and sorting features of XArrayDB.


Application Mode

True DBList 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 list 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 list to 3 - Application at design time. In code, write handlers for the ClassicRead and UnboundGetRelativeBookmark events.

Application mode was modeled after the Fetch and Update events of ComponentOne's TrueGrid Pro (VBX) product. However, unlike TrueGrid Pro, which identifies rows with absolute row numbers, True DBList identifies rows with bookmarks. This subtle change provides uniformity across data access modes, and ensures that all of the list'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.

Application mode is only used for populating a control with data. If you are using True DBList to update another data source, you must set the DataSource property to the name of a bound data control at design time.

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 list, 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 DBList 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 callback event 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 DBList runs in application mode, it is not connected to a data control. Instead, your application must supply and maintain the data, while the list handles all user interaction and data display. For example, when a user covers the list with another window, then uncovers it later, the list is completely responsible for repainting the exposed area. Your application does not need to deal with any low-level display operations.

With the list in control of low-level display, you need to concentrate solely on maintaining your data. The list 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 list 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 DBList 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 list 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 list 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 list will ask for data, nor can you assume that data will be requested in any particular order. Furthermore, since the list 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 DBList translates user interactions into events that enable you to keep your data source synchronized.

Conversely, if your application code manipulates the data source directly, you need to tell the list to update its display by using either the Refresh or ReBind method.

To summarize, True DBList's application mode is a useful tool for dealing with dynamic data. Since it has no inherent storage capability, the list 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 list 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 list, you must deal similarly with the bookmarks. The bookmarks themselves must be supplied by your code in the UnboundGetRelativeBookmark and ClassicRead 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 list 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 list 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 DBList'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 list as variant bookmarks.

Since True DBList 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 DBList

True DBList treats bookmarks as packets of binary information that cannot be interpreted. To the list, 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 list 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 list 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 list (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 two 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.


Handling the UnboundGetRelativeBookmark event in mode 3

You must always provide a handler for the UnboundGetRelativeBookmark event in application mode. True DBList 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 TDBList1_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 list 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 list 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 list 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 list 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 list

' 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 list 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 list passes a known bookmark and a column index to the ClassicRead event, which has the following syntax:

Private Sub TDBList1_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 list will display an empty cell. Note that Value need not contain a string. It can also hold numeric, boolean, or date data, and the list will convert it to a string automatically, just as it does with such data types in bound mode.


Application Mode Programming Considerations


Refreshing the Display in Mode 3

You can refresh the display with the list's Refresh and ReBind methods, which work in the same manner as documented for bound mode. When these methods are called, the list will discard its current display and call the ClassicRead event to retrieve new data.

Please note that during a ReBind operation, the list 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 list to a valid record afterwards. Or, you can avoid potential problems by reinitializing the list before performing the ReBind.


Reinitializing the List in Mode 3

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

TDBList1.Bookmark = Null

TDBList1.ReBind


Application Mode Example

For an example of how to use True DBList in application mode (DataMode 3) using a Visual Basic array as the data source, see Tutorial 15 or examine the TUTOR15.VPJ sample, which can be found in the TUTORIAL\TUTOR15subdirectory of the True DBList installation directory.


Unbound Mode

True DBList 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 list 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 list and your data source.

There are actually two row-based unbound modes: DataMode 1 - Unbound, is the original unbound mode of DBList; 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 DBList.

To use the newer row-based unbound mode, set the DataMode property of the list to 2 - Unbound Extended at design time. In code, write a handler for the UnboundReadDataEx event. 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 list'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.

Unbound mode is only used for populating a control with data. If you are using True DBList to update another data source, you must set the DataSource property to the name of a bound data control at design time.

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 list. 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 list 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 you are familiar with the Fetch and callback event of True 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 DBList runs in unbound mode, it is not connected to a data control. Instead, your application must supply and maintain the data, while the list handles all user interaction and data display. For example, when a user covers the list with another window, then uncovers it later, the list is completely responsible for repainting the exposed area. Your application does not need to deal with any low-level display operations.

With the list in control of low-level display, you need to concentrate solely on maintaining your data. In DataMode 1 - Unbound, the list 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 list 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 list fires the UnboundReadDataEx event, which combines the functionality of UnboundReadData and UnboundGetRelativeBookmark. When the list 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 list fires UnboundReadDataEx again, this time to fetch the actual data in a block of ten rows. This process continues until the list has enough data to fill its display or your event handler informs the list that the end of the dataset has been reached. As the user scrolls through the list, the UnboundReadDataEx event is fired as needed to obtain bookmarks and data.

In this respect, programming True DBList 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 list 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 should be written so that it performs as little work as possible.

The list 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 list will ask for data, nor can you assume that data will be requested in any particular order. Furthermore, since the list 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 list 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 DBList translates user interactions into events that enable you to keep your data source synchronized. Conversely, if your application code manipulates the data source directly, the list will not know that the underlying data has changed, so you need to tell the list to update its display by using either the Refresh or ReBind method.

To summarize, True DBList'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 list 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 list, you must deal similarly with the bookmarks. The bookmarks themselves must be supplied by your code as variant data in the following events:

•

UnboundGetRelativeBookmark and UnboundReadData (for DataMode 1 - Unbound)

•

UnboundReadDataEx (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 list gives you a bookmark, asking for information about a particular row in your dataset, you should be able to locate the row the list is asking for quickly. An important concept to remember is that whatever you supply to the list as a bookmark for a particular row, that is how the list will refer to that row later on. Three common examples of what to use for bookmarks are:

1.

If you use the unbound list 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 list 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 DBList'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 list as variant bookmarks.

Since True DBList 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 list and your data source via the unbound list events. The RowBuffer object is passed into the unbound list 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 list 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 list 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 list 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 list 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.

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 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 DBList and earlier versions of True DBList. 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 list requires data for display. Its syntax is as follows:

Private Sub TDBList1_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 list 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 list 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 list specifies a StartLocation bookmark indicating the 46th row, the ReadPriorRows argument is False, and the row buffer's RowCount property is 10, then the list 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 list 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 list 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 list simply and directly. The list 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 list is asked to move to row 3 using a previously obtained bookmark. The following sequence demonstrates what might happen in this situation:

1.

The list receives a bookmark for row 3. Since the data for this row is not in the list's cache, the list 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 list 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 list 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 list

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

' the setting of a list 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 list will request data, or how many times it will request the same data. In short, it is the list'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 list.


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 list 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 list'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 TDBList1_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 list 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 TDBList1_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 list columns corresponding to the columns in RowBuf.

•

The ColumnIndex array contains the indexes of the list 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 list is requesting a bookmark or data. If RowCount is 1 and ColumnCount is 0, the list is asking for a bookmark only; if ColumnCount is nonzero, the list 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 list 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 list 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 list and the row buffer no longer match.

The list generally asks for data according to the number of columns and the order of the columns as displayed on the list. For example, if your data source has 20 columns, and the list 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 list 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 list fires UnboundReadDataEx again, this time to fetch the actual data in a block of ten rows. This process continues until the list has enough data to fill its display or your event handler informs the list that the end of the dataset has been reached.

For example, if the list 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 list 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 list determines that it has reached the end of your data and stops firing UnboundReadDataEx with a positive Offset.

When the user scrolls vertically, the list 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 list might fire UnboundReadDataEx with a StartLocation representing row 90 and Offset equal to -20. In this case, the list is effectively asking for a bookmark for row 70. Once the list 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 list 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 list to request the bookmark of a row that does not exist, such behavior is normal, for this is how the list determines the boundaries of your data source. Also, since the list is designed to work with multi-user data sources, it is very conservative about boundary conditions. As long as you respond to UnboundReadDataEx consistently and correctly, the list 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 list 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 list 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 list

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

' the setting of a list 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 list will request data, or how many times it will request the same data. In short, it is the list'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 list.


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 list 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 list is asking for 10 rows of data starting with row 95 (80 + 15). Thus, the list 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 list is asking for 10 rows of data. Since StartLocation is Null, and since Offset is negative, the list 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 list 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 list 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 list 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 list 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.


Unbound Mode Programming Considerations

Refreshing the display in mode 1

Refreshing the display in mode 2

Reinitializing the list in modes 1 and 2

Calibrating the vertical scroll bar in modes 1 and 2


Refreshing the display in mode 1

In the original DBList, the Refresh and ReBind methods behaved differently in bound and unbound modes. For backward compatibility, these differences were preserved in True DBList when the DataMode property is set to 1 - Unbound.

When a list Refresh occurs, the list 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 list. Any changed data will be lost.

When a list ReBind occurs, the list refetches data by firing the UnboundReadData event, but it maintains any changed data within the current row. When redisplaying data, the list attempts to preserve the same current cell and top row, if possible.


Refreshing the display in mode 2

In DataMode 2 - Unbound Extended, the list's Refresh and ReBind methods work in the same manner as documented for bound mode. When these methods are called, the list will discard its current display and call the UnboundReadDataEx event to retrieve new data.

Please note that during a ReBind operation, the list 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 list to a valid record afterwards. Or, you can avoid potential problems by reinitializing the list before performing the ReBind.


Reinitializing the list in modes 1 and 2

In DataMode 1 - Unbound, setting the list's Bookmark property to Null before calling the list's Refresh or ReBind method will cause the UnboundGetRelativeBookmark and UnboundReadData events to fire with a StartLocation of Null just as if the list were first being displayed:

TDBList1.Bookmark = Null

TDBList1.ReBind

Similarly, in DataMode 2 - Unbound Extended, setting the list's Bookmark property to Null before calling the list's Refresh or ReBind method will cause the UnboundReadDataEx event to fire with a StartLocation of Null just as if the list were first being displayed:


Calibrating the vertical scroll bar in modes 1 and 2

When the list 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 list, especially in unbound modes.

Since data is supplied and maintained by the application code, the list does not generally know the total number of rows in the data source. Also, when the list is instructed to position to a particular record, as in an assignment to its Bookmark property, the list 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 list 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 list's ApproxCount property:

TDBList1.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 DBList in unbound mode (DataMode 1) using a Visual Basic array as the data source, see Tutorial 13 or examine the TUTOR13.VBP sample, which can be found in the TUTORIAL\TUTOR13 subdirectory of the True DBList installation directory.

For an example of how to use True DBList in unbound extended mode (DataMode 2) using a Visual Basic array as the data source, see Tutorial 14 or examine the TUTOR14.VBP sample, which can be found in the TUTORIAL\TUTOR14 subdirectory of the True DBList installation directory.

ComponentOne provides additional sample programs that demonstrate how to use the unbound modes of True DBList. You can download these programs from the ComponentOne Web site at http://www.componentone.com/.


AddItem Mode

When in AddItem mode, True DBList allows you to populate the list control (TDBList or TDBCombo) manually by using the AddItem, RemoveItem and Clear methods. In this mode, your application determines what data is contained within the list control.

To use AddItem mode, set the DataMode property of the control to 5 – AddItem at design-time, then use the AddItem method to populate the control.

The AddItem method allows you to populate individual rows within the list. The following code adds the names and street addresses to the list control. Note: To display all data, you must add the necessary number of columns to your list control. For more information, see Adding and removing columns.

Private Sub Command1_Click()

With TDBList1

.AddItem "Smith;John;210 Elm St."

.AddItem "Doe;Jane;100 Oak St."

End With

End Sub

NOTE: The default AddItem separator is “;”.You can choose a custom separator by setting the AddItemSeparator property at design-time or from code.

The RemoveItem method allows you to remove rows from the list. The code below allows you to remove the selected row from the list control.

Private Sub Command2_Click()

TDBList1.RemoveItem TDBList1.SelectedItem

End Sub

The Clear method removes all items from the list population. The code below removes the entire population from the list control.

Private Sub Command3_Click()

TDBList1.Clear

End Sub


When to Use AddItem Mode

If you do not want to use a bound data source control to populate the list, but instead want to modify the list manually.


How AddItem Mode Works

When True DBList runs in AddItem mode, it is not connected to a data control. Instead, your application must supply and maintain the data, while the list handles all user interaction and data display. In this mode, the functionality of the TDBList control is similar in most ways to the standard listbox control.

When populating the list control, the first item starts at zero. Any event that uses a bookmark will use the zero based index of the control.


Database Programming Techniques

As Tutorial 1 demonstrates, no code is necessary to create a fully functional database browser and editor using True DBList. 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 Cell Data

Selecting and Highlighting Records

Refreshing the Display

Refetching Data from the Data Source

Postponing Illegal Operations in List Events

Searching Bookmarks Using the Find Method


Changing the Current Record Position

True DBList 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 list adjusts its display to bring the new current row into view if necessary.


Accessing 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 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 cell data within the current record

You can read 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$ = TDBList1.Columns(ColIndex).Text

CurrentValue = TDBList1.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:

TDBList1.Columns(ColIndex).Text = NewText$

TDBList1.Columns(ColIndex).Value = NewValue


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.

To examine cell data in any row, where bkm is the bookmark of the desired row:

RowText$ = TDBList1.Columns(ColIndex).CellText(bkm)

RowValue = TDBList1.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 list'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 = TDBList1.GetBookmark(0) ' Current row

Bmk = TDBList1.GetBookmark(1) ' Next row

Bmk = TDBList1.GetBookmark(-1) ' Previous row

Bmk = TDBList1.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 TDBList1

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.


Selecting and Highlighting Records

For TDBCombo controls and TDBList controls with MultiSelect set to 0 - None, the SelectedItem property is used to select and highlight an individual record.

For TDBList controls with MultiSelect set to either 1 – Simple, 2 – Extended or 3 – Checkbox, you can select and highlight one or more records at run time by manipulating the list's SelBookmarks collection, which maintains a list of bookmarks corresponding to the selected rows.

Like all other collections in True DBList, the SelBookmarks collection supports Add, Item, and Remove methods and a Count property. For example, to select the list's current row, use the Add method:

TDBList1.SelBookmarks.Add TDBList1.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

To deselect a single record, use the Remove method, which takes a collection index, not a bookmark:

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

While .Count > 0

.Remove 0

Wend

End With

Tutorial 6 demonstrates how to use the SelBookmarks collection to select records that satisfy specific criteria.


Refreshing the Display

True DBList 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 list'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 list from responding to database events, you can use the Refresh or ReBind methods. If you are not using DataMode 1 - Unbound, these methods behave as follows:

Refresh

This method simply forces the list to repaint, and no database access occurs. The list maintains all modified data in the current row, and the current cell position is unchanged.

ReBind

This method causes the list to disconnect from and then reconnect to its data source. The list rebinds all columns and refetches all data. Any data changed by the user (but not yet updated to the database) will be lost. The list 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 list (unless all records are visible).

If you need to refresh a single column or row instead of the entire list, you can use the RefreshCol or RefreshRow methods instead of Refresh. To refresh an individual list cell, use the RefreshCell method of the desired Column object.

To maintain backward compatibility with the original unbound mode of DBList, the Refresh and ReBind methods behave as follows when the DataMode property is set to 1 - Unbound:

Refresh

The list 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 list 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 list (unless all records are visible).

ReBind

The list 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 list display are unchanged.


Refetching Data from the Data Source

Normally, you need not be concerned with the mechanics of data retrieval. True DBList 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 TDBList control method repopulates the specified row from the data source.

RefetchCol

Given a column index, this TDBList 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.


Postponing Illegal Operations in List Events

During most of the list events, database and other system operations are still pending, and certain operations are not allowed within these list 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 list events. If the PostMsg method is called, the list 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.

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.


Searching Bookmarks Using the Find Method

The Find method is used to search the row bookmarks contained in the list control in Bound, Unbound or Storage modes. By using the Find method you can customize the search by selecting the string to search, the method of search and the location of the start of the search.

The syntax for the find method is:

column.Find (searchStr, searchMode, includeStart, [startBmk])

SearchStr represents the string or number that you wish to search.

SearchMode is the method that your search will use to locate the bookmark. The values that SearchMode can use are:

dblSeekEQ

Finds the first match such that the column value is equal to
searchStr.

dblSeekGE

Finds the first match such that the column value is greater than or equal to searchStr.

dblSeekGT

Finds the first match such that the column value is greater than searchStr.

dblSeekLE

Finds the first match such that the column value is less than or
equal to searchStr.

dblSeekLT

Finds the first match such that the column value is less than
searchStr.

dblSeekPartialEQ

Finds the first match such that searchStr is the leading part of the column string, for example, “ab” is the leading part of “abstract”.

DblSeekIncludeEQ

Finds the first match such that the searchStr is included somewhere within the column string, for example, “put” is within the column string “computer”. (Note: This SearchMode is only available in OLEDB.)

IncludeStart takes values TRUE or FALSE. If the value is TRUE, the search will start from the current StartBmk, otherwise the search will start from the row right after the StartBmk

StartBmk is the bookmark of the row where search begins. This argument is optional, if it does not appear, the StartBmk will be the first row on the control.


Find Method Simple Code Example:

The following code searches from the beginning of the control for any bookmark in the “Date” column with a date greater than “10/21/98”.

Private Sub cmdFind_Click()

dim bk

bk = TDBList1.Columns("Date").Find("10/21/98", dblSeekGT, True)

End Sub

As you can see in the bold faced section of code we have:

•

set the SearchStr to “10/21/98”

•

set the SearchMode to dblSeekGt which will enable the search for numeric dates greater than 10/21/98

•

set the IncludeStart to True and have not specified a StartBmk which causes the default StartBmk to be the first row in the control

If you wish to search from a specific row, you would set IncludeStart to True and set StartBmk to the row where you wish to start the search.

If you wish to create a continuing search, where your SearchStr is repeated in the control (more than one instance of your string), you would set IncludeStart to False and set StartBmk to the previous incident of your Find.

For more information, see Tutorial 22 - Performing a List Search Using the Find Method.


Customizing the List's Appearance

This chapter explains how to configure the noninteractive elements of True DBList's display, such as captions, headers, footers, and dividing lines.

Captions, Headers, and Footers

Three-dimensional versus Flat Display

Borders and Dividing Lines

Modifying the Cell Border Appearance

Customizing the Scrollbars

Unpopulated Regions

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 list, column, or split by setting the Caption property of the appropriate object.

TDBList1.Caption = "List Caption"

TDBList1.Columns(0).Caption = "Column 0 Caption"

TDBList1.Splits(0).Caption = "Split 0 Caption"

Column and list captions

Column footers

Multiple-line headers and footers

Split captions


Column and list captions

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

If you are using True DBList 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 list layout according to the current RecordSource setting for the Data control to which the list 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 TDBList control itself, which lets you provide a descriptive header for the entire list.

By default, True DBList 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 list, 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:

TDBList1.Columns(0).FooterText = "Footer0"

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

.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 list or split captions, which can only occupy a single row.


Split captions

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

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


Three-dimensional versus Flat Display

True DBList supports a standard, "flat" control appearance, as well as the more attractive three-dimensional appearance used by many controls. By default, the list'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 list's border, caption bars, column headings, and column footings. It does not affect the list's data cells or row and column dividers.

When Appearance is set to 1 - 3D, the list looks like this:

When Appearance is set to 0 - Flat, the list looks like this:

When Appearance is set to 2 - MixFlat, the scroll bars are 3D while the rest of the control is flat, the list looks like this:

To achieve a 3-D appearance for the entire list, 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:

TDBList1.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 TrueDBList80.Column

For Each C In TDBList1.Columns

C.DividerStyle = dblInset

Next

•

On the General property page, set the BackColor property to gray. Or, in code:

TDBList1.BackColor = &HC0C0C0

The resulting list will look something like this.

Note that changing the RowDividerStyle property from 0 - No dividers to 4 - Inset consumes extra vertical space 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 TDBList 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

For example, setting the RowDividerStyle property to 2 - Dark gray line improves the readability of multi-column lists.

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 list 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 list normally draws to indicate split boundaries.


Modifying the Cell Border Appearance

By using combinations of the expanded Style object properties; BorderAppearance, BorderColor, BorderSize and BorderStyle, you can easily give the list cell borders a unique, professional appearance. All of the properties are available for both the TDBList and TDBCombo objects at run-time and design time.

Private Sub Command1_Click()

With TDBList1.Columns(0).Style

.BorderAppearance = dbl3DRaised

.BorderType = dblBorderTop Or dblBorderLeft

.BorderColor = vbRed

.BorderSize = 5

End With

End Sub


3D Appearance

The BorderAppearance property enables you to modify the 3D style of the cell borders by using the property pages or in code. In the example below, the cells are set to 3 – Raised Bevel, which creates a 3D effect for the given cells.

Allowable values for the BorderAppearance property are:

0 - Flat

1 - Raised

2 - Inset

3 - Raised Bevel

4 - Inset Bevel


Border Thickness

The BorderSize property enables you to modify the thickness of the cell borders within the property pages or in code. By setting the border value, you can increase or decrease the thickness of the chosen cell borders (in pixels). Note: Because the cell border thickness expands inward on the cell, increasing the cell borders will reduce the area available for the cell contents. To allow for the increased cell border thickness, you can increase the RowHeight property as required.


Border Color

The BorderColor property enables you to modify the color of the cell borders within the property pages or in code. The colors can be selected by calling specific colors, with RGB values or with the standard Windows color palette.

For more information, see Tutorial 21 - Cell Bordering and Scroll Tips/Tracking.


Customizing the Scrollbars

In some applications, you may want to change the thickness of the scroll bars on the list control. By setting the HScrollHeight and VScrollWidth properties, you can modify the thickness of each scroll bar individually in code.

As in the following code, you can change the HScrollHeight and VScrollWidth property values, to create most any scroll bar thickness variation.

Private Sub Command1_Click()

TDBList1.VScrollWidth = 200

TDBList1.HScrollHeight = 200

End Sub


Unpopulated Regions

Depending upon the number of rows and columns in the data source, a portion of the list's interior may not contain data cells. However, you can eliminate these "dead zones" using the ExtendRightColumn and EmptyRows properties.


The rightmost column

As the list 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 list.

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.


Unused data rows

If the data source contains fewer rows than the list can display, the area below the list will display empty rows below the last usable data row.

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 True, but if you set it to True, then the list 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 list.


Row Height and Multiple-line Displays

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

Adjusting the height of all list rows

Enabling wordwrap in cells

Displaying a single record on multiple lines

Implications of multiple-line mode


Adjusting the height of all list rows

You can configure the row height interactively at design time by placing the list in its visual editing mode or by changing the list'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 list 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:

TDBList1.RowHeight = 0

TDBList1.RowHeight = 3 * TDBList1.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 list 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 list'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 list's row height accommodates multiple lines.

You can use the following loop to enable wordwrap for all list columns:

Dim C As TrueDBList80.Column

For Each C In TDBList1.Columns

C.Style.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 list. If the list 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 list is a single physical row of cells displayed in the list. Do not confuse this with a line of text inside a list cell; depending upon the settings of the RowHeight and WrapText properties, data in a list cell may be displayed in multiple lines of text.

•

A row in a list is used to display a single record. A row may contain multiple lines or multiple physical rows.

The MultipleLines property of the list 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 list 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 list 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 list will automatically span or wrap the columns to multiple lines so that all columns will be visible within the width of the list. 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 list 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 list—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 list.

•

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, 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 list 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 11 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 list, 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 list 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 list 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 the TDBCombo dropdown list and the CellTips window with animation properties.

For a TDBCombo control, the AnimateWindow property controls the style of animation when the user opens or closes the dropdown list. It is only meaningful when the ComboStyle property is set to 0 - Dropdown Combo or 1 - Simple.

The allowable values for this property are as follows:

0 - No Animate (default)

1 - Roll

2 - Slide

3 - Blend

For a TDBCombo or TDBList control, 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 combo dropdown or combo and list 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.

Text Formatting

Automatic Data Translation with ValueItems

Context-sensitive Help with CellTips

Scroll Tracking and ScrollTips

Data-sensitive Cell Merging

Outlook-Style Grouping

Owner-drawn Cells


Text Formatting

In many cases, the raw numeric data that True DBList 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 DBList 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 DBList provides an event, FormatText, that enables your application to override the default formatting on a per-column basis.


Using Visual Basic's built-in formatting

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

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


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 DBList 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 TDBList1_FormatText(ByVal ColIndex As Integer, _

Value As Variant, Bookmark As Variant)

ColIndex contains the column number of the list 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 TDBList1_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 list.


Automatic Data Translation with ValueItems

Although you can use the FormatText event to map data values into more descriptive display values, True DBList 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 8 and Tutorial 9 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 DBList 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 list. If the Translate check box is not selected, you will only be able to enter items in the Value column of the property page list.

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

With TDBList1.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 list's Style property to 2 - Vertical Center. This ensures that the bitmaps (as well as textual data in other columns) are centered vertically within list 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 TrueDBList80.ValueItem

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

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:

TDBList1.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 TDBList1_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 and newer, 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. 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 property 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 TDBList1.Columns("Country").ValueItems

.Presentation = dblRadioButton

End With

If necessary, adjust the Width property of the column and the RowHeight property of the list 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 list 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 TDBList1.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 DBList.

The CellTips property determines whether the list 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 list has focus and the cursor is idle over a list cell, column header, column footer, split header, or list 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 list 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 TrueDBList80.Column

Private Sub Form_Load()

Set DescCol = TDBList1.Columns("Description")

End Sub

Private Sub TDBList1_FetchCellTips( _

ByVal SplitIndex As Integer, _

ByVal ColIndex As Integer, _

ByVal RowIndex As Long, _

CellTip As String, _

ByVal FullyDisplayed As Boolean, _

ByVal TipStyle As TrueDBList80.StyleDisp)

CellTip = DescCol.CellText(TDBList1.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.


Scroll Tracking and ScrollTips

In some instances, you may want the list control scroll bars to be a bit more interactive, allowing the user to see changes and helpful information as they navigate through the control data. By using the ScrollTrack property, the list control contents is updated as the scrollbar thumb is moved. With the ScrollTips property, an informational pop-up is provided, containing whatever content you choose.

If the ScrollTrack property is set to True, moving the scrollbar thumb causes vertical scrolling of the list display. By default, this property is False, and no scrolling occurs until the thumb is released. The ScrollTrack property can be set at design-time or in code similar to the example below.

Private Sub chkSTracking_Click()

TDBList1.ScrollTrack = chkSTracking.Value

End Sub

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.

Private Sub ChkSTips_Click()

TDBList1.ScrollTips = chkSTips.Value

End Sub

Note: You must create an event handler to define the contents of your ScrollTips. For more information, see Tutorial 21 - Cell Bordering and Scroll Tips/Tracking.


Data-sensitive Cell Merging

If the underlying list 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 noneditable cell. By default, this property is False, and each physical row within a column displays a data value, if any.

Consider the following list, 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:

TDBList1.Columns("Country").Merge = True

Executing this statement produces the following display.

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 TDBList1.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 List Elements describes a more flexible method for displaying in-cell graphics using Style objects.


Outlook-Style Grouping

The OLE DB version of True DBList 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 list as in Microsoft Outlook. When in Group mode, a "grouping area" is added to the top of the list, 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 list 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 list. 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 noneditable 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 list 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 list. Similarly, the Remove method removes a column from the grouping area and returns it to its original position within the list; 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 23- Outlook-Style Grouping (OleDB Only) for more information.


Owner-drawn Cells

For cases where you need to perform complex per-cell customizations using Windows API calls, you can draw directly to the list'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 list:

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 TDBList1_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 = TDBList1.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 list 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 list 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.


How to Use Splits

In True DBList, 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 list products, fixed (nonscrolling) columns in True DBList do not have to be at the left edge of the list, but can be at the right edge or anywhere in the middle. You can even have multiple groups of fixed columns within a list. Splits open up an endless variety of possibilities for presenting data to users of your applications.

Whenever you use True DBList, you are always using a split. A list 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 list.

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


Referencing Splits and their Properties

A TDBList 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 list's Split property:

' Read the zero-based index of the current split

Variable% = TDBList1.Split

' Set focus to the split with an index equal to Variable%

TDBList1.Split = Variable%

Each split in a list is a different view of the same data source, and behaves just like an independent list. 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 list with one split.

Note that some properties are supported by both the TDBList and Split objects. Three rules of thumb apply to properties that are common to a list 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 list are not affected.

2.

When you get the property of a TDBList object, you are accessing the same property within the current split.

3.

When you set the property of a TDBList object, you are setting the same property within all splits.

These rules apply only to a TDBList object and its associated Split objects. No other object pairs possess similar relationships.


Split properties common to TDBList

The following properties, which are supported by both Split and TDBList objects, adhere to the rules described in the preceding section:

AllowColMove

Enables interactive column movement

AllowColSelect

Enables interactive column 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

Caption

Sets/returns control caption or column heading 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

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

FooterStyle

Controls the footing style for a split

HeadingStyle

Controls the heading style for a split

HighlightRowStyle

Controls the style of the current row

HScrollHeight

Returns the horizontal scroll bar height, if present

InactiveStyle

Controls the inactive heading style for a split

LeftCol

Returns the leftmost visible column

OddRowStyle

Controls the row style for odd numbered rows

PartialRightColumn

True if rightmost column can be clipped to edge of split

ScrollBars

Sets/returns scroll bar style for a split

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


Split-only properties not supported by TDBList

The following properties are supported by Split objects but not by TDBList. Therefore, to apply a value to the entire list, you need to explicitly set the value for each split individually.

AllowSizing

Enables interactive resizing for a split

DividerStyle

Divider style for right column border

Index

Returns the ordinal index of 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 list'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 TrueDBList80.Split

Set S = TDBList1.Splits.Add(0) ' Create a split with index 0

TDBList1.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 list using the Splits collection's Count property:

' Set variable equal to the number of splits in TDBList1

variable = TDBList1.Splits.Count

You can iterate through all splits using the Count property, for example:

For n = 0 To TDBList1.Splits.Count - 1

Debug.Print TDBList1.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 TrueDBList80.Split

For Each S In TDBList1.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 TrueDBList80.Split

Set S = TDBList1.Splits.Add(TDBList1.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 DBList control maintains its own Columns collection. This provides tremendous flexibility for controlling the look and behavior of individual splits. The list 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 list with two splits, the following code will always print the same values for a given column index n:

Debug.Print TDBList1.Splits(0).Columns(n).Caption

Debug.Print TDBList1.Splits(1).Columns(n).Caption

Debug.Print TDBList1.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 TrueDBList80.Columns

Set Cols = TDBList1.Splits(0).Columns

' Append a column to the end of the Columns collection

Dim C As TrueDBList80.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:

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

Caption

Sets/returns column heading text

DataField

Data table field name for a column

FooterText

Column footing text

NumberFormat

Data formatting string 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

AllowSizing

Enables interactive resizing for a column

ButtonFooter

Controls whether a column footer acts like a standard button

ButtonHeader

Controls whether a column header acts like a standard button

DividerStyle

Divider style for right column border

FetchStyle

Controls whether the FetchCellStyle event fires for a column

FooterAlignment

Specifies column footing alignment

FooterDivider

Controls the display of dividing line in column header

FooterStyle

Controls the footing style for a column

HeadAlignment

Specifies column heading alignment

HeaderDivider

Controls display of dividing line in column header

HeadingStyle

Controls the heading style 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

The following Column object methods are also split-specific:

AddRegexCellStyle

Adds a regular expression cell condition to a column

ClearRegexCellStyle

Removes a regular expression cell condition from a column


Sizing and Scaling Splits

True DBList 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 DBList, 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 DBList 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 dblScalable, dblExact, and dblNumberOfColumns 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 list display region. SizeMode is always 0 - Scalable when a list 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 list boundaries. This mode is not applicable when a list 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 list 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 list contains only one split.

Note that when there is only one split (the list's default behavior), the split spans the entire width of the list, 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 TrueDBList80.Split

Set S = TDBList1.Splits.Add(0) ' Create a Split at the left

Set S = TDBList1.Splits.Add(0) ' Create another

the resulting list display will look like this.

Notice that each split occupies 1/3 of the total list 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:

TDBList1.Splits(0).Size = 1 ' Change relative size to 1

TDBList1.Splits(1).Size = 2 ' Change relative size to 2

TDBList1.Splits(2).Size = 3 ' Change relative size to 3

the resulting list 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 = dblScalable

Split0.Size = 1

Split1.SizeMode = dblExact

Split1.Size = 2500

Split2.SizeMode = dblScalable

Split2.Size = 2

After configuring the splits in this way, the resulting list 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 list. 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 list to reconfigure itself.

Avoid creating a list with no scalable splits. Although True DBList handles this situation, it is difficult to work with a list 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 list. If the total width of the splits is too short, True DBList displays a "null-zone" where there are no splits. If the total width of the splits is wider than the list, then True DBList 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 list 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:

TDBList1.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 DBList 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:

TDBList1.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 list 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 DBList 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 TrueDBList80.Split

Set S = TDBList1.Splits.Add(0) ' Create a Split at the left

Set S = TDBList1.Splits.Add(0) ' Create another

the resulting list 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:

TDBList1.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 DBList provides you with an easy way to keep any number of columns from scrolling at any location within the list (even in the middle!) by setting a few split properties.

As an example, assume that you have a list 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 TrueDBList80.Columns

Dim C As TrueDBList80.Column

Set Cols = TDBList1.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 TDBList1.Splits(1)

.SizeMode = dblNumberOfColumns

.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 = TDBList1.Splits(0).Columns

Cols(0).Visible = False

Cols(1).Visible = False

Set Cols = TDBList1.Splits(2).Columns

Cols(0).Visible = False

Cols(1).Visible = False


How to Use Styles

True DBList uses a style model similar to that of Microsoft Word and Excel to simplify the task of customizing a list'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

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

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


Built-in Named Styles

When a list 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 list 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 lists contain eight built-in styles, which control the display of the following list elements:

Normal

Data cells in unselected, unhighlighted rows

Heading

Column headers

Footing

Column footers

Selected

Data cells in selected rows

Caption

List and split caption bars

HighlightRow

Data cells in highlighted rows

EvenRow

Data cells in even numbered rows

OddRow

Data cells in odd numbered rows

A selected row is one whose bookmark has been added to the SelBookmarks collection, either in code or through user interaction.

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 DBList can inherit its characteristics from another style, referred to as the parent style. For a newly created list, 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

Font

The ambient font of the list's container

ForeColor

System Window Text

ForegroundPicture

None

ForegroundPicturePosition

0 - Left

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

False

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 and OddRow styles inherit from Normal, but only EvenRow overrides any properties:

BackColor

Light Cyan

The only style that does not inherit directly from Normal is Caption, which inherits from Heading. The reason that list 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 list on a form and set the Caption property of the list and its default columns. Set the FooterText property of the default columns and set the ColumnFooters property of the list to True. The list 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 list 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 list'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 list 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:

TDBList1.Styles("Heading").Alignment = dblCenter

However, you are not required to use the Style Factory property page or manipulate named members of the Styles collection in code, as the list and its component objects expose several properties that return Style objects. As the next section describes, you can fine tune the appearance of the list 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 TDBList or TDBCombo 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

EvenRowStyle

Controls the row style for even-numbered rows

FooterStyle

Controls the footing style for an object

HeadingStyle

Controls the heading style for an object

HighlightRowStyle

Controls the style of the current row

InactiveStyle

Controls the inactive heading style for an object

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

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 list shows which style properties are supported by the TDBList and TDBCombo 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 list component by modifying one or more members of an appropriate style property. For example, to make the list'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 list 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:

TDBList1.CaptionStyle.Font.Bold = True

TDBList1.Styles("Caption").Font.Bold = True

The first statement specializes the font of the list'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 list's caption bar, depending on whether the Font member of the CaptionStyle property was specialized previously. For example, if you change the list's CaptionStyle font to Arial, then change the font of the built-in Caption style to Courier, the list 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 list's caption bar.


Assigning a value to a style property

You can also customize the appearance of a list 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 list 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 list 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:

TDBList1.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 list properties.

Named styles provide templates that govern the appearance of the list, 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 list 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 TDBList properties that return named style objects: EvenRowStyle, FooterStyle, HeadingStyle, and HighlightRowStyle.

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 list 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 TDBList (or the Columns page of TDBCombo), 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 list 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 TDBList control. Similarly, an anonymous style in a Column object can inherit from its counterpart in the containing Split object. Since the TDBCombo control does not have a Splits collection, the anonymous styles of its Column objects can inherit values from the control itself.

When a list 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 list 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 list's display; however, you can perform the same operations at design time using the list's property pages.

Example 1:

TDBList1.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 list 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:

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

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

TDBList1.Style.BackColor = &H808080

In the first example, setting the Font member of the list's Style property affected the entire list, 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 list are displayed with a dark gray background.

Example 7:

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

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

TDBList1.Splits(0).Columns(0).Style.Alignment = dblCenter

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 TDBList1.Splits(0).Columns(0)

.HeadingStyle.Alignment = dblLeft

.FooterStyle.Alignment = dblRight

.Alignment = dblCenter

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

Font

Specifies the typeface, size, and other text characteristics

FooterAlignment

Specifies column footing alignment

ForeColor

Sets/returns the foreground color

HeadAlignment

Specifies column heading alignment

The following list shows the style property equivalent for each shortcut. It also indicates which properties are supported by the TDBList and TDBCombo controls, and which properties are supported by the Split and Column objects.

For example, the following statements are equivalent:

TDBList1.Columns(0).HeadAlignment = dblCenter

TDBList1.Columns(0).HeadingStyle.Alignment = dblCenter


Applying Styles to Cells

True DBList gives you three ways to control the display characteristics of individual cells:

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 DBList 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 AddRegexCellStyle method. 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 DBList, 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 contents

Applying cell styles by custom criteria

Cell style evaluation order


Specifying cell status values

The first argument to the AddRegexCellStyle method indicates the selection state that will trigger application of the specified style. It can be one of the following constants:

dblNormalRow

0 - Applies to cells in nonselected rows

dblSelectedRow

8 - Applies to cells in selected rows

dblAllRows

-1 - Applies to all cells in all rows, regardless of selection state

The values of these constants were chosen for compatibility with True DBGrid Pro.


Applying cell styles by contents

You can tell True DBList 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 list 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 TDBList, TDBCombo, Split, and Column objects, allowing you to control the range of cells for which certain conditions apply.

The AddRegexCellStyle method requires an additional argument for the regular expression string. 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 TrueDBList80.Style

S.Font.Bold = True

TDBList1.Columns(0).AddRegexCellStyle dblAllCells, 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 True.

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 True for a single column of numeric data, and handles the FetchCellStyle event to display values greater than 1000 in blue:

Private Sub TDBList1_FetchCellStyle( _

ByVal Condition As Integer, _

ByVal Split As Integer, _

Bookmark As Variant, _

ByVal Col As Integer, _

ByVal CellStyle As TrueDBList80.StyleDisp)

Dim N As Long

N = Val(TDBList1.Columns(Col).CellText(Bookmark))

If N > 1000 Then CellStyle.ForeColor = vbBlue

End Sub

The Split, Bookmark, and Col arguments identify which cell the list is displaying. The CellStyle argument conveys formatting information from your application to the list. 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 True for columns 4 and 7, and handle the FetchCellStyle event as follows:

Private Sub TDBList1_FetchCellStyle( _

ByVal Condition As Integer, _

ByVal Split As Integer, _

Bookmark As Variant, _

ByVal Col As Integer, _

ByVal CellStyle As TrueDBList80.StyleDisp)

Select Case Col

Case 4

Dim Col1 As Long, Col2 As Long

Col1 = CLng(TDBList1.Columns(1).CellText(Bookmark))

Col2 = CLng(TDBList1.Columns(2).CellText(Bookmark))

If Col1 - Col2 < 0 Then CellStyle.ForeColor = vbRed

Case 7

Dim S As String

S = TDBList1.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 True 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 list'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 lists that have the FetchRowStyle property set to True. The syntax for this event is as follows:

Private Sub TDBList1_FetchRowStyle( _

ByVal Split As Integer, _

Bookmark As Variant, _

ByVal RowStyle As TrueDBList80.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 list 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

TDBList1.FetchRowStyle = True

End Sub

Private Sub TDBList1_FetchRowStyle( _

ByVal Split As Integer, _

Bookmark As Variant, _

ByVal RowStyle As TrueDBList80.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 list, split, or column.

1.

Style property, TDBList control. The default named parent of this anonymous style is Normal.

2.

Style property, Split object. By default, this anonymous style inherits from its TDBList control counterpart.

3.

EvenRowStyle and OddRowStyle properties, Split object. By default, these anonymous styles inherit from their TDBList 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 list or split.

6.

SelectedStyle property, Split object. By default, this anonymous style inherits from its TDBList 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 TDBList control counterpart, which in turn has a default named parent of HighlightRow.

8.

AddRegexCellStyle method, if called. Cell styles specified at the Column object level have the highest priority, followed by those specified at the Split object and TDBList 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 True for a Column object.

Thus, you always have final control over the rendering of a cell via the FetchCellStyle event.


Applying Pictures to List Elements

In earlier versions of True DBList, styles were used to specify font, color, and alignment attributes. Version 6.0 extended 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 list 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 AddRegexCellStyle method.

•

Writing a handler for the FetchCellStyle or FetchRowStyle events.


Displaying background pictures

You can use background pictures to customize static list 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 list's CaptionStyle property:

With TDBList1.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 list 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 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 list a flat appearance and remove its

' row dividers and scroll bars. Assume that

' the ScaleMode of the containing form is in pixels.

With TDBList1

.Appearance = dblFlat

.Splits(0).InactiveStyle.ForeColor = vbWhite

.RowDividerStyle = dblNoDividers

.RowHeight = 16

.ScrollBars = dblNone

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 TDBList1.Splits(0).Style

.BackgroundPicture = LoadPicture("paper.bmp")

.BackgroundPictureDrawMode = dblBPTile

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

Set C = TDBList1.Columns.Add(0)

With C

.DividerStyle = dblNoDividers

.HeaderDivider = False

.Width = 48

.Visible = True

.Style.BackgroundPicture = LoadPicture("rings.bmp")

End With

TDBList1.Col = 0 ' Scroll the unbound column into view

' Resize the Title column and remove its header dividers.

Set C = TDBList1.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 TDBList1.HeadingStyle

.BackgroundPicture = LoadPicture("corner.bmp")

.BackgroundPictureDrawMode = dblBPTile

.Font.Bold = True

.Font.Size = 10

.ForeColor = vbWhite

End With


Displaying foreground pictures

You can use foreground pictures to add visual cues to static list 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 TrueDBList80.Style

Set S = TDBList1.Styles.Add("Ascending")

S.Parent = "Heading"

S.ForegroundPicture = LoadPicture("atoz.bmp")

S.ForegroundPicturePosition = dblFPRightOfText

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

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 TDBList1_HeadClick(ByVal ColIndex As Integer)

If ColIndex <> 1 Then Exit Sub

Dim SQL As String

SQL = "select * from composer order by last"

With TDBList1.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 TrueDBList80.Style

S.ForegroundPicture = LoadPicture("bach.bmp")

S.ForegroundPicturePosition = dblFPRight

TDBList1.Columns(1).AddRegexCellStyle dblAllCells, 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 TDBList1_FetchCellStyle( _

ByVal Condition As Integer, _

ByVal Split As Integer, _

Bookmark As Variant, _

ByVal Col As Integer, _

ByVal CellStyle As TrueDBList80.StyleDisp)

If Col <> 1 Then Exit Sub

If TDBList1.Columns(1).CellText(Bookmark) = "Bach" Then

CellStyle.ForegroundPicture = LoadPicture("bach.bmp")

CellStyle.ForegroundPicturePosition = dblFPRight

End If

End Sub

Prior to version 6.0, the only way to display a bitmap within a data cell was to specify a text-to-picture translation using the ValueItems collection. Although this technique was adequate for a limited set of known data values, it did not support the display of arbitrary bitmaps. Fortunately, version 8.0 overcomes this limitation. Tutorial 18 demonstrates how to use styles to display arbitrary bitmaps within data cells.


True DBList Reference

All True DBList Members

TDBList Properties

TDBList Methods

TDBList Events


All True DBList Members

TDBList Control Properties

TDBList Control Methods

TDBList Control Events

Column Object Properties

Column Object Methods

Columns Properties

Columns Methods

DataObject Object Properties

DataObject Object Methods

GroupColumns Collection Properties

GroupColumns Collection Methods

Layouts Collection Properties

Layouts Collection Methods

PrintInfos 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


TDBList Control Properties

AddItemSeparator | Determines the separator string for columns.
AllowColMove | Enables interactive column movement.
AllowColSelect | Enables interactive column selection.
AllowRowSizing | Enables interactive row resizing.
AlternatingRowStyle | Controls whether even/odd row styles are applied to a control.
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 and caption.
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 control row.
BookmarkType | Sets/returns the variant type used for passing bookmarks.
BorderAppearance | Controls the appearance (3D effects) of the cell borders.
BorderStyle | Sets/returns style for control border.
BoundColumn | Name of the RowSource field used to update DataField.
BoundText | Text value of the BoundColumn field.
Caption | Sets/returns caption for an object.
CaptionStyle | Controls the caption style for an object.
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.
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 True DBList columns.
CurrentCellVisible | Sets/returns the visibility of the current cell.
DataChanged | Sets/returns modification status of the current row or cell.
DataField | Name of the DataSource field to be updated by user selection.
DataMode | Specifies bound or unbound mode.
DataSource | Source of data to be updated once a selection is made.
DataView | Returns or sets how the list 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.
EmptyRows | Enables empty rows in an underpopulated control.
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.
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 | Returns current split extend column setting, sets all splits.
FetchRowStyle | Controls whether the FetchRowStyle event will be fired.
FirstRow | Bookmark of row occupying first display line.
Font | Specifies the overall font for a control.
FooterStyle | Controls the footing style for an object.
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.
GroupColumns | Contains a collection of grouped list column objects.
HeadingStyle | Controls the heading style for a control.
HeadLines | Number of lines allocated for heading text.
HighlightRowStyle | Controls the style of the current row.
HScrollHeight | Returns the horizontal scroll bar height, if present.
hWnd | Returns the window handle of the control.
IntegralHeight | Sets/returns a value that indicates the display of partial rows.
LayoutFileName | Sets/returns the name of a file containing list layouts.
LayoutName | Sets/returns the name of the current list layout.
LayoutURL | Sets/returns the URL used for downloading list layouts.
Layouts | Returns a collection of layout names.
LeftCol | Sets/returns the leftmost visible column.
ListCount | Returns the number of items in the list portion of a control.
ListField | Sets/returns the RowSource field used for incremental search.
MatchCol | Sets the search column when the MatchEntry property is not 0.
MatchCompare | Sets/returns the comparing mode for search.
MatchEntry | Sets/returns the type of incremental search.
MatchEntryTimeout | Sets/returns the incremental search timeout value.
MouseIcon | Sets/returns a custom mouse icon.
MousePointer | Sets/returns the mouse pointer type.
MultipleLines | Controls whether individual records span multiple lines.
MultiSelect | Controls whether users can select multiple rows.
OddRowStyle | Controls the row style for odd-numbered rows.
PartialRightColumn | True if rightmost column can be clipped to edge of split.
PrintInfo | Returns the default printer information object.
PrintInfos | Contains a collection of printer information objects.
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 control rows.
RowMember | Sets/returns the name of the row member used to populate the control.
RowSource | Specifies source of control data.
RowSubDividerColor | Controls the row subdivider color.
ScrollBars | Sets/returns scroll bar style for the control.
ScrollTips | Determines whether the list displays a pop-up window.
ScrollTrack | Controls whether the scrollbar thumb causes the control’s display to update with new data.
SelBookmarks | Contains a collection of selected row bookmarks.
SelectedItem | Sets/returns the bookmark of the currently selected item.
SelectedStyle | Controls the selected row and column style for an object.
SelEndCol | Sets/returns rightmost selected column.
SelStartCol | Sets/returns leftmost selected column.
Split | Sets/returns current split number.
Splits | Contains a collection of True DBList splits.
SpringMode | Sets/returns how the control columns are resized.
Style | Controls the normal style for a control.
Styles | Contains a collection of True DBList styles.
Text | Returns displayed cell text for the current row.
VisibleCols | Returns number of visible columns.
VisibleRows | Returns number of visible display rows.
VScrollWidth | Returns the vertical scroll bar width, if present.


TDBList Control Methods

AboutBox | Displays the About box.
AddItem | Adds an item.
AddRegexCellStyle | Adds a regular expression cell condition to a control.
CaptureImage | Returns a captured image of a control's display.
CellContaining | Identifies a row and column under an X, Y coordinate pair.
ClearFields | Clears the current column/field layout.
ClearRegexCellStyle | Removes a regular expression cell condition from a control.
ClearSelCols | Deselects all selected columns in the current split.
ColContaining | Identifies a column under an X coordinate.
ExportBegin | Begins control export to a file.
ExportEnd | Ends control export to a file.
ExportRows | Exports a sequence of control rows to a file.
ExportToDelimitedFile | Exports specified rows to a delimited text file.
ExportToFile | Exports specified rows as an HTML table.
GetBookmark | Returns a bookmark relative to the current row.
HoldFields | Uses the current column/field layout for all displays.
LoadLayout | Loads a saved layout.
PointAt | Returns the kind of control element under an X, Y coordinate pair.
PostMsg | Posts a message to a control to fire the PostEvent event.
ReBind | Reinitializes a control from its data source.
RefetchCol | Refetches data for a specified control column.
RefetchRow | Refetches data for a specified control row.
Refresh | Updates a control's screen display.
RefreshCol | Updates the display for a specified control column.
RefreshRow | Updates the display for a specified control row.
RemoveItem | Removes an item.
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 control's data area.
SplitContaining | Identifies a split under an X, Y coordinate pair.


TDBList Control Events

ClassicRead | Fired when the control requires 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.
DblClick | Fired when a mouse double click occurs.
DragCell | Fired when a drag operation is initiated.
Error | Occurs when an associated action fails.
FetchCellStyle | Fired when the FetchStyle property is True 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.
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.
OnInit | Occurs when the list 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.
Paint | Fired when the control repaints itself.
PostEvent | Occurs after a PostMsg method is called.
RowChange | Occurs when a different row becomes current.
RowResize | Occurs when rows are resized.
RowSourceChanged | Fired when the RowSource changes.
Scroll | Occurs when the control is scrolled using 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 control needs to find a row.
UnboundGetRelativeBookmark | Fired when the control needs a relative bookmark.
UnboundReadData | Fired when the control requires unbound data for display.
UnboundReadDataEx | Fired when the control requires unbound data for display.


Column Object Properties

Alignment | Specifies horizontal text alignment.
AllowSizing | Enables interactive resizing for a column.
ButtonFooter | Controls whether a column footer acts like a standard button.
ButtonHeader | Controls whether a column header acts like a standard button.
Caption | Sets/returns column heading text.
CellTop | Returns top column border, adjusted for multiple lines.
ColIndex | Returns the ordinal position of a column.
DataField | Data table field name for a column.
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.
FooterStyle | Controls the footing style for a column.
FooterText | Column footing text.
Group | Returns whether the column is being grouped.
HeadAlignment | Specifies column heading alignment.
HeaderDivider | Controls display of dividing line in column header.
HeadingStyle | Controls the heading style for a column.
Left | Returns column left border in container coordinates.
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.
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 (Column) | 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.


Column Object Methods

AddRegexCellStyle | Adds a regular expression cell condition to a column.
AutoSize | Autosizes the column width to fit the longest visible record.
CellText | Returns displayed text for any row.
CellValue | Returns underlying value for any row.
ClearRegexCellStyle | Removes a regular expression cell condition from a column.
Find | Locates the Bookmark of the 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.


Columns Properties

Count

Returns the number of columns in the collection.


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


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.


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 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.
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.
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 the visibility of the current cell.
DividerStyle | Divider style for right split border.
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.
FooterStyle | Controls the footing style for a split.
HeadingStyle | Controls the heading style for a split.
HighlightRowStyle | Controls the style of the current row.
HScrollHeight | Returns the horizontal scroll bar height, if present.
InactiveStyle | Controls the inactive heading style for a split.
Index | Returns the ordinal index of a split.
LeftCol | Returns the leftmost visible column.
OddRowStyle | Controls the row style for odd-numbered rows.
PartialRightColumn | True if rightmost column can be clipped to edge of split.
ScrollBars | Sets/returns scroll bar style for a split.
ScrollGroup | Used to synchronize vertical scrolling between splits.
SelectedStyle | Controls the selected row and column style for an object.
SelEndCol | Sets/returns rightmost selected column.
SelStartCol | Sets/returns leftmost selected column.
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

AddRegexCellStyle | Adds a regular expression cell condition to 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 (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.
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.
Name | 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.
DefaultItem | Index of default value item, or -1 if no default.
Presentation | Specifies how value items are displayed.
Translate | True to translate data values to display 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.


TDBList Properties

AddItemSeparator Property

Alignment Property

AllowColMove Property

AllowColSelect Property

AllowRowSizing Property

AllowSizing Property

AlternatingRowStyle Property

AnchorRightColumn Property

AnimateWindow Property

AnimateWindowClose Property

AnimateWindowDirection Property

AnimateWindowTime Property

AnnotatePicture Property

Appearance Property

ApproxCount Property

Array Property

BackColor Property

BackgroundPicture Property

BackgroundPictureDrawMode Property

Bookmark Property (RowBuffer)

Bookmark Property (TDBList)

BookmarkType Property

BorderAppearance Property

BorderColor Property

BorderSize Property

BorderStyle Property

BorderType Property

BoundColumn Property

BoundText Property

ButtonFooter Property

ButtonHeader Property

Caption Property

CaptionStyle Property

CellTips Property

CellTipsDelay Property

CellTipsWidth Property

CellTop Property

Col Property

ColIndex Property

ColumnCount Property

ColumnFooters Property

ColumnHeaders Property

ColumnIndex Property

ColumnName Property

Columns Property

Count Property

CurrentCellVisible Property

DataChanged Property

DataField Property

DataField Property (Column)

DataMember Property

DataMode Property

DataSource Property

DataView Property

DeadAreaBackColor Property

DefaultItem Property

DefColWidth Property

DestinationCol Property

DestinationRow Property

DestinationSplit Property

DisplayValue Property

DividerStyle Property

EmptyRows Property

Enabled Property

ErrorText Property

EvenRowStyle Property

ExportEOF Property

ExportNextBookmark Property

ExposeCellMode Property

ExtendRightColumn Property

FetchRowStyle Property

FetchStyle Property

Files Property

FirstRow Property

Font Property

FooterAlignment Property

FooterDivider Property

FooterStyle Property

FooterText Property

FootLines Property

ForeColor Property

ForegroundPicture Property

ForegroundPicturePosition Property

Group Property

GroupByCaption Property

GroupColumns Property

HeadAlignment Property

HeadingStyle Property

HeadLines Property

HeaderDivider Property

HighlightRowStyle Property

HScrollHeight Property

hWnd Property

InactiveStyle Property

Index Property

IntegralHeight Property

LayoutFileName Property

LayoutName Property

Layouts Property

LayoutURL Property

Left Property

LeftCol Property

ListCount Property

ListField Property

MatchCol Property

MatchCompare Property

MatchEntry Property

MatchEntryTimeout Property

Merge Property

MinWidth Property

MouseIcon Property

MousePointer Property

MultipleLines Property

MultiSelect Property

Name Property (Style)

NumberFormat Property

OddRowStyle Property

Order Property

OwnerDraw Property

Parent Property

PartialRightColumn Property

Presentation Property

PrintInfo Property

PrintInfos Property

RightToLeft Property

Row Property

RowCount Property

RowDividerColor Property

RowDividerStyle Property

RowHeight Property

RowMember Property

RowSource Property

RowSubDividerColor Property

ScrollBars Property

ScrollGroup Property

ScrollTips Property

ScrollTrack Property

SelBookmarks Property

SelectedItem Property

SelectedStyle Property

SelEndCol Property

SelStartCol Property

Size Property

SizeMode Property

Split Property

Splits Property

SpringMode Property

Style Property

Styles Property

Tag Property

Text Property

Top Property

Translate Property

TransparentForegroundPicture Property

Value Property (Column)

Value Property (RowBuffer)

Value Property (Style)

Value Property (ValueItem)

ValueItems Property

VerticalAlignment Property

Visible Property

VisibleCols Property

VisibleRows Property

VScrollWidth Property

Width Property

WrapText Property


AddItemSeparator Property

This property determines the separation string for columns when using the AddItem method in AddItem mode.

Syntax

object.AddItemSeparator = String

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

This property takes ; as the default value.

See Also

TDBList and TDBCombo Controls


Alignment Property

The Alignment property returns or sets a value that determines the horizontal alignment of the values in a control column or style object.

Syntax

object.Alignment = value

Remarks

Read/Write at run time and design time.

Property applies to Column and Style objects.

Values

Design Time | Run Time
0 - Left (default) | dblLeft
1 - Right | dblRight
2 - Center | dblCenter
3 - General | dblGeneral

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

See Also

Column Object, Columns Collection

Style Object, Styles Collection


AllowColMove Property

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.

Syntax

object.AllowColMove = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

If True, the user can move selected columns.

If False (the default), the user cannot move selected columns.

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

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


AllowColSelect Property

Use the AllowColSelect property to control whether the user can select columns by clicking or dragging within the column header area.

Syntax

object.AllowColSelect = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

If True (the default), the user can select columns.

If False, the user cannot select columns.

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

TDBList and TDBCombo Controls

Split Object, Splits Collection


AllowRowSizing Property

If True (the default), the user can resize rows.

Syntax

object.AllowRowSizing = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

If False, the user cannot resize rows.

If the AllowRowSizing property is True, the mouse pointer turns into a double-headed arrow when positioned over the row divider between any pair of rows at the left edge of the list, and the user can resize the rows by dragging. Any change in row size causes a RowResize event.

All rows of the TDBList control are always the same height, which is determined by the RowHeight property.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


AllowSizing Property

If True, the user can resize the column or split.

Syntax

object.AllowSizing = boolean

Remarks

Read/Write at run time and design time.

Property applies to Column and Split objects.

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.

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


AlternatingRowStyle Property

Syntax

object.AlternatingRowStyle = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

This property determines whether a control or split displays odd-numbered rows in one style and even-numbered rows in another.

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

TDBList and TDBCombo Controls

Split Object, Splits Collection


AnchorRightColumn Property

Syntax

object.AnchorRightColumn = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

This property controls the behavior of horizontal scrolling in a control or split when the last column is visible.

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 control 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 control 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 control or split behaves as if it were set to True.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


AnimateWindow Property

Syntax

object.AnimateWindow = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - No Animate (default) | dblNoAnimate
1 - Roll | dblRoll
2 - Slide | dblSlide
3 - Blend | dblBlend

For a TDBCombo control, this property controls the style of animation when the user opens or closes the dropdown list. It is only meaningful when the ComboStyle property is set to 0 - Dropdown Combo or 1 - Simple Combo.

For a TDBCombo or TDBList 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 combo dropdown or combo and list cell tips.

The allowable values for this property are as follows:

If set to 0 - No animation (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. (NT 5.0 only)

NOTE: System requirements: Windows 98 or NT 5.0, or higher. The setting 3 - Blend is not available in Windows 98.

See Also

TDBList and TDBCombo Controls


AnimateWindowClose Property

Syntax

object.AnimateWindowClose = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - No Animate Close (default) | dblNoAnimateClose
1 - Opposite Direction | dblOppositeDirection
2 - Same Direction | dblSameDirection

For a TDBCombo control, this property controls the animation effect when the user closes the dropdown list. It is only meaningful when the ComboStyle property is set to 0 - Dropdown Combo or 1 - Simple Combo, and the AnimateWindow property is set to a value other than 0 - No Animation.

For a TDBCombo or TDBList 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.

The allowable values for this property are as follows:

If set to 0 - No Animation (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

TDBList and TDBCombo Controls


AnimateWindowDirection Property

Syntax

object.AnimateWindowDirection = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Default | dblDefaultDirection
1 - Top To Bottom | dblTopToBottom
2 - Bottom To Top | dblBottomToTop
3 - Left To Right | dblLeftToRight
4 - Right To Left | dblRightToLeft
5 - Top Left To Bottom Right | dblTopLeftToBottomRight
6 - Top Right To Bottom Left | dblTopRightToBottomLeft
7 - Bottom Left To Right | dblBottomLeftToTopRight
8 - Bottom Right To Top Left | dblBottomRightToTopLeft
9 - Center | dblAnimateCenter

For a TDBCombo control, this property controls the direction of the animation of the combo dropdown list. It is only meaningful when the ComboStyle property is set to 0 - Dropdown Combo or 1 - Simple Combo, and the AnimateWindow property is set to a value other than 0 - No Animation.

For a TDBCombo or TDBList 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 AnimateWindowClose property for additional control over the behavior of the animation when the object is 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 TDBCombo is too close to the bottom of the screen to display the entire dropdown list when opened by the user, the window will open upwards.

All of the remaining directional settings are under your complete control.

NOTE: System requirements: Windows 98 or NT 5.0, or higher.

See Also

TDBList and TDBCombo Controls


AnimateWindowTime Property

Syntax

object.AnimateWindowTime = long

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

This property controls the duration of the animation effects when the AnimateWindow property is set to a value other than 0 - No Animation. 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

TDBList and TDBCombo Controls


AnnotatePicture Property

Syntax

valueitems.AnnotatePicture = boolean

Remarks

Read/Write at run time and design time.

Property applies to ValueItems collection.

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

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 Translate property of the ValueItems collection is set to True.

•

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

ValueItem Object, ValueItems Collection


Appearance Property

Syntax

object.Appearance = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Flat | dblFlat
1 - 3D (default) | dbl3D
2 - Mixed Flat | dblMixedFlat

When this property is set to 1 - 3D, the control paints its caption bars, column headings, and column footings with three-dimensional effects.

When this property is set to 0 - Flat, no visual effects are used.

When this property is set to 2 - Mixed Flat, the paint everything flat except the scrollbars and buttons.

The Appearance property is independent of the BorderStyle and BackColor properties and only affects the control's caption bars, column headings, and column footings. 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, and ColumnFooters properties to control the visibility of these components.

See Also

TDBList and TDBCombo Controls


ApproxCount Property

Syntax

object.ApproxCount = long

Remarks

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

Property applies to TDBList and TDBCombo controls.

This property sets or returns the approximate row count used by the control to calibrate the vertical scroll bar.

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 control is used in conjunction with an array.

NOTE: For a bound control, setting the ApproxCount property has no effect. However, getting the ApproxCount property will query the underlying data source.

See Also

TDBList and TDBCombo Controls


Array Property

Syntax

object.Array = XArrayDB

Remarks

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

Property applies to TDBList and TDBCombo controls.

For a control with its DataMode property set to 4 - Storage, the Array property specifies an 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

TDBList and TDBCombo Controls


BackColor Property

Syntax

object.BackColor = color

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls and Style objects.

This property controls the background color of an object. Colors may be specified as RGB values or system default colors.

The background color of a control, 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

TDBList and TDBCombo Controls

Style Object, Styles Collection


BackgroundPicture Property

Syntax

style.BackgroundPicture = variant

Remarks

Read/Write at run time and design time.

Property applies to Style object.

This property sets or returns the background bitmap of a style object. 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:

TDBList1.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, Styles Collection


BackgroundPictureDrawMode Property

Syntax

style.BackgroundPictureDrawMode = value

Remarks

Read/Write at run time and design time.

Property applies to Style object.

Values

Design Time | Run Time
0 - Center (default) | dblBPCenter
1 - Tile | dblBPTile
2 - Stretch | dblBPStretch

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.

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


Bookmark Property (RowBuffer)

Syntax

rowbuffer.Bookmark (Row) = variant

Remarks

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

Property applies to RowBuffer object.

This property returns or sets a bookmark for the specified row within a RowBuffer object passed to an unbound event procedure for a TDBList control.

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 event, your code must provide bookmarks for the rows being fetched or added.

See Also

RowBuffer Object


Bookmark Property (TDBList)

Syntax

object.Bookmark = variant

Remarks

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

Property applies to TDBList and TDBCombo controls.

This property returns or sets the bookmark identifying the current row in a TDBList and TDBCombo control.

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

See Also

TDBList and TDBCombo Controls


BookmarkType Property

Syntax

object.BookmarkType = integer

Remarks

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

Property applies to TDBList and TDBCombo controls.

The BookmarkType property returns or sets the variant type of bookmarks returned by a TDBList and TDBCombo control through its properties, methods, and events. You can 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 control are incompatible with the ADO Recordset object exposed by an OLE DB data source, even though the control 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 = TDBList1.RowBookmark(0)

You can use the BookmarkType property in conjunction with the RowSourceChanged event to circumvent type mismatch errors that may occur when a control-supplied bookmark is passed to an ADO Recordset object (or vice versa). The workaround is as follows:

Sub TDBList1_RowSourceChanged()

TDBList1.BookmarkType = VarType(ADODC1.Recordset.Bookmark)

End Sub

This code ensures that any bookmarks returned by the control are first converted to the appropriate type for the bound data source. This workaround is only needed when using the control in an HTML page; it is not needed for Visual Basic 6.0.

See Also

TDBList and TDBCombo Controls


BorderAppearance Property

Determines the appearance of the border.

Syntax

object.BorderAppearance = value

Remarks

Read/Write at run time and design time.

Property applies to Style object for TDBList and TDBCombo.

Values

Design Time | Run Time
0 - Flat(default) | dblFlatStyle
1 - 3D Raised | dbl3Draised
2 - 3D Inset | dbl3Dinset
3 - 3D Raised Bevel | dbl3DraisedBevel
4 - 3D Insert Bevel | dbl3DInsetBevel

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


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.

Property applies to Style object for TDBList and TDBCombo.

See Also

Style Object, Styles Collection


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.
Property applies to the Style object for TDBList and TDBCombo.

See Also

Style Object, Styles Collection


BorderStyle Property

This property determines whether a TDBList or TDBCombo control has a border.

Syntax

object.BorderStyle = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - None | dblNoBorder
1 - Fixed Single (default) | dblFixedSingle

See Also

TDBList and TDBCombo Controls


BorderType Property

Determines the type of border.

Syntax

object.BorderType = value

Remarks

Read/Write at run time and design time.

Values

Design Time | Run Time
0 - None (default) | dblBorderNone
1 - Left | dblBorderLeft
2 - Right | dblBorderRight
4 - Top | dblBorderTop
8 - Bottom | dblBorderBottom

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


BoundColumn Property

This property returns or sets the name of the source field in a Recordset (Data control) object that is used to supply a data value to another Recordset (Data control).

Syntax

object.BoundColumn = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Generally, you will use the TDBList and TDBCombo controls with two Data controls: one to fill the list as designated by the RowSource property, and one to update a field in a database as designated by the DataSource and DataField properties.

When the user selects an item from a TDBList control or the list portion of a TDBCombo control, the BoundColumn property determines which RowSource field supplies the data value to be used for the update. You can use the following pseudo-code to help you remember how to configure a list or combo control at design time:

DataSource.DataField = RowSource.BoundColumn

The left side of the assignment statement specifies the field to be updated; the right side specifies the set of allowable values.

NOTE: Do not confuse the BoundColumn property with the ListField property used to specify the incremental search field.

See Also

TDBList and TDBCombo Controls


BoundText Property

Syntax

object.BoundText = value

Remarks

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

Property applies to TDBList and TDBCombo controls.

The BoundText property always reflects the value of the BoundColumn field within the list portion of the control. As the current record within the Recordset (Data control) associated with the DataSource property changes, the BoundText property receives the value specified by DataField. The list or combo control then searches the records in its list to see if the BoundText value matches any BoundColumn field. If a match is found, the record is highlighted in the list or placed in the text box portion of the combo control. If no match is found, the list selection is cancelled and BoundText returns an empty string.

When the user enters a value into the text portion of a TDBCombo control, the list portion attempts to position to a matching item. If a match is found, the BoundText property receives the field value corresponding to the BoundColumn property. If no match is found, the BoundText property does not change.

When the user selects an item from the list, the BoundText property receives the data value to be used for the update, and the Data control specified by the DataSource property receives notification that an update has been requested. The new value is not actually written to the database until the current record is repositioned or the Data control's UpdateRecord (Data control) method is executed.

You can also set the BoundText property in code to position the list to a specific item.

See Also

TDBList and TDBCombo Controls


ButtonFooter Property

If True, the column footer depresses like a standard Windows command button when clicked by the user.

Syntax

column.ButtonFooter = boolean

Remarks

Read/Write at run time and design time.

Property applies to Column object.

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


ButtonHeader Property

If True, the column header depresses like a standard Windows command button when clicked by the user.

Syntax

column.ButtonHeader = boolean

Remarks

Read/Write at run time and design time.

Property applies to Column object.

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


Caption Property

For a TDBList or TDBCombo control, this property determines the text displayed in the caption bar at the top of the control.

Syntax

object.Caption = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Column and Split objects.

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

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


CaptionStyle Property

This property sets or returns the Style object that controls the appearance of a control's caption bar or a Split object's heading area.

Syntax

object.CaptionStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

TDBList and TDBCombo Controls

Split Object, Splits Collection


CellTips Property

The CellTips property determines whether the control displays a pop-up text window when the cursor is idle.

Syntax

object.CellTips = value

Remarks

Read/Write at run time and design time.
Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - None (default) | dblNoCellTips
1 - Anchored | dblAnchored
2 - Floating | dblFloating

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 control has focus and the cursor is idle over a control cell, column header, split header, or control 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 control 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.

See Also

TDBList and TDBCombo Controls


CellTipsDelay Property

The CellTipsDelay property controls the amount of idle time, in milliseconds, that must elapse before the cell tip window is displayed.

Syntax

object.CellTipsDelay = long

Remarks

Read/Write at run time and design time.
Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


CellTipsWidth Property

Syntax

object.CellTipsWidth = single

Remarks

Read/Write at run time and design time.
Property applies to TDBList and TDBCombo controls.

The CellTipsWidth property returns or sets the width of the cell tip window in terms of the coordinate system of the control's container.

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

TDBList and TDBCombo Controls


CellTop Property

Syntax

column.CellTop

Remarks

Read-only at run time. Not available at design time.

Property applies to Column object.

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 control 's container.

If the control's MultipleLines property is 0 - Disabled (the default value), a single record cannot span multiple lines in the control, and the CellTop property returns zero for all columns.

If the control's MultipleLines property is either 1 - Variable or 2 - Fixed, a single record may span multiple lines in the control. 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 control'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 control cell in the first column of the fourth displayed row:

With TDBList1

Text1.Top = .Top + .RowTop(3) + .Columns(0).CellTop

End With

NOTE: To overlay the text box exactly on a control 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 (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, Columns Collection


Col Property

Syntax

object.Col = integer

Remarks

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

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


ColIndex Property

Syntax

column.ColIndex

Remarks

Read-only at run time. Not available at design time.

Property applies to Column object.

This property returns the zero-based index of a column within the Columns collection.

See Also

Column Object, Columns Collection


ColumnCount Property

Syntax

rowbuffer.ColumnCount

Remarks

Read-only at run time. Not available at design time.

Property applies to RowBuffer object.

This property returns the number of columns in a RowBuffer object passed to an unbound event procedure for a TDBList control.

See Also

RowBuffer Object


ColumnFooters Property

Syntax

object.ColumnFooters = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


ColumnHeaders Property

Syntax

object.ColumnHeaders = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


ColumnIndex Property

Syntax

rowbuffer.ColumnIndex (Row, Col)

Remarks

Read-only at run time. Not available at design time.

Property applies to RowBuffer object.

This property returns the index of a column in a RowBuffer object passed to an unbound event procedure for a TDBList control. The index corresponds to the ColIndex property of the control 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

Syntax

rowbuffer.ColumnName (Col)

Remarks

Read-only at run time. Not available at design time.

Property applies to RowBuffer object.

This property returns the name of a column in a RowBuffer object passed to an unbound event procedure for a TDBList control. The name corresponds to the DataField property of the control 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

Syntax

object.Columns

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList and TDBCombo controls, Split object.

This property returns a collection of Column objects for a control, drop-down control, or split.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


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.

Property applies to Columns, GroupColumns, Layouts, PrintInfos, SelBookmarks, Splits, Styles, and ValueItems collections.

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

GroupColumns Object

Layouts Object

PrintInfo Object, PrintInfos Collection

SelBookmarks Object

Split Object, Splits Collection

Style Object, Styles Collection

ValueItem Object, ValueItems Collection


CurrentCellVisible Property

Syntax

object.CurrentCellVisible = boolean

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

This property returns True if the current cell (indicated by the Bookmark and Col properties) is visible within the displayed area of a control or split. It returns False if the cell is not visible.

For a TDBList or TDBCombo control, setting the CurrentCellVisible property to True causes the control to scroll so that the current cell is brought into view. If a control 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

TDBList and TDBCombo Controls

Split Object, Splits Collection


DataChanged Property

Syntax

object.DataChanged = boolean

Remarks

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

Property applies to TDBList and TDBCombo controls.

The DataChanged property returns or sets a value indicating that the data in a TDBList or TDBCombo control has been modified. If True, the data in the control differs from the data in the current record. If False (the default), the data in the control has not been changed.

When the user modifies the data in a TDBList or TDBCombo control, or you set its Text property in code, the DataChanged property is set to True. Subsequently, when the data source control attempts to move to a different record, it first updates the changed value to the underlying data source.

You can set the DataChanged property to False to prevent the underlying data source from being updated in this manner. For the intrinsic Data control, this is typically done in the Validate (Visual Basic) control event.

See Also

TDBList and TDBCombo Controls


DataField Property

Syntax

object.DataField = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

The DataField property returns or sets the name of the DataSource field that will be updated when the user selects an item from a control.

Generally, you will use the TDBList and TDBCombo controls with two Data controls: one to fill the list as designated by the RowSource property, and one to update a field in a database as designated by the DataSource and DataField properties.

If the DataField property is not specified, no updates will occur, and the control will not respond to record position changes in the Recordset (Data control) associated with DataSource.

NOTE: Do not confuse the DataField property of the control with the DataField property of the Column object or the BoundColumn property used to specify the source field for the update.

See Also

TDBList and TDBCombo Controls


DataField Property (Column)

Syntax

column.DataField = string

Remarks

Read/Write at run time and design time.

Property applies to Column object.

The DataField property returns or sets the name of the field in the database table to which a list column is bound.

When the DataMode property of the list 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 list, the DataField property must be empty in order for the column data to be requested in the UnboundColumnFetch event.

See Also

Column Object, Columns Collection


DataMember Property

Syntax

object.DataMember = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls (OLE DB only).

This property returns or sets the name of the data member used to populate the list. Typically, a data member represents a database table or query.

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.

This property is only supported by the OLE DB version of True DBList. It is used only in bound mode and has no effect in unbound or storage modes.

See Also

TDBList and TDBCombo Controls


DataMode Property

Syntax

object.DataMode = value

Remarks

Read-only at run time. Read/Write at design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Bound (default) | dblBound
1 - Unbound | dblUnbound
2 - Unbound Extended | dblUnboundEx
3 - Application | dblUnboundAp
4 - Storage | dblUnboundSt
5 - AddItem | dblAddItem

When set to 0 - Bound, the control displays data available from its bound DataSource.

When set to 1 - Unbound, the control uses the original unbound events to retrieve and update displayed data. When this mode is used, the control fires the UnboundReadData event to fetch data. This setting was retained for backward compatibility earlier versions of True DBList. 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 list 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 control 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 TDBList or TDBCombo control using the Array property. This is by far the simplest way to use the controls in unbound mode.

When set to 5 - AddItem, the list portion of the control is populated with data via the AddItem method. The first item added starts at zero. Any event that uses a bookmark will use the zero based index of the control.

See Also

TDBList and TDBCombo Controls


DataSource Property

Syntax

object.DataSource

Remarks

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

Property applies to TDBList and TDBCombo controls.

The DataSource property specifies the data control that is updated once a selection is made.

Generally, you will use the TDBList and TDBCombo controls with two Data controls: one to fill the list as designated by the RowSource property, and one to update a field in a database as designated by the DataSource and DataField properties.

See Also

TDBList and TDBCombo Controls


DataView Property

The DataView property returns or sets how the list will display data from a data source.

Syntax

TDBList.DataView = value

Remarks

Read-only at run time. Read/Write at design time.

Property applies to TDBList control (OLE DB only).

Values

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

When set to 0 - Normal, the list will only display flat files; it will not support a hierarchical view of master-detail data. If the data source is a hierarchical recordset based on master-detail tables, the list will only display data from the master table.

When set to 2 - Group, a grouping area is created at the top of the list; any columns that are placed into this area become part of the GroupColumns collection, forming a new split. When in group mode, list 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.

NOTE: This property is only supported by the OLE DB version of True DBList Pro.

See Also

TDBList and TDBCombo Controls


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.

Property applies to TDBList and TDBCombo controls.

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.

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

TDBList and TDBCombo Controls


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.

Property applies to ValueItems collection.

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 control encounters a value which is not present in the ValueItems collection.

When the DefaultItem property is set to -1, then the control 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 List row. If no row is selected, then the DefaultItem property will be set to its default value of -1. To deselect a selected row, click its record selector again.

See Also

ValueItem Object, ValueItems Collection


DefColWidth Property

This property returns or sets the default width for all control columns in terms of the coordinate system of the control's container.

Syntax

object.DefColWidth = single

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

For bound controls, the DefColWidth property is respected under the following circumstances:

•

When you execute the Retrieve Fields command at design time.

•

When the control's layout is initialized at run time.

•

When a new column is created at run time.

For unbound controls, the DefColWidth property is only respected when a new column is created at run time.

If you set the DefColWidth property to 0, the control 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:

TDBList1.DefColWidth = TDBList1.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 control. Therefore, if DefColWidth is 0, the actual column widths may not be what you expect since the control must supply a default width.

See Also

TDBList and TDBCombo Controls


DestinationCol Property

This property is used when moving from one cell to another in the control. It indicates which column will be the destination of the movement.

Syntax

object.DestinationCol

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBCombo and TDBList controls.

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: 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 control's Col property).

NOTE: Care must be exercised when using this property, because it is possible to use the value 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

TDBList and TDBCombo Controls


DestinationRow Property

This property is used when moving from one cell to another in the control. It indicates which row will be the destination of the movement.

Syntax

object.DestinationRow

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBCombo and TDBList controls.

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: 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 setting the control's Row property).

NOTE: Care must be exercised when using this property, because it is possible to use the value 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

TDBList and TDBCombo Controls


DestinationSplit Property

This property is used when moving from one cell to another in the control. It indicates which split will be the destination of the movement.

Syntax

object.DestinationSplit

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBCombo and TDBList controls.

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 List 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: 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 control's Split property).

NOTE: Care must be exercised when using this property, because it is possible to use the value 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

TDBList and TDBCombo Controls


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.

Property applies to ValueItem object.

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


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

Remarks

Read/Write at run time and design time.

Property applies to Column and Split objects.

Values

Design Time | Run Time
0 - No dividers (Split default) | dblNoDividers
1 - Black line | dblBlackLine
2 - Dark gray line (Column default) | dblDarkGrayLine
3 - Raised | dblRaised
4 - Inset | dblInset
5 - ForeColor | dblUseForeColor
6 - Light gray line | dblLightGrayLine

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

Split Object, Splits Collection


EmptyRows Property

The EmptyRows property returns or sets a value that determines how the control displays rows below the last data row.

Syntax

object.EmptyRows = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

If all of the records in the data source do not fill up the entire control, setting EmptyRows to True will fill the unpopulated control area with empty data rows. If EmptyRows is False (the default), then the unpopulated control 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

TDBList and TDBCombo Controls


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.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


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.

Property applies to TDBList and TDBCombo controls.

When a database error occurs as a result of user interaction with the control, 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 control'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 TDBList and TDBCombo control's Error event handler. A trappable error will occur if you attempt to access it in any other context.

See Also

TDBList and TDBCombo Controls


EvenRowStyle Property

This property sets or returns the Style object that controls the appearance of an even-numbered row in a control or split where the AlternatingRowStyle property is set to True.

Syntax

object.EvenRowStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

To change the appearance of odd-numbered rows, set the OddRowStyle property.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


ExportEOF Property

The ExportEOF property returns True if the current exported record position is after the last record, False if the current exported record position is on or before the last record.

Syntax

TDBList.ExportEOF

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList control.

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

TDBList and TDBCombo Controls


ExportNextBookmark Property

The ExportNextBookmark property returns the bookmark after the last row exported by the previous call to the ExportRows method.

Syntax

TDBList.ExportNextBookmark = variant

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList control.

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

TDBList1.ExportBegin
Else
TDBList1.ExportBegin Request.Cookies("user"))
End If
TDBList1.ExportRows FileName, False, 10
Response.Cookies("user") = TDBList1.ExportNextBookmark
TDBList1.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

TDBList and TDBCombo Controls


ExposeCellMode Property

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

Syntax

object.ExposeCellMode = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList control.

Values

Design Time | Run Time
0 - Scroll on Select (default) | dblScrollOnSelect
2 - Never Scroll | dblNeverScroll

If set to 0 - Scroll on Select (the default), the control 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 control to begin editing, as the control will always shift to the left when the user clicks on the rightmost column.

If set to 2 - Never Scroll, the control 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 control to shift accidentally.

NOTE: The ExposeCellMode property only governs mouse clicks, not keyboard navigation.

See Also

TDBList and TDBCombo Controls


ExtendRightColumn Property

This property allows the rightmost column of a control 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.

Property applies to TDBList and TDBCombo controls, Split object.

If True, the last column will extend to the end of the control or split.

If False (the default), the area between the last column and the end of the control 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 control contains multiple splits, then setting its ExtendRightColumn property has the same effect as setting the ExtendRightColumn property of each split individually.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


FetchRowStyle Property

If True, the FetchRowStyle event will be fired whenever the control is about to display a row of data.

Syntax

object.FetchRowStyle = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

TDBList and TDBCombo Controls

Split Object, Splits Collection


FetchStyle Property

If True, the FetchCellStyle event will be fired as needed to determine the font and color characteristics of each cell in the associated column.

Syntax

column.FetchStyle = boolean

Remarks

Read/Write at run time and design time.

Property applies to Column object.

If False (the default), the FetchCellStyle event will not be fired.

Set this value to True when you need to perform complex per-cell formatting operations that can only be done using the FetchCellStyle event. For example, if you want to apply fonts and/or colors to cells within a certain range, or cells that satisfy a complex expression, then you need to set FetchStyle to True for the desired column(s) and write code for the FetchCellStyle event.

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


Files Property

Syntax

dataobject.Files

Remarks

Read-only at run time. Not available at design time.

Property applies to DataObject object.

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 DBList 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 TDBCombo control supplies an argument of type DataObject when it fires the following events: OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.

See Also

DataObject Object, DataObjectFiles Collection


FirstRow Property

This property returns or sets a value containing the bookmark for the first visible row in a control or split.

Syntax

object.FirstRow = variant

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

For a TDBList and TDBCombo control, setting the FirstRow property causes the control to scroll so that the specified row becomes the topmost row. If a control 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

TDBList and TDBCombo Controls

Split Object, Splits Collection


Font Property

This property returns or sets the font object associated with a control, column, split, or style.

Syntax

object.Font = font

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Style object.

The font used to display text in a control, 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.

NOTE: For TDBList and TDBCombo controls, if a change to the Font property results in a change to the average character width, then all affected columns are resized proportionally to reflect the new character width.

See Also

TDBList and TDBCombo Controls

Style Object, Styles Collection


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

Remarks

Read/Write at run time and design time.

Property applies to Column object.

Values

Design Time | Run Time
0 - Left | dblLeft
1 - Right | dblRight
2 - Center | dblCenter
3 - General (default) | dblGeneral

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


FooterDivider Property

If True (the default), the right edge of the column's footer is drawn with a vertical dividing line.

Syntax

column.FooterDivider = boolean

Remarks

Read/Write at run time and design time.

Property applies to Column object.

If False, no dividing line is drawn in the column's header area.

See Also

Column Object, Columns Collection


FooterStyle Property

This property returns the Style object that controls the appearance of column footings within a control, column, or split.

Syntax

object.FooterStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Column and Split objects.

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

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


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.

Property applies to Column object.

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 control'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, Columns Collection


FootLines Property

This property returns or sets a value indicating the number of lines of text displayed in a TDBList and TDBCombo control's column footers.

Syntax

object.FootLines = single

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

The FootLines property accepts a floating point number from 0 to 10. The default value is 1, which causes the control 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

TDBList and TDBCombo Controls


ForeColor Property

This property controls the foreground color of an object.

Syntax

object.ForeColor = color

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Style object.

Colors may be specified as RGB values or system default colors.

The foreground color of a control, 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

TDBList and TDBCombo Controls

Style Object, Styles Collection


ForegroundPicture Property

This property sets or returns the foreground bitmap of a style object. If a style has no foreground bitmap, then this property returns a null variant.

Syntax

style.ForegroundPicture = variant

Remarks

Read/Write at run time and design time.

Property applies to Style object.

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:

TDBList1.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, Styles Collection


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

Remarks

Read/Write at run time and design time.

Property applies to Style object.

Values

Design Time | Run Time
0 - Left (default) | dblFPLeft
1 - Right | dblFPRight
2 - Left of Text | dblFPLeftOfText
3 - Right of Text | dblFPRightOfText
4 - Top of Text | dblFPTopOfText
5 - Bottom of Text | dblFPBottomOfText
6 - Picture Only | dblFPPictureOnly
7 - Text Only | dblFPTextOnly

Use the ForegroundPicture property to specify a foreground bitmap for a style.

See Also

Style Object, Styles Collection


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.

Property applies to Column object (OLE DB only).

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.

See Outlook-Style Grouping for more information.

See Also

Column Object, Columns Collection


GroupByCaption Property

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

Syntax

TDBList.GroupByCaption = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList control (OLE DB only).

When the DataView property is set to 2 - Group, a grouping area is created above the list. 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.

See Outlook-Style Grouping for more information.

See Also

TDBList and TDBCombo Controls


GroupColumns Property

This property returns a collection of Column objects in the list's grouping area.

Syntax

TDBList.GroupColumns

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList control (OLE DB only)

See Outlook-Style Grouping for more information.

See Also

TDBList and TDBCombo Controls


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

Remarks

Read/Write at run time and design time.

Property applies to Column object.

Values

Design Time | Run Time
0 - Left | dblLeft
1 - Right | dblRight
2 - Center | dblCenter
3 - General (default) | dblGeneral

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


HeadingStyle Property

This property returns the Style object that controls the appearance of column headings within a control, column, or split.

Syntax

object.HeadingStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Column and Split objects.

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

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


HeadLines Property

This property returns or sets a value indicating the number of lines of text displayed in a TDBList and TDBCombo control's column headers.

Syntax

object.HeadLines = single

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

The HeadLines property accepts a floating point number from 0 to 10. The default value is 1, which causes the control 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

TDBList and TDBCombo Controls


HeaderDivider Property

If True (the default), the right edge of the column's header is drawn with a vertical dividing line.

Syntax

column.HeaderDivider = boolean

Remarks

Read/Write at run time and design time.

Property applies to Column object.

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


HighlightRowStyle Property

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

Syntax

object.HighlightRowStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


HScrollHeight Property

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.

Syntax

object.HScrollHeight

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

If no horizontal scroll bar exists, then the returned value is zero. If object is a TDBList or TDBCombo 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 List layout and sizing the List and its columns.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


hWnd Property

The hWnd property returns the unique window handle assigned to a TDBList and TDBCombo control by the Microsoft Windows operating environment.

Syntax

object.hWnd

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


InactiveStyle Property

This property returns the Style object that controls the appearance of column headings within a List or split when another object has focus.

Syntax

split.InactiveStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to Split object.

NOTE: The inactive style is only used when the control'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 control or split receives or loses focus.

See Also

Split Object, Splits Collection


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.

Property applies to Split object.

See Also

Split Object, Splits Collection


IntegralHeight Property

This property determines whether partial rows are displayed in a TDBList or TDBCombo control.

Syntax

object.IntegralHeight = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


LayoutFileName Property

This property sets or returns the string containing the filename used to save and retrieve control layouts.

Syntax

object.LayoutFileName = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Setting this property alone has no effect on the control layout; the property value is used by the LoadLayout method of the control and the Add and Remove methods of the Layouts collection.

You can create control layout files at design time by setting the LayoutFileName and LayoutName properties and using the layout commands on the control's visual editing menu.

At design time, if you first set the LayoutFileName property to a valid filename in which control 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

TDBList and TDBCombo Controls


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.

Property applies to TDBList and TDBCombo controls.

Setting this property alone has no effect on the control layout; the property value is used by the LoadLayout method of the control.

At design time, if you first set the LayoutFileName property to a valid filename in which control 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

TDBList and TDBCombo Controls


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.

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


LayoutURL Property

This property sets or returns the string containing the URL (Uniform Resource Locator) used for retrieving list layouts.

Syntax

TDBList.LayoutURL = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList control.

The LayoutURL property is similar to LayoutFileName except that it downloads a list layout file from an HTTP server instead of opening a file on the local machine or a network.

You can create list layout files at design time by setting the LayoutFileName and LayoutName properties and using the layout commands on the control's visual editing menu.

If you set the LayoutURL property to a nonempty string at design time (and LayoutFileName is empty), the control 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 list on an HTML page.

In either case, the control 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:

TDBList1.LayoutName = "MyLayout"

TDBList1.LoadLayout

NOTE: Since the control downloads layout files asynchronously, the following code may not work as expected:

TDBList1.LayoutURL = "http://www.bigcorp.com/layouts.grx"

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

TDBList and TDBCombo Controls


Left Property

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

Syntax

column.Left

Remarks

Read-only at run time. Not available at design time.

Property applies to Column object.

Use the Left property in conjunction with Width, RowHeight, and RowTop to determine the size and placement of controls displayed on top of a control cell.

See Also

Column Object, Columns Collection


LeftCol Property

This property returns or sets the zero-based index of the leftmost column in a control or split.

Syntax

object.LeftCol = integer

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

For a TDBList and TDBCombo control, setting the LeftCol property causes the control to scroll so that the specified column becomes the leftmost column. If a control 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 control or split horizontally. Use the FirstRow property to determine the bookmark of the first visible row in a control or split.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


ListCount Property

Returns the number of items in the list portion of the control.

Syntax

object.ListCount

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


ListField Property

The ListField property returns or sets the name of the column used for incremental search within a TDBList or TDBCombo control.

Syntax

object.ListField = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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 control will be used.

NOTE: Do not confuse the ListField property with the BoundColumn property used to specify the source field for update operations.

See Also

TDBList and TDBCombo Controls


MatchCol Property

This property sets the search column when the MatchEntry property is not 0 (None).

Syntax

object.MatchCol = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList control.

Values

Design Time | Run Time
0 - ListField (default) | dblListField
1 - Current Mouse Position | dblCurrentMousePos
2 - Current Selected Col | dblCurrentSelectedCol
3 - Left Visible Col | dblLeftVisibleCol
4 - Right Visible Col | dblRightVisibleCol
-1 - All Cols | dblAllCols

When this property is set to 0 – ListField, the search column is the current ListField. If the ListField is not set, the search column will be the first column.

When this property is set to 1 – Current Mouse Position, the search column is the column where the mouse cursor is active.

When this property is set to 2 – Current Selected Col, the search column is the current selected column. If there is more than one selected column, the search column is the left most selected column.

When this property is set to 3 – Left Visible Col, the search column is the left most visible column.

When this property is set to 4 – Right Visible Col, the search column is the right most visible column.

When this property is set to –1 – All Cols, the search columns are all the visible columns.

See Also

TDBList and TDBCombo Controls


MatchCompare Property

This property sets/returns the comparing mode for a search when the MatchEntry property is not set to 0 (None).

Syntax

object.MatchCompare = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList.

Values

Design Time | Run Time
-6 - Partially Equal (Default) | dblSeekPartialEQ
-1 - Less Than | dblSeekLT
-2 - Less Than or Equal | dblSeekLE
-3 - Equal | dblSeekEQ
-4 - Greater Than or Equal | dblSeekGE
-5 - Greater Than | dblSeekGT
-7 - Include Equal (OLEDB only) | dblSeekIncludeEQ

The Partially Equal is the default mode, which is the same as incremental search. The search modes can be used to compare strings, numbers and dates. Include Equal mode is used to match a string inside another string and it is supported only for OLEDB version of the list.

See Also

TDBList and TDBCombo Controls


MatchEntry Property

This property returns or sets a value indicating how a TDBList control performs searches based on user input.

Syntax

TDBList.MatchEntry = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList control.

Values

Design Time | Run Time
0 - None (default) | dblMatchEntryNone
1 - Standard | dblMatchEntryStandard
2 - Extended | dblMatchEntryExtended

When set to 0 - None (the default), the control does not perform any incremental searches.

When set to 1 - Standard, the search argument is limited to one character, and the control attempts to find a match for the character entered using the first letter of entries in the list. Repeatedly typing the same letter cycles through all of the entries in the list beginning with that letter.

When set to 2 - Extended, the control searches for an entry matching all characters entered. The search is performed incrementally as characters are typed. This behavior is almost identical to that of a TDBCombo control except that the search argument is cleared when a TDBList control gains focus, or when the user presses Backspace or hesitates for a few seconds.

NOTE: The ListField property determines which column is searched.

See Also

TDBList and TDBCombo Controls


MatchEntryTimeout Property

This property returns or sets a value indicating the timeout value, in milliseconds, for incremental searching when a TDBCombo control's ComboStyle property is set to 2 - Dropdown, or when a TDBList control's MatchEntry property is set to 2 - Extended.

Syntax

object.MatchEntryTimeout = long

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

The search is performed incrementally as characters are typed. If there is no keystroke after this time value, the incremental search will be reset, allowing the user to begin a new search.

For the TDBCombo control, this means that the text entry box is cleared after the timeout period has passed, and new characters may be entered in their place.

For the TDBList control, this means that after the timeout period has passed, the next characters entered will start a new search through the list.

NOTE: The ListField property determines which column is searched.

See Also

TDBList and TDBCombo Controls


Merge Property

This property determines whether adjacent rows of like-valued data are merged within the specified column.

Syntax

column.Merge = boolean

Remarks

Read/Write at run time and design time.

Property applies to Column object.

If True, then adjacent rows of like-valued data are merged into a single noneditable cell.

If False (the default), then all cell values are displayed individually, and editing is permitted (unless otherwise restricted).

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


MinWidth Property

This property returns or sets the minimum width that a column can be sized to when the control is resized and the SpringMode property is True.

Syntax

column.MinWidth = single

Remarks

Read/Write at run time and design time.

Property applies to Column object.

See Also

Column Object, Columns Collection


MouseIcon Property

This property sets or returns the custom mouse icon used when the MousePointer property is set to 99 - Custom.

Syntax

object.MouseIcon = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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:

TDBList1.MouseIcon = LoadPicture("cross.cur")

See Also

TDBList and TDBCombo Controls


MousePointer Property

This property sets or returns a value indicating the type of mouse pointer displayed when the mouse is over the control at run time.

Syntax

object.MousePointer = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Default (default) | dblMPDefault
1 - Arrow | dbMPArrow
2 - Cross | dblMPCross
3 - I-beam | dblMPIbeam
4 - Icon | dblMPIcon
5 - Size | dblMPSize
6 - Size NE SW | dblMPSizeNESW
7 - Size NS | dblMPSizeNS
8 - Size NW SE | dblMPSizeNWSE
9 - Size EW | dblMPSizeEW
10 - Up Arrow | dblMPUpArrow
11 - Hourglass | dblMPHourglass
12 - No Drop | dblMPNoDrop
13 - Arrow Hourglass | dblMPArrowHourglass
14 - Arrow Question | dblMPArrowQuestion
15 - Size All | dblMPSizeAll
99 - Custom | dblMPCustom

When this property is set to 99 - Custom, the MouseIcon property specifies the shape of the mouse pointer.

See Also

TDBList and TDBCombo Controls


MultipleLines Property

This property determines whether a single row can span multiple lines.

Syntax

object.MultipleLines = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Disabled (default) | dblMultipleDisabled
1 - Variable | dblMultipleVariable
2 - Fixed | dblMultipleFixed

In this context, the terms line and row are defined as follows:

•

A line is a single physical row of cells displayed in a TDBList or TDBCombo. Do not confuse this with a line of text inside a control cell; depending upon the settings of the RowHeight and WrapText properties, data in a control 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 control 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 control 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 control will automatically span or wrap the columns to multiple lines so that all columns will be visible within the width of the control. 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 control 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 control may produce additional lines.

If MultipleLines is 2 - Fixed, then changing the width of individual columns or the width of the control 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 control 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.

See Also

TDBList and TDBCombo Controls


MultiSelect Property

This property returns or sets a value indicating whether users can select multiple rows and how selections can be made.

Syntax

TDBList.MultiSelect = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList control.

Values

Design Time | Run Time
0 - None (default) | dblMultiSelectNone
1 - Simple | dblMultiSelectSimple
2 - Extended | dblMultiSelectExtended
3 - Checkbox | dblMultiSelectCheckbox

If the MultiSelect property is 0 - None (the default), multiple selection is prohibited. Only one item in the list can be selected at any time.

If the MultiSelect property is 1 - Simple and the user clicks a row, that row is selected and the SelectedItem property returns a bookmark for that row. If more than one row is selected, the SelectedItem property returns the bookmark of the most recently selected row, and the SelBookmarks collection contains the bookmarks for all selected rows.

If the MultiSelect property is 2 - Extended, pressing Shift and clicking the mouse or pressing Shift and one of the arrow keys (Up Arrow, Down Arrow, Left Arrow, or Right Arrow) extends the selection from the previously selected item to the current item. Pressing Ctrl and clicking the mouse selects or deselects an item in the list. 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.

If the MultiSelect property is 3 - Checkbox, the user can select or unselect rows by clicking checkboxes or clicking the current row to toggle the state of the checkbox.

NOTE: When one of the multiple selection modes is in effect, no updates will occur.

See Also

TDBList and TDBCombo Controls


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.

Property applies to Style object.

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 TDBList or TDBCombo control is first created, its Styles collection contains eight built-in styles named Normal, Heading, Footing, Selected, Caption, HighlightRow, EvenRow, and OddRow.

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


NumberFormat Property

This property returns or sets a value indicating the format string for a control column.

Syntax

column.NumberFormat = string

Remarks

Read/Write at run time and design time.

Property applies to Column object.

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 name can be used:

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


OddRowStyle Property

This property sets or returns the Style object that controls the appearance of an odd-numbered row in a control or split where the AlternatingRowStyle property is set to True.

Syntax

object.OddRowStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

To change the appearance of even-numbered rows, set the EvenRowStyle property.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


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.

Property applies to Column object.

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 control with four columns. To move the last column (index 3) all the way to the left, you would code:

TDBList1.Columns(3).Order = 0

To reverse this action, you would set the order to the number of columns:

TDBList1.Columns(3).Order = TDBList1.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, Columns Collection


OwnerDraw Property

If True, the OwnerDrawCell event will be fired as needed to display the contents of each cell in the associated column.

Syntax

column.OwnerDraw = boolean

Remarks

Read/Write at run time and design time.

Property applies to Column object.

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


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

Property applies to Style object.

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

Set BoldHeading = TDBList1.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, Styles Collection


PartialRightColumn Property

This property determines whether the rightmost column of a control 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.

Property applies to TDBList and TDBCombo controls, Split object.

If True (the default), the rightmost column will be clipped if the control 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 control or split.

If a control contains multiple splits, then setting its PartialRightColumn property has the same effect as setting the PartialRightColumn property of each split individually.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


Presentation Property

This property determines how the members of a ValueItems collection are displayed within the associated column.

Syntax

valueitems.Presentation = value

Remarks

Read/Write at run time and design time.

Property applies to ValueItems collection.

Values

Design Time | Run Time
0 - Normal (default) | dblNormal
1 - Radio Button | dblRadioButton
4 - Check Box | dblCheckBox

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

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 list's PrintInfos collection.

Syntax

TDBList.PrintInfo

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList control.

PrintInfo objects are used to specify page layout and print job characteristics.

See Also

TDBList and TDBCombo Controls


PrintInfos Property

This property returns a collection of PrintInfo objects used to specify page layout and print job characteristics.

Syntax

TDBList.PrintInfos

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList control.

See Also

TDBList and TDBCombo Controls


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.

Property applies to TDBList and TDBCombo controls.

When the RightToLeft property is set to True:

•

Control columns begin at the right boundary of the List.

•

Fixed columns are located on the right side of the Control.

•

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 List 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 (control 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.

•

For TDBCombo, the edit box will be on the right side of the dropdown button.

See Also

TDBList and TDBCombo Controls


Row Property

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.

Syntax

object.Row = integer

Remarks

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

Property applies to TDBList and TDBCombo controls.

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 TDBList 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 TDBCombo control, changing the Row property at run time also changes the value of the SelectedItem property.

See Also

TDBList and TDBCombo Controls


RowCount Property

This property returns or sets the number of rows in a RowBuffer object passed to an unbound event procedure for a TDBList or TDBCombo control.

Syntax

rowbuffer.RowCount = long

Remarks

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

Property applies to RowBuffer object.

In the UnboundReadData event, this property indicates how many rows the control 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.

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 the controls when RowDividerStyle is 7 - Custom Color.

Syntax

object.RowDividerColor = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Colors may be specified as RGB values or system default colors.

See Also

TDBList and TDBCombo Controls


RowDividerStyle Property

This property determines the style of the border drawn between control rows.

Syntax

object.RowDividerStyle = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - No dividers | dblNoDividers
1 - Black line | dblBlackLine
2 - Dark gray line (default) | dblDarkGrayLine
3 - Raised | dblRaised
4 - Inset | dblInset
5 - ForeColor | dblUseForeColor
6 - Light gray line | dblLightGrayLine
7 - Custom Color | dblCustomColor

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

TDBList and TDBCombo Controls


RowHeight Property

This property returns or sets the height of all control rows in terms of the coordinate system of the control's container.

Syntax

object.RowHeight = single

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList1.RowHeight = 0

TDBList1.RowHeight = TDBList1.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 at the left edge of the control.

NOTE: Increasing the RowHeight property does not wrap cell text at column boundaries unless the column's WrapText property is True.

See Also

TDBList and TDBCombo Controls


RowMember Property

This property returns or sets the name of the row member used to populate the list.

Syntax

object.RowMember = string

Remarks

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

Property applies to TDBList and TDBCombo controls (OLE DB only).

Typically, a row member represents a database table or query.

A bound DataSource can expose multiple sets of data that consumers can bind to. Each set of data is called a row member, and is identified by a unique string.

This property is only supported by the OLE DB version of True DBList. It is used only in bound mode and has no effect in unbound or storage modes.

See Also

TDBList and TDBCombo Controls


RowSource Property

Sets a value that specifies the Data control used to fill the rows of a TDBList or TDBCombo control.

Syntax

object.RowSource

Remarks

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

Property applies to TDBList and TDBCombo controls.

Generally, you will use the TDBList and TDBCombo controls with two Data controls: one to fill the list as designated by the RowSource property, and one to update a field in a database as designated by the DataSource and DataField properties.

See Also

TDBList and TDBCombo Controls


RowSubDividerColor Property

This property controls the row subdivider color of the controls when RowDividerStyle is 7 - Custom Color.

Syntax

object.RowSubDividerColor = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Colors may be specified as RGB values or system default colors.

See Also

TDBList and TDBCombo Controls


ScrollBars Property

This property returns or sets a value indicating whether a control or split has horizontal or vertical scroll bars.

Syntax

object.ScrollBars = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

Values

Design Time | Run Time
0 - None | dblNone
1 - Horizontal | dblHorizontal
2 - Vertical | dblVertical
3 - Both | dblBoth
4 - Automatic (default) | dblAutomatic

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 control contains multiple splits, then setting its ScrollBars property has the same effect as setting the ScrollBars property of each split individually.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


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.

Property applies to Split object.

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


ScrollTips Property

The ScrollTips property determines whether the control 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.
Property applies to TDBList and TDBCombo controls.

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 control’s scrollbar thumb is dragged.

If you do not provide a handler for the FetchScrollTips event, tips will not be displayed.

See Also

TDBList and TDBCombo Controls


ScrollTrack Property

If True, moving the scrollbar thumb causes the control’s display to update with new data.

Syntax

object.ScrollTrack = Boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

If False (the default), moving the scrollbar thumb does not change the display.

See Also

TDBList and TDBCombo Controls


SelBookmarks Property

This property returns a collection of selected row bookmarks.

Syntax

object.SelBookmarks

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList control.

See Also

TDBList and TDBCombo Controls


SelectedItem Property

This property returns or sets the bookmark identifying the selected item in a control.

Syntax

object.SelectedItem = variant

Remarks

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

Property applies to TDBList and TDBCombo controls.

Use the value returned by the SelectedItem property to determine the current row in a TDBList or TDBCombo 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 control 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 TDBCombo control, the SelectedItem and Bookmark properties are synonymous.

See Also

TDBList and TDBCombo Controls


SelectedStyle Property

This property returns or sets the Style object that controls the appearance of selected rows and columns within a control or split.

Syntax

object.SelectedStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList control and Split object.

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

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


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.

Property applies to TDBList and TDBCombo controls, Split object.

If no columns are selected, then this property returns -1.

If a control 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 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

TDBList and TDBCombo Controls

Split Object, Splits Collection


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.

Property applies to TDBList and TDBCombo controls, Split object.

If no columns are selected, then this property returns -1.

If a control 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 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

TDBList and TDBCombo Controls

Split Object, Splits Collection


Size Property

This property returns or sets the size of a split. The meaning of the value returned by this property is determined by the split's SizeMode property setting.

Syntax

split.Size = variant

Remarks

Read/Write at run time and design time.

Property applies to Split object.

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 control'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 control's default behavior), the split spans the entire width of the control, the SizeMode property is always 0 - dblScalable, 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, Splits Collection


SizeMode Property

This property determines how the Size property is used to determine the actual size of a split.

Syntax

split.SizeMode = value

Remarks

Read/Write at run time and design time.

Property applies to Split object.

Values

Design Time | Run Time
0 - Scalable (default) | dblScalable
1 - Exact | dblExact
2 - Number of Columns | dblNumberOfColumns

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 control 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 control 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 control'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 control 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 control 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 control's default behavior), the split spans the entire width of the control, the SizeMode property is always 0 - dblScalable, 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, Splits Collection


Split Property

This property specifies the zero-based index of the current split.

Syntax

object.Split = integer

Remarks

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

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


Splits Property

This property returns a collection of Split objects.

Syntax

object.Splits

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


SpringMode Property

When this property is set to True and the control is horizontally resized, the column widths for visible columns will expand and/or shrink proportionally.

Syntax

object.SpringMode = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList.

When set to False (the default), column widths do not change as the control 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

TDBList and TDBCombo Controls


Style Property

This property returns or sets the Style object that controls the normal appearance of a cell within a control, column, or split.

Syntax

object.Style = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Column and Split objects.

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

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


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.

Property applies to TDBList and TDBCombo controls.

When a control is first created, it contains eight 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

Control and split caption bars

HighlightRow

Data cells in highlighted rows

EvenRow

Data cells in even numbered rows

OddRow

Data cells in odd numbered rows

NOTE: At design time, use the Style Factory property page to modify these built-in styles or create your own named styles.

See Also

TDBList and TDBCombo Controls


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

See Also

Column Object, Columns Collection


Text Property

When applied to a Column object, this property returns or sets the formatted data value in a column for the current row.

Syntax

object.Text = string

Remarks

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

Property applies to TDBList and TDBCombo controls, Column object.

This is the default property of the TDBList and TDBCombo controls.

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.

For TDBList controls this property returns the ListField value for the selected row. When the Text property is set in code, the control tries to find a matching ListField value and repositions the selected row if a match is found. If no match is found, the selection is cancelled and the Text property returns an empty string.

For TDBCombo controls, this property returns or sets the contents of the text box portion of the control.

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection


Top Property

This property returns the position of a column's top edge relative to the top of the control in terms of the coordinate system of the control's container.

Syntax

column.Top

Remarks

Read-only at run time. Not available at design time.

Property applies to Column object.

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 control's MultipleLines property is 0 - Disabled (the default value), a single record cannot span multiple lines in the control, and the Top property returns the same value for all columns.

If the control's MultipleLines property is either 1 - Variable or 2 - Fixed, a single record may span multiple lines in the control. For columns on the first line, the Top property returns the height of the control'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 control.

For example, the following code places a text box on top of the header for the first column:

Text1.Top = TDBList1.Top + TDBList1.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, Columns Collection


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.

Property applies to ValueItems collection.

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.

Property applies to Style object.

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

Property applies to Column object.

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


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 TDBList or TDBCombo control.

Syntax

rowbuffer.Value (Row, Col) = variant

Remarks

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

Property applies to RowBuffer object.

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.

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.

Property applies to Style object.

For style objects, the Value property is a synonym for the Name property, so the following statements are equivalent:

Debug.Print TDBList1.Styles(0)

Debug.Print TDBList1.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, Styles Collection


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.

Property applies to ValueItem object.

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 Collection


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.

Property applies to Column object.

NOTE: At design time, use the Values property page to populate a column's ValueItems collection.

See Also

Column Object, Columns Collection


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

Remarks

Read/Write at run time and design time.

Property applies to Style object.

Values

Design Time | Run Time
0 - Top (default) | dblTop
1 - Bottom | dblBottom
2 - Vertical Center | dblVertCenter

Use the Alignment property to control horizontal alignment.

See Also

Style Object, Styles Collection


Visible Property

This property returns a boolean indicating whether a column in a control 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.

Property applies to Column object.

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


VisibleCols Property

For TDBlist controls, this property returns the number of visible columns in the current split.

Syntax

object.VisibleCols

Remarks

Read-only at run time.

Property applies to TDBlist and TDBCombo controls.

The value returned includes both fully and partially displayed columns. You can use the Split property of the control to determine the index of the current split.

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

TDBList and TDBCombo Controls


VisibleRows Property

This property returns the number of visible rows in the control. The value returned includes both fully and partially displayed rows.

Syntax

object.VisibleRows = integer

Remarks

Read-only at run time.

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


VScrollWidth Property

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.

Syntax

object.VScrollWidth

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

If no vertical scroll bar exists, then the returned value is zero. If object is a TDBList or TDBCombo 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 control layout and sizing the control and its columns.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


Width Property

This property returns or sets the width of a column in terms of the coordinate system of the control's container.

Syntax

column.Width = single

Remarks

Read/Write at run time and design time.

Property applies to Column object.

Use the Width property in conjunction with Left, RowHeight, and RowTop to determine the size and placement of controls displayed on top of a control cell.

NOTE: The DefColWidth property controls the default width of new columns created at run time.

See Also

Column Object, Columns Collection


WrapText Property

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

Syntax

style.WrapText = boolean

Remarks

Read/Write at run time and design time.

Property applies to Style object.

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

Style Object, Styles Collection


TDBList Methods

AboutBox Method

Add Method

AddItem Method

AddRegexCellStyle Method

AutoSize Method

CaptureImage Method

CellContaining Method

CellText Method

CellValue Method

Clear Method (DataObject)

Clear Method (PrintInfos)

ClearFields Method

ClearRegexCellStyle Method

ClearSelCols Method

ColContaining Method

ExportBegin Method

ExportEnd Method

ExportRows Method

ExportToDelimitedFile Method

ExportToFile Method

Find Method

GetData Method

GetFormat Method

GetBookmark Method

HoldFields Method

Item Method

LoadLayout 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

RemoveItem Method

Reset Method

RowBookmark Method

RowContaining Method

RowTop Method

Scroll Method

SetData Method

SplitContaining Method


AboutBox Method

This method displays the version number and copyright notice for the specified control.

Syntax

object.AboutBox

Arguments

None

Return Value

None

Remarks

Method applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


Add Method

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.

Syntax

object.Add (item)

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

Method applies to Columns, GroupColumns, Layouts, PrintInfos, SelBookmarks, Splits, Styles, and ValueItems collections.

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 control layout to be saved to the binary layout file specified by the LayoutFileName property. All of the control'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

GroupColumns Object

Layouts Object

PrintInfo Object, PrintInfos Collection

SelBookmarks Object

Split Object, Splits Collection

Style Object, Styles Collection

ValueItem Object, ValueItems Collection


AddItem Method

This method adds an item to a the TDBList or TDBCombo object.

Syntax

object.AddItem strItem, [strValue], [nIndex]

Arguments

strItem specifies the display text of the item.

strValue specifies a string for the VALUE attribute of the item.

nIndex is an integer that specifies the item's position within the list.

Return Value

None

Remarks

Method applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


AddRegexCellStyle Method

This method allows you to control the font and color of cells within a control, column, or split according to their contents.

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

Method applies to TDBList and TDBCombo controls, Column and Split objects.

The status values (CellStyleConstants) specified by the condition argument determine which cells are affected:

1 - dblCurrentCell

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.

4 - dblUpdatedCell

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

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

The cell satisfies none of these conditions.

-1 - dblAllCells

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 (dblCurrentCell + dblSelectedRow) denotes a current cell within a selected row. You can also use a cell status value of 0 (dblNormalCell) 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 (dblAllCells).

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 DBList 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 TrueDBControl80.Style

S.Font.Bold = True
TDBList1.AddRegexCellStyle dblNormalCell, 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 control, 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

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


AutoSize Method

The AutoSize method adjusts the width of a column to accommodate the longest visible field within that column.

Syntax

column.AutoSize

Arguments

None

Return Value

None

Remarks

Method applies to Column object.

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

TDBList and TDBCombo Controls


CaptureImage Method

This method returns an image of the control in a format that you can assign to the Picture (Visual Basic) property of a Visual Basic form or control, or the PaintPicture (Printer object) method of the Printer (Visual Basic) object.

Syntax

object.CaptureImage

Arguments

None

Return Value

A picture object containing a snapshot of the control's display.

Remarks

Method applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


CellContaining Method

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.

Syntax

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

Method applies to TDBList and TDBCombo controls.

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

If the specified coordinate is outside of the control's data area, this method returns False. You can use the PointAt method to determine what kind of control 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

TDBList and TDBCombo Controls


CellText Method

The CellText method returns a formatted string representation of the data in a column for the row specified by the bookmark argument.

Syntax

column.CellText (bookmark)

Arguments

bookmark is a variant representing a control row.

Return Value

A string containing the displayed column text for the specified row.

Remarks

Method applies to Column object.

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

TDBList and TDBCombo Controls


CellValue Method

The CellValue method returns the raw data value in a column for the row specified by the bookmark argument.

Syntax

column.CellValue (bookmark)

Arguments

bookmark is a variant representing a control row.

Return Value

A variant containing the underlying data value for the specified row.

Remarks

Method applies to Column object.

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

TDBList and TDBCombo Controls


Clear Method (DataObject)

This method deletes the contents of a DataObject object.

Syntax

dataobject.Clear

Arguments

None

Return Value

None

Remarks

Method applies to DataObject object.

The TDBCombo 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 combo 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

TDBList and TDBCombo Controls


Clear Method (PrintInfos)

For a ValueItems collection associated with a Column object, the Clear method removes all of its ValueItem objects.

Syntax

object.Clear

Arguments

None

Return Value

None

Remarks

Method applies to PrintInfos and ValueItems collections.

For a PrintInfos collection associated with a control, the Clear method removes all of its PrintInfo objects, then re-creates the default PrintInfo object.

See Also

TDBList and TDBCombo Controls


ClearFields Method

The ClearFields method restores the default control 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

Method applies to TDBList and TDBCombo controls.

You can cancel the control's automatic layout behavior by invoking the HoldFields method.

See Also

TDBList and TDBCombo Controls


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

Method applies to TDBList and TDBCombo controls, Column and Split objects.

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

TDBList and TDBCombo Controls


ClearSelCols Method

The ClearSelCols method deselects all columns in a split.

Syntax

object.ClearSelCols

Arguments

None

Return Value

None

Remarks

Method applies to TDBList and TDBCombo controls, Split object.

If no columns are selected, then this method does nothing.

If a control 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 control's Split property.

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

See Also

TDBList and TDBCombo Controls


ColContaining Method

The ColContaining method returns the ColIndex value of the control column containing the specified coordinate.

Syntax

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

Method applies to TDBList control.

This value ranges from 0 to Columns.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 control column.

If coordinate is outside of the control'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

TDBList and TDBCombo Controls


ExportBegin Method

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

Syntax

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

Method applies to TDBList control.

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
TDBList1.ExportBegin
Else
TDBList1.ExportBegin Request.Cookies("user"))
End If

' Export ten rows, overwriting the file's contents

TDBList1.ExportRows FileName, False, 10

' Store the next bookmark in the "user" cookie
Response.Cookies("user") = TDBList1.ExportNextBookmark

' Terminate the export operation and redirect the

' browser to the file containing the HTML table.
TDBList1.ExportEnd
Response.Redirect FileName
End Sub

See Also

TDBList and TDBCombo Controls


ExportEnd Method

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

Syntax

TDBList.ExportEnd

Arguments

None

Return Value

None

Remarks

Method applies to TDBList control.

See Also

TDBList and TDBCombo Controls


ExportRows Method

The ExportRows method exports a sequence of rows from the control to the specified file as an HTML table.

Syntax

TDBList.ExportRows pathname, append, rows, [tablewidth]

Arguments

pathname specifies the file to which list 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

Method applies to TDBList control.

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 control caption. The output preserves as much of the control's original formatting as possible, including colors, fonts, alignment, and relative column widths.

See Also

TDBList and TDBCombo Controls


ExportToDelimitedFile Method

The ExportToDelimitedFile method exports the specified rows from the control to the specified file as delimited ASCII text, where each row (record) occupies its own line.

Syntax

TDBList.ExportToDelimitedFile pathname, [delim], [selector], [prefix], [suffix]

Arguments

pathname specifies the file to which list 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

Method applies to TDBList control.

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

All available rows are exported. If the selector argument is omitted, this value is assumed.

1 - dblRSSelectedRows

Only selected rows are exported. The control's SelBookmarks collection contains a bookmark for each selected row.

2 - dblRSCurrentRow

Only the current row is exported.

See Also

TDBList and TDBCombo Controls


ExportToFile Method

The ExportToFile method exports the specified rows from the control to the specified file as an HTML table.

Syntax

TDBList.ExportToFile pathname, append, [selector], [tablewidth]

Arguments

pathname specifies the file to which list 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

Method applies to TDBList control.

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

All available rows are exported. If the selector argument is omitted, this value is assumed.

1 - dblRSSelectedRows

Only selected rows are exported. The control's SelBookmarks collection contains a bookmark for each selected row.

2 - dblRSCurrentRow

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

TDBList and TDBCombo Controls


Find Method

This method will find the Bookmark of the row using the searchMode and the searchStr.

Syntax

column.Find (searchStr, searchMode, includeStart, [startBmk])

Arguments

SearchStr is a String or a number to search for.

SearchMode is the comparing mode for search, it may take the following values:

-1. dblSeekLT --- find the first match such that the column value is less than searchStr.

-2. dblSeekLE --- find the first match such that the column value is less than or equal to searchStr.

-3. dblSeekEQ --- find the first match such that the column value is equal to searchStr.

-4. dblSeekGE --- find the first match such that the column value is greater than or equal to searchStr.

-5. dblSeekGT --- find the first match such that the column value is greater than searchStr.

-6. dblSeekPartialEQ --- find the first match such that searchStr is the leading part of the column string, for example, “ab” is the leading part of “abstract”.

-7. dblSeekIncludeEQ --- Finds the first match such that the searchStr is included somewhere within the column string, for example, “put” is within the column string “computer”. (NOTE: This SearchMode is only available in OLEDB.)

IncludeStart takes values TRUE or FALSE. If the value is TRUE, the search will start from the startBmk, otherwise the search will start from the row right after the startBmk

StartBmk is the bookmark of the row where search starts. This argument is optional, if it does not appear, the startBmk will be the first row on the control.

Return Value

Return value is the Bookmark of row where the first match is found if the search is successful, otherwise return NULL.

Remarks

Method applies to Column object.

This method can be used for bounded, unbounded and storage mode.

See Also

TDBList and TDBCombo Controls


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

Method applies to DataObject object.

The TDBCombo control supplies an argument of type DataObject when it fires the following events: OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.

NOTE: In this version of True DBList, only the vbCFText format is supported. If you supply an argument of zero, vbCFText is assumed.

See Also

TDBList and TDBCombo Controls


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

Method applies to DataObject object.

The TDBCombo control supplies an argument of type DataObject when it fires the following events: OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.

NOTE: In this version of True DBList, only the vbCFText format is supported. This constant has a value of 1 in Visual Basic.

See Also

DataObject Object, DataObjectFiles Collection


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

Method applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


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

Method applies to TDBList and TDBCombo controls.

You can resume the control'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

TDBList and TDBCombo Controls


Item Method

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

Syntax

object.Item (index)

Arguments

index is an expression that specifies the collection member to be accessed.

Return Value

A reference to the specified object.

Remarks

Method applies to Columns, GroupColumns, Layouts, PrintInfos, SelBookmarks, Splits, Styles, and ValueItems collections.

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:

TDBList1.Columns(0)

TDBList1.Columns.Item(0)

See Also

Column Object, Columns Collection

GroupColumns Object

Layouts Object

PrintInfo Object, PrintInfos Collection

SelBookmarks Object

Split Object, Splits Collection

Style Object, Styles Collection

ValueItem Object, ValueItems Collection


LoadLayout Method

The LoadLayout method loads a previously saved control layout from a binary layout storage file and configures the control accordingly.

Syntax

object.LoadLayout

Arguments

None

Return Value

None

Remarks

Method applies to TDBList and TDBCombo controls.

You can use this method to easily switch to a predefined control 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 control 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

TDBList and TDBCombo Controls


PointAt Method

The PointAt method returns one of the constants in the preceding list, which indicates the kind of control element beneath the specified coordinate pair.

Syntax

object.PointAt (x, y)

Arguments

x and y are singles that define a coordinate pair in twips.

Return Value

Remarks

Method applies to TDBList and TDBCombo controls.

Run Time

0 - Not in List | dblNotInList
1 - At List Caption | dblAtCaption
2 - At Split Header | dblAtSplitHeader
3 - At Split Size Box | dblAtSplitSizeBox
4 - At Row Select | dblAtRowSelect
5 - At Row Size | dblAtRowSize
6 - At Column Header | dblAtColumnHeader
7 - At Column Footer | dblAtColumnFooter
8 - At Column Size | dblAtColumnSize
9 - At Data Area | dblAtDataArea

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

TDBList and TDBCombo Controls


PostMsg Method

The PostMsg method is used in conjunction with the PostEvent event to postpone operations which are illegal within the control's events.

Syntax

object.PostMsg MsgId

Arguments

MsgId is an integer that identifies the message being posted.

Return Value

None

Remarks

This method applies to TDBList and TDBCombo controls.

If the PostMsg method is called, the control 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.

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

TDBList and TDBCombo Controls


ReBind Method

This method re-establishes the connection with the bound data source, causing the TDBList or TDBCombo 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

Method applies to TDBList and TDBCombo controls.

If you have not modified the control 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 control will assume that you wish to maintain the modified control layout and will not automatically reset the columns.

For an unbound control 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 control with records from the unbound data source. After the control has finished refilling its cache, it fires the FirstRowChange event.

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 control 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 control's automatic layout response and force the control 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

TDBList and TDBCombo Controls


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

Method applies to Column object.

It also repaints the column's visible cells, firing all events necessary for redisplay.

By default, the control 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, Columns Collection


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

Method applies to Column object.

It also repaints the cell, firing all events necessary for redisplay.

By default, the control 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, Columns Collection


RefetchCol Method

The RefetchCol method repopulates the specified column from a data source control and/or unbound events.

Syntax

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

Method applies to TDBList control.

It also repaints the column's visible cells, firing all events necessary for redisplay.

By default, the control 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

TDBList and TDBCombo Controls


RefetchRow Method

The RefetchRow method repopulates the specified row from a data source control and/or unbound events.

Syntax

TDBList.RefetchRow [bookmark]

Arguments

The bookmark parameter 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

Method applies to TDBList control.

It also repaints the row, firing all events necessary for redisplay.

By default, the control 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

TDBList and TDBCombo Controls


Refresh Method

For a TDBList or TDBCombo 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

Method applies to TDBList and TDBCombo controls, Column object.

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

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection


RefreshCell Method

The RefreshCell method repaints the specified cell.

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

Method applies to Column object.

Normally, the control repaints automatically as needed. 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, Columns Collection


RefreshCol Method

The RefreshCol method repaints the visible cells in the specified column.

Syntax

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

Method applies to TDBList control.

Normally, the list 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

TDBList and TDBCombo Controls


RefreshRow Method

The RefreshRow method repaints the specified row.

Syntax

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

Method applies to TDBList control.

Normally, the list 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

TDBList and TDBCombo Controls


Remove Method

Use the Remove method to delete a specific member of a True DBList collection.

Syntax

object.Remove (index)

Arguments

index is an expression that specifies the collection member to be removed.

Return Value

None

Remarks

Method applies to Columns, GroupColumns, Layouts, PrintInfos, SelBookmarks, Splits, Styles, and ValueItems collections.

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

GroupColumns Object

Layouts Object

PrintInfo Object, PrintInfos Collection

SelBookmarks Object

Split Object, Splits Collection

Style Object, Styles Collection

ValueItem Object, ValueItems Collection


RemoveItem Method

This method removes an item to a the TDBList or TDBCombo object.

Syntax

object.RemoveItem [nIndex]

Arguments

nIndex is an integer that specifies the item's position within the list. The index is zero-based.

Return Value

None

Remarks

Method applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


Reset Method

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

Syntax

style.Reset

Method applies to Style object.

Arguments

None

Return Value

None

Remarks

Method applies to Style object.

See Also

TDBList and TDBCombo Controls

Style Object, Styles Collection


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

Method applies to TDBList and TDBCombo controls.

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 control's Bookmark property) if the current row is visible and the rownumber argument is equal to the control'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

TDBList and TDBCombo Controls


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

Method applies to TDBList and TDBCombo controls.

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

If coordinate is outside of the control'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

TDBList and TDBCombo Controls


RowTop Method

The RowTop method returns the Y coordinate of the top of a visible row relative to the top of the control, as given by the control'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 control's container.

Remarks

Method applies to TDBList and TDBCombo controls.

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

See Also

TDBList and TDBCombo Controls


Scroll Method

This method scrolls the control 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

Method applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


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

Method applies to DataObject object.

The TDBCombo control supplies an argument of type DataObject when it fires the following events: OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag.

NOTE: In this version of True DBList, only the vbCFText format is supported. If you omit the format argument, vbCFText is assumed.

See Also

DataObject Object, DataObjectFiles Collection


SplitContaining Method

The SplitContaining method returns the Index value of the split containing the specified coordinate pair.

Syntax

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

Method applies to TDBList and TDBCombo controls.

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

If either argument is outside of the control'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

TDBList and TDBCombo Controls


TDBList Events

ClassicRead Event

Click Event

ColMove Event

ColResize Event

DblClick Event

DragCell Event

Error Event

FetchCellStyle Event

FetchCellTips Event

FetchRowStyle Event

FetchScrollTips Event

FirstRowChange 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

OnInit Event

OwnerDrawCell Event

OwnerDrawCellPrint Event

Paint Event

PostEvent Event

RowChange Event

RowResize Event

RowSourceChanged Event

Scroll Event

SelChange Event

UnboundColumnFetch Event

UnboundFindData Event

UnboundGetRelativeBookmark Event

UnboundReadData Event

UnboundReadDataEx Event


ClassicRead Event

The ClassicRead event is fired when an unbound control (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 control.

Remarks

Event applies to TDBList and TDBCombo controls.

To return an unbound value to the control, simply set the Value argument to the desired result. If you do not assign a value, the cell will remain blank.

See Also

TDBList and TDBCombo Controls


Click Event

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

Syntax

object_Click ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

Clicking a control also generates MouseDown and MouseUp events in addition to the Click event. The order of events for both the TDBList and TDBCombo controls is MouseDown, MouseUp, and Click.

When the user clicks a noncurrent row, the Click event fires before the control attempts to reposition to the row that was clicked. If the attempt succeeds, the control then fires the 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

TDBList and TDBCombo Controls


ColMove Event

The ColMove event occurs when the user has finished moving the selected columns.

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

Event applies to TDBList and TDBCombo controls.

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.

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

TDBList and TDBCombo Controls


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

Event applies to TDBList and TDBCombo controls.

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 control to be repainted even if the Cancel argument is True.

See Also

TDBList and TDBCombo Controls


DblClick Event

The DblClick event occurs when the user presses then releases a mouse button twice in rapid succession over the control.

Syntax

object_DblClick ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

Double clicking a control also generates MouseDown, MouseUp, and Click events in addition to the DblClick event. The order of events for the control is MouseDown, MouseUp, Click, DblClick, and MouseUp.

See Also

TDBList and TDBCombo Controls


DragCell Event

The DragCell event is triggered when the user presses the left mouse button and starts dragging the mouse.

Syntax

TDBList_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

Event applies to TDBList control.

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 control's Drag (Visual Basic) method.

See Also

TDBList and TDBCombo Controls


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

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


FetchCellStyle Event

The FetchCellStyle event occurs when the control is about to display cell data in a column whose FetchStyle property is set to True.

Syntax

object_FetchCellStyle (ByVal Condition As Integer, ByVal Split As Integer, Bookmark As Variant, ByVal Col As Integer, ByVal CellStyle As TrueDBList80.StyleDisp)

TDBDropDown_FetchCellStyle (ByVal Condition As Integer, Bookmark As Variant, ByVal Col As Integer, ByVal CellStyle As TrueDBList80.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.

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

Event applies to TDBList and TDBCombo controls.

By setting one or more properties of the Style object passed in the CellStyle parameter, your application can change the appearance of individual cells.

See the CellTip constants for a list of allowable values.

You can also set the ForegroundPicture property of the CellStyle parameter to display distinct bitmaps on a per-cell basis.

See Also

TDBList and TDBCombo Controls


FetchCellTips Event

If the CellTips property is not set to 0 - None, the FetchCellTips event will be fired whenever the control has focus and the cursor is idle for a small amount of time (defined by the CellTipsDelay property) over a data cell, column header, column footer, split header, or control caption bar.

Syntax

object_FetchCellTips (ByVal SplitIndex As Integer, ByVal ColIndex As Integer, ByVal RowIndex As Long, CellTip As String, ByVal FullyDisplayed As Boolean, ByVal TipStyle As TrueDBList80.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

Event applies to TDBList and TDBCombo controls.

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 control 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 control column, ColIndex will be negative and equal to one of the following CellTipConstants, depending upon the cursor position:

dblOnEmptyColumn

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:

dblOnColumnHeader

Cursor is over a column header

dblOnSplitHeader

Cursor is over a split header

dblOnEmptyRow

Cursor is over the empty rows area (if EmptyRows is True) or the blank area (if EmptyRows is False)

dblOnCaption

Cursor is over the control caption

dblOnAddNew

Cursor is over the AddNew row

dblOnColumnFooter

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 control 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 row, 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 control'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

TDBList and TDBCombo Controls


FetchRowStyle Event

Syntax

object_FetchRowStyle (ByVal Split As Integer, Bookmark As Variant, ByVal RowStyle As TrueDBList80.StyleDisp)

TDBDropDown_FetchRowStyle (Bookmark As Variant, ByVal RowStyle As TrueDBList80.StyleDisp)

Arguments

Split is the zero-based index of the split for which formatting information is being requested.

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

Remarks

Event applies to TDBList and TDBCombo controls.

The FetchRowStyle event is fired whenever the control is about to display a row of data, but only if the FetchRowStyle property is True for the control or one of its splits.

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

TDBList and TDBCombo Controls


FetchScrollTips Event

If the ScrollTips property is True, the FetchScrollTips event will be fired whenever the control has focus and the scrollbar thumb is moved using the mouse.

Syntax

TDBlist_FetchScrollTips (ByVal SplitIndex As Integer, ByVal ColIndex as Integer, Bookmark As Variant, ByVal ScrollBar as ScrollBarsConstants, ScrollTip As String, ByVal TipStyle As TrueOleDBList70.StyleDisp)

TDBCombo_FetchScrollTips (ByVal ColIndex as Integer, Bookmark As Variant, ByVal ScrollBar as ScrollBarsConstants, ScrollTip As String, ByVal TipStyle As TrueOleDBList70.StyleDisp)

Arguments

SplitIndex is the zero-based index of the split that the scrollbar is associated with.

ColIndex is the leftmost column in the current split.

Bookmark is a variant that uniquely identifies the topmost control 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.

Remarks

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


FirstRowChange Event

The FirstRowChange event occurs when the first displayed row of a control or split is changed.

Syntax

object_FirstRowChange (ByVal SplitIndex As Integer)

TDBDropDown_FirstRowChange ( )

Arguments

SplitIndex is the zero-based index of the split in which the row change occurred.

Remarks

Event applies to TDBList and TDBCombo controls.

This event is triggered under several circumstances:

•

When the control is first displayed.

•

When the user scrolls through the control with the vertical scroll bar or navigation keys.

•

When data in the control 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 FirstRowChange, LeftColChange, and RowChange.

See Also

TDBList and TDBCombo Controls


FootClick Event

The FootClick event occurs when the user clicks on the footer for a particular control column.

Syntax

object_FootClick (ColIndex As Integer)

Arguments

ColIndex is an integer that identifies the column footer that was clicked.

Remarks

Event applies to TDBList and TDBCombo controls.

One possible action for this event is to re-sort the Recordset (Data control) object based on the selected column.

See Also

TDBList and TDBCombo Controls


FormatText Event

The FormatText event occurs when the control is about to display cell data in a column whose NumberFormat property is set to the string FormatText Event.

Syntax

object_FormatText (ColIndex As Integer, Value As Variant)

Arguments

ColIndex is an integer that identifies the column being displayed.

Value is a variant containing the underlying data value.

Remarks

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


GroupColMove Event

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

Syntax

TDBList_GroupColMove (ByVal Position As Integer, 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 TDBList 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 list.

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.

See Outlook-Style Grouping for more information.

See Also

TDBList and TDBCombo Controls


GroupHeadClick Event

The GroupHeadClick event occurs when the user clicks on the header for a particular list column in the grouping area.

Syntax

TDBList_GroupHeadClick (ColIndex As Integer)

Arguments

ColIndex is an integer that identifies the column header that was clicked.

Remarks

Event applies to TDBList control (OLE DB only).

One possible action for this event is to re-sort the Recordset (Data control) object based on the selected column.

See Outlook-Style Grouping for more information.

See Also

TDBList and TDBCombo Controls


HeadClick Event

The HeadClick event occurs when the user clicks on the header for a particular control column.

Syntax

object_HeadClick (ColIndex As Integer)

Arguments

ColIndex is an integer that identifies the column header that was clicked.

Remarks

Event applies to TDBList and TDBCombo controls.

One possible action for this event is to re-sort the Recordset (Data control) object based on the selected column.

See Also

TDBList and TDBCombo Controls


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

Event applies to TDBList and TDBCombo controls.

Although the KeyUp and KeyDown events are fired for most keystrokes, they are 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

TDBList and TDBCombo Controls


KeyPress Event

Use the KeyPress event to test keystrokes for validity or to format characters as they are typed.

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 control. Changing KeyAscii to 0 cancels the keystroke so the control receives no character.

Remarks

Event applies to TDBList and TDBCombo controls.

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.

See Also

TDBList and TDBCombo Controls


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

Event applies to TDBList and TDBCombo controls.

Although the KeyUp and KeyDown events are fired for most keystrokes, they are 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

TDBList and TDBCombo Controls


LayoutReady Event

The LayoutReady event fires when asynchronous downloading of a control layout file has completed.

Syntax

object_LayoutReady ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

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 control 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 control on an HTML page.

In either case, the control 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:

TDBList1.LayoutName = "MyLayout"

TDBList1.LoadLayout

NOTE: You can create control layout files at design time by setting the LayoutFileName and LayoutName properties and using the layout commands on the control's visual editing menu.

See Also

TDBList and TDBCombo Controls


LeftColChange Event

The LeftColChange event occurs when the first visible column of a control is changed.

Syntax

object_LeftColChange ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

This event is triggered under several circumstances:

•

When the control is first displayed.

•

When the user scrolls through the control 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 FirstRowChange, LeftColChange, and RowChange.

See Also

TDBList and TDBCombo Controls


MouseDown Event

Use a MouseDown or MouseUp event procedure to specify actions that will occur when a given mouse button is pressed or released.

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 control's container.

Remarks

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


MouseMove Event

The MouseMove event is generated continually as the mouse pointer moves across the control.

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 control's container.

Remarks

Event applies to TDBList and TDBCombo controls.

This event is primarily useful for implementing drag-and-drop behavior on a per-column basis.

See Also

TDBList and TDBCombo Controls


MouseUp Event

Use a MouseDown or MouseUp event procedure to specify actions that will occur when a given mouse button is pressed or 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 control's container.

Remarks

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


OnInit Event

The OnInit event occurs after the list is initially loaded.

Syntax

TDBList_OnInit ( )

Arguments

None

Remarks

Event applies to TDBList control.

This event precedes RowSourceChanged as well as the unbound events. You can always use this event to initialize the list independent of its container.

See Also

TDBList and TDBCombo Controls


OwnerDrawCell Event

The OwnerDrawCell event occurs just before the cell specified by the Bookmark, Col, and Split arguments is to be painted.

Syntax

object_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

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


OwnerDrawCellPrint Event

The OwnerDrawCellPrint event occurs just before the cell specified by the Bookmark, Col, and Split arguments is to be printed.

Syntax

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

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

Event applies to TDBList control.

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

TDBList and TDBCombo Controls


Paint Event

The Paint event is triggered whenever the control repaints itself (that is, whenever it receives a WM_PAINT message).

Syntax

object_Paint ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

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 control's hWnd property to paint special effects such as lines, bitmaps, and icons in appropriate cells of the control.

See Also

TDBList and TDBCombo Controls


PostEvent Event

The PostEvent event is used in conjunction with the PostMsg method to postpone operations that are illegal within the control's events.

Syntax

object_PostEvent (ByVal MsgId As Integer)

Arguments

MsgId is an integer that identifies the message posted by the PostMsg method.

Remarks

Event applies to TDBList and TDBCombo controls.

If the PostMsg method is called, the control 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.

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

TDBList and TDBCombo Controls


RowChange Event

The RowChange event occurs when the current row changes to a different row.

Syntax

TDBList_RowChange ( )

Arguments

None

Remarks

Event applies to TDBList control.

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

TDBList and TDBCombo Controls


RowResize Event

The RowResize event occurs when the user has finished resizing a control row.

Syntax

object_RowResize (Cancel As Integer)

Arguments

Cancel is an integer that may be set to True to undo resizing.

Remarks

Event applies to TDBList and TDBCombo controls.

Your event procedure can accept the change, alter the degree of change, or cancel the change completely.

The 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 control to be repainted even if the Cancel argument is True.

See Also

TDBList and TDBCombo Controls


RowSourceChanged Event

The RowSourceChanged event fires when a bound data source is changed or requeried.

Syntax

object_RowSourceChanged ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

This event also fires when a bound control is first loaded.

The RowSourceChanged event fires before the control is filled with data. Therefore, you can use this event to initialize the control 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 DBCombo, you can use the RowSourceChanged event in conjunction with the BookmarkType property to circumvent type mismatch errors that may occur when a control-supplied bookmark is passed to an ADO Recordset object (or vice versa). The workaround is as follows:

Sub TDBList1_DataSourceChanged()

TDBList1.BookmarkType = VarType(ADODC1.Recordset.Bookmark)

End Sub

This code ensures that any bookmarks returned by the combo are first converted to the appropriate type for the bound data source. This workaround is only needed when using the combo in an HTML page; it is not needed for Visual Basic 6.0.

See Also

TDBList and TDBCombo Controls


Scroll Event

The Scroll event occurs when the user scrolls the control 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

Event applies to TDBList and TDBCombo controls.

This event is fired before the control 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 control 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 control'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 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

TDBList and TDBCombo Controls


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

Event applies to TDBList and TDBCombo controls.

This event is triggered under several circumstances:

•

When the user selects a single row.

•

When the user adds a row to the list of selected rows by clicking it 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.

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

TDBList and TDBCombo Controls


UnboundColumnFetch Event

The UnboundColumnFetch event is fired when a bound control (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

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

Remarks

Event applies to TDBList and TDBCombo controls.

For a bound control, 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 control, 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.

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 control contains one or more unbound columns.

During the execution of this event, row movement is not permitted.

See Also

TDBList and TDBCombo Controls


UnboundFindData Event

When a list or combo control is activated, it will attempt to position to the record that matches the current cell text of its parent control.

Syntax

object_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 list or combo control 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

Event applies to TDBList and TDBCombo controls.

To do this, the control will fire the UnboundFindData event, which allows you to set the current record position within the control.

The SeekFlags argument specifies how to compare the Value argument to dropdown column data:

dblSeekLT

Find first column data less than Value

dblSeekLE

Find first column data less than or equal to Value

dblSeekEQ

Find first column data equal to Value

dblSeekGE

Find first column data greater than or equal to Value

dblSeekGT

Find first column data greater than Value

dblSeekPartialEQ

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

TDBList and TDBCombo Controls


UnboundGetRelativeBookmark Event

This event is used in conjunction with the UnboundReadData or ClassicRead events when the control needs to obtain positional information about your underlying data.

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

Event applies to TDBList and TDBCombo controls.

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.

By coding this event for DataMode setting 1 - Unbound, you can dramatically improve the performance of the control. 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 control of BOF/EOF conditions.

See Also

TDBList and TDBCombo Controls


UnboundReadData Event

The UnboundReadData event is fired when an unbound control (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 control display.

Syntax

object_UnboundReadData (ByVal RowBuf As TrueDBList80.RowBuffer, StartLocation As Variant, ByVal ReadPriorRows As Boolean)

Arguments

RowBuf is a RowBuffer object used to transfer row data to the control.

StartLocation is a variant bookmark that identifies the row to position to before fetching the next or previous page of records. If Null, the control 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 control is requesting records that precede StartLocation. If False, the control is requesting records that follow StartLocation.

Remarks

Event applies to TDBList and TDBCombo controls.

The RowBuf argument acts like a two-dimensional array of variants corresponding to the control cells being fetched. By populating its Value property with the appropriate data, your event procedure transfers rows from the unbound dataset to the control.

Use the row buffer's RowCount property to determine how many rows of data the control 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 control by populating the row buffer's Bookmark property for each row returned. Keep in mind that the bookmark-based TDBList 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 control 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 DBList 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 control performs accurately with large multi-user databases.

See Also

TDBList and TDBCombo Controls


UnboundReadDataEx Event

The UnboundReadDataEx event is fired when an unbound control (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 control display.

Syntax

object_UnboundReadDataEx (ByVal RowBuf As TrueDBList80.RowBuffer, StartLocation As Variant, ByVal Offset As Long, ApproximatePosition As Long)

Arguments

RowBuf is a RowBuffer object used to transfer row data to the control.

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

Event applies to TDBList and TDBCombo controls.

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 control cells being fetched. By populating its Value property with the appropriate data, your event procedure transfers rows from the unbound dataset to the control.

Use the row buffer's RowCount property to determine how many rows of data the control is requesting. Use its ColumnCount property to determine the number of columns to be populated, if any. If ColumnCount is zero, the control is requesting the bookmark of a single row; if ColumnCount is nonzero, the control is requesting RowCount rows of data and their corresponding bookmarks.

The ColumnIndex property specifies the control 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 control by populating the row buffer's Bookmark property for each row returned. Keep in mind that the bookmark-based TDBList 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 control 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

TDBList and TDBCombo Controls


TDBCombo Reference

TDBCombo Members

TDBCombo Control Properties

TDBCombo Methods

TDBCombo Events


TDBCombo Members

All of the properties for the TDBCombo control are listed below, and are documented in the following section.

TDBCombo Properties

AddItemSeparator | Determines the separator string for columns.
AllowColMove | Enables interactive column movement.
AllowColSelect | Enables interactive column selection.
AllowRowSizing | Enables interactive row resizing.
AlternatingRowStyle | Controls whether even/odd row styles are applied to a control.
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 and caption.
ApproxCount | Sets/returns the approximate number of rows.
Array | Specifies an XArrayDB object as the data source.
AutoCompletion | True if the combo's text box auto fills with the matched entry.
AutoDropdown | True if typing a character automatically opens the combo's list.
AutoSize | When True, the height of the edit box is set to the font height.
BackColor | Sets/returns the background color.
Bookmark | Sets/returns bookmark of current control row.
BookmarkType | Sets/returns the variant type used for passing bookmarks.
BorderAppearance | Controls the appearance (3D effects) of the cell borders.
BorderStyle | Sets/returns style for control border.
BoundColumn | Name of the RowSource field used to update DataField.
BoundText | Text value of the BoundColumn field.
Caption | Sets/returns caption for an object.
CaptionStyle | Controls the caption style for an object.
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.
Col | Sets/returns current column number.
ColumnFooters | Turns column footers on or off.
ColumnHeaders | Turns column headings on or off.
Columns | Contains a collection of True DBList columns.
ComboStyle | Sets/returns the display type of a combo box.
CurrentCellVisible | Sets/returns the visibility of the current cell.
DataChanged | Sets/returns modification status of the current row or cell.
DataField | Name of the DataSource field to be updated by user selection.
DataMode | Specifies bound or unbound mode.
DataSource | Source of data to be updated once a selection is made.
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.
DropdownPosition | Sets/returns the position of the drop-down portion of the control.
DropdownWidth | Sets/returns the width of the drop-down portion of the control.
EditBackColor | Sets/returns the background color of the text box portion.
EditFont | Specifies the font used for the text box portion.
EditForeColor | Sets/returns the foreground color of the text box portion.
EditHeight | Sets/returns the height for the edit portion of the combo box.
EmptyRows | Enables empty rows in an underpopulated control.
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 | Returns current split extend column setting, sets all splits.
FetchRowStyle | Controls whether the FetchRowStyle event will be fired.
FirstRow | Bookmark of row occupying first display line.
Font | Specifies the overall font for a control.
FooterStyle | Controls the footing style for an object.
FootLines | Number of lines allocated for footing text.
ForeColor | Sets/returns the foreground color.
GapHeight | Sets/returns the distance between the edit portion and the dropdown portion of the combo box.
HeadingStyle | Controls the heading style for a control.
HeadLines | Number of lines allocated for heading text.
HighlightRowStyle | Controls the style of the current row.
HScrollHeight | Returns the horizontal scroll bar height, if present.
hWnd | Returns the window handle of the control.
IntegralHeight | Sets/returns a value that indicates the display of partial rows.
LayoutFileName | Sets/returns the name of a file containing list layouts.
LayoutName | Sets/returns the name of the current list layout.
Layouts | Returns a collection of layout names.
LeftCol | Sets/returns the leftmost visible column.
LimitToList | True if the NotInList event is fired when an item is not found.
ListCount | Returns the number of items in the list portion of a control.
ListField | Sets/returns the RowSource field used for incremental search.
Locked | If true, data entry prohibited for an object.
MatchEntryTimeout | Sets/returns the incremental search timeout value.
MaxComboItems | Sets the number of items to display in the dropdown portion of the combo box.
MouseIcon | Sets/returns a custom mouse icon.
MousePointer | Sets/returns the mouse pointer type.
MultipleLines | Controls whether individual records span multiple lines.
OddRowStyle | Controls the row style for odd-numbered rows.
OLEDragMode | Controls whether a list handles OLE drag operations.
OLEDropMode | Controls whether a list handles OLE drop operations.
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 control rows.
RowMember | Sets/returns the name of the row member used to populate the control.
RowSource | Specifies source of control data.
RowSubDividerColor | Controls the row subdivider color.
RowTracking | True if rows are highlighted as the mouse moves over them.
ScrollBars | Sets/returns scroll bar style for the control.
ScrollTips | Determines whether the list displays a pop-up window.
ScrollTrack | Controls whether the scrollbar thumb causes the control’s display to update with new data.
SelectedItem | Sets/returns the bookmark of the currently selected item.
SelEndCol | Sets/returns rightmost selected column.
SelLength | Sets/returns length of selected text.
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 DBList splits.
Style | Controls the normal style for a control.
Styles | Contains a collection of True DBList styles.
Text | Returns displayed cell text for the current row.
VisibleCols | Returns number of visible columns.
VisibleRows | Returns number of visible display rows.
VScrollWidth | Returns the vertical scroll bar width, if present.

TDBCombo Methods

AboutBox | Displays the About box.
AddItem | Adds an item.
AddRegexCellStyle | Adds a regular expression cell condition to a control.
CaptureImage | Returns a captured image of a control's display.
CellContaining | Identifies a row and column under an X, Y coordinate pair.
ClearFields | Clears the current column/field layout.
ClearRegexCellStyle | Removes a regular expression cell condition from a control.
ClearSelCols | Deselects all selected columns in the current split.
CloseCombo | Closes the list portion of the combo if it is open.
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.
LoadLayout | Loads a saved layout.
OLEDrag | Initiates an OLE drag/drop operation.
OpenCombo | Opens the list portion of the combo if it is closed.
PointAt | Returns the kind of control element under an X, Y coordinate pair.
PostMsg | Posts a message to a control to fire the PostEvent event.
ReBind | Reinitializes a control from its data source.
Refresh | Updates a control's screen display.
RemoveItem | Removes an item.
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 control's data area.
SplitContaining | Identifies a split under an X, Y coordinate pair.

TDBCombo Events

Change | Occurs when text box contents change.
ClassicRead | Fired when the control requires unbound data for display.
Click | Fired when a mouse click occurs.
Close | Fired when control closes drop-down portion.
ColMove | Occurs before repainting when columns are moved.
ColResize | Occurs before repainting when a column is resized.
DblClick | Fired when a mouse double click occurs.
Error | Occurs when an associated action fails.
FetchCellStyle | Fired when the FetchStyle property is True 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.
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.
ItemChange | Occurs when a different combo item is selected.
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.
Mismatch | If LimitToList is True, fired when combo item not found.
MouseDown | Occurs when a mouse button is pressed.
MouseMove | Occurs when the mouse moves.
MouseUp | Occurs when a mouse button is released.
NotInList | If LimitToList is True, fired when item not found.
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 combo.
OLEGiveFeedback | Occurs after every OLEDragOver event.
OLESetData | Occurs when data is requested in a particular format.
OLEStartDrag | Occurs when a drag operation is initiated.
Open | Fired when control opens drop-down portion.
OwnerDrawCell | Fired when an owner-drawn cell is about to be rendered.
Paint | Fired when the control repaints itself.
PostEvent | Occurs after a PostMsg method is called.
RowResize | Occurs when rows are resized.
RowSourceChanged | Fired when the RowSource changes.
Scroll | Occurs when the control is scrolled using 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 control needs to find a row.
UnboundGetRelativeBookmark | Fired when the control needs a relative bookmark.
UnboundReadData | Fired when the control requires unbound data for display.
UnboundReadDataEx | Fired when the control requires unbound data for display.


TDBCombo Control Properties

AddItemSeparator Property (TDBCombo)

AllowColMove Property (TDBCombo)

AllowColSelect Property (TDBCombo)

AllowRowSizing Property (TDBCombo)

AlternatingRowStyle Property (TDBCombo)

AnchorRightColumn Property (TDBCombo)

AnimateWindow Property (TDBCombo)

AnimateWindowClose Property (TDBCombo)

AnimateWindowDirection Property (TDBCombo)

AnimateWindowTime Property (TDBCombo)

AutoCompletion Property

AutoDropDown Property

AutoSize Property

Appearance Property (TDBCombo)

ApproxCount Property (TDBCombo)

Array Property (TDBCombo)

BackColor Property (TDBCombo)

Bookmark Property (TDBCombo)

BookmarkType Property (TDBCombo)

BorderAppearance Property (TDBCombo)

BorderColor Property (TDBCombo)

BorderSize Property (TDBCombo)

BorderStyle Property (TDBCombo)

BorderType Property (TDBCombo)

BoundColumn Property (TDBCombo)

BoundText Property (TDBCombo)

Caption Property (TDBCombo)

CaptionStyle Property (TDBCombo)

CellTips Property (TDBCombo)

CellTipsDelay Property (TDBCombo)

CellTipsWidth Property (TDBCombo)

Col Property (TDBCombo)

ColumnFooters Property (TDBCombo)

ColumnHeaders Property (TDBCombo)

Columns Property (TDBCombo)

ComboStyle Property

CurrentCellVisible Property (TDBCombo)

DataChanged Property (TDBCombo)

DataField Property (TDBCombo)

DataMember Property (TDBCombo)

DataMode Property (TDBCombo)

DataSource Property (TDBCombo)

DeadAreaBackColor Property (TDBCombo)

DefColWidth Property (TDBCombo)

DestinationCol Property (TDBCombo)

DestinationRow Property (TDBCombo)

DestinationSplit Property (TDBCombo)

DropdownPosition Property

DropdownWidth Property

EditBackColor Property

EditFont Property

EditForeColor Property

EditHeight Property

EmptyRows Property (TDBCombo)

Enabled Property (TDBCombo)

ErrorText Property (TDBCombo)

EvenRowStyle Property (TDBCombo)

ExtendRightColumn Property (TDBCombo)

FetchRowStyle Property (TDBCombo)

FirstRow Property (TDBCombo)

Font Property (TDBCombo)

FooterStyle Property (TDBCombo)

FootLines Property (TDBCombo)

ForeColor Property (TDBCombo)

GapHeight Property

HeadingStyle Property (TDBCombo)

HeadLines Property (TDBCombo)

HighlightRowStyle Property (TDBCombo)

HScrollHeight Property (TDBCombo)

hWnd Property (TDBCombo)

IntegralHeight Property (TDBCombo)

LayoutFileName Property (TDBCombo)

LayoutName Property (TDBCombo)

Layouts Property (TDBCombo)

LeftCol Property (TDBCombo)

LimitToList Property

ListCount Property (TDBCombo)

ListField Property (TDBCombo)

Locked Property

MatchEntryTimeout Property (TDBCombo)

MaxComboItems Property

MouseIcon Property (TDBCombo)

MousePointer Property (TDBCombo)

MultipleLines Property (TDBCombo)

OddRowStyle Property (TDBCombo)

OLEDragMode Property

OLEDropMode Property

PartialRightColumn Property (TDBCombo)

RightToLeft Property (TDBCombo)

Row Property (TDBCombo)

RowDividerColor Property (TDBCombo)

RowDividerStyle Property (TDBCombo)

RowHeight Property (TDBCombo)

RowMember Property (TDBCombo)

RowSource Property (TDBCombo)

RowSubDividerColor Property (TDBCombo)

RowTracking Property

ScrollBars Property (TDBCombo)

ScrollTips Property (TDBCombo)

ScrollTrack Property (TDBCombo)

SelLength Property

SelStart Property

SelText Property

SelectedItem Property (TDBCombo)

SelEndCol Property (TDBCombo)

SelStartCol Property (TDBCombo)

Split Property (TDBCombo)

Splits Property (TDBCombo)

Style Property (TDBCombo)

Styles Property (TDBCombo)

Tag Property (TDBCombo)

Text Property (TDBCombo)

VisibleCols Property (TDBCombo)

VisibleRows Property (TDBCombo)

VScrollWidth Property (TDBCombo)


AddItemSeparator Property (TDBCombo)

This property determines the separation string for columns when using the AddItem method in AddItem mode.

Syntax

object.AddItemSeparator = String

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

This property takes ; as the default value.

See Also

TDBList and TDBCombo Controls


AllowColMove Property (TDBCombo)

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.

Syntax

object.AllowColMove = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

If True, the user can move selected columns.

If False (the default), the user cannot move selected columns.

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

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


AllowColSelect Property (TDBCombo)

Use the AllowColSelect property to control whether the user can select columns by clicking or dragging within the column header area.

Syntax

object.AllowColSelect = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

If True (the default), the user can select columns.

If False, the user cannot select columns.

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

TDBList and TDBCombo Controls

Split Object, Splits Collection


AllowRowSizing Property (TDBCombo)

If True (the default), the user can resize rows.

Syntax

object.AllowRowSizing = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

If False, the user cannot resize rows.

If the AllowRowSizing property is True, the mouse pointer turns into a double-headed arrow when positioned over the row divider between any pair of rows at the left edge of the list, and the user can resize the rows by dragging. Any change in row size causes a RowResize event.

All rows of the TDBList control are always the same height, which is determined by the RowHeight property.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


AlternatingRowStyle Property (TDBCombo)

Syntax

object.AlternatingRowStyle = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

This property determines whether a control or split displays odd-numbered rows in one style and even-numbered rows in another.

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

TDBList and TDBCombo Controls

Split Object, Splits Collection


AnchorRightColumn Property (TDBCombo)

Syntax

object.AnchorRightColumn = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

This property controls the behavior of horizontal scrolling in a control or split when the last column is visible.

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 control 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 control 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 control or split behaves as if it were set to True.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


AnimateWindow Property (TDBCombo)

Syntax

object.AnimateWindow = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - No Animate (default) | dblNoAnimate
1 - Roll | dblRoll
2 - Slide | dblSlide
3 - Blend | dblBlend

For a TDBCombo control, this property controls the style of animation when the user opens or closes the dropdown list. It is only meaningful when the ComboStyle property is set to 0 - Dropdown Combo or 1 - Simple Combo.

For a TDBCombo or TDBList 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 combo dropdown or combo and list cell tips.

The allowable values for this property are as follows:

If set to 0 - No animation (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. (NT 5.0 only)

NOTE: System requirements: Windows 98 or NT 5.0, or higher. The setting 3 - Blend is not available in Windows 98.

See Also

TDBList and TDBCombo Controls


AnimateWindowClose Property (TDBCombo)

Syntax

object.AnimateWindowClose = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - No Animate Close (default) | dblNoAnimateClose
1 - Opposite Direction | dblOppositeDirection
2 - Same Direction | dblSameDirection

For a TDBCombo control, this property controls the animation effect when the user closes the dropdown list. It is only meaningful when the ComboStyle property is set to 0 - Dropdown Combo or 1 - Simple Combo, and the AnimateWindow property is set to a value other than 0 - No Animation.

For a TDBCombo or TDBList 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.

The allowable values for this property are as follows:

If set to 0 - No Animation (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

TDBList and TDBCombo Controls


AnimateWindowDirection Property (TDBCombo)

Syntax

object.AnimateWindowDirection = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Default | dblDefaultDirection
1 - Top To Bottom | dblTopToBottom
2 - Bottom To Top | dblBottomToTop
3 - Left To Right | dblLeftToRight
4 - Right To Left | dblRightToLeft
5 - Top Left To Bottom Right | dblTopLeftToBottomRight
6 - Top Right To Bottom Left | dblTopRightToBottomLeft
7 - Bottom Left To Right | dblBottomLeftToTopRight
8 - Bottom Right To Top Left | dblBottomRightToTopLeft
9 - Center | dblAnimateCenter

For a TDBCombo control, this property controls the direction of the animation of the combo dropdown list. It is only meaningful when the ComboStyle property is set to 0 - Dropdown Combo or 1 - Simple Combo, and the AnimateWindow property is set to a value other than 0 - No Animation.

For a TDBCombo or TDBList 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 AnimateWindowClose property for additional control over the behavior of the animation when the object is 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 TDBCombo is too close to the bottom of the screen to display the entire dropdown list when opened by the user, the window will open upwards.

All of the remaining directional settings are under your complete control.

NOTE: System requirements: Windows 98 or NT 5.0, or higher.

See Also

TDBList and TDBCombo Controls


AnimateWindowTime Property (TDBCombo)

Syntax

object.AnimateWindowTime = long

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

This property controls the duration of the animation effects when the AnimateWindow property is set to a value other than 0 - No Animation. 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

TDBList and TDBCombo Controls


AutoCompletion Property

Syntax

TDBCombo.AutoCompletion = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

This property controls whether matching incremental search values are automatically copied to the text portion of a combo during editing.

If True, when the user enters one or more characters that match a value in the combo's 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), automatic completion does not occur, and the text portion of the control contains only the characters entered by the user.

See Also

TDBList and TDBCombo Controls


AutoDropDown Property

Syntax

column.AutoDropDown = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo object.

For columns with a built-in ValueItems combo box or associated TDBCombo 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

TDBList and TDBCombo Controls


AutoSize Property

Syntax

object.AutoSize = value

Remarks

Read/Write at run time and design time.

Property applies to the TDBCombo control.

When this property is set to True (default), the height of the edit box will be set to the current font height.

When this property is set to False, the edit height becomes adjustable.

NOTE: The EditHeight property is directly related to this property. If AutoSize is True, you cannot set the EditHeight.

See Also

TDBList and TDBCombo Controls


Appearance Property (TDBCombo)

Syntax

object.Appearance = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Flat | dblFlat
1 - 3D (default) | dbl3D
2 - Mixed Flat | dblMixedFlat

When this property is set to 1 - 3D, the control paints its caption bars, column headings, and column footings with three-dimensional effects.

When this property is set to 0 - Flat, no visual effects are used.

When this property is set to 2 - Mixed Flat, the paint everything flat except the scrollbars and buttons.

The Appearance property is independent of the BorderStyle and BackColor properties and only affects the control's caption bars, column headings, and column footings. 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, and ColumnFooters properties to control the visibility of these components.

See Also

TDBList and TDBCombo Controls


ApproxCount Property (TDBCombo)

Syntax

object.ApproxCount = long

Remarks

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

Property applies to TDBList and TDBCombo controls.

This property sets or returns the approximate row count used by the control to calibrate the vertical scroll bar.

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 control is used in conjunction with an array.

NOTE: For a bound control, setting the ApproxCount property has no effect. However, getting the ApproxCount property will query the underlying data source.

See Also

TDBList and TDBCombo Controls


Array Property (TDBCombo)

Syntax

object.Array = XArrayDB

Remarks

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

Property applies to TDBList and TDBCombo controls.

For a control with its DataMode property set to 4 - Storage, the Array property specifies an 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

TDBList and TDBCombo Controls


BackColor Property (TDBCombo)

Syntax

object.BackColor = color

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, and Style objects.

This property controls the background color of an object. Colors may be specified as RGB values or system default colors.

The background color of a control, 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

TDBList and TDBCombo Controls

Style Object, Styles Collection


Bookmark Property (TDBCombo)

Syntax

object.Bookmark = variant

Remarks

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

Property applies to TDBList and TDBCombo controls.

This property returns or sets the bookmark identifying the current row in a TDBList and TDBCombo control.

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

See Also

TDBList and TDBCombo Controls


BookmarkType Property (TDBCombo)

Syntax

object.BookmarkType = integer

Remarks

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

Property applies to TDBList and TDBCombo controls.

The BookmarkType property returns or sets the variant type of bookmarks returned by a TDBList and TDBCombo control through its properties, methods, and events. You can 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 control are incompatible with the ADO Recordset object exposed by an OLE DB data source, even though the control 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 = TDBList1.RowBookmark(0)

You can use the BookmarkType property in conjunction with the RowSourceChanged event to circumvent type mismatch errors that may occur when a control-supplied bookmark is passed to an ADO Recordset object (or vice versa). The workaround is as follows:

Sub TDBList1_RowSourceChanged()

TDBList1.BookmarkType = VarType(ADODC1.Recordset.Bookmark)

End Sub

This code ensures that any bookmarks returned by the control are first converted to the appropriate type for the bound data source. This workaround is only needed when using the control in an HTML page; it is not needed for Visual Basic 6.0.

See Also

TDBList and TDBCombo Controls


BorderAppearance Property (TDBCombo)

Determines the appearance of the border.

Syntax

object.BorderAppearance = value

Remarks

Read/Write at run time and design time.

Property applies to Style object for TDBList and TDBCombo.

Values

Design Time | Run Time
0 - Flat(default) | dblFlatStyle
1 - 3D Raised | dbl3Draised
2 - 3D Inset | dbl3Dinset
3 - 3D Raised Bevel | dbl3DraisedBevel
4 - 3D Insert Bevel | dbl3DInsetBevel

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


BorderColor Property (TDBCombo)

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.

Property applies to Style object for TDBList and TDBCombo.

See Also

Style Object, Styles Collection


BorderSize Property (TDBCombo)

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.
Property applies to Style object for TDBList and TDBCombo.

See Also

Style Object, Styles Collection


BorderStyle Property (TDBCombo)

This property determines whether a TDBList or TDBCombo control has a border.

Syntax

object.BorderStyle = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - None | dblNoBorder
1 - Fixed Single (default) | dblFixedSingle

See Also

TDBList and TDBCombo Controls


BorderType Property (TDBCombo)

Determines the type of border.

Syntax

object.BorderType = value

Remarks

Read/Write at run time and design time.

Property applies to Style object for TDBList and TDBCombo.

Values

Design Time | Run Time
0 - None (default) | dblBorderNone
1 - Left | dblBorderLeft
2 - Right | dblBorderRight
4 - Top | dblBorderTop
8 - Bottom | dblBorderBottom

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


BoundColumn Property (TDBCombo)

This property returns or sets the name of the source field in a Recordset (Data control) object that is used to supply a data value to another Recordset (Data control).

Syntax

object.BoundColumn = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Generally, you will use the TDBList and TDBCombo controls with two Data controls: one to fill the list as designated by the RowSource property, and one to update a field in a database as designated by the DataSource and DataField properties.

When the user selects an item from a TDBList control or the list portion of a TDBCombo control, the BoundColumn property determines which RowSource field supplies the data value to be used for the update. You can use the following pseudo-code to help you remember how to configure a list or combo control at design time:

DataSource.DataField = RowSource.BoundColumn

The left side of the assignment statement specifies the field to be updated; the right side specifies the set of allowable values.

NOTE: Do not confuse the BoundColumn property with the ListField property used to specify the incremental search field.

See Also

TDBList and TDBCombo Controls


BoundText Property (TDBCombo)

Syntax

object.BoundText = value

Remarks

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

Property applies to TDBList and TDBCombo controls.

The BoundText property always reflects the value of the BoundColumn field within the list portion of the control. As the current record within the Recordset (Data control) associated with the DataSource property changes, the BoundText property receives the value specified by DataField. The list or combo control then searches the records in its list to see if the BoundText value matches any BoundColumn field. If a match is found, the record is highlighted in the list or placed in the text box portion of the combo control. If no match is found, the list selection is cancelled and BoundText returns an empty string.

When the user enters a value into the text portion of a TDBCombo control, the list portion attempts to position to a matching item. If a match is found, the BoundText property receives the field value corresponding to the BoundColumn property. If no match is found, the BoundText property does not change.

When the user selects an item from the list, the BoundText property receives the data value to be used for the update, and the Data control specified by the DataSource property receives notification that an update has been requested. The new value is not actually written to the database until the current record is repositioned or the Data control's UpdateRecord (Data control) method is executed.

You can also set the BoundText property in code to position the list to a specific item.

See Also

TDBList and TDBCombo Controls


Caption Property (TDBCombo)

For a TDBList or TDBCombo control, this property determines the text displayed in the caption bar at the top of the control.

Syntax

object.Caption = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Column and Split objects.

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

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


CaptionStyle Property (TDBCombo)

This property sets or returns the Style object that controls the appearance of a control's caption bar or a Split object's heading area.

Syntax

object.CaptionStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

TDBList and TDBCombo Controls

Split Object, Splits Collection


CellTips Property (TDBCombo)

The CellTips property determines whether the control displays a pop-up text window when the cursor is idle.

Syntax

object.CellTips = value

Remarks

Read/Write at run time and design time.
Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - None (default) | dblNoCellTips
1 - Anchored | dblAnchored
2 - Floating | dblFloating

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 control has focus and the cursor is idle over a control cell, column header, split header, or control 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 control 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.

See Also

TDBList and TDBCombo Controls


CellTipsDelay Property (TDBCombo)

The CellTipsDelay property controls the amount of idle time, in milliseconds, that must elapse before the cell tip window is displayed.

Syntax

object.CellTipsDelay = long

Remarks

Read/Write at run time and design time.
Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


CellTipsWidth Property (TDBCombo)

Syntax

object.CellTipsWidth = single

Remarks

Read/Write at run time and design time.
Property applies to TDBList and TDBCombo controls.

The CellTipsWidth property returns or sets the width of the cell tip window in terms of the coordinate system of the control's container.

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

TDBList and TDBCombo Controls


Col Property (TDBCombo)

Syntax

object.Col = integer

Remarks

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

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


ColumnFooters Property (TDBCombo)

Syntax

object.ColumnFooters = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


ColumnHeaders Property (TDBCombo)

Syntax

object.ColumnHeaders = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


Columns Property (TDBCombo)

Syntax

object.Columns

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList and TDBCombo controls, Split object.

This property returns a collection of Column objects for a control, drop-down control, or split.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


ComboStyle Property

Syntax

TDBCombo.ComboStyle

Remarks

Read-only at run time. Read/Write at design time.

Property applies to TDBCombo control.

Values

Design Time | Run Time
0 - Dropdown Combo (default) | dbcDropdownCombo
1 - Simple Combo | dbcSimpleCombo
2 - Dropdown List | dbcDropdownList

The ComboStyle property returns a value indicating the display type and behavior of the control.

When set to 0 - Dropdown Combo, the control includes a text box and a drop-down list. The user can select from the list or type in the text box.

When set to 1 - Simple Combo, the control includes a text box and a list which is always displayed. The user can select from the list or type in the text box. The size of a simple combo box includes both the text and list portions. By default, a simple combo box is sized so that none of the list is displayed. To display more of the list, resize the control at design time or increase its Height (Visual Basic)property at run time.

When set to 2 - Dropdown List, the control includes a text box and a drop-down list as in setting 0 - Dropdown Combo. However, this style disallows text entry and permits selection only from the drop-down list.

See Also

TDBList and TDBCombo Controls


CurrentCellVisible Property (TDBCombo)

Syntax

object.CurrentCellVisible = boolean

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

This property returns True if the current cell (indicated by the Bookmark and Col properties) is visible within the displayed area of a control or split. It returns False if the cell is not visible.

For a TDBList or TDBCombo control, setting the CurrentCellVisible property to True causes the control to scroll so that the current cell is brought into view. If a control 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

TDBList and TDBCombo Controls

Split Object, Splits Collection


DataChanged Property (TDBCombo)

Syntax

object.DataChanged = boolean

Remarks

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

Property applies to TDBList and TDBCombo controls.

The DataChanged property returns or sets a value indicating that the data in a TDBList or TDBCombo control has been modified. If True, the data in the control differs from the data in the current record. If False (the default), the data in the control has not been changed.

When the user modifies the data in a TDBList or TDBCombo control, or you set its Text property in code, the DataChanged property is set to True. Subsequently, when the data source control attempts to move to a different record, it first updates the changed value to the underlying data source.

You can set the DataChanged property to False to prevent the underlying data source from being updated in this manner. For the intrinsic Data control, this is typically done in the Validate (Visual Basic) control event.

See Also

TDBList and TDBCombo Controls


DataField Property (TDBCombo)

Syntax

object.DataField = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

The DataField property returns or sets the name of the DataSource field that will be updated when the user selects an item from a control.

Generally, you will use the TDBList and TDBCombo controls with two Data controls: one to fill the list as designated by the RowSource property, and one to update a field in a database as designated by the DataSource and DataField properties.

If the DataField property is not specified, no updates will occur, and the control will not respond to record position changes in the Recordset (Data control) associated with DataSource.

NOTE: Do not confuse the DataField property of the control with the DataField property of the Column object or the BoundColumn property used to specify the source field for the update.

See Also

TDBList and TDBCombo Controls


DataMember Property (TDBCombo)

Syntax

object.DataMember = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls (OLE DB only).

This property returns or sets the name of the data member used to populate the list. Typically, a data member represents a database table or query.

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.

This property is only supported by the OLE DB version of True DBList. It is used only in bound mode and has no effect in unbound or storage modes.

See Also

TDBList and TDBCombo Controls


DataMode Property (TDBCombo)

Syntax

object.DataMode = value

Remarks

Read-only at run time. Read/Write at design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Bound (default) | dblBound
1 - Unbound | dblUnbound
2 - Unbound Extended | dblUnboundEx
3 - Application | dblUnboundAp
4 - Storage | dblUnboundSt
5 - AddItem | dblAddItem

When set to 0 - Bound, the control displays data available from its bound DataSource.

When set to 1 - Unbound, the control uses the original unbound events to retrieve and update displayed data. When this mode is used, the control fires the UnboundReadData event to fetch data. This setting was retained for backward compatibility earlier versions of True DBList. 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 list 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 control 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 TDBList or TDBCombo control using the Array property. This is by far the simplest way to use the controls in unbound mode.

When set to 5 - AddItem, the list portion of the control is populated with data via the AddItem method. The first item added starts at zero. Any event that uses a bookmark will use the zero based index of the control.

See Also

TDBList and TDBCombo Controls


DataSource Property (TDBCombo)

Syntax

object.DataSource

Remarks

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

Property applies to TDBList and TDBCombo controls.

The DataSource property specifies the data control that is updated once a selection is made.

Generally, you will use the TDBList and TDBCombo controls with two Data controls: one to fill the list as designated by the RowSource property, and one to update a field in a database as designated by the DataSource and DataField properties.

See Also

TDBList and TDBCombo Controls


DeadAreaBackColor Property (TDBCombo)

This property controls the background color of the dead area object.

Syntax

object.DeadAreaBackColor = color

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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.

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

TDBList and TDBCombo Controls


DefColWidth Property (TDBCombo)

This property returns or sets the default width for all control columns in terms of the coordinate system of the control's container.

Syntax

object.DefColWidth = single

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

For bound controls, the DefColWidth property is respected under the following circumstances:

•

When you execute the Retrieve Fields command at design time.

•

When the control's layout is initialized at run time.

•

When a new column is created at run time.

For unbound controls, the DefColWidth property is only respected when a new column is created at run time.

If you set the DefColWidth property to 0, the control 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:

TDBList1.DefColWidth = TDBList1.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 control. Therefore, if DefColWidth is 0, the actual column widths may not be what you expect since the control must supply a default width.

See Also

TDBList and TDBCombo Controls


DestinationCol Property (TDBCombo)

This property is used when moving from one cell to another in the control. It indicates which column will be the destination of the movement.

Syntax

object.DestinationCol

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBCombo and TDBList controls.

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: 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 control's Col property).

NOTE: Care must be exercised when using this property, because it is possible to use the value 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

TDBList and TDBCombo Controls


DestinationRow Property (TDBCombo)

This property is used when moving from one cell to another in the control. It indicates which row will be the destination of the movement.

Syntax

object.DestinationRow

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBCombo and TDBList controls.

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: 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 setting the control's Row property).

NOTE: Care must be exercised when using this property, because it is possible to use the value 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

TDBList and TDBCombo Controls


DestinationSplit Property (TDBCombo)

This property is used when moving from one cell to another in the control. It indicates which split will be the destination of the movement.

Syntax

object.DestinationSplit

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBCombo and TDBList controls.

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 List 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: 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 control's Split property).

NOTE: Care must be exercised when using this property, because it is possible to use the value 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

TDBList and TDBCombo Controls


DropdownPosition Property

The DropdownPosition property returns or sets a value that determines the position of the drop-down portion of a combo control.

Syntax

TDBCombo.DropdownPosition = value

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

Values

Design Time | Run Time
0 - Default Position | dblDefaultPosition
1 - Right Down | dblRightDown
2 - Right Up | dblRightUp
3 - Left Down | dblLeftDown
4 - Left Up | dblLeftUp

It is only meaningful when the ComboStyle property is set to 0 - Dropdown Combo or 2 - Dropdown List.

If the DropdownPosition property is set to 0 - Default Position, the dropdown list will open to the right and down. If there is not enough room at the bottom of the screen, the window will open upwards. If there is not enough room at the right edge of the screen, the window will open towards the left.

The other values will force the behavior of the dropdown list regardless of whether there is enough room at the edge of the screen or not, if you also specify the DropdownWidth property.

See Also

TDBList and TDBCombo Controls


DropdownWidth Property

The DropdownWidth property returns or sets a value that determines the width of the drop-down portion of a combo control.

Syntax

TDBCombo.DropdownWidth = single

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

By default, this property returns zero, which indicates that the text and drop-down portions of the control have the same width, as given by the Width (Visual Basic)property.

You can set this property to a nonzero value at either design time or run time to provide additional room for multicolumn drop-down lists. Use with the DropdownPosition property for additional control of the dropdown list behavior.

See Also

TDBList and TDBCombo Controls


EditBackColor Property

This property controls the background color of an object's editing window when editing is in progress. Colors may be specified as RGB values or system default colors.

Syntax

TDBCombo.EditBackColor = color

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

By default, EditBackColor inherits its value from the BackColor property, which is initially set to the system Window Background color as determined by your Control Panel settings.

See Also

TDBList and TDBCombo Controls


EditFont Property

This property returns or sets the font associated with the text box portion of a TDBCombo control.

Syntax

TDBCombo.EditFont = font

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

By default, EditFont inherits its value from the control's Font property.

NOTE: If a change to the EditFont property results in a change in height, then the height of the text box portion is resized proportionally to reflect the new character height.

See Also

TDBList and TDBCombo Controls


EditForeColor Property

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

Syntax

TDBCombo.EditForeColor = color

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

Colors may be specified as RGB values or system default colors.

By default, the EditForeColor property inherits its value from the ForeColor property, which is initially set to the system Window Text color as determined by your Control Panel settings.

See Also

TDBList and TDBCombo Controls


EditHeight Property

This property will set/return the height for the edit portion of the combo box.

Syntax

object.EditHeight = Value

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

Values

Float

The text will be in the vertical middle of the edit portion of the combo.

See Also

TDBList and TDBCombo Controls


EmptyRows Property (TDBCombo)

The EmptyRows property returns or sets a value that determines how the control displays rows below the last data row.

Syntax

object.EmptyRows = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

If all of the records in the data source do not fill up the entire control, setting EmptyRows to True will fill the unpopulated control area with empty data rows. If EmptyRows is False (the default), then the unpopulated control 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

TDBList and TDBCombo Controls


Enabled Property (TDBCombo)

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.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


ErrorText Property (TDBCombo)

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.

Property applies to TDBList and TDBCombo controls.

When a database error occurs as a result of user interaction with the control, 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 control'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 TDBList and TDBCombo control's Error event handler. A trappable error will occur if you attempt to access it in any other context.

See Also

TDBList and TDBCombo Controls


EvenRowStyle Property (TDBCombo)

This property sets or returns the Style object that controls the appearance of an even-numbered row in a control or split where the AlternatingRowStyle property is set to True.

Syntax

object.EvenRowStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

To change the appearance of odd-numbered rows, set the OddRowStyle property.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


ExtendRightColumn Property (TDBCombo)

This property allows the rightmost column of a control 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.

Property applies to TDBList and TDBCombo controls, Split object.

If True, the last column will extend to the end of the control or split.

If False (the default), the area between the last column and the end of the control 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 control contains multiple splits, then setting its ExtendRightColumn property has the same effect as setting the ExtendRightColumn property of each split individually.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


FetchRowStyle Property (TDBCombo)

If True, the FetchRowStyle event will be fired whenever the control is about to display a row of data.

Syntax

object.FetchRowStyle = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

TDBList and TDBCombo Controls

Split Object, Splits Collection


FirstRow Property (TDBCombo)

This property returns or sets a value containing the bookmark for the first visible row in a control or split.

Syntax

object.FirstRow = variant

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

For a TDBList and TDBCombo control, setting the FirstRow property causes the control to scroll so that the specified row becomes the topmost row. If a control 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

TDBList and TDBCombo Controls

Split Object, Splits Collection


Font Property (TDBCombo)

This property returns or sets the font object associated with a control, column, split, or style.

Syntax

object.Font = font

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Style object.

The font used to display text in a control, 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.

NOTE: For TDBList and TDBCombo controls, if a change to the Font property results in a change to the average character width, then all affected columns are resized proportionally to reflect the new character width.

See Also

TDBList and TDBCombo Controls

Style Object, Styles Collection


FooterStyle Property (TDBCombo)

This property returns the Style object that controls the appearance of column footings within a control, column, or split.

Syntax

object.FooterStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Column and Split objects.

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

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


FootLines Property (TDBCombo)

This property returns or sets a value indicating the number of lines of text displayed in a TDBList and TDBCombo control's column footers.

Syntax

object.FootLines = single

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

The FootLines property accepts a floating point number from 0 to 10. The default value is 1, which causes the control 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

TDBList and TDBCombo Controls


ForeColor Property (TDBCombo)

This property controls the foreground color of an object.

Syntax

object.ForeColor = color

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Style object.

Colors may be specified as RGB values or system default colors.

The foreground color of a control, 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

TDBList and TDBCombo Controls

Style Object, Styles Collection


GapHeight Property

This property will set/return the length between the edit portion and the dropdown portion of the combo box.

Syntax

object.GapHeight = Value

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

Values

Float

The default value is 2 pixels, and the value can not be set to less than 2 pixels.

See Also

TDBList and TDBCombo Controls


HeadingStyle Property (TDBCombo)

This property returns the Style object that controls the appearance of column headings within a control, column, or split.

Syntax

object.HeadingStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Column and Split objects.

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

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


HeadLines Property (TDBCombo)

This property returns or sets a value indicating the number of lines of text displayed in a TDBList and TDBCombo control's column headers.

Syntax

object.HeadLines = single

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

The HeadLines property accepts a floating point number from 0 to 10. The default value is 1, which causes the control 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

TDBList and TDBCombo Controls


HighlightRowStyle Property (TDBCombo)

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

Syntax

object.HighlightRowStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


HScrollHeight Property (TDBCombo)

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.

Syntax

object.HScrollHeight

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

If no horizontal scroll bar exists, then the returned value is zero. If object is a TDBList or TDBCombo 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 List layout and sizing the List and its columns.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


hWnd Property (TDBCombo)

The hWnd property returns the unique window handle assigned to a TDBList and TDBCombo control by the Microsoft Windows operating environment.

Syntax

object.hWnd

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


IntegralHeight Property (TDBCombo)

This property determines whether partial rows are displayed in a TDBList or TDBCombo control.

Syntax

object.IntegralHeight = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


LayoutFileName Property (TDBCombo)

This property sets or returns the string containing the filename used to save and retrieve control layouts.

Syntax

object.LayoutFileName = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Setting this property alone has no effect on the control layout; the property value is used by the LoadLayout method of the control and the Add and Remove methods of the Layouts collection.

You can create control layout files at design time by setting the LayoutFileName and LayoutName properties and using the layout commands on the control's visual editing menu.

At design time, if you first set the LayoutFileName property to a valid filename in which control 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

TDBList and TDBCombo Controls


LayoutName Property (TDBCombo)

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.

Property applies to TDBList and TDBCombo controls.

Setting this property alone has no effect on the control layout; the property value is used by the LoadLayout method of the control.

At design time, if you first set the LayoutFileName property to a valid filename in which control 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

TDBList and TDBCombo Controls


Layouts Property (TDBCombo)

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.

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


LeftCol Property (TDBCombo)

This property returns or sets the zero-based index of the leftmost column in a control or split.

Syntax

object.LeftCol = integer

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

For a TDBList and TDBCombo control, setting the LeftCol property causes the control to scroll so that the specified column becomes the leftmost column. If a control 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 control or split horizontally. Use the FirstRow property to determine the bookmark of the first visible row in a control or split.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


LimitToList Property

This property determines if the NotInList event fires when an incremental search value is not found.

Syntax

TDBCombo.LimitToList = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

If True, the NotInList event will fire whenever the user enters a value into the text portion of a TDBCombo control and the value is not found in the list portion of the control.

If False (the default), the NotInList event will not fire.

By writing a handler for the NotInList event, you can enable your users to add new items to the Recordset (Data control) specified by the control's RowSource property.

See Also

TDBList and TDBCombo Controls


ListCount Property (TDBCombo)

Returns the number of items in the list portion of the control.

Syntax

object.ListCount

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


ListField Property (TDBCombo)

The ListField property returns or sets the name of the column used for incremental search within a TDBList or TDBCombo control.

Syntax

object.ListField = string

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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 control will be used.

NOTE: Do not confuse the ListField property with the BoundColumn property used to specify the source field for update operations.

See Also

TDBList and TDBCombo Controls


Locked Property

This property returns or sets a value indicating whether the control can be edited.

Syntax

TDBCombo.Locked = boolean

Remarks

Read/Write at run time and design time.

Property applies to the TDBCombo control.

If True, the user cannot modify data in the TDBCombo control; however, the user can highlight data in the text box and copy it.

If False (the default), the user can modify data in the TDBCombo control.

This property does not affect programmatic access to the TDBCombo control.

See Also

TDBList and TDBCombo Controls


MatchEntryTimeout Property (TDBCombo)

This property returns or sets a value indicating the timeout value, in milliseconds, for incremental searching when a TDBCombo control's ComboStyle property is set to 2 - Dropdown, or when a TDBList control's MatchEntry property is set to 2 - Extended.

Syntax

object.MatchEntryTimeout = long

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

The search is performed incrementally as characters are typed. If there is no keystroke after this time value, the incremental search will be reset, allowing the user to begin a new search.

For the TDBCombo control, this means that the text entry box is cleared after the timeout period has passed, and new characters may be entered in their place.

For the TDBList control, this means that after the timeout period has passed, the next characters entered will start a new search through the list.

NOTE: The ListField property determines which column is searched.

See Also

TDBList and TDBCombo Controls


MaxComboItems Property

This property will set the number of items to display in the dropdown portion of the combobox.

Syntax

TDBCombo.MaxComboItems = short

Remarks

Read/Write at run time and design time.

Property is only applicable when the ComboStyle is DropDown or DropDownList.

NOTE: You will no longer be able to size a DropDown or DropDownList style combo to configure the dropdown height.

See Also

TDBList and TDBCombo Controls


MouseIcon Property (TDBCombo)

This property sets or returns the custom mouse icon used when the MousePointer property is set to 99 - Custom.

Syntax

object.MouseIcon = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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:

TDBList1.MouseIcon = LoadPicture("cross.cur")

See Also

TDBList and TDBCombo Controls


MousePointer Property (TDBCombo)

This property sets or returns a value indicating the type of mouse pointer displayed when the mouse is over the control at run time.

Syntax

object.MousePointer = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Default (default) | dblMPDefault
1 - Arrow | dbMPArrow
2 - Cross | dblMPCross
3 - I-beam | dblMPIbeam
4 - Icon | dblMPIcon
5 - Size | dblMPSize
6 - Size NE SW | dblMPSizeNESW
7 - Size NS | dblMPSizeNS
8 - Size NW SE | dblMPSizeNWSE
9 - Size EW | dblMPSizeEW
10 - Up Arrow | dblMPUpArrow
11 - Hourglass | dblMPHourglass
12 - No Drop | dblMPNoDrop
13 - Arrow Hourglass | dblMPArrowHourglass
14 - Arrow Question | dblMPArrowQuestion
15 - Size All | dblMPSizeAll
99 - Custom | dblMPCustom

When this property is set to 99 - Custom, the MouseIcon property specifies the shape of the mouse pointer.

See Also

TDBList and TDBCombo Controls


MultipleLines Property (TDBCombo)

This property determines whether a single row can span multiple lines.

Syntax

object.MultipleLines = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - Disabled (default) | dblMultipleDisabled
1 - Variable | dblMultipleVariable
2 - Fixed | dblMultipleFixed

In this context, the terms line and row are defined as follows:

•

A line is a single physical row of cells displayed in a TDBList or TDBCombo. Do not confuse this with a line of text inside a control cell; depending upon the settings of the RowHeight and WrapText properties, data in a control 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 control 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 control 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 control will automatically span or wrap the columns to multiple lines so that all columns will be visible within the width of the control. 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 control 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 control may produce additional lines.

If MultipleLines is 2 - Fixed, then changing the width of individual columns or the width of the control 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 control 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.

See Also

TDBList and TDBCombo Controls


OddRowStyle Property (TDBCombo)

This property sets or returns the Style object that controls the appearance of an odd-numbered row in a control or split where the AlternatingRowStyle property is set to True.

Syntax

object.OddRowStyle = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

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

To change the appearance of even-numbered rows, set the EvenRowStyle property.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


OLEDragMode Property

This property returns or sets a value that indicates whether the combo or the programmer handles an OLE drag/drop operation.

Syntax

TDBCombo.OLEDragMode = value

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

Values

Design Time | Run Time
0 - Manual (default) | dbcOLEDragManual
1 - Automatic | dbcOLEDragAutomatic

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

See Also

TDBList and TDBCombo Controls


OLEDropMode Property

This property returns or sets a value that indicates how the combo handles drop operations.

Syntax

TDBCombo.OLEDropMode = value

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

Values

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

When OLEDropMode is set to the default value of 0 - None, the combo does not accept OLE drops and displays the No Drop cursor.

When OLEDropMode is set to 1 - Manual, the combo triggers the OLE drop events, allowing the programmer to handle the OLE drop operation in code.

When OLEDropMode is set to 2 - Automatic, the combo automatically accepts OLE drops if the DataObject contains data in a format it recognizes. No mouse or OLE drag/drop events on the combo will occur when OLEDropMode is set to 2 - Automatic.

NOTE: Currently, the only data format recognized by the combo is text.

See Also

TDBList and TDBCombo Controls


PartialRightColumn Property (TDBCombo)

This property determines whether the rightmost column of a control 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.

Property applies to TDBList and TDBCombo controls, Split object.

If True (the default), the rightmost column will be clipped if the control 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 control or split.

If a control contains multiple splits, then setting its PartialRightColumn property has the same effect as setting the PartialRightColumn property of each split individually.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


RightToLeft Property (TDBCombo)

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.

Property applies to TDBList and TDBCombo controls.

When the RightToLeft property is set to True:

•

Control columns begin at the right boundary of the List.

•

Fixed columns are located on the right side of the Control.

•

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 List 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 (control 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.

•

For TDBCombo, the edit box will be on the right side of the dropdown button.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


Row Property (TDBCombo)

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.

Syntax

object.Row = integer

Remarks

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

Property applies to TDBList and TDBCombo controls.

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 TDBList 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 TDBCombo control, changing the Row property at run time also changes the value of the SelectedItem property.

See Also

TDBList and TDBCombo Controls


RowDividerColor Property (TDBCombo)

This property controls the row divider color of the controls when RowDividerStyle is 7 - Custom Color.

Syntax

object.RowDividerColor = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Colors may be specified as RGB values or system default colors.

See Also

TDBList and TDBCombo Controls


RowDividerStyle Property (TDBCombo)

This property determines the style of the border drawn between control rows.

Syntax

object.RowDividerStyle = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Values

Design Time | Run Time
0 - No dividers | dblNoDividers
1 - Black line | dblBlackLine
2 - Dark gray line (default) | dblDarkGrayLine
3 - Raised | dblRaised
4 - Inset | dblInset
5 - ForeColor | dblUseForeColor
6 - Light gray line | dblLightGrayLine
7 - Custom Color | dblCustomColor

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

TDBList and TDBCombo Controls


RowHeight Property (TDBCombo)

This property returns or sets the height of all control rows in terms of the coordinate system of the control's container.

Syntax

object.RowHeight = single

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

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

TDBList1.RowHeight = 0

TDBList1.RowHeight = TDBList1.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 at the left edge of the control.

NOTE: Increasing the RowHeight property does not wrap cell text at column boundaries unless the column's WrapText property is True.

See Also

TDBList and TDBCombo Controls


RowMember Property (TDBCombo)

This property returns or sets the name of the row member used to populate the list.

Syntax

object.RowMember = string

Remarks

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

Property applies to TDBList and TDBCombo controls (OLE DB only).

Typically, a row member represents a database table or query.

A bound DataSource can expose multiple sets of data that consumers can bind to. Each set of data is called a row member, and is identified by a unique string.

This property is only supported by the OLE DB version of True DBList. It is used only in bound mode and has no effect in unbound or storage modes.

See Also

TDBList and TDBCombo Controls


RowSource Property (TDBCombo)

Sets a value that specifies the Data control used to fill the rows of a TDBList or TDBCombo control.

Syntax

object.RowSource

Remarks

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

Property applies to TDBList and TDBCombo controls.

Generally, you will use the TDBList and TDBCombo controls with two Data controls: one to fill the list as designated by the RowSource property, and one to update a field in a database as designated by the DataSource and DataField properties.

See Also

TDBList and TDBCombo Controls


RowSubDividerColor Property (TDBCombo)

This property controls the row subdivider color of the controls when RowDividerStyle is 7 - Custom Color.

Syntax

TDBList.RowSubDividerColor = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

Colors may be specified as RGB values or system default colors.

See Also

TDBList and TDBCombo Controls


RowTracking Property

This property controls whether rows are automatically highlighted as the mouse is moved over the drop-down portion of a TDBCombo control.

Syntax

TDBCombo.RowTracking = boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBCombo control.

If True (the default), individual rows are highlighted as the mouse moves over them.

If False, moving the mouse does not change the highlighted row.

NOTE: When RowTracking is True and the user highlights a different row by moving the mouse, the ItemChange event will not fire.


ScrollBars Property (TDBCombo)

This property returns or sets a value indicating whether a control or split has horizontal or vertical scroll bars.

Syntax

object.ScrollBars = value

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Split object.

Values

Design Time | Run Time
0 - None | dblNone
1 - Horizontal | dblHorizontal
2 - Vertical | dblVertical
3 - Both | dblBoth
4 - Automatic (default) | dblAutomatic

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 control contains multiple splits, then setting its ScrollBars property has the same effect as setting the ScrollBars property of each split individually.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


ScrollTips Property (TDBCombo)

The ScrollTips property determines whether the control 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.

Property applies to TDBList and TDBCombo controls.

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 control’s scrollbar thumb is dragged.

If you do not provide a handler for the FetchScrollTips event, tips will not be displayed.

See Also

TDBList and TDBCombo Controls


ScrollTrack Property (TDBCombo)

If True, moving the scrollbar thumb causes the control’s display to update with new data.

Syntax

object.ScrollTrack = Boolean

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls.

If False (the default), moving the scrollbar thumb does not change the display.

See Also

TDBList and TDBCombo Controls


SelLength Property

This property returns or sets the number of characters selected within the list's editing window.

Syntax

TDBCombo.SelLength = long

Remarks

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

Property applies to TDBCombo control.

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

TDBList and TDBCombo Controls


SelStart Property

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

Syntax

TDBCombo.SelStart = long

Remarks

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

Property applies to TDBCombo control.

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

TDBList and TDBCombo Controls


SelText Property

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

Syntax

TDBCombo.SelText = string

Remarks

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

Property applies to TDBCombo control.

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

TDBList and TDBCombo Controls


SelectedItem Property (TDBCombo)

This property returns or sets the bookmark identifying the selected item in a control.

Syntax

object.SelectedItem = variant

Remarks

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

Property applies to TDBList and TDBCombo controls.

Use the value returned by the SelectedItem property to determine the current row in a TDBList or TDBCombo 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 control 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 TDBCombo control, the SelectedItem and Bookmark properties are synonymous.

See Also

TDBList and TDBCombo Controls


SelEndCol Property (TDBCombo)

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.

Property applies to TDBList and TDBCombo controls, Split object.

If no columns are selected, then this property returns -1.

If a control 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 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

TDBList and TDBCombo Controls

Split Object, Splits Collection


SelStartCol Property (TDBCombo)

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.

Property applies to TDBList and TDBCombo controls, Split object.

If no columns are selected, then this property returns -1.

If a control 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 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

TDBList and TDBCombo Controls

Split Object, Splits Collection


Split Property (TDBCombo)

This property specifies the zero-based index of the current split.

Syntax

object.Split = integer

Remarks

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

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


Splits Property (TDBCombo)

This property returns a collection of Split objects.

Syntax

object.Splits

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


Style Property (TDBCombo)

This property returns or sets the Style object that controls the normal appearance of a cell within a control, column, or split.

Syntax

object.Style = variant

Remarks

Read/Write at run time and design time.

Property applies to TDBList and TDBCombo controls, Column and Split objects.

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

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


Styles Property (TDBCombo)

This property returns a collection of named Style objects.

Syntax

object.Styles

Remarks

Read-only at run time. Not available at design time.

Property applies to TDBList and TDBCombo controls.

When a control is first created, it contains eight 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

Control and split caption bars

HighlightRow

Data cells in highlighted rows

EvenRow

Data cells in even numbered rows

OddRow

Data cells in odd numbered rows

NOTE: At design time, use the Style Factory property page to modify these built-in styles or create your own named styles.

See Also

TDBList and TDBCombo Controls


Tag Property (TDBCombo)

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.

Property applies to Column object for TDBList and TDBCombo.

Unlike other properties, the value of the Tag property is not used by the control.

See Also

Column Object, Columns Collection


Text Property (TDBCombo)

When applied to a Column object, this property returns or sets the formatted data value in a column for the current row.

Syntax

object.Text = string

Remarks

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

Property applies to TDBList and TDBCombo controls, Column object.

This is the default property of the TDBList and TDBCombo controls.

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.

For TDBList controls this property returns the ListField value for the selected row. When the Text property is set in code, the control tries to find a matching ListField value and repositions the selected row if a match is found. If no match is found, the selection is cancelled and the Text property returns an empty string.

For TDBCombo controls, this property returns or sets the contents of the text box portion of the control.

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection


VisibleCols Property (TDBCombo)

For TDBlist controls, this property returns the number of visible columns in the current split.

Syntax

object.VisibleCols

Remarks

Read-only at run time.

Property applies to TDBlist and TDBCombo controls.

The value returned includes both fully and partially displayed columns. You can use the Split property of the control to determine the index of the current split.

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

TDBList and TDBCombo Controls


VisibleRows Property (TDBCombo)

This property returns the number of visible rows in the control. The value returned includes both fully and partially displayed rows.

Syntax

object.VisibleRows = integer

Remarks

Read-only at run time.

Property applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


VScrollWidth Property (TDBCombo)

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.

Syntax

object.VScrollWidth

Remarks

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

Property applies to TDBList and TDBCombo controls, Split object.

If no vertical scroll bar exists, then the returned value is zero. If object is a TDBList or TDBCombo 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 control layout and sizing the control and its columns.

See Also

TDBList and TDBCombo Controls

Split Object, Splits Collection


TDBCombo Methods

AboutBox Method (TDBCombo)

AddItem Method (TDBCombo)

AddRegexCellStyle Method (TDBCombo)

CaptureImage Method (TDBCombo)

CellContaining Method (TDBCombo)

ClearFields Method (TDBCombo)

ClearRegexCellStyle Method (TDBCombo)

ClearSelCols Method (TDBCombo)

CloseCombo Method

GetBookmark Method (TDBCombo)

HoldFields Method (TDBCombo)

LoadLayout Method (TDBCombo)

OLEDrag Method

OpenCombo Method

PointAt Method (TDBCombo)

PostMsg Method (TDBCombo)

ReBind Method (TDBCombo)

Refresh Method (TDBCombo)

RemoveItem Method (TDBCombo)

RowBookmark Method (TDBCombo)

RowContaining Method (TDBCombo)

RowTop Method (TDBCombo)

Scroll Method (TDBCombo)

SplitContaining Method (TDBCombo)


AboutBox Method (TDBCombo)

This method displays the version number and copyright notice for the specified control.

Syntax

object.AboutBox

Remarks

Method applies to TDBList and TDBCombo controls.

Arguments

None

Return Value

None

See Also

TDBList and TDBCombo Controls


AddItem Method (TDBCombo)

This method adds an item to a the TDBList or TDBCombo object.

Syntax

object.AddItem strItem, [strValue], [nIndex]

Remarks

Method applies to TDBList and TDBCombo controls.

Arguments

strItem specifies the display text of the item.

strValue specifies a string for the VALUE attribute of the item.

nIndex is an integer that specifies the item's position within the list.

Return Value

None

See Also

TDBList and TDBCombo Controls


AddRegexCellStyle Method (TDBCombo)

This method allows you to control the font and color of cells within a control, column, or split according to their contents.

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

Method applies to TDBList and TDBCombo controls, Column and Split objects.

The status values (CellStyleConstants) specified by the condition argument determine which cells are affected:

1 - dblCurrentCell

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.

4 - dblUpdatedCell

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

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

The cell satisfies none of these conditions.

-1 - dblAllCells

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 (dblCurrentCell + dblSelectedRow) denotes a current cell within a selected row. You can also use a cell status value of 0 (dblNormalCell) 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 (dblAllCells).

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 DBList 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 TrueDBControl80.Style

S.Font.Bold = True
TDBList1.AddRegexCellStyle dblNormalCell, 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 control, 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

TDBList and TDBCombo Controls

Column Object, Columns Collection

Split Object, Splits Collection


CaptureImage Method (TDBCombo)

This method returns an image of the control in a format that you can assign to the Picture (Visual Basic) property of a Visual Basic form or control, or the PaintPicture (Printer object) method of the Printer (Visual Basic) object.

Syntax

object.CaptureImage

Remarks

Method applies to TDBList and TDBCombo controls.

Arguments

None

Return Value

A picture object containing a snapshot of the control's display.

See Also

TDBList and TDBCombo Controls


CellContaining Method (TDBCombo)

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.

Syntax

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

Method applies to TDBList and TDBCombo controls.

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

If the specified coordinate is outside of the control's data area, this method returns False. You can use the PointAt method to determine what kind of control 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

TDBList and TDBCombo Controls


ClearFields Method (TDBCombo)

The ClearFields method restores the default control 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

Method applies to TDBList and TDBCombo controls.

You can cancel the control's automatic layout behavior by invoking the HoldFields method.

See Also

TDBList and TDBCombo Controls


ClearRegexCellStyle Method (TDBCombo)

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

Method applies to TDBList and TDBCombo controls, Column and Split objects.

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

TDBList and TDBCombo Controls


ClearSelCols Method (TDBCombo)

The ClearSelCols method deselects all columns in a split.

Syntax

object.ClearSelCols

Arguments

None

Return Value

None

Remarks

Method applies to TDBList and TDBCombo controls, Split object.

If no columns are selected, then this method does nothing.

If a control 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 control's Split property.

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

See Also

TDBList and TDBCombo Controls


CloseCombo Method

The CloseCombo method closes the list portion of the control if not already closed.

Syntax

TDBCombo.CloseCombo

Remarks

Method applies to TDBCombo control.

Arguments

None

Return Value

None

See Also

TDBList and TDBCombo Controls


GetBookmark Method (TDBCombo)

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

Method applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


HoldFields Method (TDBCombo)

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

Method applies to TDBList and TDBCombo controls.

You can resume the control'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

TDBList and TDBCombo Controls


LoadLayout Method (TDBCombo)

The LoadLayout method loads a previously saved control layout from a binary layout storage file and configures the control accordingly.

Syntax

object.LoadLayout

Arguments

None

Return Value

None

Remarks

Method applies to TDBList and TDBCombo controls.

You can use this method to easily switch to a predefined control 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 control 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

TDBList and TDBCombo Controls


OLEDrag Method

The OLEDrag method initiates an OLE drag/drop operation.

Syntax

TDBCombo.OLEDrag

Arguments

None

Return Value

None

Remarks

Method applies to TDBCombo control.

When this method is called, the list fires its OLEStartDrag event, enabling your application to supply data to a target component.

See Also

TDBList and TDBCombo Controls


OpenCombo Method

The OpenCombo method opens the list portion of the control if not already open.

Syntax

TDBCombo.OpenCombo

Arguments

None

Return Value

None

Remarks

Method applies to TDBCombo control.

See Also

TDBList and TDBCombo Controls


PointAt Method (TDBCombo)

The PointAt method returns one of the constants in the preceding list, which indicates the kind of control element beneath the specified coordinate pair.

Syntax

object.PointAt (x, y)

Arguments

x and y are singles that define a coordinate pair in twips.

Return Value

Remarks

Method applies to TDBList and TDBCombo controls.

Run Time

0 - Not in List | dblNotInList
1 - At List Caption | dblAtCaption
2 - At Split Header | dblAtSplitHeader
3 - At Split Size Box | dblAtSplitSizeBox
4 - At Row Select | dblAtRowSelect
5 - At Row Size | dblAtRowSize
6 - At Column Header | dblAtColumnHeader
7 - At Column Footer | dblAtColumnFooter
8 - At Column Size | dblAtColumnSize
9 - At Data Area | dblAtDataArea

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

TDBList and TDBCombo Controls


PostMsg Method (TDBCombo)

The PostMsg method is used in conjunction with the PostEvent event to postpone operations which are illegal within the control's events.

Syntax

object.PostMsg MsgId

Arguments

MsgId is an integer that identifies the message being posted.

Return Value

None

Remarks

This method applies to TDBList and TDBCombo controls.

If the PostMsg method is called, the control 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.

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

TDBList and TDBCombo Controls


ReBind Method (TDBCombo)

This method re-establishes the connection with the bound data source, causing the TDBList or TDBCombo 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

Method applies to TDBList and TDBCombo controls.

If you have not modified the control 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 control will assume that you wish to maintain the modified control layout and will not automatically reset the columns.

For an unbound control 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 control with records from the unbound data source. After the control has finished refilling its cache, it fires the FirstRowChange event.

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 control 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 control's automatic layout response and force the control 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

TDBList and TDBCombo Controls


Refresh Method (TDBCombo)

For a TDBList or TDBCombo 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

Method applies to TDBList and TDBCombo controls, Column object.

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

See Also

TDBList and TDBCombo Controls

Column Object, Columns Collection


RemoveItem Method (TDBCombo)

This method removes an item to a the TDBList or TDBCombo object.

Syntax

object.RemoveItem [nIndex]

Arguments

nIndex is an integer that specifies the item's position within the list. The index is zero-based.

Return Value

None

Remarks

Method applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


RowBookmark Method (TDBCombo)

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

Method applies to TDBList and TDBCombo controls.

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 control's Bookmark property) if the current row is visible and the rownumber argument is equal to the control'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

TDBList and TDBCombo Controls


RowContaining Method (TDBCombo)

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

Method applies to TDBList and TDBCombo controls.

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

If coordinate is outside of the control'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

TDBList and TDBCombo Controls


RowTop Method (TDBCombo)

The RowTop method returns the Y coordinate of the top of a visible row relative to the top of the control, as given by the control'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 control's container.

Remarks

Method applies to TDBList and TDBCombo controls.

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

See Also

TDBList and TDBCombo Controls


Scroll Method (TDBCombo)

This method scrolls the control 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

Method applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


SplitContaining Method (TDBCombo)

The SplitContaining method returns the Index value of the split containing the specified coordinate pair.

Syntax

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

Method applies to TDBList and TDBCombo controls.

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

If either argument is outside of the control'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

TDBList and TDBCombo Controls


TDBCombo Events

ClassicRead Event (TDBCombo)

Change Event

Click Event (TDBCombo)

Close Event

ColMove Event (TDBCombo)

ColResize Event (TDBCombo)

DblClick Event (TDBCombo)

Error Event (TDBCombo)

FetchCellStyle Event (TDBCombo)

FetchCellTips Event (TDBCombo)

FetchRowStyle Event (TDBCombo)

FetchScrollTips Event (TDBCombo)

FirstRowChange Event (TDBCombo)

FootClick Event (TDBCombo)

FormatText Event (TDBCombo)

HeadClick Event (TDBCombo)

ItemChange Event

KeyDown Event (TDBCombo)

KeyPress Event (TDBCombo)

KeyUp Event (TDBCombo)

LayoutReady Event (TDBCombo)

LeftColChange Event (TDBCombo)

Mismatch Event

MouseDown Event (TDBCombo)

MouseMove Event (TDBCombo)

MouseUp Event (TDBCombo)

OLECompleteDrag Event

OLEDragDrop Event

OLEDragOver Event

OLEGiveFeedback Event

OLESetData Event

OLEStartDrag Event

Open Event

OwnerDrawCell Event (TDBCombo)

NotInList Event

Paint Event (TDBCombo)

PostEvent Event (TDBCombo)

RowResize Event (TDBCombo)

RowSourceChanged Event (TDBCombo)

Scroll Event (TDBCombo)

SelChange Event (TDBCombo)

UnboundColumnFetch Event (TDBCombo)

UnboundFindData Event (TDBCombo)

UnboundGetRelativeBookmark Event (TDBCombo)

UnboundReadData Event (TDBCombo)

UnboundReadDataEx Event (TDBCombo)


ClassicRead Event (TDBCombo)

The ClassicRead event is fired when an unbound control (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 control.

Remarks

Event applies to TDBList and TDBCombo controls.

To return an unbound value to the control, simply set the Value argument to the desired result. If you do not assign a value, the cell will remain blank.

See Also

TDBList and TDBCombo Controls


Change Event

The Change event is fired only if the ComboStyle property is set to 0 - Dropdown Combo or 1 - Simple Combo and the user changes the text by typing into the text box portion of the combo control.

Syntax

TDBCombo_Change ( )

Arguments

None

Remarks

Event applies to TDBCombo control.

See Also

TDBList and TDBCombo Controls


Click Event (TDBCombo)

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

Syntax

object_Click ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

Clicking a control also generates MouseDown and MouseUp events in addition to the Click event. The order of events for both the TDBList and TDBCombo controls is MouseDown, MouseUp, and Click.

When the user clicks a noncurrent row, the Click event fires before the control attempts to reposition to the row that was clicked. If the attempt succeeds, the control then fires the 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

TDBList and TDBCombo Controls


Close Event

The Close event occurs when the user closes the list portion of the control by clicking the drop-down button or by pressing Alt + Down Arrow while the control is open.

Syntax

TDBCombo_Close ( )

Arguments

None

Remarks

Event applies to TDBCombo control.

This event is fired only when ComboStyle property is set to 0 - Dropdown Combo or 2 - Dropdown List.

See Also

TDBList and TDBCombo Controls


ColMove Event (TDBCombo)

The ColMove event occurs when the user has finished moving the selected columns.

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

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.

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.

Event applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


ColResize Event (TDBCombo)

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 control to be repainted even if the Cancel argument is True.

Event applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


DblClick Event (TDBCombo)

The DblClick event occurs when the user presses then releases a mouse button twice in rapid succession over the control.

Syntax

object_DblClick ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

Double clicking a control also generates MouseDown, MouseUp, and Click events in addition to the DblClick event. The order of events for the control is MouseDown, MouseUp, Click, DblClick, and MouseUp.

See Also

TDBList and TDBCombo Controls


Error Event (TDBCombo)

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

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


FetchCellStyle Event (TDBCombo)

The FetchCellStyle event occurs when the control is about to display cell data in a column whose FetchStyle property is set to True.

Syntax

object_FetchCellStyle (ByVal Condition As Integer, ByVal Split As Integer, Bookmark As Variant, ByVal Col As Integer, ByVal CellStyle As TrueDBList80.StyleDisp)

TDBDropDown_FetchCellStyle (ByVal Condition As Integer, Bookmark As Variant, ByVal Col As Integer, ByVal CellStyle As TrueDBList80.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.

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.

See the CellTip constants for a list of allowable values.

You can also set the ForegroundPicture property of the CellStyle parameter to display distinct bitmaps on a per-cell basis.

Event applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


FetchCellTips Event (TDBCombo)

If the CellTips property is not set to 0 - None, the FetchCellTips event will be fired whenever the control has focus and the cursor is idle for a small amount of time (defined by the CellTipsDelay property) over a data cell, column header, column footer, split header, or control caption bar.

Syntax

object_FetchCellTips (ByVal SplitIndex As Integer, ByVal ColIndex As Integer, ByVal RowIndex As Long, CellTip As String, ByVal FullyDisplayed As Boolean, ByVal TipStyle As TrueDBList80.StyleDisp)

Arguments

Event applies to TDBList and TDBCombo controls.

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 control 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 control column, ColIndex will be negative and equal to one of the following CellTipConstants, depending upon the cursor position:

dblOnEmptyColumn

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:

dblOnColumnHeader

Cursor is over a column header

dblOnSplitHeader

Cursor is over a split header

dblOnEmptyRow

Cursor is over the empty rows area (if EmptyRows is True) or the blank area (if EmptyRows is False)

dblOnCaption

Cursor is over the control caption

dblOnAddNew

Cursor is over the AddNew row

dblOnColumnFooter

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 control 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 row, 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 control'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

TDBList and TDBCombo Controls


FetchRowStyle Event (TDBCombo)

Syntax

object_FetchRowStyle (ByVal Split As Integer, Bookmark As Variant, ByVal RowStyle As TrueDBList80.StyleDisp)

TDBDropDown_FetchRowStyle (Bookmark As Variant, ByVal RowStyle As TrueDBList80.StyleDisp)

Arguments

Split is the zero-based index of the split for which formatting information is being requested.

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

Remarks

The FetchRowStyle event is fired whenever the control is about to display a row of data, but only if the FetchRowStyle property is True for the control or one of its splits.

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.

Event applies to TDBList and TDBCombo controls.

See Also

TDBList and TDBCombo Controls


FetchScrollTips Event (TDBCombo)

If the ScrollTips property is True, the FetchScrollTips event will be fired whenever the control has focus and the scrollbar thumb is moved using the mouse.

Syntax

TDBlist_FetchScrollTips (ByVal SplitIndex As Integer, ByVal ColIndex as Integer, Bookmark As Variant, ByVal ScrollBar as ScrollBarsConstants, ScrollTip As String, ByVal TipStyle As TrueOleDBList70.StyleDisp)

TDBCombo_FetchScrollTips (ByVal ColIndex as Integer, Bookmark As Variant, ByVal ScrollBar as ScrollBarsConstants, ScrollTip As String, ByVal TipStyle As TrueOleDBList70.StyleDisp)

Arguments

SplitIndex is the zero-based index of the split that the scrollbar is associated with.

ColIndex is the leftmost column in the current split.

Bookmark is a variant that uniquely identifies the topmost control 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.

Remarks

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


FirstRowChange Event (TDBCombo)

The FirstRowChange event occurs when the first displayed row of a control or split is changed.

Syntax

object_FirstRowChange (ByVal SplitIndex As Integer)

TDBDropDown_FirstRowChange ( )

Arguments

SplitIndex is the zero-based index of the split in which the row change occurred.

Remarks

Event applies to TDBList and TDBCombo controls.

This event is triggered under several circumstances:

•

When the control is first displayed.

•

When the user scrolls through the control with the vertical scroll bar or navigation keys.

•

When data in the control 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 FirstRowChange, LeftColChange, and RowChange.

See Also

TDBList and TDBCombo Controls


FootClick Event (TDBCombo)

The FootClick event occurs when the user clicks on the footer for a particular control column.

Syntax

object_FootClick (ColIndex As Integer)

Arguments

ColIndex is an integer that identifies the column footer that was clicked.

Remarks

Event applies to TDBList and TDBCombo controls.

One possible action for this event is to re-sort the Recordset (Data control) object based on the selected column.

See Also

TDBList and TDBCombo Controls


FormatText Event (TDBCombo)

The FormatText event occurs when the control is about to display cell data in a column whose NumberFormat property is set to the string FormatText Event.

Syntax

object_FormatText (ColIndex As Integer, Value As Variant)

Arguments

ColIndex is an integer that identifies the column being displayed.

Value is a variant containing the underlying data value.

Remarks

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


HeadClick Event (TDBCombo)

The HeadClick event occurs when the user clicks on the header for a particular control column.

Syntax

object_HeadClick (ColIndex As Integer)

Arguments

ColIndex is an integer that identifies the column header that was clicked.

Remarks

Event applies to TDBList and TDBCombo controls.

One possible action for this event is to re-sort the Recordset (Data control) object based on the selected column.

See Also

TDBList and TDBCombo Controls


ItemChange Event

The ItemChange event occurs when the contents of the text box portion of a combo and the current row in the list portion change simultaneously.

Syntax

TDBCombo_ItemChange ( )

Arguments

None

Remarks

Event applies to TDBCombo control.

This event is triggered under several circumstances:

•

When the user selects a different item from the list portion.

•

When the user enters characters into the text portion that result in an incremental match.

•

When the user changes the current record position by interacting with a bound data control.

•

When the current record position or DataField value is changed in code.

Typically, you attach an ItemChange event procedure to a combo control to carry out commands and command-like actions.

See Also

TDBList and TDBCombo Controls


KeyDown Event (TDBCombo)

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

Event applies to TDBList and TDBCombo controls.

Although the KeyUp and KeyDown events are fired for most keystrokes, they are 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

TDBList and TDBCombo Controls


KeyPress Event (TDBCombo)

Use the KeyPress event to test keystrokes for validity or to format characters as they are typed.

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 control. Changing KeyAscii to 0 cancels the keystroke so the control receives no character.

Remarks

Event applies to TDBList and TDBCombo controls.

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.

See Also

TDBList and TDBCombo Controls


KeyUp Event (TDBCombo)

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

Event applies to TDBList and TDBCombo controls.

Although the KeyUp and KeyDown events are fired for most keystrokes, they are 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

TDBList and TDBCombo Controls


LayoutReady Event (TDBCombo)

The LayoutReady event fires when asynchronous downloading of a control layout file has completed.

Syntax

object_LayoutReady ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

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 control 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 control on an HTML page.

In either case, the control 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:

TDBList1.LayoutName = "MyLayout"

TDBList1.LoadLayout

NOTE: You can create control layout files at design time by setting the LayoutFileName and LayoutName properties and using the layout commands on the control's visual editing menu.

See Also

TDBList and TDBCombo Controls


LeftColChange Event (TDBCombo)

The LeftColChange event occurs when the first visible column of a control is changed.

Syntax

object_LeftColChange ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

This event is triggered under several circumstances:

•

When the control is first displayed.

•

When the user scrolls through the control 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 FirstRowChange, LeftColChange, and RowChange.

See Also

TDBList and TDBCombo Controls


Mismatch Event

The Mismatch event is triggered whenever the user enters a value in the text portion of a combo box that is not found in the list portion.

Syntax

TDBCombo_Mismatch (NewEntry As String, Reposition As Integer)

Arguments

NewEntry is a string representing the text that was entered by the user but not found in the list.

Reposition is an integer that may be set to False in order to prevent the current row from moving back to the top of the list when a mismatch has been typed.

Remarks

Event applies to TDBCombo control.

By default, Reposition is 0 - True, which resets the current row back to the top of the list portion when the event is fired.

If you set Reposition to 1 - False, and the combo cannot locate NewEntry, the current row remains unchanged when this event is fired.

NOTE: This event is only fired when the LimitToList property is True and the ComboStyle property is set to 0- Dropdown Combo or 1- Simple Combo .

See Also

TDBList and TDBCombo Controls


MouseDown Event (TDBCombo)

Use a MouseDown or MouseUp event procedure to specify actions that will occur when a given mouse button is pressed or released.

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 control's container.

Remarks

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


MouseMove Event (TDBCombo)

The MouseMove event is generated continually as the mouse pointer moves across the control.

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 control's container.

Remarks

Event applies to TDBList and TDBCombo controls.

This event is primarily useful for implementing drag-and-drop behavior on a per-column basis.

See Also

TDBList and TDBCombo Controls


MouseUp Event (TDBCombo)

Use a MouseDown or MouseUp event procedure to specify actions that will occur when a given mouse button is pressed or 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 control's container.

Remarks

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


OLECompleteDrag Event

The OLECompleteDrag event occurs when a combo is the source component of a drag/drop operation.

Syntax

TDBCombo_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

Event applies to TDBCombo control.

This event informs the combo 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 combo 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 combo control needs to delete the object from itself after the move.

See Also

TDBList and TDBCombo Controls


OLEDragDrop Event

The OLEDragDrop event occurs when a combo control is the target component of a drag/drop operation and its OLEDropMode is set to 1 - Manual.

Syntax

TDBCombo_OLEDragDrop (Data As TrueDBCombo80.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 combo's container.

Remarks

Event applies to TDBCombo control.

This event informs the combo 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

TDBList and TDBCombo Controls


OLEDragOver Event

The OLEDragOver event occurs when a combo control is the target component of a drag/drop operation and its OLEDropMode is set to 1 - Manual.

Syntax

TDBCombo_OLEDragOver (Data As TrueDBCombo80.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 combo'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 combo control. The value will be one of the following:

0 - vbEnter

The source component is being dragged within the range of the target combo control.

1 - vbLeave

The source component is being dragged out of the range of the target combo control.

2 - vbOver

The source component has moved from one position within the target combo control to another.

Remarks

Event applies to TDBCombo control.

This event informs the combo 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

TDBList and TDBCombo Controls


OLEGiveFeedback Event

The OLEGiveFeedback event occurs when a combo control is the source component of a drag/drop operation.

Syntax

TDBCombo_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

Event applies to TDBCombo control.

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.

The OLEGiveFeedback event occurs after every OLEDragOver event of the target component. 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

TDBList and TDBCombo Controls


OLESetData Event

The OLESetData event occurs when a combo 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

TDBCombo_OLESetData (Data As TrueDBCombo80.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

Event applies to TDBCombo control.

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 combo is text.

See Also

TDBList and TDBCombo Controls


OLEStartDrag Event

The OLEStartDrag event occurs when a combo control is a source component of a drag/drop operation and its OLEDrag method is called.

Syntax

TDBCombo_OLEStartDrag (Data As TrueDBCombo80.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 combo 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

Event applies to TDBCombo control.

This event enables your application to specify the data formats and drop effects that the source combo 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

TDBList and TDBCombo Controls


Open Event

The Open event occurs when the user opens the list portion of the control by clicking the drop-down button or by pressing Alt + Down Arrow while the control is closed.

Syntax

TDBCombo_Open ( )

Arguments

None

Remarks

Event applies to TDBCombo control.

This event is fired only when ComboStyle property is set to 0 - Dropdown Combo or 2 - Dropdown List.

See Also

TDBList and TDBCombo Controls


OwnerDrawCell Event (TDBCombo)

The OwnerDrawCell event occurs just before the cell specified by the Bookmark, Col, and Split arguments is to be painted.

Syntax

object_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

Event applies to TDBList and TDBCombo controls.

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

TDBList and TDBCombo Controls


NotInList Event

The NotInList event is triggered whenever the user enters a value in the text portion of a combo box that is not found in the list portion.

Syntax

TDBCombo_NotInList (NewEntry as String, Retry as Integer)

Arguments

NewEntry is a string representing the text that was entered by the user but not found in the list.

Retry is an integer that may be set to True in order to force the control to requery the list for the new entry.

Remarks

Event applies to TDBCombo control.

You can add the new value to the row source within this event, then set the Retry argument to True in order to force the control to requery the list and reposition the selected item to the newly added record. By default, Retry is 0, which indicates that no further searching should occur.

If you set Retry to True in consecutive firings of this event, and the combo still cannot locate NewEntry, then this event will not fire again until the user changes the search string by typing or deleting characters.

NOTE: This event is only fired when the LimitToList property is True and the user presses the Enter key while the list portion of the combo is closed.

See Also

TDBList and TDBCombo Controls


Paint Event (TDBCombo)

The Paint event is triggered whenever the control repaints itself (that is, whenever it receives a WM_PAINT message).

Syntax

object_Paint ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

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 control's hWnd property to paint special effects such as lines, bitmaps, and icons in appropriate cells of the control.

See Also

TDBList and TDBCombo Controls


PostEvent Event (TDBCombo)

The PostEvent event is used in conjunction with the PostMsg method to postpone operations that are illegal within the control's events.

Syntax

object_PostEvent (ByVal MsgId As Integer)

Arguments

MsgId is an integer that identifies the message posted by the PostMsg method.

Remarks

Event applies to TDBList and TDBCombo controls.

If the PostMsg method is called, the control 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.

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

TDBList and TDBCombo Controls


RowResize Event (TDBCombo)

The RowResize event occurs when the user has finished resizing a control row.

Syntax

object_RowResize (Cancel As Integer)

Arguments

Cancel is an integer that may be set to True to undo resizing.

Remarks

Event applies to TDBList and TDBCombo controls.

Your event procedure can accept the change, alter the degree of change, or cancel the change completely.

The 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 control to be repainted even if the Cancel argument is True.

See Also

TDBList and TDBCombo Controls


RowSourceChanged Event (TDBCombo)

The RowSourceChanged event fires when a bound data source is changed or requeried.

Syntax

object_RowSourceChanged ( )

Arguments

None

Remarks

Event applies to TDBList and TDBCombo controls.

This event also fires when a bound control is first loaded.

The RowSourceChanged event fires before the control is filled with data. Therefore, you can use this event to initialize the control 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 DBCombo, you can use the RowSourceChanged event in conjunction with the BookmarkType property to circumvent type mismatch errors that may occur when a control-supplied bookmark is passed to an ADO Recordset object (or vice versa). The workaround is as follows:

Sub TDBList1_DataSourceChanged()

TDBList1.BookmarkType = VarType(ADODC1.Recordset.Bookmark)

End Sub

This code ensures that any bookmarks returned by the combo are first converted to the appropriate type for the bound data source. This workaround is only needed when using the combo in an HTML page; it is not needed for Visual Basic 6.0.

See Also

TDBList and TDBCombo Controls


Scroll Event (TDBCombo)

The Scroll event occurs when the user scrolls the control 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

Event applies to TDBList and TDBCombo controls.

This event is fired before the control 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 control 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 control'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

TDBList and TDBCombo Controls


SelChange Event (TDBCombo)

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

Event applies to TDBList and TDBCombo controls.

This event is triggered under several circumstances:

•

When the user selects a single row.

•

When the user adds a row to the list of selected rows by clicking it 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.

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

TDBList and TDBCombo Controls


UnboundColumnFetch Event (TDBCombo)

The UnboundColumnFetch event is fired when a bound control (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

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

Remarks

Event applies to TDBList and TDBCombo controls.

For a bound control, 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 control, 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.

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 control contains one or more unbound columns.

During the execution of this event, row movement is not permitted.

See Also

TDBList and TDBCombo Controls


UnboundFindData Event (TDBCombo)

When a list or combo control is activated, it will attempt to position to the record that matches the current cell text of its parent control.

Syntax

object_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 list or combo control 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

Event applies to TDBList and TDBCombo controls.

To do this, the control will fire the UnboundFindData event, which allows you to set the current record position within the control.

The SeekFlags argument specifies how to compare the Value argument to dropdown column data:

dblSeekLT

Find first column data less than Value

dblSeekLE

Find first column data less than or equal to Value

dblSeekEQ

Find first column data equal to Value

dblSeekGE

Find first column data greater than or equal to Value

dblSeekGT

Find first column data greater than Value

dblSeekPartialEQ

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

TDBList and TDBCombo Controls


UnboundGetRelativeBookmark Event (TDBCombo)

This event is used in conjunction with the UnboundReadData or ClassicRead events when the control needs to obtain positional information about your underlying data.

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

Event applies to TDBList and TDBCombo controls.

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.

By coding this event for DataMode setting 1 - Unbound, you can dramatically improve the performance of the control. 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 control of BOF/EOF conditions.

See Also

TDBList and TDBCombo Controls


UnboundReadData Event (TDBCombo)

The UnboundReadData event is fired when an unbound control (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 control display.

Syntax

object_UnboundReadData (ByVal RowBuf As TrueDBList80.RowBuffer, StartLocation As Variant, ByVal ReadPriorRows As Boolean)

Arguments

RowBuf is a RowBuffer object used to transfer row data to the control.

StartLocation is a variant bookmark that identifies the row to position to before fetching the next or previous page of records. If Null, the control 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 control is requesting records that precede StartLocation. If False, the control is requesting records that follow StartLocation.

Remarks

Event applies to TDBList and TDBCombo controls.

The RowBuf argument acts like a two-dimensional array of variants corresponding to the control cells being fetched. By populating its Value property with the appropriate data, your event procedure transfers rows from the unbound dataset to the control.

Use the row buffer's RowCount property to determine how many rows of data the control 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 control by populating the row buffer's Bookmark property for each row returned. Keep in mind that the bookmark-based TDBList 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 control 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 DBList 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 control performs accurately with large multiuser databases.

See Also

TDBList and TDBCombo Controls


UnboundReadDataEx Event (TDBCombo)

The UnboundReadDataEx event is fired when an unbound control (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 control display.

Syntax

object_UnboundReadDataEx (ByVal RowBuf As TrueDBList80.RowBuffer, StartLocation As Variant, ByVal Offset As Long, ApproximatePosition As Long)

Arguments

RowBuf is a RowBuffer object used to transfer row data to the control.

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

Event applies to TDBList and TDBCombo controls.

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 control cells being fetched. By populating its Value property with the appropriate data, your event procedure transfers rows from the unbound dataset to the control.

Use the row buffer's RowCount property to determine how many rows of data the control is requesting. Use its ColumnCount property to determine the number of columns to be populated, if any. If ColumnCount is zero, the control is requesting the bookmark of a single row; if ColumnCount is nonzero, the control is requesting RowCount rows of data and their corresponding bookmarks.

The ColumnIndex property specifies the control 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 control by populating the row buffer's Bookmark property for each row returned. Keep in mind that the bookmark-based TDBList 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 control 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

TDBList and TDBCombo Controls


Constant Reference

Alignment Constants

AnimateWindow Constants

AnimateWindowClose Constants

AnimateWindowDirection Constants

Appearance Constants

BackgroundPictureDrawMode Constants

BorderAppearance Constants

BorderStyle Constants

BorderType Constants

CellStyle Constants

CellTip Constants

CellTipPresentation Constants

ComboStyle Constants

DataMode Constants

DataView Constants

DividerStyle Constants

DropdownPosition Constants

Error Constants

ExposeCellMode Constants

ForegroundPicturePosition Constants

MatchCol Constants

MatchCompare Constants

MatchEntry Constants

Menu Constants

MousePointer Constants

MultipleLines Constants

MultiSelect Constants

OLEDragMode Constants

OLEDropMode Constants

PointAt Constants

Presentation Constants

RowSelector Constants

ScrollBars Constants

SplitSizeMode Constants

UnboundFind Constants

VerticalAlignment Constants


Alignment Constants

Applies To

Alignment, FooterAlignment, and HeadAlignment properties

Values

Design Time | Run Time
0 - Left (default) | dblLeft
1 - Right | dblRight
2 - Center | dblCenter
3 - General (default) | dblGeneral


AnimateWindow Constants

Applies To

AnimateWindow property

Values

Design Time | Run Time
0 - No Animate (default) | dblNoAnimate
1 - Roll | dblRoll
2 - Slide | dblSlide
3 - Blend | dblBlend


AnimateWindowClose Constants

Applies To

AnimateWindowClose property

Values

Design Time | Run Time
0 - No Animate Close (default) | dblNoAnimateClose
1 - Opposite Direction | dblOppositeDirection
2 - Same Direction | dblSameDirection


AnimateWindowDirection Constants

Applies To

AnimateWindowDirection property

Values

Design Time | Run Time
0 - Default | dblDefaultDirection
1 - Top To Bottom | dblTopToBottom
2 - Bottom To Top | dblBottomToTop
3 - Left To Right | dblLeftToRight
4 - Right To Left | dblRightToLeft
5 - Top Left To Bottom Right | dblTopLeftToBottomRight
6 - Top Right To Bottom Left | dblTopRightToBottomLeft
7 - Bottom Left To Right | dblBottomLeftToTopRight
8 - Bottom Right To Top Left | dblBottomRightToTopLeft
9 - Center | dblAnimateCenter


Appearance Constants

Applies To

Appearance property

Values

Design Time | Run Time
0 - Flat | dblFlat
1 - 3D (default) | dbl3D
2 - Mixed Flat | dblMixedFlat


BackgroundPictureDrawMode Constants

Applies To

BackgroundPictureDrawMode property

Values

Design Time | Run Time
0 - Center (default) | dblBPCenter
1 - Tile | dblBPTile
2 - Stretch | dblBPStretch


BorderAppearance Constants

Applies To

BorderAppearance property

Values

Design Time | Run Time
0 - Flat(default) | dblFlatStyle
1 - 3D Raised | dbl3DRaised
2 - 3D Inset | dbl3DInset
3 - 3D Raised Bevel | dbl3DRaisedBevel
4 - 3D Insert Bevel | dbl3DInsetBevel


BorderStyle Constants

Applies To

BorderStyle property

Values

Design Time | Run Time
0 - None | dblNoBorder
1 - Fixed Single (default) | dblFixedSingle


BorderType Constants

Applies To

BorderType property

Values

Design Time | Run Time
0 - None (default) | dblBorderNone
1 - Left | dblBorderLeft
2 - Right | dblBorderRight
4 - Top | dblBorderTop
8 - Bottom | dblBorderBottom


CellStyle Constants

Applies To

AddRegexCellStyle and ClearRegexCellStyle methods; FetchCellStyle event

Values

Description | Run Time
-1 - Applies to all cells in all rows | dblAllRows
0 - Cells in nonselected rows | dblNormalRow
8 - Cells in selected rows | dblSelectedRow


CellTip Constants

Applies To

FetchCellTips event

Values

Description | Run Time
-2 - On Empty Column | dblOnEmptyColumn
-1 - On Column Header | dblOnColumnHeader
-2 - On Split Header | dblOnSplitHeader
-3 - On Empty Row | dblOnEmptyRow
-4 - On Caption | dblOnCaption
-5 - On AddNew Row | dblOnAddNew
-6 - On Column Footer | dblOnColumnFooter


CellTipPresentation Constants

Applies To

CellTips property

Values

Design Time | Run Time
0 - None (default) | dblNoCellTips
1 - Anchored | dblAnchored
2 - Floating | dblFloating


ComboStyle Constants

Applies To

ComboStyle property

Values

Design Time | Run Time
0 - Dropdown Combo (default) | dbcDropdownCombo
1 - Simple Combo | dbcSimpleCombo
2 - Dropdown List | dbcDropdownList


DataMode Constants

Applies To

DataMode property

Values

Design Time | Run Time
0 - Bound (default) | dblBound
1 - Unbound | dblUnbound
2 - Unbound Extended | dblUnboundEx
3 - Application | dblUnboundAp
4 - Storage | dblUnboundSt
5 - AddItem | dblAddItem


DataView Constants

Applies To

DataView property

Values

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


DividerStyle Constants

Applies To

DividerStyle and RowDividerStyle properties

Values

Design Time | Run Time
0 - No dividers (Split default) | dblNoDividers
1 - Black line | dblBlackLine
2 - Dark gray line (non-Split default) | dblDarkGrayLine
3 - Raised | dblRaised
4 - Inset | dblInset
5 - ForeColor | dblUseForeColor
6 - Light gray line | dblLightGrayLine


DropdownPosition Constants

Applies To

TDBCombo control

Values

Description | Run Time
0 - Default Position | dblDefaultPosition
1 - Right Down | dblRightDown
2 - Right Up | dblRightUp
3 - Left Down | dblLeftDown
4 - Left Up | dblLeftUp


Error Constants

Applies To

Trappable errors for TDBList and TDBCombo controls

Values

Description | Run Time
4097 - Cannot initialize data bindings | dblBINDERROR
4098 - Invalid setting for name property | dblINVPROPVAL
6145 - Invalid column index | dblCOLINDEX
6146 - Control not properly initialized | dblNOTINIT
6147 - Column not found | dblCNOTFOUND
6148 - Invalid row number | dblINVROWNUM
6149 - Invalid bookmark | dblINVBOOKMARK
6150 - Invalid selected row bookmark index | dblBADSELRIDX
6151 - Scroll arguments out of range | dblSCROLLRANGE
6152 - Invalid setting for ScrollBars property | dblINVSBSTYLE
6153 - Error occurred while trying to update record | dblUPDERROR
6154 - Error occurred while trying to add record | dblADDERROR
6155 - Error occurred while trying to delete record | dblDELERROR
6156 - Data type mismatch during field update | dblCOLDATA
6157 - Data type incompatible with column data type | dblINCOMPAT
6158 - name is not a valid data field name | dblFIELDERR
6161 - Operation is invalid within the event name | dblBADEVENT
6162 - Property is not available in this context | dblNOPROPNOW
6163 - No current record | dblNOCURREC
6164 - Caption text is too long | dblCAPTOOLONG
6244 - Invalid split index | dblSPLITINDEX
6245 - Invalid value list index | dblVLINDEX
6246 - Error accessing value item | dblVITEMERR
6247 - Invalid style index | dblSTYLEINDEX
6248 - Duplicate style name | dblDUPSTYLE
6249 - Error accessing style | dblSTYLEERR
6250 - Error updating style | dblUPDSTYLE
6251 - Error removing style | dblREMSTYLE
6252 - Error adding cell condition | dblADDCELLCOND
6253 - Invalid style name | dblSTYLENAME
6254 - Error applying style | dblAPPLYSTYLE
6255 - Bitmap is too large | dblBMPTOOLARGE


ExposeCellMode Constants

Applies To

ExposeCellMode property

Values

Design Time | Run Time
0 - Scroll on Select (default) | dblScrollOnSelect
2 - Never Scroll | dblNeverScroll


ForegroundPicturePosition Constants

Applies To

ForegroundPicturePosition property

Values

Design Time | Run Time
0 - Left (default) | dblFPLeft
1 - Right | dblFPRight
2 - Left of Text | dblFPLeftOfText
3 - Right of Text | dblFPRightOfText
4 - Top of Text | dblFPTopOfText
5 - Bottom of Text | dblFPBottomOfText
6 - Picture Only | dblFPPictureOnly
7 - Text Only | dblFPTextOnly


MatchCol Constants

Applies To

MatchCol property

Values

Design Time | Run Time
0 - ListField (default) | dblListField
1 - Current Mouse Position | dblCurrentMousePos
2 - Current Selected Col | dblCurrentSelectedCol
3 - Left Visible Col | dblLeftVisibleCol
4 - Right Visible Col | dblRightVisibleCol
-1 - All Cols | dblAllCols


MatchCompare Constants

Applies To

MatchCompare property

Values

Design Time | Run Time
-6 - Partially Equal (Default) | dblSeekPartialEQ
-1 - Less Than | dblSeekLT
-2 - Less Than or Equal | dblSeekLE
-3 - Equal | dblSeekEQ
-4 - Greater Than or Equal | dblSeekGE
-5 - Greater Than | dblSeekGT
-7 - Include Equal (OLEDB only) | dblSeekIncludeEQ


MatchEntry Constants

Applies To

MatchEntry property

Values

Design Time | Run Time
0 - None (default) | dblMatchEntryNone
1 - Standard | dblMatchEntryStandard
2 - Extended | dblMatchEntryExtended


Menu Constants

Applies To

GetMenuText and SetMenuText methods

Values

Constant | Menu Command
0 - dblpMenuFile | File
1 - dblpMenuPrint | Print
2 - dblpMenuExit | Exit
3 - dblpMenuView | View
4 - dblpMenuZoomIn | Zoom In
5 - dblpMenuZoomOut | Zoom Out
6 - dblpMenuFit | Fit in Window
7 - dblpMenuPgFirst | First Page
8 - dblpMenuPgPrev | Previous Page
9 - dblpMenuPgNext | Next Page
10 - dblpMenuPgLast | Last Page
11 - dblpMenuPrintSomePages | Print Some Pages
12 - dblpMenuPrintCurrPage | Print Current Page
13 - dblpDlgPagesCaption | Print Some Pages dialog caption
14 - dblpDlgPagesPrompt | Print Some Pages dialog prompt
15 - dblpDlgPagesOk | Print Some Pages dialog OK button text
16 - dblpDlgPagesCancel | Print Some Pages Cancel button text
17 - dblpTipPrint | Print Document
18 - dblpTipZoomIn | Zoom In
19 - dblpTipZoomOut | Zoom Out
20 - dblpTipFit | Fit in Window
21 - dblpTipZoom | Zoom Factor
22 - dblpTipPgFirst | First Page
23 - dblpTipPgPrev | Previous Page
24 - dblpTipPgNext | Next Page
25 - dblpTipPgLast | Last Page
26 - dblpTipPageOf | Current page number
27 - dblpTipStop | Stop Pagination


MousePointer Constants

Applies To

MousePointer property

Values

Design Time | Run Time
0 - Default (default) | dblMPDefault
1 - Arrow | dblMPArrow
2 - Cross | dblMPCross
3 - I-beam | dblMPIbeam
4 - Icon | dblMPIcon
5 - Size | dblMPSize
6 - Size NE SW | dblMPSizeNESW
7 - Size NS | dblMPSizeNS
8 - Size NW SE | dblMPSizeNWSE
9 - Size EW | dblMPSizeEW
10 - Up Arrow | dblMPUpArrow
11 - Hourglass | dblMPHourglass
12 - No Drop | dblMPNoDrop
13 - Arrow Hourglass | dblMPArrowHourglass
14 - Arrow Question | dblMPArrowQuestion
15 - Size All | dblMPSizeAll
99 - Custom | dblMPCustom


MultipleLines Constants

Applies To

MultipleLines property

Values

Design Time | Run Time
0 - Disabled (default) | dblMultipleDisabled
1 - Variable | dblMultipleVariable
2 - Fixed | dblMultipleFixed


MultiSelect Constants

Applies To

MultiSelect property

Values

Design Time | Run Time
0 - None (default) | dblMultiSelectNone
1 - Simple | dblMultiSelectSimple
2 - Extended | dblMultiSelectExtended
3 - Checkbox | dblMultiSelectCheckbox


OLEDragMode Constants

Applies To

OLEDragMode property

Values

Design Time | Run Time
0 - Manual (default) | dbcOLEDragManual
1 - Automatic | dbcOLEDragAutomatic


OLEDropMode Constants

Applies To

OLEDropMode property

Values

Design Time | Run Time
0 - None (default) | dbcOLEDropNone
1 - Manual | dbcOLEDropManual
2 - Automatic | dbcOLEDropAutomatic


PointAt Constants

Applies To

PointAt method

Values

Description | Run Time
0 - Not in List | dblNotInList
1 - At List Caption | dblAtCaption
2 - At Split Header | dblAtSplitHeader
3 - At Split Size Box | dblAtSplitSizeBox
4 - At Row Select | dblAtRowSelect
5 - At Row Size | dblAtRowSize
6 - At Column Header | dblAtColumnHeader
7 - At Column Footer | dblAtColumnFooter
8 - At Column Size | dblAtColumnSize
9 - At Data Area | dblAtDataArea
10 - At Group Area | dbgAtGroupArea
11 - At Group Header | dbgAtGroupHeader


Presentation Constants

Applies To

Presentation property

Values

Design Time | Run Time
0 - Normal (default) | dblNormal
1 - Radio Button | dblRadioButton
4 - Check Box | dblCheckBox


RowSelector Constants

Applies To

ExportToDelimitedFile, ExportToFile, PrintData, and PrintPreview methods

Values

Description | Run Time
0 - All Rows | dblRSAllRows
1 - Selected Rows | dblRSSelectedRows
2 - Current Row | dblRSCurrentRow


ScrollBars Constants

Applies To

ScrollBars property

Values

Design Time | Run Time
0 - None | dblNone
1 - Horizontal | dblHorizontal
2 - Vertical | dblVertical
3 - Both | dblBoth
4 - Automatic (default) | dblAutomatic


SplitSizeMode Constants

Applies To

SizeMode property

Values

Design Time | Run Time
0 - Scalable (default) | dblScalable
1 - Exact | dblExact
2 - Number of Columns | dblNumberOfColumns


UnboundFind Constants

Applies To

UnboundFindData event

Values

Description | Run Time
-1 - Less Than | dblSeekLT
-2 - Less Than or Equal | dblSeekLE
-3 - Equal | dblSeekEQ
-4 - Greater Than or Equal | dblSeekGE
-5 - Greater Than | dblSeekGT
-6 - Partially Equal | dblSeekPartialEQ


VerticalAlignment Constants

Applies To

VerticalAlignment property

Values

Design Time | Run Time
0 - Top (default) | dblTop
1 - Bottom | dblBottom
2 - Vertical Center | dblVertCenter


PrintInfo Reference


PrintInfo Object Members

PrintInfo 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.
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.
PageHeader | Sets/returns the page header for a PrintInfo object.
PageHeaderFont | Sets/returns the page header font for a PrintInfo object.
PageSetupCancelled | Returns true if the Page Setup dialog is cancelled by the user.
PreviewCaption | Sets/returns the print preview window caption.
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.
RepeatListHeader | Sets/returns whether the list 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 list's contents directly to the printer.
PrintPreview | Opens the print preview window on the list's contents.
SetMenuText | Overrides the default text for the specified PrintPreview menu item.
SubstituteFont | Adds a substitution font for printing.


PrintInfo Object Properties

Collate Property (PrintInfo)

Default Property (PrintInfo)

Draft Property (PrintInfo)

Name Property (PrintInfo)

NoClipping Property (PrintInfo)

NumberOfCopies Property (PrintInfo)

PageFooter Property (PrintInfo)

PageFooterFont Property (PrintInfo)

PageHeader Property (PrintInfo)

PageHeaderFont Property (PrintInfo)

PageSetupCancelled Property (PrintInfo)

PreviewCaption Property (PrintInfo)

PreviewMaximize Property (PrintInfo)

PreviewPageOf Property (PrintInfo)

RangeOfPages Property (PrintInfo)

RepeatColumnFooters Property (PrintInfo)

RepeatColumnHeaders Property (PrintInfo)

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

Property applies to PrintInfo object.

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


Default Property (PrintInfo)

This property sets or returns a boolean that determines whether the target object is the default PrintInfo for the associated TDBList control.

Syntax

PrintInfo.Default = boolean

Remarks

Read/Write at run time and design time.

Property applies to PrintInfo object.

If True (the default), the PrintInfo property of the associated TDBList control returns the target object.

If False, the target object can only be accessed through the PrintInfos collection of the associated TDBList control.

When a TDBList control is first created, its PrintInfos collection contains a single PrintInfo object whose Default property is True.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

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


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.

Property applies to PrintInfo object.

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

See Also

PrintInfo Object, PrintInfos Collection


NoClipping Property (PrintInfo)

This property sets or returns a boolean that determined how cell text is clipped during print and print preview operations.

Syntax

PrintInfo.NoClipping = boolean

Remarks

Read/Write at run time and design time.

Property applies to PrintInfo object.

If False (the default), text inside of list cells is clipped to the cell boundaries, as it is in the normal list view.

If set to True, any text inside the list 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, PrintInfos Collection


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.

Property applies to PrintInfo object.

When NumberOfCopies is greater than 1, the order in which pages are printed is determined by the Collate property.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

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:

TDBList1.PrintInfo.PageFooter = "\tCONFIDENTIAL"

Use the PageHeader property to specify a string to be printed at the top of each page.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

By default, this is the same value returned by the list's Font property.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

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

TDBList1.PrintInfo.PageHeader = CStr(Now) & "\t\tPage \p"

Use the PageFooter property to specify a string to be printed at the bottom of each page.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

By default, this is the same value returned by the list's Font property.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

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


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.

Property applies to PrintInfo object.

By default, this property returns an empty string, and no window caption is displayed.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

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


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.

Property applies to PrintInfo object.

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


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.

Property applies to PrintInfo object.

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 list 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, PrintInfos Collection


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.

Property applies to PrintInfo object.

If True, column footers are printed at the bottom of each physical page.

If False (the default), column footers are printed on the first page only.

NOTE: If the ColumnFooters property of the associated TDBList control is False, then column footers are not printed, regardless of the setting of this property.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

If True, column headers are printed at the top of each physical page below the split headers and list header, if present.

If False (the default), column headers are printed on the first page only.

NOTE: If the ColumnHeaders property of the associated TDBList control is False, then column headers are not printed, regardless of the setting of this property.

See Also

PrintInfo Object, PrintInfos Collection


RepeatListHeader Property (PrintInfo)

This property sets or returns a boolean that determines whether the list caption should appear on each page.

Syntax

PrintInfo.RepeatListHeader = boolean

Remarks

Read/Write at run time and design time.

Property applies to PrintInfo object.

If True, the list caption is printed at the top of each physical page.

If False (the default), the list caption is printed on the first page only.

NOTE: If the Caption property of the associated TDBList control is not set, then the list header is not printed, regardless of the setting of this property.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

If True, split captions are printed at the top of each physical page below the list 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 TDBList control, then the split headers are not printed, regardless of the setting of this property.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

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

TDBList1.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. You cannot access an individual attribute such as the printer name; all page setup settings must be saved and restored as a unit.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

See Also

PrintInfo Object, PrintInfos Collection


SettingsMarginBottom Property (PrintInfo)

This property provides access to the bottom margin in the print Settings blob, allowing you to control the margin setting at the bottom of the page.

Syntax

PrintInfo.SettingsMarginBottom = long

Remarks

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

Property applies to PrintInfo object.

The setting is in twips. The following code will result in a one-inch margin at the bottom of the printed page:

TDBList1.PrintInfo.SettingsMarginBottom = 1440

See Also

PrintInfo Object, PrintInfos Collection


SettingsMarginLeft Property (PrintInfo)

This property provides access to the left margin in the print Settings blob, allowing you to control the left margin setting.

Syntax

PrintInfo.SettingsMarginLeft = long

Remarks

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

Property applies to PrintInfo object.

The setting is in twips. The following code will result in a one-inch left margin on the printed page:

TDBList1.PrintInfo.SettingsMarginLeft = 1440

See Also

PrintInfo Object, PrintInfos Collection


SettingsMarginRight Property (PrintInfo)

This property provides access to the right margin in the print Settings blob, allowing you to control the right margin setting.

Syntax

PrintInfo.SettingsMarginRight = long

Remarks

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

Property applies to PrintInfo object.

The setting is in twips. The following code will result in a one-inch right margin on the printed page:

TDBList1.PrintInfo.SettingsMarginRight = 1440

See Also

PrintInfo Object, PrintInfos Collection


SettingsMarginTop Property (PrintInfo)

This property provides access to the top margin in the print Settings blob, allowing you to control the margin setting at the top of the page.

Syntax

PrintInfo.SettingsMarginTop = long

Remarks

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

Property applies to PrintInfo object.

The setting is in twips. The following code will result in a one-inch margin at the top of the printed page:

TDBList1.PrintInfo.SettingsMarginTop = 1440

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

See Also

PrintInfo Object, PrintInfos Collection


SettingsPaperHeight Property (PrintInfo)

Use this property to specify the paper height in the print Settings blob. The setting is in twips.

Syntax

PrintInfo.SettingsPaperHeight = long

Remarks

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

Property applies to PrintInfo object.

See Also

PrintInfo Object, PrintInfos Collection


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.

Property applies to PrintInfo object.

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


SettingsPaperWidth Property (PrintInfo)

Use this property to specify the paper width in the print Settings blob. The setting is in twips.

Syntax

PrintInfo.SettingsPaperWidth = long

Remarks

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

Property applies to PrintInfo object.

See Also

PrintInfo Object, PrintInfos Collection


UnitsPerInch (PrintInfo)

Use the UnitsPerInch property to determine the logical resolution of a printer device context.

Syntax

PrintInfo.UnitsPerInch = long

Remarks

Read-only at run time. Not available at design time.

Property applies to PrintInfo object.

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


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.

Property applies to PrintInfo object.

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.


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

Use the GetMenuText method to retrieve 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

Method applies to PrintInfo object.

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


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.

Remarks

Method applies to PrintInfo object.

See Also

PrintInfo Object, PrintInfos Collection


PageSetup Method (PrintInfo)

The PageSetup method opens the page setup dialog for printing and print preview.

Syntax

PrintInfo.PageSetup

Arguments

None

Return Value

None

Remarks

Method applies to PrintInfo object.

This is a standard Windows dialog 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, PrintInfos Collection


PrintData Method (PrintInfo)

The PrintData method prints the specified rows in the associated list 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

Method applies to PrintInfo object.

Generally, this 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 list's SelBookmarks collection contains a bookmark for each selected row.

2 - dbgCurrentRow

Only the current row is printed. The list's Bookmark property returns the bookmark of the current row.

The printed output preserves as much of the associated list's original formatting as possible, including colors, fonts, alignment, and relative column widths. If present, the list 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 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, PrintInfos Collection


PrintPreview Method (PrintInfo)

The PrintPreview method opens a separate application window in which end users can preview the output that would be generated by the PrintData method.

Syntax

PrintInfo.PrintPreview [selector]

Arguments

selector is an optional RowSelectorConstants value that specifies the rows to be previewed.

Return Value

None

Remarks

Method applies to PrintInfo object.

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 list's SelBookmarks collection contains a bookmark for each selected row.

2 - dbgCurrentRow

Only the current row is previewed. The list's Bookmark property returns the bookmark of the current row.

The printed output preserves as much of the associated list's original formatting as possible, including colors, fonts, alignment, and relative column widths. If present, the list 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 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, PrintInfos Collection


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

Method applies to PrintInfo object.

The index argument can be one of the following constants:

Constant | Menu Command
0 - dblpMenuFile | File
1 - dblpMenuPrint | Print
2 - dblpMenuExit | Exit
3 - dblpMenuView | View
4 - dblpMenuZoomIn | Zoom In
5 - dblpMenuZoomOut | Zoom Out
6 - dblpMenuFit | Fit in Window
7 - dblpMenuPgFirst | First Page
8 - dblpMenuPgPrev | Previous Page
9 - dblpMenuPgNext | Next Page
10 - dblpMenuPgLast | Last Page
11 - dblpMenuPrintSomePages | Print Some Pages
12 - dblpMenuPrintCurrPage | Print Current Page
13 - dblpDlgPagesCaption | Print Some Pages dialog caption
14 - dblpDlgPagesPrompt | Print Some Pages dialog prompt
15 - dblpDlgPagesOk | Print Some Pages dialog OK button text
16 - dblpDlgPagesCancel | Print Some Pages Cancel button text
17 - dblpTipPrint | Print Document
18 - dblpTipZoomIn | Zoom In
19 - dblpTipZoomOut | Zoom Out
20 - dblpTipFit | Fit in Window
21 - dblpTipZoom | Zoom Factor
22 - dblpTipPgFirst | First Page
23 - dblpTipPgPrev | Previous Page
24 - dblpTipPgNext | Next Page
25 - dblpTipPgLast | Last Page
26 - dblpTipPageOf | Current page number
27 - dblpTipStop | Stop Pagination

Use the GetMenuText method to retrieve the text for the specified item.

See Also

PrintInfo Object, PrintInfos Collection


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

Method applies to PrintInfo object.

If the AvailableFont argument is omitted, any prior substitution is discarded.

See Also

PrintInfo Object, PrintInfos Collection


XArrayDB Reference

XArrayDB Object Members

XArrayDB Object Properties

XArrayDB Object Methods

XArrayDB Object Constants


XArrayDB Object Members

XArrayDB Object Properties

Count | Returns the number of elements for a given dimension.
DefaultColumnType | Sets/returns the default data type for the specified column.
LowerBound | Returns the lower bound for a given dimension.
Notify | Controls notification of OLEDBSimpleProviderListener objects.
Precision | Sets/returns the floating point precision value.
UpperBound | Returns the upper bound for a given dimension.
Value | Sets/returns the value of an individual array element.

XArrayDB Object Methods

AboutBox | Displays a dialog box with information about the array object.
AppendColumns | Appends new columns to an array object.
AppendRows | Appends new rows to an array object.
Clear | Deallocates all data associated with an array object.
Delete | Deletes an index from a given dimension.
DeleteColumns | Deletes a range of columns from an array object.
DeleteRows | Deletes a range of rows from an array object.
Find | Searches for a given value within an array column.
Get | Returns the value of an array element.
Insert | Inserts a new index into a given dimension.
InsertColumns | Inserts new columns into an array object.
InsertRows | Inserts new rows into an array object.
LoadRows | Loads a VB array into an XArrayDB object.
QuickSort | Uses the quicksort method to sort an array.
ReDim | Sets the dimensions of an array object while preserving its data.
Set | Assigns a value to an array element.


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

Property applies to XArrayDB object.

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.

Values

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.

Property applies to XArrayDB object.

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.

Property applies to XArrayDB object.

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.

Property applies to XArrayDB object.

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.

Property applies to XArrayDB object.

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.

Property applies to XArrayDB object.

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)

The Value property sets or returns the variant value of an individual XArrayDB 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.

Property applies to XArrayDB object.

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

Remarks

Method applies to XArrayDB object.

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

Method applies to XArrayDB object.

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

Method applies to XArrayDB object.

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

Method applies to XArrayDB object.

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

Method applies to XArrayDB object.

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.

Remarks

Method applies to XArrayDB object.

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.

Remarks

Method applies to XArrayDB object.

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)

A long integer corresponding to the index of the next row that contains a matching value.

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

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

Method applies to XArrayDB object.

The Find method searches for a specified value within a column of an XArrayDB object, starting at a particular row. 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

Method applies to XArrayDB object.

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

Method applies to XArrayDB object.

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)

This method inserts count columns into an XArrayDB object starting at column index and returns the number of columns successfully inserted.

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

Method applies to XArrayDB object.

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.

Remarks

Method applies to XArrayDB object.

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

Method applies to XArrayDB object.

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 TDBList 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 TDBList1.Array = MyArray

TDBList1.ReBind

See Also

XArrayDB Object


QuickSort Method (XArrayDB)

The QuickSort method sorts a range of rows in an XArrayDB object according to the specified column(s).

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

Method applies to XArrayDB object.

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)

This method is used to set or reset the dimensions of an XArrayDB object while preserving any existing 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

Method applies to XArrayDB object.

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

Method applies to XArrayDB object.

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 Remarks

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 Remarks

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 Remarks

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.