Style Property (TDBCombo)

Transcription

Copyright © 1987-2005 ComponentOne LLC. All rights reserved.
Corporate Headquarters
ComponentOne LLC
4516 Henry Street
Suite 500
Pittsburgh, PA 15213 USA
Internet:
info@ComponentOne.com
Web site:
http://www.componentone.com
Sales
E-mail: sales@componentone.com
Telephone: 1.800.858.2739 or 1.412.681.4343 (Pittsburgh, PA USA Office)
Technical Support
See Technical Support in this manual for information on obtaining technical support.
Trademarks
ComponentOne True DBList Pro 8.0 and the ComponentOne True DBList Pro 8.0 logo are trademarks, and ComponentOne is a
registered trademark of ComponentOne LLC. All other trademarks used herein are the properties of their respective owners.
Warranty
ComponentOne warrants that the original CD (or diskettes) are free from defects in material and workmanship, assuming normal
use, for a period of 90 days from the date of purchase. If a defect occurs during this time, you may return the defective CD (or disk)
to ComponentOne, along with a dated proof of purchase, and ComponentOne will replace it at no charge. After 90 days, you can
obtain a replacement for a defective CD (or disk) by sending it and a check for $25 (to cover postage and handling) to
ComponentOne.
Except for the express warranty of the original CD (or disks) set forth here, ComponentOne makes no other warranties, express or
implied. Every attempt has been made to ensure that the information contained in this manual is correct as of the time it was
written. We are not responsible for any errors or omissions. ComponentOne’s liability is limited to the amount you paid for the
product. ComponentOne is not liable for any special, consequential, or other damages for any reason.
Copying and Distribution
While you are welcome to make backup copies of the software for your own use and protection, you are not permitted to make
copies for the use of anyone else. We put a lot of time and effort into creating this product, and we appreciate your support in
seeing that it is used by licensed users only. Please read the License Agreement in this manual before copying and redistributing any
ComponentOne True DBList Pro 8.0 files.
· iii
Table of Contents
Table of Contents ....................................................................................................................... iii
Overview ........................................................................................................................................ 1
Product Profile ........................................................................................................................ 1
Installation............................................................................................................................... 3
Adding the True DBList Components to the Toolbox ...................................................... 3
Upgrading ............................................................................................................................... 4
END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE.............. 5
Redistributable Files............................................................................................................. 12
Technical Support................................................................................................................. 13
Getting Started............................................................................................................................ 15
Syntax Changes..................................................................................................................... 15
Terminology.......................................................................................................................... 15
Using the True DBList and True DBCombo Controls ..................................................... 16
The Basics..................................................................................................................................... 23
Specifying a Data Source ..................................................................................................... 23
Choosing a Column Layout ................................................................................................ 24
Configuring Columns at Design Time .............................................................................. 26
Configuring Columns at Run Time ................................................................................... 29
Understanding Bookmarks ................................................................................................. 31
True DBList Samples ................................................................................................................. 33
ICursor and OLEDB Samples ............................................................................................. 33
Tutorials ....................................................................................................................................... 35
Tutorial 1 - Binding True DBList to a Data Control......................................................... 35
Tutorial 2 - Incremental Search and Auto Completion with True DBCombo ............. 37
Tutorial 3 - Lookup Combo Update with Two Data Controls ....................................... 39
Tutorial 4 - Displaying Master-Detail Relationships ....................................................... 40
Tutorial 5 - Using True DBList with SQL Query Results................................................ 41
Tutorial 6 - Selecting Multiple Rows Using Bookmarks ................................................. 43
Tutorial 7 - Defining Unbound Columns in a Bound List .............................................. 45
Tutorial 8 - Displaying Translated Data............................................................................ 47
Tutorial 9 - Enhancing the User Interface with In-Cell Bitmaps.................................... 49
Tutorial 10 - Using Styles to Highlight Related Data ...................................................... 51
Tutorial 11 - Displaying Rows in Alternating Colors...................................................... 54
Tutorial 12 - Creating a List with Fixed, Nonscrolling Columns................................... 55
Tutorial 13 - Displaying Array Data in Unbound Mode................................................. 57
Tutorial 14 - Displaying Array Data in Unbound Extended Mode ............................... 61
Tutorial 15 - Displaying Array Data in Unbound Application Mode........................... 64
Tutorial 16 - Displaying Array Data in Unbound Storage Mode .................................. 66
Tutorial 17 - Sorting and Searching ................................................................................... 68
Tutorial 18 - Displaying Arbitrary Bitmaps...................................................................... 70
Tutorial 19 - Reusable Layouts ........................................................................................... 73
Tutorial 20 - Printing, Print Preview, and Export ............................................................ 75
Tutorial 21 - Cell Bordering and Scroll Tips/Tracking ................................................... 78
Tutorial 22 – Performing a List Search Using the Find Method .................................... 83
Tutorial 23 - Outlook-Style Grouping (OLEDB Only)..................................................... 88
iv ·
Object Model ............................................................................................................................... 93
True DBList Pro Objects and Collections .......................................................................... 93
TDBList and TDBCombo Controls..................................................................................... 94
Column Object, Columns Collection ................................................................................. 95
DataObject Object, DataObjectFiles Collection................................................................. 95
GroupColumns Object ......................................................................................................... 95
Layouts Object ...................................................................................................................... 96
PrintInfo Object, PrintInfos Collection .............................................................................. 96
RowBuffer Object.................................................................................................................. 96
SelBookmarks Object............................................................................................................ 96
Split Object, Splits Collection .............................................................................................. 97
Style Object, Styles Collection............................................................................................. 97
ValueItem Object, ValueItems Collection ......................................................................... 98
XArrayDB Object .................................................................................................................. 98
Working with Objects and Collections .............................................................................. 99
Design Time Interaction.......................................................................................................... 103
Context Menu...................................................................................................................... 103
Visual Editing Mode .......................................................................................................... 104
Property Page Overview ................................................................................................... 109
True DBList Property Pages.............................................................................................. 119
Reusable Layouts................................................................................................................ 140
Run Time Interaction ............................................................................................................... 143
Navigation and Scrolling................................................................................................... 143
Searching and Field Completion ...................................................................................... 145
Selection and Movement ................................................................................................... 146
Sizing and Splitting ............................................................................................................ 149
Drag-and-Drop Behavior................................................................................................... 150
Additional User Interaction Features .............................................................................. 152
Bound Mode .............................................................................................................................. 153
Binding True DBList Pro Controls to a Data Source...................................................... 153
Visual Basic Data Control Considerations ...................................................................... 154
Remote Data Control (RDC) Considerations.................................................................. 156
Unbound Columns............................................................................................................. 156
Storage Mode............................................................................................................................. 161
When to Use Storage Mode............................................................................................... 161
Using the XArrayDB Object .............................................................................................. 161
Interactions between True DBList and XArrayDB......................................................... 163
Storage Mode Examples .................................................................................................... 165
Application Mode..................................................................................................................... 167
When to Use Application Mode ....................................................................................... 167
How Application Mode Works ........................................................................................ 167
Application Mode Bookmarks.......................................................................................... 168
Application Mode Events.................................................................................................. 170
Application Mode Programming Considerations.......................................................... 171
Application Mode Example .............................................................................................. 171
Unbound Mode ......................................................................................................................... 173
When to Use Unbound Mode ........................................................................................... 173
How Unbound Mode Works ............................................................................................ 174
Unbound Mode Bookmarks.............................................................................................. 175
·v
Using the RowBuffer Object ............................................................................................. 175
Unbound Mode Events...................................................................................................... 176
Unbound Mode Programming Considerations ............................................................. 184
Unbound Mode Examples ................................................................................................ 185
AddItem Mode.......................................................................................................................... 187
When to Use AddItem Mode............................................................................................ 187
How AddItem Mode Works ............................................................................................. 187
Database Programming Techniques ..................................................................................... 189
Changing the Current Record Position ........................................................................... 189
Accessing Cell Data............................................................................................................ 189
Selecting and Highlighting Records ................................................................................ 190
Refreshing the Display....................................................................................................... 191
Refetching Data from the Data Source ............................................................................ 192
Postponing Illegal Operations in List Events ................................................................. 192
Searching Bookmarks Using the Find Method............................................................... 192
Customizing the List's Appearance....................................................................................... 195
Captions, Headers, and Footers ....................................................................................... 195
Three-dimensional versus Flat Display........................................................................... 197
Borders and Dividing Lines .............................................................................................. 199
Modifying the Cell Border Appearance .......................................................................... 200
Customizing the Scrollbars ............................................................................................... 202
Unpopulated Regions ........................................................................................................ 202
Row Height and Multiple-line Displays ......................................................................... 204
Alternating Row Colors..................................................................................................... 207
Horizontal and Vertical Alignment ................................................................................. 207
Window Animation ........................................................................................................... 208
Data Presentation Techniques ............................................................................................... 209
Text Formatting .................................................................................................................. 209
Automatic Data Translation with ValueItems................................................................ 211
Context-sensitive Help with CellTips.............................................................................. 219
Scroll Tracking and ScrollTips.......................................................................................... 221
Data-sensitive Cell Merging.............................................................................................. 221
Outlook-Style Grouping .................................................................................................... 223
Owner-drawn Cells............................................................................................................ 224
How to Use Splits ..................................................................................................................... 229
Referencing Splits and their Properties ........................................................................... 229
Creating and Removing Splits.......................................................................................... 231
Working with Columns in Splits...................................................................................... 231
Sizing and Scaling Splits.................................................................................................... 233
Creating and Resizing Splits through User Interaction ................................................ 235
Vertical Scrolling and Split Groups ................................................................................. 237
Horizontal Scrolling and Fixed Columns........................................................................ 239
How to Use Styles..................................................................................................................... 241
Built-in Named Styles ........................................................................................................ 241
Working with Style Properties ......................................................................................... 244
Applying Styles to Cells .................................................................................................... 254
Applying Pictures to List Elements ................................................................................. 257
True DBList Reference ............................................................................................................ 265
vi ·
All True DBList Members.................................................................................................. 265
TDBList Properties ............................................................................................................. 276
TDBList Methods................................................................................................................ 359
TDBList Events ................................................................................................................... 388
TDBCombo Reference ............................................................................................................. 415
TDBCombo Members......................................................................................................... 415
TDBCombo Control Properties......................................................................................... 420
TDBCombo Methods.......................................................................................................... 476
TDBCombo Events ............................................................................................................. 490
Constant Reference................................................................................................................... 521
PrintInfo Reference .................................................................................................................. 535
PrintInfo Object Members ................................................................................................. 535
PrintInfo Object Properties................................................................................................ 536
PrintInfo Object Methods .................................................................................................. 552
XArrayDB Reference................................................................................................................ 559
XArrayDB Object Members............................................................................................... 559
XArrayDB Object Properties ............................................................................................. 560
XArrayDB Object Methods................................................................................................ 564
XArrayDB Object Constants.............................................................................................. 575
Index............................................................................................................................................ 577
Product Profile · 1
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 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:
2 · Overview
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 · 3
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.
4 · Overview
In the Components dialog box, find and select the ComponentOne True DBList Pro 8.0 Control. Click
OK.
Control Name
Icon
Class Name
Prog ID
ComponentOne True DBList Pro 8.0
TDBList
TrueDBList80.TDBList
TDBCombo
TrueDBList80.TDBCombo
ComponentOne True DBList Pro 8.0 (OLEDB)
TDBList
TrueOleDBList80.TDBList
TDBCombo
TrueOleDBList80.TDBCombo
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:
FROM
OCX
TDBL_32
TDBL_32
TDBL5
TDBL5
TDBL5
TDBL5
TDBL6
TDBL6
TDBL6
TDBL6
TDBL7
TDBL7
TDBL8
TDBL8
TO
Version
True DBList Pro 5.0 for VB6
True DBList Pro 5.0 for VB6
True DBList Pro 5.0
True DBList Pro 5.0
True DBList Pro 5.0 OLEDB
True DBList Pro 6.0
True DBList Pro 6.0
True DBList Pro 7.0
True DBList Pro 8.0
OCX
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
TDBL8
Version
True DBList Pro 8.0
True DBList Pro 8.0
True DBList Pro 8.0
True DBList Pro 8.0
True DBList Pro 8.0
True DBList Pro 8.0
True DBList Pro 8.0
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.
END-USER LICENSE AGREEMENT FOR COMPONENTONE SOFTWARE · 5
•
Click the OK button to place the migration utility icon on the toolbar.
After you have added the True 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 FOR COMPONENTONE
SOFTWARE
IMPORTANT-READ CAREFULLY: This End User License Agreement (this "EULA") contains the terms
and conditions regarding your use of the SOFTWARE (as defined below). This EULA contains material
limitations to your rights in that regard. You should read this EULA carefully and treat it as valuable
property.
I. THIS EULA.
1.
Software Covered by this EULA. This EULA governs your use of the ComponentOne, LLC
("C1") software product(s) enclosed or otherwise accompanied herewith (individually and
collectively, the "SOFTWARE"). The term "SOFTWARE" includes, to the extent provided by C1:
1) any revisions, updates and/or upgrades thereto; 2) any data, image or executable files,
databases, data engines, computer software, or similar items customarily used or distributed with
computer software products; 3) anything in any form whatsoever intended to be used with or in
conjunction with the SOFTWARE; and 4) any associated media, documentation (including
physical, electronic and on-line) and printed materials (the "Documentation").
2.
This EULA is a Legally Binding Agreement Between You and C1. If you are acting as an agent
of a company or another legal person, such as an officer or other employee acting for your
employer, then "you" and "your" mean your principal, the entity or other legal person for whom
you are acting. However, importantly, even if you are acting as an agent for another, you may
still be personally liable for violation of federal and State laws, such as copyright infringement.
This EULA is a legally binding agreement between you and C1. You intend to be legally bound
to this EULA to the same extent as if C1 and you physically signed this EULA. By installing,
copying, or otherwise using the SOFTWARE, you agree to be bound by the terms and conditions
contained in this EULA. If you do not agree to all of the terms and conditions contained in this
EULA, you may not install or use the SOFTWARE. If, for whatever reason, installation has
begun or has been completed, you should cancel installation or un-install the SOFTWARE, as the
case may be. (You may click on the "exit" button or its equivalent to immediately abort
6 · Overview
installation.) If you do not agree to all of these terms and conditions, then you must promptly
return the SOFTWARE to the place of business from which you obtained it in accordance with
any return policies of such place of business. Return policies may vary between or among
resellers, and you must comply with your particular reseller's return policies as agreed at the
point of purchase. If the place of business from which you purchased the SOFTWARE does not
honor a complete refund for a period of thirty (30) days from the date of proof of purchase, then
you may return the SOFTWARE directly to C1 for a period of thirty (30) days from the date of
your purchase. To return the product directly to C1, you must obtain a C1 Return Authorization
Number by contacting C1, and you must forward all items purchased, including the proof of
purchase, directly to C1. The return must be postage-prepaid, and post-marked within thirty (30)
days from the proof of purchase, time being of the essence. The return option to C1 is only
available to the original purchaser of an unopened factory packaged item.
II. YOUR LICENSE TO DEVELOP AND TO DISTRIBUTE.
As provided in more detail below, this EULA grants you two licenses: 1) a license to use the SOFTWARE
to develop other software products (the "Development License"); and 2) a license to use and/or
distribute the Developed Software (the "Distribution License"). Both of these licenses (individually and
collectively, the "Licenses") are explained and defined in more detail below.
1.
Definitions. The following terms have the respective meanings as used in this EULA:
"Network Server" means a computer with one or more computer central processing units (CPU's)
that operates for the purpose of serving other computers logically or physically connected to it,
including, but not limited to, other computers connected to it on an internal network, intranet or
the Internet. "Web Server" means a type of Network Server that serves other computers more
particularly connected to it over an intranet or the Internet.
"Developed Software" means those computer software products that are developed by or
through the use of the SOFTWARE. "Developed Web Server Software" means those Developed
Software products that reside logically or physically on at least one Web Server and are operated
(meaning the computer software instruction set is carried out) by the Web Server's central
processing unit(s) (CPU). "Developed Legacy Software" means those Developed Software
products that are not Developed Web Server Software, including, for example, stand-alone
applications and applications accessed by a file server only. "Redistributable Files" means the
SOFTWARE files or other portions of the SOFTWARE that are provided by C1 and are identified
as such in the Documentation for distribution by you with the Developed Software. "Developer"
means a human being or any other automated device using the SOFTWARE in accordance with
the terms and conditions of this EULA.
"Developer Seat License" means that each Developer using or otherwise accessing the
programmatic interface or the SOFTWARE must obtain the right to do so by purchasing a
separate End User License.
“Source Code” shall mean computer software code or programs in human readable format, such
as a printed listing of such a program written in a high-level computer language. The term
"Source Code" includes, but is not limited to, documents and materials in support of the
development effort of the SOFTWARE, such as flow charts, pseudo code and program notes.
2.
Your Development License. You are hereby granted a limited, royalty-free, non-exclusive right
to use the SOFTWARE to design, develop, and test Developed Software, on the express condition
that, and only for so long as, you fully comply with all terms and conditions of this EULA.
The SOFTWARE is licensed to you on a Developer Seat License basis.
The Developer Seat License means that you may perform an installation of the SOFTWARE for
use in designing, testing and creating Developed Software by a single Developer on one or more
computers, each with a single set of input devices, so long as such computer/computers is/are
used only by one single Developer at any given time and not concurrently. Conversely, you may
not install or use the SOFTWARE on a computer that is a network server or a computer at which
the SOFTWARE is used by more than one Developer. You may not network the SOFTWARE or
any component part of it, where it is or may be used by more than one Developer unless you
purchase an additional Development License for each Developer. You must purchase another
separate license to the SOFTWARE in order to add additional developer seats, whether the
additional developers are accessing the SOFTWARE in a stand-alone environment or on a
computer network.
In all cases, you may not use C1's name, logo, or trademarks to market your Developed Software
without the express written consent of C1; (b) you must include the following C1 copyright
notice in your Developed Software documentation and/or in the "About Box" of your Developed
Software, and wherever the copyright/rights notice is located in the Developed Software
(“Portions Copyright © ComponentOne, LLC 1991-2002. All Rights Reserved.”); (c) agree to
indemnify, hold harmless, and defend C1, its suppliers and resellers, from and against any claims
or lawsuits, including attorney's fees that may arise from the use or distribution of your
Developed Software; (d) you may use the SOFTWARE only to create Developed Software that is
significantly different than the SOFTWARE.
3.
Your Distribution License.
License to Distribute Developed Software. Subject to the terms and conditions in this EULA,
you are granted the license to use and to distribute Developed Software on a royalty-free basis,
provided that the Developed Software incorporates the SOFTWARE as an integral part of the
Developed Software in machine-language compiled format (customarily an ".exe", or ".dll", etc.).
You may not distribute, bundle, wrap or subclass the SOFTWARE as Developed Software which,
when used in a "designtime" development environment, exposes the programmatic interface of
the SOFTWARE. You may distribute, on a royalty-free basis, Redistributable Files with
Developed Software only.
4.
Specific Product Limitations. Notwithstanding anything in this EULA to the contrary, if the
license you have purchased is for any of the following products, then the following additional
limitations will apply:
a. ComponentOne Reports for .NET Designer Edition. ComponentOne Reports for .NET
Designer Edition includes at least: 1) one dynamic link library (c1.win.c1reportdesigner.dll) file
known as C1ReportDesigner Component, 2) one executable (ReportDesigner.exe) file known as
C1ReportDesigner Application and, 3) the Source Code of the C1ReportDesigner Application.
The C1ReportDesigner Component is subject to the general terms and restrictions set forth in this
EULA. The C1ReportDesigner Application is an executable file used to design and prepare
reports; the C1ReportDesigner Application may be distributed, free of royalties, only in
conjunction with the Developed Software.
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
8 · Overview
exclusively in conjunction with and/or as a part of the Developed Software. You are expressly
not granted the right to distribute, disclose or otherwise make available to any third party the
licensed Source Code, any modified version, derivative work, or any portion thereof, in source
code format.
C1 shall retain all right, title and interest in and to the licensed Source Code, and all C1 updates,
modifications or enhancements thereof. Nothing herein shall be deemed to transfer any
ownership or title rights in and to the licensed Source Code from C1 to you.
SOURCE CODE IS LICENSED TO YOU AS IS. C1 DOES NOT AND SHALL NOT PROVIDE
YOU WITH ANY TECHNICAL SUPPORT FOR YOUR SOURCE CODE LICENSE.
b. VSView Reporting Edition. VSView Reporting Edition includes at least one executable file
listed as “VSRptX.exe” (where X indicates the version number i.e.7,8, etc.), known as “Designer.”
The file "VSRptX.exe”, or any upgrade or future versions of the Designer, are subject to the
restrictions set forth in this EULA and may not be distributed with your Developed Software or
in any other way.
c. Doc-to-Help and ComponentOne Natural Search. You may use Doc-To-Help to create online
help, manuals or other documentation in electronic or printed format (the "Output Documents").
You may distribute and incorporate in such Output Documents those files identified in the
documentation as Redistributable Files. Except for those specific Redistributable Files, you MAY
NOT distribute the SOFTWARE, in any format, to others.
d. Studio Products. You may not share the component parts of the Studio Products licensed to
you with other Developers, nor may you allow the use and/or installation of such components
by other Developers.
e. ComponentOne Response and SOAP Channel. ComponentOne Response is intended to be
installed on a Network Server. C1 grants to you the following rights to the SOFTWARE: a)
Installation: You may install one copy of the SOFTWARE on a single Network Server; b) Use:
When installed and initialized, the SOFTWARE creates a database file which contains the
embodiment of a solution knowledge base (the database hereinafter referred to as the
"Knowledge Base").
You may use the SOFTWARE to create Knowledge Bases on one Network Server only. To create
or to operate Knowledge Bases in more than one Network Server, you must purchase one
additional SOFTWARE license for each additional Network Server.
5.
Updates/Upgrades; Studio Subscription. Subject to the terms and conditions of this EULA, the
Licenses are perpetual. Updates and upgrades to the SOFTWARE may be provided by C1 from
time-to-time, and, if so provided by C1, are provided upon the terms and conditions offered at
that time by C1 in its sole discretion. C1 may provide updates and upgrades to the SOFTWARE
for free or for any charge, at any time or never, and through its chosen manner of access and
distribution, all in C1's sole and complete discretion.
C1 licenses certain of its separately-licensed products bundled together in a product suite, called
the C1 "Studio" product line (the "Studio Products"). The exact separately-licensed products that
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.
10 · Overview
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, endusers, or for any end-uses that are restricted by U.S. export laws and regulations, and any
amendments thereof, which include, but are not limited to, the following:
Restricted Countries: Restricted Countries currently include, but are not necessarily limited to
Cuba, Iran, Iraq, Libya, Montenegro, North Korea, Serbia, Sudan, and Syria.
Restricted End-Users: Any End-User whom you know or have reason to know will use
SOFTWARE or Developed Software in the design, development, or production of missiles and
missile technology, nuclear weapons and weapons technology, or chemical and biological
weapons. Any national of any of the Restricted Countries, wherever located, who intends to
transmit or transport the SOFTWARE or Developed Software to one of the Restricted Countries.
Restricted End-Uses: Any use of SOFTWARE and Developed Software related to the design,
development, or production of missiles and missile technology, nuclear weapons and weapons
technology, or chemical and biological weapons.
These restrictions change from time to time. You represent and warrant that neither the BXA nor
any other United States federal agency has suspended, revoked or denied your export privileges.
C1 acknowledges that it shall use reasonable efforts to supply you with all reasonably necessary
information regarding the SOFTWARE and its business to enable you to fully comply with the
provisions of this Section. If you have any questions regarding your obligations under United
States of America export regulations, you should contact the Bureau of Export Administration,
United States Department of Commerce, Exporter Counseling Division, Washington DC. U.S.A.
(202) 482-4811, http://www.bxa.doc.gov.
7.
U.S. Government Restricted Rights. The SOFTWARE and documentation are provided with
RESTRICTED RIGHTS. For solicitations issued before December 1, 1995, by the United States of
America, its agencies and/or instrumentalities (the "Government"), other than the Department of
Defense, the use, duplication or disclosure of the software and documentation provided to the
Government under this EULA shall be subject to the RESTRICTED RIGHTS as set forth in
subparagraphs (c)(1) and (2) of the Commercial Computer Software - Restricted Rights clause at
48 CFR ch.1 52.227-19. For solicitations issued before September 29, 1995, by the Department of
Defense, the use, duplication or disclosure of the software and documentation provided under
this EULA shall be subject to the RESTRICTED RIGHTS as set forth in subparagraph (c)(1)(ii) of
the Rights in Technical Data and Computer Software clause at 48 CFR ch.2 252.227-7013. You
will comply with any requirements of the Government to obtain such RESTRICTED RIGHTS
protection, including without limitation, the placement of any restrictive legends on the
SOFTWARE, and any license agreement used in connection with the distribution of the
SOFTWARE. Manufacturer is ComponentOne, LLC, 4516 Henry Street, Suite 501, Pittsburgh,
Pennsylvania 15213 USA. For solicitations issued by the Government on or after December 1,
1995 and the Department of Defense on or after September 29, 1995, the only rights provided in
the software and documentation provided herein shall be those contained in this EULA. Under
no circumstances shall C1 be obligated to comply with any Governmental requirements
regarding the submission of or the request for exemption from submission of cost or pricing data
or cost accounting requirements. For any distribution of the SOFTWARE that would require
compliance by C1 with the Government's requirements relating to cost or pricing data or cost
accounting requirements, you must obtain an appropriate waiver or exemption from such
requirements for the benefit of C1 from the appropriate Government authority before the
distribution and/or license of the SOFTWARE to the Government.
IV. WARRANTIES AND REMEDIES.
1.
Limited Warranty. C1 warrants that the original media, if any, are free from defects for ninety
(90) days from the date of delivery of the SOFTWARE. EXCEPT AS OTHERWISE PROVIDED
IN THE PRECEDING SENTENCE, AND TO THE MAXIMUM EXTENT PERMITTED BY
APPLICABLE LAW, C1 EXPRESSLY DISCLAIMS ANY WARRANTY FOR THE SOFTWARE,
DOCUMENTATION AND ANYTHING ELSE PROVIDED BY C1 HEREBY AND C1
PROVIDES THE SAME IN “AS IS” CONDITION WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
THE ENTIRE RISK ARISING OUT OF USE OR PERFORMANCE OF THE SOFTWARE AND
DOCUMENTATION REMAINS WITH YOU. THIS LIMITED WARRANTY GIVES YOU
SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS WHICH VARY FROM STATE TO
STATE.
2.
Limited Remedy. C1's entire liability and your exclusive remedy under this EULA shall be, at
C1's sole option, either (a) return of the price paid for the SOFTWARE; (b) repair the SOFTWARE
through updates distributed online or otherwise in C1's discretion; or (c) replace the SOFTWARE
with SOFTWARE that substantially performs as described in the SOFTWARE documentation,
provided that you return the SOFTWARE in the same manner as provided in Section I.2 for
return of the SOFTWARE for non-acceptance of this EULA. Any media for any repaired or
replacement SOFTWARE will be warranted for the remainder of the original warranty period or
thirty (30) days, whichever is longer. THESE REMEDIES ARE NOT AVAILABLE OUTSIDE OF
THE UNITED STATES OF AMERICA. TO THE MAXIMUM EXTENT PERMITTED BY
APPLICABLE LAW, IN NO EVENT SHALL C1 BE LIABLE FOR ANY DAMAGES
WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF
BUSINESS PROFIT, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION,
OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE, EVEN IF C1 HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES. BECAUSE SOME STATES/JURISDICTIONS DO NOT ALLOW THE
EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL
DAMAGES IN CERTAIN CASES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.
V. MISCELLANEOUS.
1.
This is the Entire Agreement. This EULA (including any addendum or amendment to this EULA
included with the SOFTWARE) is the final, complete and exclusive statement of the entire
agreement between you and C1 relating to the SOFTWARE. This EULA supersedes any prior
and contemporaneous proposals, purchase orders, advertisements, and all other communications
in relation to the subject matter of this EULA, whether oral or written. No terms or conditions,
other than those contained in this EULA, and no other understanding or agreement which in any
way modifies these terms and conditions, shall be binding upon the parties unless entered into in
writing executed between the parties, or by other non-oral manner of agreement whereby the
parties objectively and definitively act in a manner to be bound (such as by continuing with an
installation of the SOFTWARE, "clicking-through" a questionnaire, etc.) Employees, agents and
other representatives of C1 are not permitted to orally modify this EULA.
12 · Overview
2.
You Indemnify C1. . You agree to indemnify, hold harmless, and defend C1 and its suppliers
and resellers from and against any and all claims or lawsuits, including attorney's fees, which
arise out of or result from your breach of any of the terms and conditions of this EULA.
3.
Interpretation of this EULA. If for any reason a court of competent jurisdiction finds any
provision of this EULA, or any portion thereof, to be unenforceable, that provision of this EULA
will be enforced to the maximum extent permissible so as to effect the intent of the parties, and
the remainder of this EULA will continue in full force and effect. Formatives of defined terms
shall have the same meaning of the defined term. Failure by either party to enforce any provision
of this EULA will not be deemed a waiver of future enforcement of that or any other provision.
Except as otherwise required or superseded by law, this EULA is governed by the laws of the
Commonwealth of Pennsylvania, without regard to its conflict of laws principles. The parties
consent to the personal jurisdiction and venue of the Commonwealth of Pennsylvania, in the
County of Allegheny, and agree that any legal proceedings arising out of this EULA shall be
conducted solely in such Commonwealth. If the SOFTWARE was acquired outside the United
States, then local law may apply.
Redistributable Files
True DBList Pro 8.0 is developed and published by ComponentOne LLC. You may use it to develop
applications in conjunction with Microsoft Visual Studio or any other programming environment that
enables the user to use and integrate the control(s). You may also distribute, free of royalties, the
following Redistributable Files with any such application you develop to the extent that they are used
separately on a single CPU on the client/workstation side of the network:
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 TODL8.OCX. This file is not used by
TDBL8.OCX, which contains built-in unbound mode support. This file is shared
with True DBGrid 8.0.
TDBGPP8.DLL
Printing, print preview, and export support DLL for use with TDBL8.OCX and
TODL8.OCX. This file is shared with True DBGrid 8.0.
XADB8.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 · 13
Site licenses are available for groups of multiple developers. Please contact Sales@ComponentOne.com
for details.
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.
Syntax Changes · 15
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
16 · Getting Started
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
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
Using the True DBList and True DBCombo Controls · 17
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 dropdown 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 (page 24).
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 (page
23).
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
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 (page 192).
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
MatchCompare
MatchEntry
Sets/returns the type of incremental search
MultiSelect
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
Specifying a Data Source · 23
The Basics
This chapter explains the three fundamental concepts that you need to master in order to use True DBList
effectively:
Data sources
Column layouts
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?
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.
24 · The Basics
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 (page 153).
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 (page 161).
What is Application Mode?
If you prefer to work with standard Visual Basic arrays, application mode is recommended, as it is wellsuited 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 (page 167).
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 (page 173).
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 (page 187).
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:
Automatic layouts, derived at run time from the Data control's Recordset (Data control).
Customized layouts, derived at design time from the Data control's Recordset (Data control), and
optionally tailored using the control's property pages.
Choosing a Column Layout · 25
Run-time layouts, created or modified in code by manipulating the Columns collection and its
Column object members.
Automatic Layouts
If you do not define a column layout at design time, True 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.
26 · The Basics
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.
Configuring Columns at Design Time · 27
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:
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).
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 (page 103).
28 · The Basics
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:
Independent vertical scrolling panes
Fixed nonscrolling columns
Configuring Columns at Run Time · 29
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 (page 115).
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:
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.
30 · The Basics
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
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
(page 93).
Understanding Bookmarks · 31
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 (page 270) 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:
32 · The Basics
' 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 (page 168).
ICursor and OLEDB Samples · 33
True DBList Samples
Please be advised that this ComponentOne software title is accompanied by various sample projects
and/or demos, which may or not make use of other ComponentOne development tools. While the
sample projects and/or demos included with the software are used to demonstrate and highlight the
product’s features, and how the control may be integrated with the rest of the ComponentOne product
line, some of the controls used in the demo/sample project may not be included with the purchase of
certain individual products.
ICursor and OLEDB Samples
APIToX
This sample shows how you can populate XArrayDB from an ODBC database. The
advantage is that there is no overhead of DAO, ADO or RDO. This sample uses the
TDBList control.
DAOToX
This sample dumps everything from a recordset to an XArrayDB. The difference
between this sample and the RDOToXarray is only the redimensioning of the
XArrayDB. With the recordset we always know how many records we have so we
can ReDim the XArrayDB up front. This sample uses the TDBList control.
Odbc6
This sample shows how you can use ODBC API to populate the list in Unbound
extended mode. This sample uses the TDBList control.
OwnerDraw
This is a small sample that shows how you can use GDI calls in list's OwnerDraw
event. This sample uses the TDBList control.
RDOToX
This sample dumps everything from a resultset to an XArrayDB. The advantage is
that after this is done you can disconnect from the server and all work is done
locally. The obvious disadvantage is the concurrency issues. This sample uses the
TDBList control.
Ub1DAO
This sample uses Unbound 1 mode and a TDBList to display records from a
recordset. This unbound mode is provided for compatibility with older products.
New applications should use the UnboundExtended mode. This sample uses the
TDBList control.
Ub2ADO
This sample shows how you can populate the list in Unbound extended mode from
an ADO recordset. This sample uses the TDBList control.
Ub2ARR
This sample uses a generic data class. For small data sets you should use
DataMode 4 - Storage with XArrayDB. This sample uses the TDBList control.
Ub2DAO
This sample populates the list with the DAO recordset in Unbound extended mode.
This sample uses the TDBList control.
Ub2RDO
This sample populates the list with the RDO Resultset in Unbound extended mode.
This sample uses the TDBList control.
Tutorial 1 - Binding True DBList to a Data Control · 35
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
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.
36 · Tutorials
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 (page 143) 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.
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.
Tutorial 2 - Incremental Search and Auto Completion with True DBCombo · 37
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.
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.
2.
Place a Data control (Data1) and a True DBCombo control (TDBCombo1) on the form (Form1) as
shown in the following figure.
38 · Tutorials
3.
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.
•
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 · 39
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.
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.
•
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
40 · Tutorials
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.
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 masterdetail relationships.
1.
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 & "'"
Tutorial 5 - Using True DBList with SQL Query Results · 41
Data2.RecordSource = strSQL
Data2.Refresh
End Sub
•
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).
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.
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.
RecordSource (Data control) property to Customer.
4.
42 · Tutorials
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
•
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.
SELECT Company FROM Customer
then press the Execute SQL command button. The list responds by displaying only one column
for the Company field.
9.
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.
Tutorial 6 - Selecting Multiple Rows Using Bookmarks · 43
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.
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.
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.
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.
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).
44 · Tutorials
3.
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:
' 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:
' 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
Tutorial 7 - Defining Unbound Columns in a Bound List · 45
•
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.
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.
2.
Place a Data control (Data1) and a True DBList control (TDBList1) on the form (Form1).
3.
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.
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 (page 103).
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.
46 · Tutorials
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 (page 156).
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
Tutorial 8 - Displaying Translated Data · 47
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.
•
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.
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 (page 45.)
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).
48 · Tutorials
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
2
3
4
5
Prospective
Normal
Buyer
Distributor
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.
•
TDBList1 displays data from the joined tables as in Tutorial 7.
•
The CustType column now displays the translated text instead of numeric values.
Tutorial 9 - Enhancing the User Interface with In-Cell Bitmaps · 49
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 (page 47.)
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
50 · Tutorials
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:
9.
Value
DisplayValue
1
2
MAIL.BMP
PERSON.BMP
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.
Tutorial 10 - Using Styles to Highlight Related Data · 51
•
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.
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.
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.
52 · Tutorials
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
Select Case Index
Case 0
ButtonFlag = 0
TDBList1.FetchRowStyle =
Case 1
ButtonFlag = 1
Case 2
End Select
As Integer)
True
True
False
TDBList1.Refresh
End Sub
5.
Enter the following code in the Form_Load (Visual Basic) event:
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
•
TDBList1 displays data as in Tutorial 9 (page 49.)
•
Click the Prospective Customers button. The list should appear as follows.
Tutorial 10 - Using Styles to Highlight Related Data · 53
•
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.
54 · Tutorials
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.
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.
Tutorial 12 - Creating a List with Fixed, Nonscrolling Columns · 55
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.
•
TDBList1 displays data as in Tutorial 9 (page 49, )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.
•
TDBList1 displays data as in the previous figure, except that even-numbered rows now have a
light gray background.
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 (page 35 )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:
' Before modifying the list's properties, make sure the
' list is initialized by refreshing the Data control.
Data1.Refresh
56 · Tutorials
' 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 Cols As TrueDBList80.Columns
Set Cols = TDBList1.Splits(0).Columns
For Each C In Cols
C.Visible = False
Next C
Cols(0).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:
Cols(0).Visible = False
End Sub
•
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.
Tutorial 12.
Tutorial 13 - Displaying Array Data in Unbound Mode · 57
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 (page 229).
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 (page 61)), application
mode (Tutorial 15 (page 64)), or storage mode (Tutorial 16 (page 66)) instead. For detailed instructions on
how to use unbound mode 1, see Unbound Mode (page 173).
1.
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.
58 · Tutorials
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
Tutorial 13 - Displaying Array Data in Unbound Mode · 59
Else
' Requesting data in rows prior to StartLocation
RelPos = -1
' Requesting data in rows after StartLocation
RelPos = 1
End If
If IsNull(StartLocation) 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.
60 · Tutorials
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.
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
•
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.
Tutorial 13.
Tutorial 14 - Displaying Array Data in Unbound Extended Mode · 61
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 (page 57. )Unbound
mode 2 is both easier to use and more efficient than unbound mode 1. For detailed instructions on how
to use unbound mode 2, see Unbound Mode (page 173).
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.
2.
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.
We shall configure the combo as in Tutorial 13 (page 57.)
4.
Pages dialog.
5.
Columns(00) and Columns(01) to Column 0 and Column 1, respectively.
We first create and initialize a two-dimensional array to hold the data to be displayed in the list. As in
Tutorial 13 (page 57, )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
As explained in Tutorial 13 (page 57, )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
62 · Tutorials
' 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 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)
Tutorial 14 - Displaying Array Data in Unbound Extended Mode · 63
' 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.
Option Explicit
9.
In the Form_Load (Visual Basic) event, initialize the elements of the Class1 instance and set the
setting this value will enable the combo to position the vertical scroll bar accurately.
Row = 100
Col = 2
' Fill with values
Next Col
Next Row
End Sub
•
Tutorial 14.
64 · Tutorials
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 (page 167).
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.
2.
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.
We shall configure the combo as in Tutorial 14 (page 61.)
4.
Pages dialog.
5.
Columns(00) and Columns(01) to Column 0 and Column 1, respectively.
We first create and initialize a two-dimensional array to hold the data to be displayed in the list. As in
Tutorial 14 (page 61, )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
As explained in Tutorial 14 (page 61, )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 (page 57:)
' Fired when the Combo needs to reposition itself
Private Sub TDBC_UnboundGetRelativeBookmark( _
StartLocation As Variant, ByVal OffSet 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"
Tutorial 15 - Displaying Array Data in Unbound Application Mode · 65
'
'
'
'
'
'
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 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, _
'
'
'
'
'
'
'
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.
Option Explicit
9.
In the Form_Load (Visual Basic) event, initialize the elements of the Class1 instance and set the
setting this value will enable the combo to position the vertical scroll bar accurately.
Row = 100
Col = 2
66 · Tutorials
' Fill with values
Next Col
Next Row
End Sub
•
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.
2.
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.
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.
Tutorial 16 - Displaying Array Data in Unbound Storage Mode · 67
6.
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.
Next, we create the XArrayDB object in code.
9.
' 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.
' 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
•
The combo displays the data assigned to the XArrayDB and appears as follows.
68 · Tutorials
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.
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).
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:
Tutorial 17 - Sorting and Searching · 69
' 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:
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
•
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.)
70 · Tutorials
•
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.
Tutorial 18 - Displaying Arbitrary Bitmaps · 71
1.
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 (page 73), 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
72 · Tutorials
12. Enter the following code in the Form_Load (Visual Basic) event:
' 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:
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 <> "."
x.ReDim
x(i, 1)
i = i +
End If
s = Dir
Wend
And s <> ".." Then
0, x.UpperBound(1) + 1, 0, 1
= s
1
' 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
•
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.
Tutorial 19 - Reusable Layouts · 73
•
You have created a fully functional bitmap browser with just a few lines of code.
For more information, see Applying Pictures to List Elements (page 257).
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.
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.
74 · Tutorials
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:
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
' Save current layout
TDBList1.LayoutFileName = App.Path & "\Tutor19.grx"
TDBList1.Layouts.Add "TestLayout"
End Sub
' 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
Tutorial 20 - Printing, Print Preview, and Export · 75
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
•
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 (page 140).
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.
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:
76 · Tutorials
' 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:
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
' 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
•
True DBList displays the data using the font and color changes specified in step 4.
Tutorial 20 - Printing, Print Preview, and Export · 77
•
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.
78 · Tutorials
•
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.
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).
Tutorial 21 - Cell Bordering and Scroll Tips/Tracking · 79
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:
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
80 · Tutorials
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
Tutorial 21 - Cell Bordering and Scroll Tips/Tracking · 81
Case 0:
border
Case 1:
border
Case 2:
border
Case 3:
border
End Select
End If
Next chk
= border Or dblBorderTop
= border Or dblBorderLeft
= border Or dblBorderBottom
= border Or dblBorderRight
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:
82 · Tutorials
•
Notice how you can now manipulate border options at run-time by using the check boxes and
drop down menus.
•
Click on the Scroll Tips and Scroll Tracking check boxes. Notice how information is displayed as
you scroll through the table using the scroll bar.
Tutorial 22 – Performing a List Search Using the Find Method · 83
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.
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.
84 · Tutorials
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
Dim X1
Dim X2
Dim X3
3.
Explicit
As New XArrayDB 'corresponding to 3 TDBComboboxes
As New XArrayDB
As New XArrayDB
To connect Data1 to the datasource and fill the three TDBCombo Boxes with values at runtime,
add the following code:
'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
.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
.Array = X3
.BoundText = "UserCode"
End With
Text2.Text = ""
End Sub
4.
To handle the Command1 click event, add the following code:
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
86 · Tutorials
5.
Finally, add the code below to clear the memory:
Private
Set
Set
Set
End Sub
Sub Form_Unload(Cancel As Integer)
X1 = Nothing
X2 = Nothing
X3 = Nothing
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.
88 · Tutorials
•
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 (page 223) for more information.
NOTE: The DataView property is only supported by the OLE DB version of True DBList.
1.
Tutorial 23 - Outlook-Style Grouping (OLEDB Only) · 89
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 & ", "
90 · Tutorials
End If
strSort = strSort & "[" & Col.DataField & "]"
Next Col
TDBList1.HoldFields
Adodc1.Recordset.Sort = strSort
End Sub
•
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.
Tutorial 23 - Outlook-Style Grouping (OLEDB Only) · 91
•
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!
True DBList Pro Objects and Collections · 93
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 (page 99), 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
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.
94 · Object Model
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 (page 103)
Run Time Interaction (page 143)
Bound Mode (page 153)
Storage Mode (page 161)
Application Mode (page 167)
Unbound Mode (page 173)
AddItem Mode (page 187)
Reference Topics
TDBList Control Properties (page 265)
TDBList Control Methods (page 268)
TDBList Control Events (page 269)
Column Object, Columns Collection · 95
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 (page 29)
Reference Topics
Column Object Properties (page 270)
Column Object Methods (page 271)
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 (page 272)
DataObject Object Methods (page 272)
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 (page 223)
Reference Topics
GroupColumns Collection Properties (page 272)
GroupColumns Collection Methods (page 272)
96 · Object Model
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 (page 140)
Reference Topics
Layouts Collection Properties (page 272)
Layouts Collection Methods (page 272)
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 (page 536)
PrintInfo Object Methods (page 552)
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 (page 173)
Reference Topics
RowBuffer Object Properties (page 273)
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
Split Object, Splits Collection · 97
programmatically using its Add and Remove methods. This collection is accessed using the
SelBookmarks property.
See Also
Selecting and Highlighting Records (page 190)
Reference Topics
SelBookmarks Collection Properties (page 273)
SelBookmarks Collection Methods (page 273)
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 (page 229)
Reference Topics
Split Object Properties (page 273)
Split Object Methods (page 274)
Splits Collection Properties (page 274)
Splits Collection Methods (page 274)
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 (page 241)
98 · Object Model
Reference Topics
Style Object Properties (page 275)
Style Object Methods (page 275)
Styles Collection Properties (page 275)
Styles Collection Methods (page 275)
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 (page 211)
Reference Topics
ValueItem Object Properties (page 275)
ValueItems Collection Properties (page 276)
ValueItems Collection Methods (page 276)
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 (page 161)
Working with Objects and Collections · 99
Reference Topics
XArrayDB Object Properties (page 560)
XArrayDB Object Methods (page 564)
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
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
100 · Object Model
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
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.
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):
.Property1 = variable1
Working with Objects and Collections · 101
.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
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
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:
102 · Object Model
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
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
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:
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.
Context Menu · 103
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
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.
104 · Design Time Interaction
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
(page 104).
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 (page 109).
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.
Visual Editing Mode · 105
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
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.
Visual Editing Mode · 107
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 · 109
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
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
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 (page 119) 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 rightclicked). 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
True DBList Property Pages · 119
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)
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
BoundText
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
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
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
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
MatchCol
MatchCompare
MatchEntry
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
OddRowStyle
Controls the row style for odd-numbered rows
PrintInfos
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
Splits
Contains a collection list splits
Style
Controls the normal style for a control
General properties by category
Appearance properties
AnimateWindow
AnimateWindowClose
AnimateWindowTime
Appearance
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
ColumnHeaders
DefColWidth
EmptyRows
Enables empty rows in an underpopulated list
FootLines
HeadLines
IntegralHeight
MultipleLines
RowDividerColor
RowDividerStyle
RowHeight
Specifies height of all list rows
RowSubDividerColor
Behavior properties
CellTips
CellTipsDelay
CellTipsWidth
Enabled
ExposeCellMode
FetchRowStyle
ListField
MatchCompare
MatchEntry
MatchEntryTimeout
MouseIcon
MousePointer
MultiSelect
Sets/returns the type of selection allowed in the list
PrintInfos
RightToLeft
ScrollTips
ScrollTrack
Color properties
BackColor
ForeColor
Data properties
BoundColumn
BoundText
DataMember
Sets/returns a data member offered by an OLE DB provider
DataMode
MatchCol
Font properties
Font
Specifies the overall font for a list
Layout properties
LayoutFileName
LayoutName
LayoutURL
Sets/returns the URL used for downloading list layouts
Style properties
CaptionStyle
Controls the caption style for a list
EvenRowStyle
FooterStyle
Controls the footing style for a list
HeadingStyle
Controls the heading style for a list
HighlightRowStyle
InactiveStyle
Controls the inactive heading style for a list
OddRowStyle
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
AnimateWindowClose
AnimateWindowTime
Appearance
AutoCompletion
AutoDropdown
AutoSize
BackColor
BorderStyle
Sets/returns style for control border
BoundColumn
BoundText
Caption
CaptionStyle
CellTips
CellTipsDelay
CellTipsWidth
ColumnFooters
Turns column footers on or off
ColumnHeaders
Columns
Contains a collection of TrueDBList columns
ComboStyle
Sets/returns the display type of a combo box
DataMode
DefColWidth
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
EmptyRows
Enables empty rows in an underpopulated control
Enabled
EvenRowStyle
ExtendRightColumn
Returns current split extend column setting, sets all splits
FetchRowStyle
Font
Specifies the overall font for a control
FooterStyle
FootLines
ForeColor
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
HighlightRowStyle
IntegralHeight
LayoutFileName
LayoutName
LimitToList
True if the NotInList event is fired when an item is not found
ListField
MatchEntryTimeout
MaxComboItems
Sets the number of items to display in the dropdown portion of the
combo box
MouseIcon
MousePointer
MultipleLines
OddRowStyle
OLEDragMode
OLEDropMode
PartialRightColumn
True if rightmost column can be clipped to edge of split
RightToLeft
RowDividerColor
RowDividerStyle
RowHeight
Specifies height of all control rows
RowSubDividerColor
RowTracking
ScrollTips
ScrollTrack
Splits
Contains a collection of TrueDBList splits
Style
Controls the normal style for a control
General properties by category (TDBCombo)
AnimateWindow
AnimateWindowClose
AnimateWindowTime
Appearance
Controls 3-D display of column headings
BorderStyle
Sets/returns style for drop-down border
Caption
ColumnFooters
ColumnHeaders
DefColWidth
EditHeight
EmptyRows
Enables empty rows in an underpopulated drop-down
ExtendRightColumn
True if rightmost column extends to edge of split
FootLines
GapHeight
portion of the combo box
HeadLines
IntegralHeight
Controls whether partial rows are displayed
MaxComboItems
Sets the number of items to display in the dropdown portion of the
combo box
PartialRightColumn
RowDividerColor
RowDividerStyle
RowHeight
Specifies height of all drop-down rows
RowSubDividerColor
Behavior properties
AutoCompletion
AutoDropdown
AutoSize
CellTips
CellTipsDelay
CellTipsWidth
Enabled
ExtendRightColumn
True if rightmost column extends to edge of split
FetchRowStyle
ListField
MatchEntryTimeout
MouseIcon
MousePointer
OLEDragMode
OLEDropMode
PartialRightColumn
RightToLeft
RowTracking
ScrollBars
Sets/returns scroll bar style for the drop-down
ScrollTips
ScrollTrack
Color properties
BackColor
EditBackColor
Sets/returns the background color of the text box portion
EditForeColor
Sets/returns the foreground color of the text box portion
ForeColor
Data properties
BoundColumn
BoundText
DataMode
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
FooterStyle
Controls the footing style for a drop-down
HeadingStyle
Controls the heading style for a drop-down
HighlightRowStyle
OddRowStyle
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 (page 104.)
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
Caption
FooterText
Column footing text
Data properties
DataField
NumberFormat
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 (page 104.)
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
ExtendRightColumn
Sets/returns extended right column for a split
FetchRowStyle
FooterStyle
Controls the footing style for a split
HeadingStyle
Controls the heading style for a split
HighlightRowStyle
InactiveStyle
Controls the inactive heading style for a split
OddRowStyle
PartialRightColumn
ScrollBars
Sets/returns scroll bar style for a split
ScrollGroup
Used to synchronize vertical scrolling between splits
SelectedStyle
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
AnchorRightColumn
Caption
Sets/returns split caption text
DividerStyle
Divider style for right split border
ExtendRightColumn
FetchRowStyle
PartialRightColumn
Size
SizeMode
Behavior properties
AllowColMove
AllowColSelect
AllowRowSizing
AllowSizing
AnchorRightColumn
ExtendRightColumn
PartialRightColumn
ScrollBars
ScrollGroup
Style properties
AlternatingRowStyle
CaptionStyle
EvenRowStyle
FooterStyle
HeadingStyle
HighlightRowStyle
InactiveStyle
OddRowStyle
SelectedStyle
Style
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
Alignment
DividerStyle
FetchStyle
FooterAlignment
FooterDivider
Controls display of dividing line in column footer
HeadAlignment
HeaderDivider
Merge
Order
OwnerDraw
Visible
Width
Behavior properties
AllowSizing
ButtonFooter
ButtonHeader
Style properties
FooterStyle
Style
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
BorderSize
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
Alignment
BorderAppearance
Controls the appearance (3D effects) of the cell borders
BorderColor
BorderSize
BorderType
Controls which, if any, cell borders are displayed
VerticalAlignment
WrapText
Behavior properties
Parent
Color properties
BackColor
ForeColor
Font properties
Font
Picture properties
BackgroundPicture
ForegroundPicture
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.
Reusable Layouts · 141
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.
property to the name of an existing layout file.
2.
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.
property to the name of an existing layout file.
2.
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.
Navigation and Scrolling · 143
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
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
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
144 · Run Time Interaction
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.
Searching and Field Completion · 145
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
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.
Selection and Movement · 147
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 · 149
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 (page 105).
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-anddrop 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
Drag-and-Drop Behavior · 151
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 (page 221)
Outlook-Style Grouping (page 223)
Binding True DBList Pro Controls to a Data Source · 153
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
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.
Icon
Control Name
File Name
Data Sources Supported
Built-in Data Control (VB5, VB6)
TDB8.OCX
TDBL8.OCX
Remote Date Control (RDC)
ADO Data Control
Data Environment (VB6)
Remote Data Services (RDS)
Tabular Data Contol (TDC)
These two controls are functionally equivalent; they differ only in how they access data.
154 · Bound Mode
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 (page 103).
•
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
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.
Visual Basic Data Control Considerations · 155
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.
156 · Bound Mode
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 (page 41) 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 (page 153. )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
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
Unbound Columns · 157
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, _
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:
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:
158 · Bound Mode
Dim ucfClone As Recordset ' Global UnboundColumnFetch clone
Data1.Refresh ' Make sure the recordset is created first
Set ucfClone = Data1.Recordset.Clone()
End Sub
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 ucfField As Field
' Global UnboundColumnFetch field
Data1.Refresh
Set ucfField = ucfClone.Fields(1)
End Sub
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:
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 ucfLength As Field
Dim ucfWidth As Field
Data1.Refresh
Set ucfLength = ucfClone.Fields("Length")
Set ucfWidth = ucfClone.Fields("Width")
End Sub
Unbound Columns · 159
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.
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 ucfLength As Field
Dim ucfWidth As Field
Data1.Refresh
Set ucfLength = ucfClone.Fields("Length")
Set ucfWidth = ucfClone.Fields("Width")
End Sub
Select Case TDBList1.Columns(Col).Caption
Case "Area"
' Calculate "Area" column of list
160 · Bound Mode
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.
When to Use Storage Mode · 161
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
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.
162 · Storage Mode
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
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 twodimensional 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
Debug.Print
Debug.Print
Debug.Print
MyArray.LowerBound(1)
MyArray.UpperBound(1)
MyArray.LowerBound(2)
MyArray.UpperBound(2)
'
'
'
'
prints
prints
prints
prints
1
20
0
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.
Interactions between True DBList and XArrayDB · 163
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:
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.
164 · Storage Mode
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:
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:
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.
Storage Mode Examples · 165
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:
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 (page 66) or examine the UNBOUND4.VBP sample, which can be found
in the TUTORIAL\UNBOUND4 subdirectory of the True DBList installation directory. Tutorial 17 (page
68) demonstrates the searching and sorting features of XArrayDB.
When to Use Application Mode · 167
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
time.
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,
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
168 · Application Mode
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 eventhandling 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.
Application Mode Bookmarks · 169
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.
170 · Application Mode
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, _
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 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
Application Mode Programming Considerations · 171
' programmer to ensure the bookmark is valid, and to take
' the appropriate action if it is not.
End If
The UnboundGetRelativeBookmark event is also used to improve performance in DataMode 1 Unbound. For more information, see Unbound Mode (page 173).
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, _
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.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 (page 64) or examine the TUTOR15.VPJ sample, which can be found in
the TUTORIAL\TUTOR15subdirectory of the True DBList installation directory.
When to Use Unbound Mode · 173
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 rowbased 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
time.
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:
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.
174 · Unbound Mode
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 · 175
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 (page 168).
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
176 · Unbound Mode
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
'
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)
'
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
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
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
Unbound Mode Events · 177
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,
RowBuf.Value(1,
RowBuf.Value(2,
...
RowBuf.Value(9,
ColIndex) = Data for row 47
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,
RowBuf.Value(1,
RowBuf.Value(2,
...
RowBuf.Value(9,
178 · Unbound Mode
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,
RowBuf.Value(1,
RowBuf.Value(2,
RowBuf.Value(3,
ColIndex)
ColIndex)
ColIndex)
ColIndex)
RowBuf.RowCount = 4
=
=
=
=
Data
Data
Data
Data
for
for
for
for
row
row
row
row
47
48
49
50
' 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
...
3.
' Since all 10 rows were processed
The UnboundReadData event is called again, this time with:
RowBuf.ColumnCount = Number of columns
ReadPriorRows = True
4.
The event code responds as follows:
RowBuf.RowCount = 3
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:
Else
End If
Else
' 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( _
ByVal Offset As Long, _
NewLocation As Variant, _
For more information on the UnboundGetRelativeBookmark event, see Application Mode (page 167).
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( _
180 · Unbound Mode
ByVal RowBuf As RowBuffer, _
ByVal Offset 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,
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,
RowBuf.Value(1,
RowBuf.Value(2,
...
RowBuf.Value(9,
However, if Offset is -3, a different set of values must be returned:
RowBuf.Value(0,
RowBuf.Value(1,
RowBuf.Value(2,
...
RowBuf.Value(9,
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,
RowBuf.Value(1,
RowBuf.Value(2,
RowBuf.Value(3,
ColIndex)
ColIndex)
ColIndex)
ColIndex)
RowBuf.RowCount = 4
=
=
=
=
Data
Data
Data
Data
for
for
for
for
row
row
row
row
47
48
49
50
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.
182 · Unbound Mode
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 Offset < 0 Then
Else
End If
Else
' 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
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:
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.RowCount = 5
Example 3:
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:
...
Example 4:
RowBuf.RowCount = 1
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.RowCount = 1
Example 5:
RowBuf.RowCount = 1
Offset = -15
184 · Unbound Mode
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
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.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.
Unbound Mode Examples · 185
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 (page 57) 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 (page 61) 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/.
When to Use AddItem Mode · 187
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 (page
29).
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.
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.
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.
Changing the Current Record Position · 189
Database Programming Techniques
As Tutorial 1 (page 35) 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 (page 31), as the remainder of this chapter
presupposes knowledge of bookmarks.
NOTE: The terminology and code samples used in this chapter are specific to Visual Basic's intrinsic Data
control. However, you can generally apply similar techniques to other data source controls as well.
Changing the Current Record Position
True 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 (page 29).
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.
190 · Database Programming Techniques
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
Bmk
Bmk
Bmk
Bmk As Variant
= TDBList1.GetBookmark(0)
= TDBList1.GetBookmark(-1)
'
'
'
'
Current row
Next row
Previous row
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
Refreshing the Display · 191
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 (page 43) 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.
192 · Database Programming Techniques
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.
Searching Bookmarks Using the Find Method · 193
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 (page 83).
Captions, Headers, and Footers · 195
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
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
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 (page 29).
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.
196 · Customizing the List's Appearance
Column footers
Just as the ColumnHeaders property controls the display of column captions, the ColumnFooters
property controls the display of the column footer row. Column footers, which are similar in appearance
to column headers, are always displayed at the bottom of the 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.
Three-dimensional versus Flat Display · 197
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 threedimensional 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:
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.
Borders and Dividing Lines · 199
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 deemphasize 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.
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.
Modifying the Cell Border Appearance · 201
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 (page 78).
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.
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.
Unpopulated Regions · 203
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
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 (page 143).
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.
Row Height and Multiple-line Displays · 205
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:
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 · 207
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 (page 54) demonstrates how to change the default alternating colors at design time.
Horizontal and Vertical Alignment
Use the Alignment property of the Column object to control the horizontal placement of cell text within a
column. The allowable values for this property are as follows:
0 - Left
1 - Right
2 - Center
3 - General
The setting 3 - General, which is the default for data cells, indicates that the alignment should be based
upon the underlying data type. For example, strings are left-aligned, while numbers are right-aligned.
Use the VerticalAlignment member of the Style property to control the vertical placement of text within
the cells of a 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 (page 242)
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 (page 241).
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.
Text Formatting · 209
Data Presentation Techniques
This chapter explains how to display cell data in a variety of textual and graphical formats.
Text Formatting
In many cases, the raw numeric data that True DBList receives from its data source is not suitable for enduser 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.
210 · Data Presentation Techniques
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:
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
Case 2
result = result
Case 3
result = result
Case 4
result = result
Case 5
result = result
Case 6
result = result
& "I"
& "II"
& "III"
& "IV"
& "V"
& "VI"
Automatic Data Translation with ValueItems · 211
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?
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 (page 47) and Tutorial 9 (page 49) provide step-by-step instructions for using the Values
property page.
At run time, you can manipulate the ValueItems collection as you would any other True 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
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:
.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 leftaligned as usual, but the bitmap is right-aligned.
To place the cell text below the bitmap while centering both items, set the Alignment property to 2 Center and the ForegroundPicturePosition property to 4 - Top of Text.
NOTE: For an illustration of all possible combinations of the Alignment and ForegroundPicturePosition
properties, see Displaying foreground pictures (page 260).
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:
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 (page 260).
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:
.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.
Context-sensitive Help with CellTips · 219
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:
.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
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 · 221
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 (page 78).
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.
Outlook-Style Grouping · 223
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 (page 213. )The section Applying Pictures to List Elements (page 257) 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) (page 88) 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.
Owner-drawn Cells · 225
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:
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
Owner-drawn Cells · 227
' 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.
Referencing Splits and their Properties · 229
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
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.
230 · How to Use Splits
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
AllowColSelect
AllowRowSizing
AlternatingRowStyle
AnchorRightColumn
Caption
Sets/returns control caption or column heading text
CaptionStyle
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
FetchRowStyle
FirstRow
Bookmark of row occupying first display line
FooterStyle
HeadingStyle
HighlightRowStyle
HScrollHeight
Returns the horizontal scroll bar height, if present
InactiveStyle
LeftCol
Returns the leftmost visible column
OddRowStyle
Controls the row style for odd numbered rows
PartialRightColumn
ScrollBars
SelectedStyle
SelEndCol
Sets/returns rightmost selected column
SelStartCol
Sets/returns leftmost selected column
Style
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
DividerStyle
Index
Returns the ordinal index of a split
ScrollGroup
Creating and Removing Splits · 231
Size
SizeMode
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 (page 104) 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:
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:
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:
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).
' Append a column to the end of the Columns collection
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
DataField
FooterText
Column footing text
NumberFormat
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
AllowSizing
ButtonFooter
ButtonHeader
DividerStyle
FetchStyle
FooterAlignment
Sizing and Scaling Splits · 233
FooterDivider
Controls the display of dividing line in column header
FooterStyle
HeadAlignment
HeaderDivider
HeadingStyle
Controls the heading style for a column
Merge
Order
OwnerDraw
Style
Visible
Width
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:
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
Creating and Resizing Splits through User Interaction · 235
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.
Vertical Scrolling and Split Groups · 237
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:
Set S = TDBList1.Splits.Add(0) ' Create a Split at the left
Set S = TDBList1.Splits.Add(0) ' Create another
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 · 239
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
For Each C In Cols
C.Visible = False
Next C
' Configure Splits(1) to display exactly two columns, and
' disable resizing
.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
Built-in Named Styles · 241
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
BackColor
BackgroundPicture
Font
ForeColor
ForegroundPicture
Parent
VerticalAlignment
WrapText
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.
242 · How to Use Styles
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
0 - Center
Font
The ambient font of the list's container
ForeColor
System Window Text
ForegroundPicture
None
0 - Left
Parent
None
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
Built-in Named Styles · 243
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
EvenRowStyle
FooterStyle
HeadingStyle
Controls the heading style for an object
HighlightRowStyle
InactiveStyle
Controls the inactive heading style for an object
OddRowStyle
SelectedStyle
Style
Working with Style Properties · 245
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
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:
.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
BackColor
Font
Specifies the typeface, size, and other text characteristics
FooterAlignment
ForeColor
HeadAlignment
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 (page 134).
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 Styles to Cells · 255
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:
ByVal Condition As Integer, _
ByVal Split As Integer, _
ByVal Col As Integer, _
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:
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 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
Data1.Refresh
Set RS = Data1.Recordset.Clone
TDBList1.FetchRowStyle = True
End Sub
Private Sub TDBList1_FetchRowStyle( _
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.
Applying Pictures to List Elements · 257
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
ForegroundPicture
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.
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"
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
(page 254. )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:
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 (page 70) demonstrates how to use styles to display arbitrary
bitmaps within data cells.
All True DBList Members · 265
True DBList Reference
All True DBList Members
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.
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.
266 · True DBList Reference
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
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
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.
UnboundGetRelativeBook
mark
Fired when the control needs a relative bookmark.
UnboundReadData
UnboundReadDataEx
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
AllowColSelect
AllowRowSizing
AllowSizing
Enables interactive resizing for a split.
AlternatingRowStyle
Controls whether even/odd row styles are applied to a split.
AnchorRightColumn
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
DividerStyle
Divider style for right split border.
EvenRowStyle
ExtendRightColumn
Sets/returns extended right column for a split.
FetchRowStyle
FirstRow
FooterStyle
Controls the footing style for a split.
HeadingStyle
Controls the heading style for a split.
HighlightRowStyle
HScrollHeight
InactiveStyle
Controls the inactive heading style for a split.
Index
Returns the ordinal index of a split.
LeftCol
Returns the leftmost visible column.
OddRowStyle
PartialRightColumn
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
SelStartCol
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
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.
Controls how a style's background picture is displayed.
BorderAppearance
BorderColor
Specifies the color for the border.
BorderSize
Specifies the size of cell border.
BorderType
Controls which, if any, cell borders are displayed.
EllipsisText
Controls word ellipsis within cells.
Font
Specifies the typeface, size, and other text characteristics.
ForeColor
Controls the foreground color.
ForegroundPicture
Sets/returns the foreground picture associated with a style.
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.
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
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 (page 94)
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
AllowColMove Property · 277
Remarks
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 rightaligned. 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 (page 95)
Style Object, Styles Collection (page 97)
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
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
Split Object, Splits Collection (page 97)
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
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
AllowRowSizing Property
If True (the default), the user can resize rows.
Syntax
object.AllowRowSizing = boolean
Remarks
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
AllowSizing Property · 279
AllowSizing Property
If True, the user can resize the column or split.
Syntax
object.AllowSizing = boolean
Remarks
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
AlternatingRowStyle Property
Syntax
object.AlternatingRowStyle = boolean
Remarks
This property determines whether a control or split displays odd-numbered rows in one style and evennumbered 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
AnchorRightColumn Property
Syntax
object.AnchorRightColumn = boolean
Remarks
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
AnimateWindow Property
Syntax
object.AnimateWindow = value
Remarks
Values
Design Time
Run Time
dblNoAnimate
1 - Roll
dblRoll
2 - Slide
dblSlide
3 - Blend
dblBlend
AnimateWindowClose Property · 281
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.
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
AnimateWindowClose Property
Syntax
object.AnimateWindowClose = value
Remarks
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.
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
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
AnimateWindowDirection Property
Syntax
object.AnimateWindowDirection = value
Remarks
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
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.
AnimateWindowTime Property · 283
All of the remaining directional settings are under your complete control.
See Also
AnimateWindowTime Property
Syntax
object.AnimateWindowTime = long
Remarks
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).
See Also
AnnotatePicture Property
Syntax
valueitems.AnnotatePicture = boolean
Remarks
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 (page 260).
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 (page 98)
Appearance Property
Syntax
object.Appearance = value
Remarks
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
ApproxCount Property
Syntax
object.ApproxCount = long
Remarks
Read/Write at run time. Not available at design time.
Array Property · 285
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
Array Property
Syntax
object.Array = XArrayDB
Remarks
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
BackColor Property
Syntax
object.BackColor = color
Remarks
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
BackgroundPicture Property
Syntax
style.BackgroundPicture = variant
Remarks
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
BackgroundPictureDrawMode Property
Syntax
style.BackgroundPictureDrawMode = value
Remarks
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.
Bookmark Property (RowBuffer) · 287
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
Bookmark Property (RowBuffer)
Syntax
rowbuffer.Bookmark (Row) = variant
Remarks
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 (page 96)
Bookmark Property (TDBList)
Syntax
object.Bookmark = variant
Remarks
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.
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
BookmarkType Property
Syntax
object.BookmarkType = integer
Remarks
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
BorderAppearance Property
Determines the appearance of the border.
Syntax
object.BorderAppearance = value
Remarks
Property applies to Style object for TDBList and TDBCombo.
Values
Design Time
Run Time
0 - Flat(default)
dblFlatStyle
BorderColor Property · 289
Design Time
Run Time
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
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
See Also
BorderSize Property
The BorderSize property returns or sets the size of the cell border.
Syntax
object.BorderSize = single
Remarks
Property applies to the Style object for TDBList and TDBCombo.
See Also
BorderStyle Property
This property determines whether a TDBList or TDBCombo control has a border.
Syntax
object.BorderStyle = value
Remarks
Values
Design Time
Run Time
0 - None
dblNoBorder
1 - Fixed Single (default)
dblFixedSingle
See Also
BorderType Property
Determines the type of border.
Syntax
object.BorderType = value
Remarks
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
BoundColumn Property · 291
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
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
NOTE: Do not confuse the BoundColumn property with the ListField property used to specify the
incremental search field.
See Also
BoundText Property
Syntax
object.BoundText = value
Remarks
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.
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
ButtonFooter Property
If True, the column footer depresses like a standard Windows command button when clicked by the user.
Syntax
column.ButtonFooter = boolean
Remarks
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
ButtonHeader Property
If True, the column header depresses like a standard Windows command button when clicked by the
user.
Syntax
column.ButtonHeader = boolean
Remarks
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.
Caption Property · 293
See Also
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
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
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
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
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
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.
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.
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
CellTipsDelay Property
The CellTipsDelay property controls the amount of idle time, in milliseconds, that must elapse before the
CellTipsWidth Property · 295
Syntax
object.CellTipsDelay = long
Remarks
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
CellTipsWidth Property
Syntax
object.CellTipsWidth = single
Remarks
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
CellTop Property
Syntax
column.CellTop
Remarks
Read-only at run time. Not available at design time.
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
Col Property
Syntax
object.Col = integer
Remarks
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
ColIndex Property
Syntax
column.ColIndex
Remarks
This property returns the zero-based index of a column within the Columns collection.
See Also
ColumnCount Property · 297
ColumnCount Property
Syntax
rowbuffer.ColumnCount
Remarks
This property returns the number of columns in a RowBuffer object passed to an unbound event
procedure for a TDBList control.
See Also
ColumnFooters Property
Syntax
object.ColumnFooters = boolean
Remarks
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
ColumnHeaders Property
Syntax
object.ColumnHeaders = boolean
Remarks
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
ColumnIndex Property
Syntax
rowbuffer.ColumnIndex (Row, Col)
Remarks
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
ColumnName Property
Syntax
rowbuffer.ColumnName (Col)
Remarks
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
Columns Property
Syntax
object.Columns
Count Property · 299
Remarks
This property returns a collection of Column objects for a control, drop-down control, or split.
See Also
Count Property
This property returns the number of items in a collection.
Syntax
collection.Count
Remarks
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
GroupColumns Object (page 95)
Layouts Object (page 96)
PrintInfo Object, PrintInfos Collection (page 96)
SelBookmarks Object (page 96)
CurrentCellVisible Property
Syntax
object.CurrentCellVisible = boolean
Remarks
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
DataChanged Property
Syntax
object.DataChanged = boolean
Remarks
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
DataField Property
Syntax
object.DataField = string
Remarks
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.
DataField Property (Column) · 301
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
DataField Property (Column)
Syntax
column.DataField = string
Remarks
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
DataMember Property
Syntax
object.DataMember = string
Remarks
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
DataMode Property
Syntax
object.DataMode = value
Remarks
Read-only at run time. Read/Write at design time.
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
DataSource Property · 303
DataSource Property
Syntax
object.DataSource
Remarks
Read/Write at design time. Not available at run time.
The DataSource property specifies the data control that is updated once a selection is made.
See Also
DataView Property
The DataView property returns or sets how the list will display data from a data source.
Syntax
TDBList.DataView = value
Remarks
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 masterdetail 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.
NOTE: This property is only supported by the OLE DB version of True DBList Pro.
See Also
DeadAreaBackColor Property
This property controls the background color of the dead area object.
Syntax
object.DeadAreaBackColor = color
Remarks
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
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
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.
DefColWidth Property · 305
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
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
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
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
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
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
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).
GroupHeadClick, HeadClick, MouseDown, MouseUp. Any attempt to access the DestinationRow
setting the control's Row property).
DestinationSplit Property · 307
succeed. The value returned by this property only indicates what the correct destination row will be if
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
previous location).
See Also
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
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.
GroupHeadClick, HeadClick, MouseDown, MouseUp. Any attempt to access the DestinationSplit
setting the control's Split property).
succeed. The value returned by this property only indicates what the correct destination split will be if
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
previous location).
See Also
DisplayValue Property
This property returns or sets the translated data value for a member of a ValueItems collection.
Syntax
valueitem.DisplayValue = variant
Remarks
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.
See Also
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
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 (page 235).
EllipsisText Property · 309
See Also
EllipsisText Property
Controls word ellipsis within cells.
Syntax
EllipsisText As Boolean
See Also
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
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
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
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
ErrorText Property
This property returns the error message string from the underlying data source.
Syntax
object.ErrorText
Remarks
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
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
By default, this is the built-in EvenRow style.
To change the appearance of odd-numbered rows, set the OddRowStyle property.
See Also
ExportEOF Property · 311
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
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
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
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
ExposeCellMode Property
This property controls how the rightmost column reacts when clicked by the user.
Syntax
object.ExposeCellMode = value
Remarks
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
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
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.
FetchRowStyle Property · 313
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
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
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
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
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 percell basis.
See Also
Files Property
Syntax
dataobject.Files
Remarks
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.
See Also
DataObject Object, DataObjectFiles Collection (page 95)
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
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.
Font Property · 315
See Also
Font Property
This property returns or sets the font object associated with a control, column, split, or style.
Syntax
object.Font = font
Remarks
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
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
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
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
If False, no dividing line is drawn in the column's header area.
See Also
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
By default, this is the built-in Footing style.
See Also
FooterText Property
This property returns or sets the text displayed in the column's footing area.
Syntax
column.FooterText = string
FootLines Property · 317
Remarks
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
See Also
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
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
ForeColor Property
This property controls the foreground color of an object.
Syntax
object.ForeColor = color
Remarks
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
See Also
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
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
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
Group Property · 319
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
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 Also
GroupByCaption Property
This property sets or returns the text displayed in the grouping area when no group is defined.
Syntax
TDBList.GroupByCaption = string
Remarks
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 Also
GroupColumns Property
This property returns a collection of Column objects in the list's grouping area.
Syntax
TDBList.GroupColumns
Remarks
Property applies to TDBList control (OLE DB only)
See Also
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
Values
Design Time
Run Time
0 - Left
dblLeft
1 - Right
dblRight
2 - Center
dblCenter
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
HeadingStyle Property · 321
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
By default, this is the built-in Heading style.
See Also
HeadLines Property
TDBCombo control's column headers.
Syntax
object.HeadLines = single
Remarks
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
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
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
HighlightRowStyle Property
This property sets or returns the Style object that controls the appearance of a highlighted row.
Syntax
object.HighlightRowStyle = variant
Remarks
By default, this is the built-in HighlightRow style.
See Also
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
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.
hWnd Property · 323
See Also
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
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
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
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
Index Property
This property returns the zero-based index of a split within the Splits collection.
Syntax
split.Index
Remarks
See Also
IntegralHeight Property
This property determines whether partial rows are displayed in a TDBList or TDBCombo control.
Syntax
object.IntegralHeight = boolean
Remarks
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
LayoutFileName Property
This property sets or returns the string containing the filename used to save and retrieve control layouts.
Syntax
object.LayoutFileName = string
Remarks
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.
LayoutName Property · 325
NOTE: If the LayoutFileName property is nonempty, it takes precedence over LayoutURL, and
asynchronous downloading will not occur.
See Also
LayoutName Property
This property sets or returns the string (maximum length of 30 characters) containing the current layout
name.
Syntax
object.LayoutName = string
Remarks
LoadLayout method of the control.
See Also
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
See Also
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
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"
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
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
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
LeftCol Property · 327
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
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
ListCount Property
Returns the number of items in the list portion of the control.
Syntax
object.ListCount
Remarks
See Also
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
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
MatchCol Property
This property sets the search column when the MatchEntry property is not 0 (None).
Syntax
object.MatchCol = value
Remarks
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
MatchCompare Property · 329
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
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
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
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
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
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.
See Also
Merge Property
This property determines whether adjacent rows of like-valued data are merged within the specified
column.
Syntax
column.Merge = boolean
Remarks
MinWidth Property · 331
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
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
See Also
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
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
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
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
MultipleLines Property
This property determines whether a single row can span multiple lines.
Syntax
object.MultipleLines = value
MultiSelect Property · 333
Remarks
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
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
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
Name Property (Style)
This property returns the name of a style object.
Syntax
style.Name
Remarks
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.
NumberFormat Property · 335
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
NumberFormat Property
This property returns or sets a value indicating the format string for a control column.
Syntax
column.NumberFormat = string
Remarks
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
OddRowStyle Property
This property sets or returns the Style object that controls the appearance of an odd-numbered row in a
Syntax
object.OddRowStyle = variant
Remarks
By default, this is the built-in OddRow style.
To change the appearance of even-numbered rows, set the EvenRowStyle property.
See Also
Order Property
This property sets or returns the zero-based display position of a column within the Columns collection.
Syntax
column.Order = integer
OwnerDraw Property · 337
Remarks
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
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
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
Parent Property
This property sets or returns the parent style of a named style object.
Syntax
style.Parent = variant
Remarks
Read/Write at run time and design time (with restrictions).
If a style has no parent, then this property returns a null variant.
The Parent property is used at run time to change the parent style from which the style in question
inherits. Typically, this is done when creating a new style in code, as in the following example:
Dim BoldHeading As 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
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
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
Presentation Property · 339
Presentation Property
This property determines how the members of a ValueItems collection are displayed within the
associated column.
Syntax
valueitems.Presentation = value
Remarks
Values
Design Time
Run Time
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.
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
PrintInfo Property
This property returns the default PrintInfo object of the list's PrintInfos collection.
Syntax
TDBList.PrintInfo
Remarks
PrintInfo objects are used to specify page layout and print job characteristics.
See Also
PrintInfos Property
This property returns a collection of PrintInfo objects used to specify page layout and print job
characteristics.
Syntax
TDBList.PrintInfos
Remarks
See Also
RightToLeft Property
The property provides an appearance and functionality familiar to Middle East or Latin users.
Syntax
object.RightToLeft = boolean
Remarks
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
Row Property · 341
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
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
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
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
RowDividerColor Property
This property controls the row divider color of the controls when RowDividerStyle is 7 - Custom Color.
Syntax
object.RowDividerColor = value
Remarks
See Also
RowDividerStyle Property
This property determines the style of the border drawn between control rows.
Syntax
object.RowDividerStyle = value
Remarks
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
RowHeight Property
This property returns or sets the height of all control rows in terms of the coordinate system of the
Syntax
object.RowHeight = single
RowMember Property · 343
Remarks
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 = 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
RowMember Property
This property returns or sets the name of the row member used to populate the list.
Syntax
object.RowMember = string
Remarks
Typically, a row member represents a database table or query.
called a row member, and is identified by a unique string.
See Also
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
See Also
RowSubDividerColor Property
This property controls the row subdivider color of the controls when RowDividerStyle is 7 - Custom
Color.
Syntax
object.RowSubDividerColor = value
Remarks
See Also
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
Values
Design Time
Run Time
0 - None
dblNone
1 - Horizontal
dblHorizontal
2 - Vertical
dblVertical
3 - Both
dblBoth
4 - Automatic (default)
dblAutomatic
ScrollGroup Property · 345
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
ScrollGroup Property
This property is used to synchronize vertical scrolling between splits.
Syntax
split.ScrollGroup = integer
Remarks
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
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
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
If you do not provide a handler for the FetchScrollTips event, tips will not be displayed.
See Also
ScrollTrack Property
If True, moving the scrollbar thumb causes the control’s display to update with new data.
Syntax
object.ScrollTrack = Boolean
Remarks
If False (the default), moving the scrollbar thumb does not change the display.
See Also
SelBookmarks Property
This property returns a collection of selected row bookmarks.
Syntax
object.SelBookmarks
Remarks
See Also
SelectedItem Property
This property returns or sets the bookmark identifying the selected item in a control.
Syntax
object.SelectedItem = variant
Remarks
Use the value returned by the SelectedItem property to determine the current row in a TDBList or
TDBCombo control.
SelectedStyle Property · 347
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
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
Property applies to TDBList control and Split object.
By default, this is the built-in Selected style.
See Also
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
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
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
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.
See Also
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
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.
SizeMode Property · 349
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
SizeMode Property
This property determines how the Size property is used to determine the actual size of a split.
Syntax
split.SizeMode = value
Remarks
Values
Design Time
Run Time
0 - Scalable (default)
dblScalable
1 - Exact
dblExact
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 Property
This property specifies the zero-based index of the current split.
Syntax
object.Split = integer
Remarks
See Also
Splits Property
This property returns a collection of Split objects.
Syntax
object.Splits
Remarks
See Also
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
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.
Style Property · 351
See Also
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
By default, this is the built-in Normal style.
See Also
Styles Property
This property returns a collection of named Style objects.
Syntax
object.Styles
Remarks
When a control is first created, it contains eight built-in styles, which control the following display
aspects:
Normal
Heading
Column headers
Footing
Column footers
Selected
Caption
Control and split caption bars
HighlightRow
EvenRow
OddRow
NOTE: At design time, use the Style Factory property page to modify these built-in styles or create your
own named styles.
See Also
Tag Property
This property returns or sets an expression that stores any extra data needed for your program.
Syntax
object.Tag = value
Remarks
Unlike other properties, the value of the Tag property is not used by the control.
See Also
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
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
Top Property · 353
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
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
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
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.
See Also
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
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
Value Property (Column)
This property returns or sets the underlying data value in a column for the current row.
Syntax
column.Value = variant
Remarks
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
Value Property (RowBuffer) · 355
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
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
Value Property (Style)
This property returns the name of a style object.
Syntax
style.Value = variant
Remarks
Read/Write at run time (with restrictions). Not available at design time.
For style objects, the Value property is a synonym for the Name property, so the following statements are
equivalent:
Debug.Print 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
Value Property (ValueItem)
This property returns or sets the underlying data value for a member of a ValueItems collection.
Syntax
valueitem.Value = variant
Remarks
Property applies to ValueItem object.
The DisplayValue property returns the translated data value for a value item.
See Also
ValueItems Property
This property returns a collection of ValueItem objects for a column.
Syntax
column.ValueItems
Remarks
NOTE: At design time, use the Values property page to populate a column's ValueItems collection.
See Also
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
Values
Design Time
Run Time
0 - Top (default)
dblTop
1 - Bottom
dblBottom
Visible Property · 357
Design Time
Run Time
2 - Vertical Center
dblVertCenter
Use the Alignment property to control horizontal alignment.
See Also
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
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
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.
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
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
See Also
VScrollWidth Property
The VScrollWidth property returns the width of a split's vertical scroll bar in container units, which
Syntax
object.VScrollWidth
Remarks
If no vertical scroll bar exists, then the returned value is zero. If object is a TDBList or TDBCombo
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
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
WrapText Property · 359
Use the Width property in conjunction with Left, RowHeight, and RowTop to determine the size and
NOTE: The DefColWidth property controls the default width of new columns created at run time.
See Also
WrapText Property
This property returns or sets a value indicating whether an object wordwraps text at cell boundaries.
Syntax
style.WrapText = boolean
Remarks
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
See Also
TDBList Methods
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
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
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
AddItem Method · 361
See Also
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
See Also
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.
\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.
AutoSize Method · 363
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
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 (page 149) for more information.
See Also
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
See Also
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
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
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.
CellValue Method · 365
Remarks
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
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
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
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
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.
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
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
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
ClearRegexCellStyle Method · 367
Return Value
None
Remarks
You can cancel the control's automatic layout behavior by invoking the HoldFields method.
See Also
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
regex is an optional regular expression string.
Return Value
None
Remarks
If no such cell condition exists, then calling this method has no effect.
If regex is omitted, then all cell conditions for any regular expression matching the condition argument are
removed. If condition is -1 (dbgAllCells), then all regex cell conditions are removed, regardless of status
or expression.
If regex is supplied, then the single cell condition matching both arguments is removed. However, if
condition is -1 (dbgAllCells), then all cell conditions for the specified regular expression are removed,
regardless of status.
See Also
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
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.
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
See Also
ExportBegin Method · 369
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
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
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
See Also
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
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.
ExportToDelimitedFile Method · 371
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
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
delim specifies an optional delimiter string used to separate fields.
selector is an optional value that specifies the rows to be exported.
prefix specifies an optional string used with suffix to surround each value.
suffix specifies an optional string used with prefix to surround each value.
Return Value
None
Remarks
Fields are delimited by the delim string (the default delim is empty). Field values can also be placed
between a prefix string and suffix string.
The selector argument determines the rows to be exported. It can be one of the following constant values:
0 - 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
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
append is a boolean that specifies whether rows are added to the end of the file.
selector is an optional RowSelectorConstants value that specifies the rows to be exported.
tablewidth is an optional variant used to qualify the generated <table> tag.
Return Value
None
Remarks
The append argument should be set to True to add the table to the end of an existing file, False to overwrite
the entire file. In either case, the file is created if it does not exist.
The selector argument determines the rows to be exported. It can be one of the following constant values:
0 - 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
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
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.
GetData Method · 373
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
This method can be used for bounded, unbounded and storage mode.
See Also
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
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
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
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
GetBookmark Method
The GetBookmark method returns a bookmark for a row relative to the current row, which need not be
visible.
Syntax
object.GetBookmark (offset)
Arguments
offset is a long integer that defines the target row relative to the current row.
Return Value
A variant containing a bookmark relative to the current row as specified by offset.
Remarks
If offset is 0, this method returns the bookmark of the current row. The value returned will be the same as
that returned by the Bookmark property.
HoldFields Method · 375
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
HoldFields Method
The HoldFields method sets the current column/field layout as the customized layout so that subsequent
ReBind operations will use the current layout for display.
Syntax
object.HoldFields
Arguments
None
Return Value
None
Remarks
You can resume the 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
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
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
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
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.
PointAt Method · 377
See Also
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
Return Value
Remarks
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
where the user clicked or dropped another control in terms of a control element.
See Also
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
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
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
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
Refetch Method · 379
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.
See Also
Refetch Method
The Refetch method repopulates the cells of the specified column from a data source control and/or
unbound events.
Syntax
column.Refetch
Arguments
None
Return Value
None
Remarks
It also repaints the column's visible cells, firing all events necessary for redisplay.
By default, the 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
RefetchCell Method
The RefetchCell method repopulates the specified cell from a data source control and/or unbound
events.
Syntax
column.RefetchCell [bookmark]
Arguments
bookmark is an optional variant that specifies the row containing the cell to refetch. If not specified, the
current row is assumed. If specified, it must be a valid bookmark.
Return Value
None
Remarks
It also repaints the cell, firing all events necessary for redisplay.
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
See Also
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
It also repaints the column's visible cells, firing all events necessary for redisplay.
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
See Also
RefetchRow Method · 381
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
It also repaints the row, firing all events necessary for redisplay.
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
See Also
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 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
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
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
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
RefreshRow Method · 383
Remarks
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
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
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
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
All collections accept a zero-based index argument. The Columns, GroupColumns, Layouts, PrintInfos,
and Styles collections also accept named arguments.
See Also
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
See Also
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
RowBookmark Method · 385
Return Value
None
Remarks
Method applies to Style object.
See Also
RowBookmark Method
The RowBookmark method returns a bookmark for a visible row relative to the first displayed row.
Syntax
object.RowBookmark (rownumber)
Arguments
rownumber is an integer denoting a displayed row.
Return Value
A variant containing a bookmark corresponding to the display row specified by rownumber.
Remarks
If rownumber is 0, this method returns the bookmark of the first displayed row. The value returned will be
the same as that returned by the FirstRow property.
Allowable values for the rownumber argument range from 0 to VisibleRows - 1.
This method only returns the current row (as determined by the 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
RowContaining Method
The RowContaining method returns the zero-based index of the display row containing the specified
coordinate.
Syntax
object.RowContaining (coordinate)
Arguments
coordinate is a single that defines a vertical coordinate (Y value) in twips.
Return Value
An integer corresponding to the display row beneath the specified Y coordinate.
Remarks
This value ranges from 0 to VisibleRows - 1.
When handling mouse and drag events, this method is useful when you need to determine where the
user clicked or dropped another control in terms of a control row.
See Also
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
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
Use the RowTop method in conjunction with RowHeight, Left, and Width to determine the size and
See Also
Scroll Method
This method scrolls the control horizontally and vertically in a single operation.
Syntax
object.Scroll coloffset, rowoffset
SetData Method · 387
Arguments
coloffset is a long integer denoting the number of columns to scroll and the direction in which to scroll
them.
rowoffset is a long integer denoting the number of rows to scroll and the direction in which to scroll them.
Return Value
None
Remarks
Positive offsets scroll right and down. Negative offsets scroll left and up. Column offsets that are out of
range cause a trappable error. Row offsets that are out of range scroll to the beginning or end of the
database.
The same effect can be achieved by setting the LeftCol and FirstRow properties, but these must be set
independently.
See Also
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
NOTE: In this version of True DBList, only the vbCFText format is supported. If you omit the format
argument, vbCFText is assumed.
See Also
SplitContaining Method
The SplitContaining method returns the Index value of the split containing the specified coordinate pair.
Syntax
object.SplitContaining (x, y)
Arguments
Return Value
An integer corresponding to the index of the split beneath the specified coordinate pair.
Remarks
This value ranges from 0 to Splits.Count - 1.
If either argument is outside of the control's data area, this method returns -1.
See Also
TDBList Events
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
Click Event · 389
Click Event
The Click event occurs when the user presses then releases a mouse button over the control.
Syntax
object_Click ( )
Arguments
None
Remarks
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
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
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
ColResize Event
The ColResize event occurs after the user has finished resizing a column, but before columns to the right
are repositioned.
Syntax
object_ColResize (ByVal ColIndex As Integer, Cancel As Integer)
Arguments
ColIndex is an integer that identifies the column that was resized.
Cancel is an integer that may be set to True to undo resizing.
Remarks
Your event procedure can accept the change, alter the degree of change, or cancel the change completely.
If you set the Cancel argument to True, the previous column width is restored and no repainting occurs.
To alter the degree of change, set the Width property of the Column object specified by the ColIndex
argument to the desired value.
It is not necessary to execute the Refresh method within this event procedure. Doing so causes the
control to be repainted even if the Cancel argument is True.
See Also
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
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
DragCell Event
The DragCell event is triggered when the user presses the left mouse button and starts dragging the
mouse.
Error Event · 391
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
Error Event
The Error event occurs only as the result of a data access error that takes place when no Visual Basic code
is being executed.
Syntax
object_Error (DataError As Integer, Response As Integer)
Arguments
DataError is an integer that identifies the error that occurred.
Response is an integer that may be set to 0 to suppress error message display.
Remarks
Even if your application handles run time errors in code, errors can still occur when none of your code is
executing, as when the user clicks a Data control button or changes the current record by interacting with
a bound control. If a data access error results from such an action, the Error event is fired.
If you set the Response argument to 0, no error message will be displayed.
If the Response argument retains its default value of 1, or if you do not code an event procedure for the
Error event, the message associated with the error will be displayed.
NOTE: Use the ErrorText property to retrieve the error string that will be displayed.
See Also
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,
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 (page 524) 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
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.
FetchCellTips Event · 393
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
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
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
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
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.
FirstRowChange Event · 395
Remarks
attributes of the current split.
See Also
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
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
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
One possible action for this event is to re-sort the Recordset (Data control) object based on the selected
column.
See Also
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
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
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
ColIndex is an integer that identifies the column being moved. This is the absolute index.
Remarks
Event applies to TDBList control (OLE DB only).
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.
GroupHeadClick Event · 397
See Also
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).
column.
See Also
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
Remarks
column.
See Also
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
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
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
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
KeyUp Event · 399
KeyUp Event
The KeyUp event occurs when the user releases a key.
Syntax
object_KeyUp (KeyCode As Integer, Shift As Integer)
Arguments
Remarks
•
•
Navigation keys.
•
•
See Also
LayoutReady Event
The LayoutReady event fires when asynchronous downloading of a control layout file has completed.
Syntax
object_LayoutReady ( )
Arguments
None
Remarks
The location of the layout file is determined by the LayoutURL property.
initializing a control on an HTML page.
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
LeftColChange Event
The LeftColChange event occurs when the first visible column of a control is changed.
Syntax
object_LeftColChange ( )
Arguments
None
Remarks
•
•
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.
RowChange.
See Also
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
MouseMove Event · 401
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
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
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.
Remarks
This event is primarily useful for implementing drag-and-drop behavior on a per-column basis.
See Also
MouseUp Event
Syntax
object_MouseUp (Button As Integer, Shift As Integer, X As Single, Y As Single)
Arguments
Remarks
See Also
OnInit Event
The OnInit event occurs after the list is initially loaded.
Syntax
TDBList_OnInit ( )
Arguments
None
Remarks
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
OwnerDrawCell Event · 403
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
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
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.
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
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
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
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
PostEvent Event · 405
PostEvent Event
The PostEvent event is used in conjunction with the PostMsg method to postpone operations that are
Syntax
object_PostEvent (ByVal MsgId As Integer)
Arguments
MsgId is an integer that identifies the message posted by the PostMsg method.
Remarks
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
See Also
RowChange Event
The RowChange event occurs when the current row changes to a different row.
Syntax
TDBList_RowChange ( )
Arguments
None
Remarks
•
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
RowResize Event
The RowResize event occurs when the user has finished resizing a control row.
Syntax
object_RowResize (Cancel As Integer)
Arguments
Remarks
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.
See Also
RowSourceChanged Event
The RowSourceChanged event fires when a bound data source is changed or requeried.
Syntax
object_RowSourceChanged ( )
Arguments
None
Remarks
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.
Scroll Event · 407
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()
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
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
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.
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
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
•
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
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
UnboundFindData Event · 409
Remarks
For a bound control, any column with an empty DataField property and a non-empty Caption property
is considered an unbound column.
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
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
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
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.
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
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
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.
UnboundReadData Event · 411
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
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
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
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
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
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.
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
Remarks
Before returning from the UnboundReadDataEx event, you must fill the Bookmark array of RowBuf with
unique row identifiers, and the Value array with the actual data. For example, if Offset is 1 (or -1), then
you must fill in RowBuf, starting from the row that follows (or precedes) StartLocation.
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.
UnboundReadDataEx Event · 413
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.
unbound dataset.
See Also
TDBCombo Members · 415
TDBCombo Reference
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
AllowColSelect
AllowRowSizing
AlternatingRowStyle
Controls whether even/odd row styles are applied to a control.
AnchorRightColumn
AnimateWindow
Controls the object's animation style.
AnimateWindowClose
Controls the animation effect when the object is closed.
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
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.
416 · TDBCombo Reference
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
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
ExtendRightColumn
Returns current split extend column setting, sets all splits.
FetchRowStyle
FirstRow
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
portion of the combo box.
HeadingStyle
Controls the heading style for a control.
HeadLines
Number of lines allocated for heading text.
HighlightRowStyle
HScrollHeight
hWnd
Returns the window handle of the control.
IntegralHeight
Sets/returns a value that indicates the display of partial rows.
IsOpen
Indicates whether the dropdown list is opened or closed.
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
OLEDragMode
Controls whether a list handles OLE drag operations.
OLEDropMode
Controls whether a list handles OLE drop operations.
PartialRightColumn
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
update with new data.
SelectedItem
Sets/returns the bookmark of the currently selected item.
SelEndCol
SelLength
Sets/returns length of selected text.
SelStart
Sets/returns start of selected text.
SelStartCol
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
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
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.
UnboundGetRelativeBook
mark
Fired when the control needs a relative bookmark.
UnboundReadData
UnboundReadDataEx
TDBCombo Control Properties
AddItemSeparator Property (TDBCombo)
This property determines the separation string for columns when using the AddItem method in AddItem
mode.
Syntax
object.AddItemSeparator = String
Remarks
This property takes ; as the default value.
AllowColMove Property (TDBCombo) · 421
See Also
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
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
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
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
AllowRowSizing Property (TDBCombo)
If True (the default), the user can resize rows.
Syntax
object.AllowRowSizing = boolean
Remarks
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
AlternatingRowStyle Property (TDBCombo)
Syntax
object.AlternatingRowStyle = boolean
Remarks
This property determines whether a control or split displays odd-numbered rows in one style and evennumbered 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
AnchorRightColumn Property (TDBCombo) · 423
AnchorRightColumn Property (TDBCombo)
Syntax
object.AnchorRightColumn = boolean
Remarks
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
AnimateWindow Property (TDBCombo)
Syntax
object.AnimateWindow = value
Remarks
Values
Design Time
Run Time
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.
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
AnimateWindowClose Property (TDBCombo)
Syntax
object.AnimateWindowClose = value
Remarks
Values
Design Time
Run Time
dblNoAnimateClose
2 - Same Direction
dblSameDirection
For a TDBCombo control, this property controls the animation effect when the user closes the dropdown
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
AnimateWindowDirection Property (TDBCombo) · 425
If set to 2 - Same Direction, the animation of the closing object occurs in the same direction as that specified
Use the AnimateWindowTime property to control the duration of the object's closing animation.
See Also
AnimateWindowDirection Property (TDBCombo)
Syntax
object.AnimateWindowDirection = value
Remarks
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
9 - Center
dblAnimateCenter
For a TDBCombo control, this property controls the direction of the animation of the combo dropdown
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.
See Also
AnimateWindowTime Property (TDBCombo)
Syntax
object.AnimateWindowTime = long
Remarks
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).
See Also
AutoCompletion Property
Syntax
TDBCombo.AutoCompletion = boolean
Remarks
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
AutoDropDown Property
Syntax
column.AutoDropDown = boolean
Remarks
AutoSize Property · 427
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
AutoSize Property
Syntax
object.AutoSize = value
Remarks
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
Appearance Property (TDBCombo)
Syntax
object.Appearance = value
Remarks
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
ApproxCount Property (TDBCombo)
Syntax
object.ApproxCount = long
Remarks
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
Array Property (TDBCombo)
Syntax
object.Array = XArrayDB
Remarks
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.
BackColor Property (TDBCombo) · 429
See Also
BackColor Property (TDBCombo)
Syntax
object.BackColor = color
Remarks
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
See Also
Bookmark Property (TDBCombo)
Syntax
object.Bookmark = variant
Remarks
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.
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
BookmarkType Property (TDBCombo)
Syntax
object.BookmarkType = integer
Remarks
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()
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
BorderAppearance Property (TDBCombo)
Determines the appearance of the border.
Syntax
object.BorderAppearance = value
Remarks
Values
Design Time
Run Time
0 - Flat(default)
dblFlatStyle
1 - 3D Raised
dbl3Draised
2 - 3D Inset
dbl3Dinset
3 - 3D Raised Bevel
dbl3DraisedBevel
BorderColor Property (TDBCombo) · 431
Design Time
Run Time
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
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
See Also
BorderSize Property (TDBCombo)
The BorderSize property returns or sets the size of the cell border.
Syntax
object.BorderSize = single
Remarks
See Also
BorderStyle Property (TDBCombo)
This property determines whether a TDBList or TDBCombo control has a border.
Syntax
object.BorderStyle = value
Remarks
Values
Design Time
Run Time
0 - None
dblNoBorder
dblFixedSingle
See Also
BorderType Property (TDBCombo)
Determines the type of border.
Syntax
object.BorderType = value
Remarks
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
BoundColumn Property (TDBCombo) · 433
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
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
NOTE: Do not confuse the BoundColumn property with the ListField property used to specify the
incremental search field.
See Also
BoundText Property (TDBCombo)
Syntax
object.BoundText = value
Remarks
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.
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
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
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
See Also
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
CellTips Property (TDBCombo) · 435
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
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
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.
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.
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
Use the CellTipsWidth property to control the width of the cell tip window.
See Also
CellTipsDelay Property (TDBCombo)
The CellTipsDelay property controls the amount of idle time, in milliseconds, that must elapse before the
Syntax
object.CellTipsDelay = long
Remarks
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
CellTipsWidth Property (TDBCombo)
Syntax
object.CellTipsWidth = single
Remarks
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
Col Property (TDBCombo)
Syntax
object.Col = integer
Remarks
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
ColumnFooters Property (TDBCombo) · 437
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
ColumnFooters Property (TDBCombo)
Syntax
object.ColumnFooters = boolean
Remarks
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
ColumnHeaders Property (TDBCombo)
Syntax
object.ColumnHeaders = boolean
Remarks
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
Columns Property (TDBCombo)
Syntax
object.Columns
Remarks
This property returns a collection of Column objects for a control, drop-down control, or split.
See Also
ComboStyle Property
Syntax
TDBCombo.ComboStyle
Remarks
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 dropdown list.
See Also
CurrentCellVisible Property (TDBCombo)
Syntax
object.CurrentCellVisible = boolean
DataChanged Property (TDBCombo) · 439
Remarks
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
DataChanged Property (TDBCombo)
Syntax
object.DataChanged = boolean
Remarks
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
DataField Property (TDBCombo)
Syntax
object.DataField = string
Remarks
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.
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
DataMember Property (TDBCombo)
Syntax
object.DataMember = string
Remarks
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.
called a data member, and is identified by a unique string.
See Also
DataMode Property (TDBCombo)
Syntax
object.DataMode = value
Remarks
Values
Design Time
Run Time
0 - Bound (default)
dblBound
DataSource Property (TDBCombo) · 441
Design Time
Run Time
1 - Unbound
dblUnbound
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
DataSource Property (TDBCombo)
Syntax
object.DataSource
Remarks
The DataSource property specifies the data control that is updated once a selection is made.
See Also
DeadAreaBackColor Property (TDBCombo)
This property controls the background color of the dead area object.
Syntax
object.DeadAreaBackColor = color
Remarks
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
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
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:
DestinationCol Property (TDBCombo) · 443
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
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
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.
GroupHeadClick, HeadClick, MouseDown, MouseUp. Any attempt to access the DestinationCol
setting the control's Col property).
succeed. The value returned by this property only indicates what the correct destination column will be if
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
previous location).
See Also
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
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).
GroupHeadClick, HeadClick, MouseDown, MouseUp. Any attempt to access the DestinationRow
setting the control's Row property).
succeed. The value returned by this property only indicates what the correct destination row will be if
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
previous location).
See Also
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
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.
GroupHeadClick, HeadClick, MouseDown, MouseUp. Any attempt to access the DestinationSplit
DropdownPosition Property · 445
setting the control's Split property).
succeed. The value returned by this property only indicates what the correct destination split will be if
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
previous location).
See Also
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
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
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
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
EditBackColor Property
This property controls the background color of an object's editing window when editing is in progress.
Syntax
TDBCombo.EditBackColor = color
Remarks
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
EditFont Property
This property returns or sets the font associated with the text box portion of a TDBCombo control.
Syntax
TDBCombo.EditFont = font
Remarks
EditForeColor Property · 447
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
EditForeColor Property
This property controls the foreground color of an object's editing window when editing is in progress.
Syntax
TDBCombo.EditForeColor = color
Remarks
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
EditHeight Property
This property will set/return the height for the edit portion of the combo box.
Syntax
object.EditHeight = Value
Remarks
Values
Float
The text will be in the vertical middle of the edit portion of the combo.
See Also
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
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
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
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
ErrorText Property (TDBCombo)
This property returns the error message string from the underlying data source.
Syntax
object.ErrorText
Remarks
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
EvenRowStyle Property (TDBCombo) · 449
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
EvenRowStyle Property (TDBCombo)
This property sets or returns the Style object that controls the appearance of an even-numbered row in a
Syntax
object.EvenRowStyle = variant
Remarks
By default, this is the built-in EvenRow style.
To change the appearance of odd-numbered rows, set the OddRowStyle property.
See Also
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
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
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
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
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
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.
Font Property (TDBCombo) · 451
See Also
Font Property (TDBCombo)
This property returns or sets the font object associated with a control, column, split, or style.
Syntax
object.Font = font
Remarks
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
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
By default, this is the built-in Footing style.
See Also
FootLines Property (TDBCombo)
TDBCombo control's column footers.
Syntax
object.FootLines = single
Remarks
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
ForeColor Property (TDBCombo)
This property controls the foreground color of an object.
Syntax
object.ForeColor = color
Remarks
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
See Also
GapHeight Property
This property will set/return the length between the edit portion and the dropdown portion of the
combo box.
HeadingStyle Property (TDBCombo) · 453
Syntax
object.GapHeight = Value
Remarks
Values
Float
The default value is 2 pixels, and the value can not be set to less than 2 pixels.
See Also
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
By default, this is the built-in Heading style.
See Also
HeadLines Property (TDBCombo)
TDBCombo control's column headers.
Syntax
object.HeadLines = single
Remarks
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
HighlightRowStyle Property (TDBCombo)
This property sets or returns the Style object that controls the appearance of a highlighted row.
Syntax
object.HighlightRowStyle = variant
Remarks
By default, this is the built-in HighlightRow style.
See Also
HScrollHeight Property (TDBCombo)
The HScrollHeight property returns the height of a split's horizontal scroll bar in container units, which
Syntax
object.HScrollHeight
Remarks
If no horizontal scroll bar exists, then the returned value is zero. If object is a TDBList or TDBCombo
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
hWnd Property (TDBCombo) · 455
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
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
IntegralHeight Property (TDBCombo)
This property determines whether partial rows are displayed in a TDBList or TDBCombo control.
Syntax
object.IntegralHeight = boolean
Remarks
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
IsOpen Property
Indicates whether the dropdown list is opened or closed.
Syntax
IsOpen As Boolean
See Also
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
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.
NOTE: If the LayoutFileName property is nonempty, it takes precedence over LayoutURL, and
asynchronous downloading will not occur.
See Also
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
LoadLayout method of the control.
See Also
Layouts Property (TDBCombo) · 457
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
See Also
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
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
LimitToList Property
This property determines if the NotInList event fires when an incremental search value is not found.
Syntax
TDBCombo.LimitToList = boolean
Remarks
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
ListCount Property (TDBCombo)
Returns the number of items in the list portion of the control.
Syntax
object.ListCount
Remarks
See Also
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
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
Locked Property
This property returns or sets a value indicating whether the control can be edited.
MatchEntryTimeout Property (TDBCombo) · 459
Syntax
TDBCombo.Locked = boolean
Remarks
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
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
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.
See Also
MaxComboItems Property
This property will set the number of items to display in the dropdown portion of the combobox.
Syntax
TDBCombo.MaxComboItems = short
Remarks
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
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
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
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
Values
Design Time
Run Time
dblMPDefault
1 - Arrow
dbMPArrow
2 - Cross
dblMPCross
3 - I-beam
dblMPIbeam
MultipleLines Property (TDBCombo) · 461
Design Time
Run Time
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
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
MultipleLines Property (TDBCombo)
This property determines whether a single row can span multiple lines.
Syntax
object.MultipleLines = value
Remarks
Values
Design Time
Run Time
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
OddRowStyle Property (TDBCombo)
This property sets or returns the Style object that controls the appearance of an odd-numbered row in a
Syntax
object.OddRowStyle = variant
Remarks
By default, this is the built-in OddRow style.
To change the appearance of even-numbered rows, set the EvenRowStyle property.
See Also
OLEDragMode Property · 463
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
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
OLEDropMode Property
This property returns or sets a value that indicates how the combo handles drop operations.
Syntax
TDBCombo.OLEDropMode = value
Remarks
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
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
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
RightToLeft Property (TDBCombo)
The property provides an appearance and functionality familiar to Middle East or Latin users.
Syntax
object.RightToLeft = boolean
Remarks
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).
Row Property (TDBCombo) · 465
•
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
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
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
RowDividerColor Property (TDBCombo)
This property controls the row divider color of the controls when RowDividerStyle is 7 - Custom Color.
Syntax
object.RowDividerColor = value
Remarks
See Also
RowDividerStyle Property (TDBCombo)
This property determines the style of the border drawn between control rows.
Syntax
object.RowDividerStyle = value
Remarks
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
RowHeight Property (TDBCombo)
This property returns or sets the height of all control rows in terms of the coordinate system of the
Syntax
object.RowHeight = single
RowMember Property (TDBCombo) · 467
Remarks
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 = 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
RowMember Property (TDBCombo)
This property returns or sets the name of the row member used to populate the list.
Syntax
object.RowMember = string
Remarks
Typically, a row member represents a database table or query.
called a row member, and is identified by a unique string.
See Also
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
See Also
RowSubDividerColor Property (TDBCombo)
This property controls the row subdivider color of the controls when RowDividerStyle is 7 - Custom
Color.
Syntax
TDBList.RowSubDividerColor = value
Remarks
See Also
RowTracking Property
This property controls whether rows are automatically highlighted as the mouse is moved over the dropdown portion of a TDBCombo control.
Syntax
TDBCombo.RowTracking = boolean
Remarks
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) · 469
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
Values
Design Time
Run Time
0 - None
dblNone
1 - Horizontal
dblHorizontal
2 - Vertical
dblVertical
3 - Both
dblBoth
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
ScrollTips Property (TDBCombo)
The ScrollTips property determines whether the control displays a pop-up text window when the
Syntax
object.ScrollTips = boolean
Remarks
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
If you do not provide a handler for the FetchScrollTips event, tips will not be displayed.
See Also
ScrollTrack Property (TDBCombo)
If True, moving the scrollbar thumb causes the control’s display to update with new data.
Syntax
object.ScrollTrack = Boolean
Remarks
If False (the default), moving the scrollbar thumb does not change the display.
See Also
SelLength Property
This property returns or sets the number of characters selected within the list's editing window.
Syntax
TDBCombo.SelLength = long
Remarks
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
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
SelText Property · 471
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
See Also
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
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
See Also
SelectedItem Property (TDBCombo)
This property returns or sets the bookmark identifying the selected item in a control.
Syntax
object.SelectedItem = variant
Remarks
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
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
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.
See Also
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
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.
Split Property (TDBCombo) · 473
Setting this property to -1 deselects all columns and also sets the SelEndCol property to -1.
See Also
Split Property (TDBCombo)
This property specifies the zero-based index of the current split.
Syntax
object.Split = integer
Remarks
See Also
Splits Property (TDBCombo)
This property returns a collection of Split objects.
Syntax
object.Splits
Remarks
See Also
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
By default, this is the built-in Normal style.
See Also
Styles Property (TDBCombo)
This property returns a collection of named Style objects.
Syntax
object.Styles
Remarks
When a control is first created, it contains eight built-in styles, which control the following display
aspects:
Normal
Heading
Column headers
Footing
Column footers
Selected
Caption
Control and split caption bars
HighlightRow
EvenRow
OddRow
NOTE: At design time, use the Style Factory property page to modify these built-in styles or create your
own named styles.
See Also
Tag Property (TDBCombo)
This property returns or sets an expression that stores any extra data needed for your program.
Syntax
object.Tag = value
Remarks
Property applies to Column object for TDBList and TDBCombo.
Unlike other properties, the value of the Tag property is not used by the control.
Text Property (TDBCombo) · 475
See Also
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
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
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
VisibleCols Property (TDBCombo)
For TDBlist controls, this property returns the number of visible columns in the current split.
Syntax
object.VisibleCols
Remarks
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
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
See Also
VScrollWidth Property (TDBCombo)
The VScrollWidth property returns the width of a split's vertical scroll bar in container units, which
Syntax
object.VScrollWidth
Remarks
If no vertical scroll bar exists, then the returned value is zero. If object is a TDBList or TDBCombo
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
TDBCombo Methods
AboutBox Method (TDBCombo)
This method displays the version number and copyright notice for the specified control.
Syntax
object.AboutBox
AddItem Method (TDBCombo) · 477
Remarks
Arguments
None
Return Value
None
See Also
AddItem Method (TDBCombo)
This method adds an item to a the TDBList or TDBCombo object.
Syntax
object.AddItem strItem, [strValue], [nIndex]
Remarks
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
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
style is a Style object that specifies font and color attributes.
regex is a regular expression string.
Return Value
None
Remarks
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
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.
p$
A dollar sign at the end of a pattern forces a match to occur at the end of 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
CaptureImage Method (TDBCombo) · 479
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
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
Arguments
None
Return Value
A picture object containing a snapshot of the control's display.
See Also
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
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
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.
See Also
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
You can cancel the control's automatic layout behavior by invoking the HoldFields method.
See Also
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
regex is an optional regular expression string.
ClearSelCols Method (TDBCombo) · 481
Return Value
None
Remarks
If no such cell condition exists, then calling this method has no effect.
If regex is omitted, then all cell conditions for any regular expression matching the condition argument are
removed. If condition is -1 (dbgAllCells), then all regex cell conditions are removed, regardless of status
or expression.
If regex is supplied, then the single cell condition matching both arguments is removed. However, if
condition is -1 (dbgAllCells), then all cell conditions for the specified regular expression are removed,
regardless of status.
See Also
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
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
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
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
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.
LoadLayout Method (TDBCombo) · 483
Syntax
object.HoldFields
Arguments
None
Return Value
None
Remarks
You can resume the control's automatic layout behavior by invoking the ClearFields method.
See Also
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
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
OLEDrag Method
The OLEDrag method initiates an OLE drag/drop operation.
Syntax
TDBCombo.OLEDrag
Arguments
None
Return Value
None
Remarks
When this method is called, the list fires its OLEStartDrag event, enabling your application to supply
data to a target component.
See Also
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
See Also
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
PostMsg Method (TDBCombo) · 485
Return Value
Remarks
Run Time
0 - Not in List
dblNotInList
1 - At List Caption
dblAtCaption
2 - At Split Header
dblAtSplitHeader
dblAtSplitSizeBox
4 - At Row Select
dblAtRowSelect
5 - At Row Size
dblAtRowSize
dblAtColumnHeader
dblAtColumnFooter
8 - At Column Size
dblAtColumnSize
9 - At Data Area
dblAtDataArea
where the user clicked or dropped another control in terms of a control element.
See Also
PostMsg Method (TDBCombo)
The PostMsg method is used in conjunction with the PostEvent event to postpone operations which are
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.
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.
See Also
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
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.
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.
See Also
Refresh Method (TDBCombo) · 487
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 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
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
See Also
RowBookmark Method (TDBCombo)
The RowBookmark method returns a bookmark for a visible row relative to the first displayed row.
Syntax
object.RowBookmark (rownumber)
Arguments
Return Value
A variant containing a bookmark corresponding to the display row specified by rownumber.
Remarks
If rownumber is 0, this method returns the bookmark of the first displayed row. The value returned will be
the same as that returned by the FirstRow property.
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
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
This value ranges from 0 to VisibleRows - 1.
RowTop Method (TDBCombo) · 489
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.
See Also
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
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
Use the RowTop method in conjunction with RowHeight, Left, and Width to determine the size and
See Also
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
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
SplitContaining Method (TDBCombo)
The SplitContaining method returns the Index value of the split containing the specified coordinate pair.
Syntax
object.SplitContaining (x, y)
Arguments
Return Value
An integer corresponding to the index of the split beneath the specified coordinate pair.
Remarks
This value ranges from 0 to Splits.Count - 1.
If either argument is outside of the control's data area, this method returns -1.
See Also
TDBCombo Events
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)
Change Event · 491
Arguments
Remarks
See Also
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
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
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
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
This event is fired only when ComboStyle property is set to 0 - Dropdown Combo or 2 - Dropdown List.
See Also
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
Remarks
denotes the right edge.
To determine which columns are being moved, examine the SelStartCol and SelEndCol properties.
NOTE: This event is only fired when the user moves the selected columns to a new location.
See Also
ColResize Event (TDBCombo) · 493
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.
Remarks
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.
See Also
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
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
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
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
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,
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 (page 524) for a list of allowable values.
FetchCellTips Event (TDBCombo) · 495
You can also set the ForegroundPicture property of the CellStyle parameter to display distinct bitmaps on
a per-cell basis.
See Also
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
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
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
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.
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
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.
See Also
FetchScrollTips Event (TDBCombo) · 497
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
attributes of the current split.
See Also
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
•
•
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.
RowChange.
See Also
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
column.
See Also
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
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
HeadClick Event (TDBCombo) · 499
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
Remarks
column.
See Also
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
•
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
KeyDown Event (TDBCombo)
The KeyDown event occurs when the user presses a key.
Syntax
object_KeyDown (KeyCode As Integer, Shift As Integer)
Arguments
Remarks
•
•
Navigation keys.
•
•
See Also
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
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
KeyUp Event (TDBCombo) · 501
KeyUp Event (TDBCombo)
The KeyUp event occurs when the user releases a key.
Syntax
object_KeyUp (KeyCode As Integer, Shift As Integer)
Arguments
Remarks
•
•
Navigation keys.
•
•
See Also
LayoutReady Event (TDBCombo)
The LayoutReady event fires when asynchronous downloading of a control layout file has completed.
Syntax
object_LayoutReady ( )
Arguments
None
Remarks
The location of the layout file is determined by the LayoutURL property.
initializing a control on an HTML page.
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
LeftColChange Event (TDBCombo)
The LeftColChange event occurs when the first visible column of a control is changed.
Syntax
object_LeftColChange ( )
Arguments
None
Remarks
•
•
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.
RowChange.
See Also
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.
MouseDown Event (TDBCombo) · 503
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
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
MouseDown Event (TDBCombo)
Syntax
object_MouseDown (Button As Integer, Shift As Integer, X As Single, Y As Single)
Arguments
Remarks
See Also
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
Remarks
This event is primarily useful for implementing drag-and-drop behavior on a per-column basis.
See Also
MouseUp Event (TDBCombo)
Syntax
object_MouseUp (Button As Integer, Shift As Integer, X As Single, Y As Single)
Arguments
OLECompleteDrag Event · 505
Remarks
See Also
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
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
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.
Drop results in a copy of data from the source to the target. The original data
is unaltered by the drag operation.
Drop results in a link to the original data being created between drag source
and drop target.
always expressed in terms of the coordinate system of the combo's container.
Remarks
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
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
method. The SetData and Clear methods cannot be used here.
OLEGiveFeedback Event · 507
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:
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.
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
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
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
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
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
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
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.
OLEStartDrag Event · 509
NOTE: Currently, the only data format recognized by the combo is text.
See Also
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
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:
Drop results in a copy of data from the source to the target. The original
data is unaltered by the drag operation.
Drop results in a link to the original data being created between drag
source and drop target.
Remarks
This event enables your application to specify the data formats and drop effects that the source 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
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
This event is fired only when ComboStyle property is set to 0 - Dropdown Combo or 2 - Dropdown List.
See Also
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.
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
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
NotInList Event · 511
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
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
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
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
PostEvent Event (TDBCombo)
The PostEvent event is used in conjunction with the PostMsg method to postpone operations that are
Syntax
object_PostEvent (ByVal MsgId As Integer)
Arguments
MsgId is an integer that identifies the message posted by the PostMsg method.
Remarks
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
See Also
RowResize Event (TDBCombo)
The RowResize event occurs when the user has finished resizing a control row.
Syntax
object_RowResize (Cancel As Integer)
Arguments
Remarks
The RowHeight property determines the height of all rows in the control.
RowSourceChanged Event (TDBCombo) · 513
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.
See Also
RowSourceChanged Event (TDBCombo)
The RowSourceChanged event fires when a bound data source is changed or requeried.
Syntax
object_RowSourceChanged ( )
Arguments
None
Remarks
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()
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
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
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.
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
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
•
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).
UnboundColumnFetch Event (TDBCombo) · 515
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
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
Remarks
For a bound control, any column with an empty DataField property and a non-empty Caption property
is considered an unbound column.
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
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
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
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.
UnboundReadData Event (TDBCombo) · 517
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.
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
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
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
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
Arguments
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
Use its ColumnCount property to determine the number of columns to be populated.
unbound dataset.
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
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
UnboundReadDataEx Event (TDBCombo) · 519
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.
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
Remarks
Before returning from the UnboundReadDataEx event, you must fill the Bookmark array of RowBuf with
unique row identifiers, and the Value array with the actual data. For example, if Offset is 1 (or -1), then
you must fill in RowBuf, starting from the row that follows (or precedes) StartLocation.
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.
unbound dataset.
See Also
Alignment Constants · 521
Constant Reference
Alignment Constants
Applies To
Alignment, FooterAlignment, and HeadAlignment properties
Values
Design Time
Run Time
0 - Left (default)
dblLeft
1 - Right
dblRight
2 - Center
dblCenter
dblGeneral
AnimateWindow Constants
Applies To
AnimateWindow property
Values
Design Time
Run Time
dblNoAnimate
1 - Roll
dblRoll
2 - Slide
dblSlide
3 - Blend
dblBlend
AnimateWindowClose Constants
Applies To
AnimateWindowClose property
Values
Design Time
Run Time
dblNoAnimateClose
2 - Same Direction
dblSameDirection
AnimateWindowDirection Constants
Applies To
AnimateWindowDirection property
522 · Constant Reference
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
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
BorderStyle Constants · 523
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
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
DataView Constants · 525
Values
Design Time
Run Time
0 - Bound (default)
dblBound
1 - Unbound
dblUnbound
dblUnboundEx
3 - Application
dblUnboundAp
4 - Storage
dblUnboundSt
5 - AddItem
dblAddItem
DataView Constants
Applies To
DataView property
Values
Design Time
Run Time
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
Description
Run Time
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
trying to add record
dblADDERROR
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
ExposeCellMode Constants · 527
Description
Run Time
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
Design Time
Run Time
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
dblSeekLE
-3 - Equal
dblSeekEQ
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
Menu Constants · 529
Design Time
Run Time
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
Constant
Menu Command
27 - dblpTipStop
Stop Pagination
MousePointer Constants
Applies To
MousePointer property
Values
Design Time
Run Time
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
dblMPArrowHourglass
14 - Arrow Question
dblMPArrowQuestion
15 - Size All
dblMPSizeAll
99 - Custom
dblMPCustom
MultipleLines Constants
Applies To
MultipleLines property
Values
Design Time
Run Time
dblMultipleDisabled
1 - Variable
dblMultipleVariable
2 - Fixed
dblMultipleFixed
MultiSelect Constants · 531
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
dblAtSplitSizeBox
Description
Run Time
4 - At Row Select
dblAtRowSelect
5 - At Row Size
dblAtRowSize
dblAtColumnHeader
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
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
SplitSizeMode Constants · 533
Design Time
Run Time
3 - Both
dblBoth
dblAutomatic
SplitSizeMode Constants
Applies To
SizeMode property
Values
Design Time
Run Time
0 - Scalable (default)
dblScalable
1 - Exact
dblExact
dblNumberOfColumns
UnboundFind Constants
Applies To
UnboundFindData event
Values
Description
Run Time
-1 - Less Than
dblSeekLT
dblSeekLE
-3 - Equal
dblSeekEQ
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 Object Members · 535
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.
NeedTotalPageCount
Sets/returns whether the total page count is needed for owner-drawn
page headers or footers.
NoClipping
Sets/returns whether printed text is clipped to cell boundaries.
NumberOfCopies
Sets/returns the number of copies to print.
PageFooter
Sets/returns the page footer for a PrintInfo object.
PageFooterFont
Sets/returns the page footer font for a PrintInfo object.
PageFooterHeight
Sets/returns the height of an owner-drawn page footer (twips).
PageFooterOwnerDraw
Sets/returns whether a page footer is owner drawn.
PageHeader
Sets/returns the page header for a PrintInfo object.
PageHeaderFont
Sets/returns the page header font for a PrintInfo object.
PageHeaderHeight
Sets/returns the height of an owner drawn page header (twips).
PageHeaderOwnerDraw
Sets/returns whether the page header is owner drawn.
PageSetupCancelled
Returns true if the Page Setup dialog is cancelled by the user.
PreviewAllowFileOps
Sets/returns whether the file load/save are allowed in preview.
PreviewCaption
Sets/returns the print preview window caption.
PreviewInitHeight
Sets/returns the print preview window's initial height (0 for auto).
PreviewInitPosX
Sets/returns the print preview window's initial x pos.
PreviewInitPosY
Sets/returns the print preview window's initial y pos.
PreviewInitScreenFill
Sets/returns the print preview window's initial screen fill (percent).
PreviewInitWidth
Sets/returns the print preview window's initial width (0 for auto).
PreviewInitZoom
Sets/returns the print preview window's initial zoom factor (percent).
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.
536 · PrintInfo Reference
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
This property sets or returns a boolean that determines whether output should be collated when printing
multiple copies.
Syntax
PrintInfo.Collate = boolean
Remarks
Default Property · 537
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
Default Property
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
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
Draft Property
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
If True, rendered or printed output is in draft quality.
If False (the default), rendered or printed output uses the default settings.
See Also
Name Property
This property sets or returns the string used to identify a PrintInfo object within a PrintInfos collection.
Syntax
PrintInfo.Name = string
Remarks
When a TDBList control is first created, its PrintInfos collection contains a single PrintInfo object named
DefaultPrintInfo.
See Also
NeedTotalPageCount Property
Sets/returns whether the total page count is needed for owner-drawn page headers or footers.
Syntax
NeedTotalPageCount As Boolean
See Also
NoClipping Property
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
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.
NumberOfCopies Property · 539
See Also
NumberOfCopies Property
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
When NumberOfCopies is greater than 1, the order in which pages are printed is determined by the
Collate property.
See Also
PageFooter Property
This property sets or returns a string to be printed at the bottom of each page.
Syntax
PrintInfo.PageFooter = string
Remarks
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
PageFooterFont Property
This property sets or returns the font used to display the PageFooter string.
Syntax
PrintInfo.PageFooterFont = font
Remarks
By default, this is the same value returned by the list's Font property.
See Also
PageFooterHeight Property
Sets/returns the height of an owner-drawn page footer (twips).
Syntax
PageFooterHeight As Long
See Also
PageFooterOwnerDraw Property
Sets/returns whether a page footer is owner drawn.
Syntax
PageFooterOwnerDraw As Boolean
See Also
PageHeader Property
This property sets or returns a string to be printed at the top of each page.
Syntax
PrintInfo.PageHeader = string
Remarks
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."
PageHeaderFont Property · 541
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
PageHeaderFont Property
This property sets or returns the font used to display the PageHeader string.
Syntax
PrintInfo.PageHeaderFont = font
Remarks
By default, this is the same value returned by the list's Font property.
See Also
PageHeaderHeight Property
Sets/returns the height of an owner drawn page header (twips).
Syntax
PageHeaderHeight As Long
See Also
PageHeaderOwnerDraw Property
Sets/returns whether the page header is owner drawn.
Syntax
PageHeaderOwnerDraw As Boolean
See Also
PageSetupCancelled Property
This property returns a boolean that determines whether the PageSetup dialog has been cancelled by the
user.
Syntax
PrintInfo.PageSetupCancelled
Remarks
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
PreviewAllowFileOps Property
Sets/returns whether the file load/save are allowed in preview.
Syntax
PreviewAllowFileOps As Boolean
See Also
PreviewCaption Property
This property sets or returns a string that will be displayed in the title bar of the PrintPreview window.
Syntax
PrintInfo.PreviewCaption = string
Remarks
By default, this property returns an empty string, and no window caption is displayed.
See Also
PreviewInitHeight Property
Syntax
PreviewInitHeight As Long
PreviewInitPosX Property · 543
See Also
PreviewInitPosX Property
Sets/returns the print preview window's initial x pos.
Syntax
PreviewInitPosX As Long
See Also
PreviewInitPosY Property
Syntax
PreviewInitPosY As Long
See Also
PreviewInitScreenFill Property
Sets/returns the print preview window's initial screen fill (percent).
Syntax
PreviewInitScreenFill As Long
See Also
PreviewInitWidth Property
Sets/returns the print preview window's initial width (0 for auto).
Syntax
PreviewInitWidth As Long
See Also
PreviewInitZoom Property
Sets/returns the print preview window's initial zoom factor (percent).
Syntax
PreviewInitZoom As Long
See Also
PreviewMaximize Property
This property sets or returns a boolean that determines whether the PrintPreview dialog is initially
maximized when first displayed.
Syntax
PrintInfo.PreviewMaximize = boolean
Remarks
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
PreviewPageOf Property
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
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
RangeOfPages Property · 545
RangeOfPages Property
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
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
RepeatColumnFooters Property
This property sets or returns a boolean that determines whether column footers should appear on each
page.
Syntax
PrintInfo.RepeatColumnFooters = boolean
Remarks
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
RepeatColumnHeaders Property
This property sets or returns a boolean that determines whether column headers should appear on each
page.
Syntax
PrintInfo.RepeatColumnHeaders = boolean
Remarks
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
RepeatListHeader Property
This property sets or returns a boolean that determines whether the list caption should appear on each
page.
Syntax
PrintInfo.RepeatListHeader = boolean
Remarks
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
RepeatSplitHeaders Property
This property sets or returns a boolean that determines whether split captions should appear on each
page.
Settings Property · 547
Syntax
PrintInfo.RepeatSplitHeaders = boolean
Remarks
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
Settings Property
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
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
SettingsDeviceName Property
Use this property to specify the printer device name in the print Settings blob.
Syntax
PrintInfo.SettingsDeviceName = string
Remarks
See Also
SettingsMarginBottom Property
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
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
SettingsMarginLeft Property
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
SettingsMarginRight Property · 549
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
SettingsMarginRight Property
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
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
SettingsMarginTop Property
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
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
SettingsOrientation Property
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
See Also
SettingsPaperBin Property
Use this property to specify the paper bin to be used in the print Settings blob.
Syntax
PrintInfo.SettingsPaperBin = integer
Remarks
See Also
SettingsPaperHeight Property
Use this property to specify the paper height in the print Settings blob. The setting is in twips.
Syntax
PrintInfo.SettingsPaperHeight = long
Remarks
See Also
SettingsPaperSize Property
Use this property to specify the paper size in the print Settings blob.
Syntax
PrintInfo.SettingsPaperSize = integer
Remarks
SettingsPaperWidth Property · 551
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
SettingsPaperWidth Property
Use this property to specify the paper width in the print Settings blob. The setting is in twips.
Syntax
PrintInfo.SettingsPaperWidth = long
Remarks
See Also
UnitsPerInch Property
Use the UnitsPerInch property to determine the logical resolution of a printer device context.
Syntax
PrintInfo.UnitsPerInch = long
Remarks
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
VariableRowHeight Property
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
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
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
GetSubstituteFont Method
The GetSubstituteFont method retrieves the name of a replacement font specified in a prior call to the
SubstituteFont method.
PageSetup Method · 553
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
See Also
PageSetup Method
The PageSetup method opens the page setup dialog for printing and print preview.
Syntax
PrintInfo.PageSetup
Arguments
None
Return Value
None
Remarks
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
PrintData Method
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
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
PrintPreview Method
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
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:
SetMenuText Method · 555
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
SetMenuText Method
If you are developing an international application, you can use the SetMenuText method to change the
names of the menu commands in the PrintPreview window.
Syntax
PrintInfo.SetMenuText index, string
Arguments
index is a constant that specifies a menu item in the PrintPreview window.
string is the replacement text for the specified menu item
Return Value
None
Remarks
The index argument can be one of the following constants:
Constant
Menu Command
0 - dblpMenuFile
File
1 - dblpMenuPrint
Print
2 - dblpMenuExit
Exit
3 - dblpMenuView
View
4 - dblpMenuZoomIn
Zoom In
5 - dblpMenuZoomOut
Zoom Out
6 - dblpMenuFit
Fit in Window
Constant
Menu Command
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
SubstituteFont Method
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.
SubstituteFont Method · 557
Remarks
If the AvailableFont argument is omitted, any prior substitution is discarded.
See Also
XArrayDB Object Members · 559
XArrayDB Reference
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.
560 · XArrayDB Reference
XArrayDB Object Properties
Count Property (XArrayDB)
This property returns a long integer that specifies the number of elements contained in a given dimension
of an XArrayDB object.
Syntax
XArrayDB.Count (nDim)
Arguments
nDim is a one-based integer specifying an array dimension.
Remarks
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):
Dim N As Long
N = MyArray.Count(1) ' returns 100
N = MyArray.Count(2) ' returns 6
See Also
XArrayDB Object (page 98)
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
LowerBound Property (XArrayDB) · 561
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
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
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
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):
Dim N As Long
N = MyArray.LowerBound(1) ' returns 1
562 · XArrayDB Reference
N = MyArray.LowerBound(2) ' returns 0
See Also
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
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.
S

Style Property (TDBCombo)

Transcription

Similar documents

FARREL-MCWHIRTER PARK - Cascade Orienteering Club

Split Data in One Column Into Two or More Columns

Alpha Epsilon Rho Alpha Kappa Psi

We Deliver Flyers!

McVeighs Pumpkin Patch

Poly-Classic® Craftsman Series Column Installation of Tapered

Trajan`s Column. pdf

We Deliver Flyers!

to your all access subscription

Window Sticker - FordDirect.com