ComponentOne Query 8.0

Product Profile

Feature List

Quick Reference for All Properties

Quick Reference for All Events

Quick Reference for All Methods

Tutorials


Overview

Welcome to ComponentOne Query 8.0, an end-user-oriented run-time query builder. C1Query enables developers to easily build applications with end-user ad hoc query functionality.

ComponentOne has a user-friendly distribution policy. We want every programmer to obtain a copy of Query 8.0 for Active X to try for as long as they wish. Those who like Query 8.0 and find it useful may buy a license for a reasonable price. The only restriction is that unlicensed copies of Query 8.0 for Active X will display a ComponentOne banner every time they are loaded to remind developers to license the product.

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

Corporate Headquarters

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

http://www.componentone.com


Product Profile

ComponentOne Query 8.0 is an end-user-oriented run-time query builder. It is an ActiveX control allowing developers to easily build applications with end-user ad hoc query functionality.

ComponentOne Query 8.0 has the following advantages over existing query tools, which make it a unique, revolutionary tool for enabling ad hoc query functionality in applications:

•

ComponentOne Query 8.0 collects end user input and generates an SQL query or an ADO Filter condition at run time. This enables developers to add ad hoc query functionality to their applications, making it directly available to end users, instead of preparing all imaginable queries beforehand, in design time environment.

•

ComponentOne Query 8.0 shields end users from the complexities of database structure. Queries are constructed using convenient names and business concepts known to end users, and the user interface is fully customizable by the developer. No special skills are required in order to use C1Query 8.0 in an application. Users don’t even have to be aware of the fact that C1Query was used to create the application.

•

ComponentOne Query 8.0 has a powerful query generation engine, supporting queries spanning multiple tables. It allows developers to create schemas exposing database fields to users in a customized form, specifying relationships between tables.

•

ComponentOne Query 8.0 has a built-in user interface, making implementing ad hoc functionality as easy as dropping two controls on a form. The user interface can be easily customized in a virtually unrestricted variety of ways using a special template mechanism and other customization provisions. This is one of the most important advantages over existing query solutions: you are not forced to use a specific user interface, it can be modified to satisfy any application needs.

•

ComponentOne Query 8.0 is a component, an ActiveX control. As a component, it integrates into your application, makes adding ad hoc query functionality just another task in building the application. Your user does not need to learn a special query tool or even to know that the C1Query 8.0 component is used in your application.

•

ComponentOne Query 8.0 run-time use is royalty-free. You pay for it once, only for using it designing your applications. Your users have it free of charge, as a part of your application.


Installation

To install Query 8.0, use the SETUP.EXE utility provided on the installation CD or diskettes. When you are prompted, enter the registration key (found on the CD case or the diskette) exactly as it is printed and click REGISTER to complete the registration.

The following file will be installed into your Windows\System directory or, if you use Windows NT, into your WinNT\System and WinNT\System32 directories. To use Query 8.0 in your Visual Basic projects, you must include these files in the project:

C1Query8.ocx

The following folders will be created by the setup utility:

ComponentOne

Directory used to store ComponentOne control information.

ComponentOne\Query 8.0

contains sample projects and a README.TXT file with information about Query 8.0.


Adding ComponentOne Query 8.0 Control to a Visual Basic Project

After you have opened a new or existing project in Visual Basic 6.0, you can add ComponentOne Query 8.0 to the Visual Basic Toolbox by following these instructions:

Open the Visual Studio IDE (Microsoft Development Environment). Make sure the Toolbox is visible (select Toolbox in the View menu, if necessary). Right-click the Toolbox to open the toolbox context menu.

If you want the Query 8.0 component to appear on its own tab in the Toolbox, select Add Tab from the context menu and type in the tab name, for example, “Query”. Select the tab where you want the component to appear. Right-click that tab and select Customize Toolbox… from the context menu. The Customize Toolbox dialog box will open.

In the Customize Toolbox dialog box, go to the .NET Framework Components tab. Sort the list by Namespace (click the Namespace column header) and check the check box for the component belonging to namespace C1.Web.C1WebGrid.

The two ComponentOne Query 8.0 icons will be added to the Visual Basic Toolbox, one for the C1Query control, and one for the C1QueryFrame control:


Feature List

ComponentOne Query provides everything you need to add powerful ad hoc query functionality to applications. It supports a wide variety of features making it powerful and at the same time extremely flexible, customizable in each and every aspect, so developers can provide their users with any imaginable visual interface, according to their needs.

Powerful Query Engine

ComponentOne Query works with a schema containing database structure information and all the additional information necessary to generate SQL queries, such as joins and relationships between tables. C1Query contains a special schema designer that helps you create and maintain C1Query schemas.

All SQL Databases Supported

SQL queries generated by C1Query can run in every database supporting SQL. You can execute them using any database access engine available in Windows: ADO/OLE DB, DAO, ODBC, native database interfaces. C1Query allows you to customize the resulting SQL syntax, adjusting it to your database requirements.

Database Structure Import

ComponentOne Query schema designer can import a database structure from any OLE DB data source, and create a complete customizable schema for you. If necessary, you can also create a schema manually, without connecting to a database.

Simple DataSource Mode

If your queries don’t span multiple tables (a common case in many applications), using C1Query becomes a matter of point-and-click. C1Query can be bound to any ADO/OLE DB data source, just like any data-aware control, and it will instantly be able to receive user input and generate queries. No need to use schema designer or even know about C1Query schemas.

Built-in User Interface

ComponentOne Query provides a built-in user interface allowing you to enter user conditions and a selection of result fields in an intuitive and visually appealing style. But, best of all, this built-in UI is fully customizable, to the extent unheard of in the development community.

Customizing UI with Templates

Every visual aspect of the ComponentOne Query UI can be customized. This includes colors, fonts and many other visual styles, words and phrases used in query display, composition of condition elements. All this is done in a consistent, easy and flexible way, using HTML templates. Using simple HTML snippets, you can specify how you want to render conditions and other query elements. HTML is used exclusively for UI customization. C1Query is a regular ActiveX control, it can be used in Visual Basic and any other ActiveX-enabled environment, without HTML pages, and template customization will still be available.

Customizing UI with Scripts

You can customize C1Query UI even further, replacing the general display layout with a completely different one. With the help of a special script, you can change the layout, the rules of query composition, as your query appears on display. User interaction with such query remains fully functional although its layout is completely changed.

Using Custom UI

You can even go as far in customizing the UI as not using the built-in UI at all, substituting it with your own UI that you can create on a Visual Basic form or using any other means. Then you can still benefit from the powerful C1Query query generation engine. C1Query object model allows you to programmatically set the fields and conditions specified by the user and generate the SQL statement from them.

Query Engine on the Web

ComponentOne Query can be used in web applications to submit queries from a thin browser-based client to the server and generate SQL statement on the server. WebQueryASP sample in the Samples\ASP directory shows how to do that using ASP (Active Server Pages). In this case, C1Query is used to generate SQL query statements from user input received from a browser client. C1Query is used only on the server. The client is a generic HTML browser, no ActiveX or other plug-ins required.

Hierarchical Folder Structure

The C1Query user interface exposes fields to the end user in the form of a hierarchical folder structure. This enables developers to name and organize query fields according to the customer business domain rather than deal with database table and column names.

Convenient Value Editing

Entering constant values in queries, end users have the convenience of built-in editors for types like date/time, numeric, etc. Date/time values are edited using the standard date-time picker control with dropdown calendar.

Lookup Lists

You can specify the lookup data source for a field and C1Query will present the end user with a lookup combo or menu. For example, the user can select a product from a list of products, instead of entering an id. Adding a lookup is as easy as calling a method and specifying the data source and the names of the fields in the lookup. And it is fully customizable. You can create fixed lookup lists in schema, retrieve them from a database, or fill them programmatically in a special event.

Custom Editors

If the default C1Query edit and lookup facilities are not enough, you can specify any ActiveX control as an editor for a constant value in a query. This way you can implement custom editing and custom lookup.

Multi-Table Views

ComponentOne Query schema designer enables the developer to create multi-table views combining information stored in different tables.

Calculated Fields

Calculated fields can be added to schema views, so the user can query these fields as if they were stored in the databse.

Join Relationships

ComponentOne Query schema contains relationships between tables. C1Query engine uses relationships to join tables in the generated SQL query.

Join Groups

As a simplified method of joining tables, C1Query allows you to assign fields to join groups. Fields belonging to the same join group can be used by C1Query engine to join tables in the generated SQL query.

Custom Condition Relationships

ComponentOne Query schema designer allows you to specify arbitrary SQL conditions that are automatically applied (added to the generated SQL) once certain views (tables) appear in the query.


End-User License Agreement

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

I. THIS EULA.

1.

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

2.

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

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

II. YOUR LICENSE TO DEVELOP AND TO DISTRIBUTE.

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

1.

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

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

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

"Developer Seat License" means that each Developer using or otherwise accessing the programmatic interface or the SOFTWARE must obtain the right to do so by purchasing a separate End User License. "Network Server CPU License" means that a separate End User License must be purchased for each CPU operating the computer software at issue in the reference.

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

2.

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

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

The Developer Seat License means that you may perform a single install of the SOFTWARE for use in designing, testing and creating Developed Software by a single Developer on a single computer with a single set of input devices, so long as such computer is used only by one Developer. Conversely, you may not install or use the SOFTWARE on a computer that is a network server or a computer at which the SOFTWARE is used by more than one Developer. You may not network the SOFTWARE or any component part of it, where it is or may be used by more than one Developer unless you purchase an additional Development License for each Developer. You must purchase another separate license to the SOFTWARE in order to add additional developer seats, whether the additional developers are accessing the SOFTWARE in a stand-alone environment or on a computer network. If the SOFTWARE is used to create Developed Web Server Software, then you may perform a single install of the SOFTWARE for use in designing, testing and creating Developed Web Server Software by a single Developer on a single computer or Network Server, either with a single CPU only. An additional Network Server CPU License is required for each additional CPU on the single computer or Network Server, as the case may be, upon which the SOFTWARE and/or the Developed Web Server Software is installed and a separate license for each separate computer. That is, for Developed Web Server Software, if the computer or Network Server operating the SOFTWARE has 2 CPU's, then you would need to purchase one additional Network Server CPU License (beyond the one Developer Seat License granted in this EULA).

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

3.

Your Distribution License.

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

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

4.

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

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

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

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

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

b. VS View Reporting Edition. VS View Reporting Edition includes at least one executable file listed as “VSRpt7.exe”, known as “Designer.” The file "VSRpt7.exe”, or any upgrade or future versions of the Designer, are subject to the restrictions set forth in this EULA and may not be distributed with your Developed Software or in any other way.

c. VSForum. VSForum is intended to be installed on a Network Server. C1 grants to you the following rights to the SOFTWARE: a) Installation: You may install one copy of the SOFTWARE on a single Network Server; b) Use: When installed and initialized, the SOFTWARE creates a database file which contains the embodiment of a discussion forum (the database hereinafter referred to as the "Forum"). You may use the SOFTWARE to create one Forum on one Network Server only, which server may be connected at any point to an unlimited number of workstations or computers operating on one or more networks. You are specifically NOT LICENSED to create or operate multiple Forums. To create or to operate more than one FORUM, you must purchase one additional SOFTWARE license for each additional Forum.

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

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

5.

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

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

6.

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

7.

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

III. INTELLECTUAL PROPERTY.

1.

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

2.

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

3.

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

4.

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

5.

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

6.

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

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

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

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

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

7.

U.S. Government Restricted Rights. The SOFTWARE and documentation are provided with RESTRICTED RIGHTS. For solicitations issued before December 1, 1995, by the United States of America, its agencies and/or instrumentalities (the "Government"), other than the Department of Defense, the use, duplication or disclosure of the software and documentation provided to the Government under this EULA shall be subject to the RESTRICTED RIGHTS as set forth in subparagraphs (c)(1) and (2) of the Commercial Computer Software - Restricted Rights clause at 48 CFR ch.1 52.227-19. For solicitations issued before September 29, 1995, by the Department of Defense, the use, duplication or disclosure of the software and documentation provided under this EULA shall be subject to the RESTRICTED RIGHTS as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at 48 CFR ch.2 252.227-7013. You will comply with any requirements of the Government to obtain such RESTRICTED RIGHTS protection, including without limitation, the placement of any restrictive legends on the SOFTWARE, and any license agreement used in connection with the distribution of the SOFTWARE. Manufacturer is ComponentOne, LLC, 4516 Henry Street, Suite 501, Pittsburgh, Pennsylvania 15213 USA. For solicitations issued by the Government on or after December 1, 1995 and the Department of Defense on or after September 29, 1995, the only rights provided in the software and documentation provided herein shall be those contained in this EULA. Under no circumstances shall C1 be obligated to comply with any Governmental requirements regarding the submission of or the request for exemption from submission of cost or pricing data or cost accounting requirements. For any distribution of the SOFTWARE that would require compliance by C1 with the Government's requirements relating to cost or pricing data or cost accounting requirements, you must obtain an appropriate waiver or exemption from such requirements for the benefit of C1 from the appropriate Government authority before the distribution and/or license of the SOFTWARE to the Government.

IV. WARRANTIES AND REMEDIES.

1.

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

2.

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

V. MISCELLANEOUS.

1.

This is the Entire Agreement. This EULA (including any addendum or amendment to this EULA included with the SOFTWARE) is the final, complete and exclusive statement of the entire agreement between you and C1 relating to the SOFTWARE. This EULA supersedes any prior and contemporaneous proposals, purchase orders, advertisements, and all other communications in relation to the subject matter of this EULA, whether oral or written. No terms or conditions, other than those contained in this EULA, and no other understanding or agreement which in any way modifies these terms and conditions, shall be binding upon the parties unless entered into in writing executed between the parties, or by other non-oral manner of agreement whereby the parties objectively and definitively act in a manner to be bound (such as by continuing with an installation of the SOFTWARE, "clicking-through" a questionnaire, etc.) Employees, agents and other representatives of C1 are not permitted to orally modify this EULA.

2.

You Indemnify C1. You agree to indemnify, hold harmless, and defend C1 and its suppliers and resellers from and against any and all claims or lawsuits, including attorney's fees, that arise or result from this EULA.

3.

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


Redistributable Files

ComponentOne Query 8.0 for Active X is developed and published by ComponentOne LLC. You may use it for development with Microsoft Visual Studio or any other programming environment. You may also distribute the following control files, royalty free, with any application you develop:

C1Query8.OCX

C1qschd8.exe (schema designer)

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

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

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

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


Technical Support

ComponentOne Query 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 C1Query users:

•

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

•

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

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.c1query@componentone.com

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

•

Your ComponentOne product serial number.

•

The version and name of your operating system.

•

Your development environment and its version.

For more information on technical support, go to:

www.componentone.com/support

Peer-to-Peer Newsgroup

ComponentOne also sponsors a peer-to-peer newsgroup for ComponentOne Query 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 ComponentOne Query. However, ComponentOne may monitor the newsgroup to ensure accuracy of information and provide comments when necessary. You can access the newsgroup from the ComponentOne Web site at: www.componentone.com/newsgroups.


System Requirements

ComponentOne Query requires Microsoft Internet Explorer 4.0 or better to be installed on the user’s computer. It is not necessary to have Internet Explorer available as a standalone application. C1Query uses only the kernel Internet Explorer functionality, freely redistributable and included by default in the operating systems such as Windows 2000, Windows 98 and Windows ME. For other Windows operating systems, you can check the presence of the necessary DLLs, such as MSHTML.DLL, SHDOCVW.DLL, etc, and if they are not present or are outdated (before version 4.0), install Internet Explorer or its kernel functionality components.

ComponentOne Query also uses Microsoft XML parser. Installing Internet Explorer 5.0 or better ensures that the XML parser is available. The parser can also be downloaded from Microsoft web site at msdn.microsoft.com/xml.


ComponentOne Query Files

In order for C1Query to function at design time, the following files must reside in the same directory:

C1Query8.ocx, c1qschd8.exe, c1qschg8.dll

The C1Query8.ocx file must be registered by the usual command:

REGSVR32 C1Query8.ocx

The C1Query setup program places the files in the installation directory and registers C1Query8.ocx.

Files c1qschd8.exe and c1qschg8.dll are only necessary at design time. At run time, only C1Query8.ocx is required.

If you want to use the C1QueryUI control, a user control built in Visual Basic (full source code provided in the USERCTL directory), you must register it with

REGSVR32 C1QUERY80UI.OCX

Registering C1QUERY80UI.OCX is required in Tutorial 5. You must have Visual Basic runtime DLL installed on your computer in order to use the C1QueryUI control.


Getting Started


Product Components

C1Query Control

Schema Designer

C1Query Frame Control

C1QueryUI Control


C1Query Control

The C1Query control, invisible at run time, is in effect, the engine for ComponentOne Query. Its BuildSQL method generates SQL statements. The generated SQL statement can then be retrieved from the SQL property. C1Query control stores the schema. Schema designer, a GUI application used to create and modify the schema stored in a C1Query control, can be launched from the C1Query context menu.

See Using C1Query Control to Generate SQL for detailed description.


Schema Designer

The schema designer is a GUI application used to create a schema for a C1Query control: import database structure creating a new schema or modify the schema stored in the control. To open schema designer, select Schema Designer… from the context menu of a C1Query control. The schema designer can also be used as a standalone application: C1QSCHD1.EXE. A schema can be saved and restored from a file.

See Schema Designer for detailed description.


C1Query Frame Control

The C1QueryFrame control is responsible for the user interface portion of C1Query. It displays query conditions and result fields, and allows the end user to enter and edit them. Its ContentsType property determines whether a C1QueryFrame control displays filter conditions (resulting in the WHERE clause of the generated statement) or result fields (resulting in the SELECT part of the generated statement).

A C1QueryFrame control is associated with a C1Query control with the SchemaControl property. You can associate either one or two C1QueryFrame controls to a single C1Query control. If there are two associated controls, one of them must display filter conditions, the other – result fields, according to their ContentsType property. If there is no C1QueryFrame control with result fields, C1Query generates a SELECT * statement, selecting all fields from the tables appearing in the query.

See Developing a User Interface for detailed description.


C1QueryUI Control

C1QueryUI control is an ActiveX control created in Visual Basic, with full source code provided in the USERCTL subdirectory. It contains two C1QueryFrame controls, responsible for the two parts of the query: filter conditions and result fields.

C1QueryUI control is provided both for reference and for sample implementation of C1QueryFrame custom editors and other features, wrapped up in an ActiveX control. Its code can serve as a source of useful techniques. You will find it especially useful in implementing custom editing, see Custom Editing and Lookup.

C1QueryUI provides custom editing for data fields with Microsoft Date-Time Picker control, numeric fields with a customized Text control, boolean fields with a combo box. It also has a SetLookup method enabling the user to pick a value from a lookup combo box based on a database table.

See an example of using C1QueryUI control in Tutorial 5.

To use the C1QueryUI control, you must register it:

REGSVR32 C1QUERY80UI.OCX

You must have Visual Basic runtime DLL installed on your computer in order to use the C1QueryUI control.

A C1QueryUI control must be attached to a C1Query control by setting its SchemaControl property to the name of the C1Query control.


Tutorials and Samples

The product contains eight tutorials helping you master ComponentOne Query. We recommend that you start learning C1Query with reading and experimenting with tutorials. See Tutorials for detailed step-by-step instructions. Tutorial products are located in the TUTORIALS directory.

ComponentOne Query also comes with sample projects demonstrating different programming techniques, located in the SAMPLES directory.


Tutorials

Eight tutorials are presented here to help you master ComponentOne Query. The tutorials assume that you are familiar with programming in Visual Basic and have a general knowledge of databases and how to use ADO/OLE DB data sources with bound controls. The tutorials provide step-by-step instructions and require no prior knowledge of ComponentOne Query. By following these instructions, you will be able to create projects demonstrating a variety of ComponentOne Query features. You will also get a good sense of what ComponentOne Query can do and how to do it.

We encourage you to run the tutorial projects in Visual Basic and experiment with your own modifications. This is the best and quickest way to learn how to realize the full potential of ComponentOne Query.

The tutorials use the standard simple Access database NWIND.MDB included in Microsoft Visual Basic. The database is not provided with ComponentOne Query, you need to have it already installed on your computer. The tutorials assume this database is located in

C:\Program Files\Microsoft Visual Studio\VB98\Nwind.mdb

If your database is located in a different directory, you can manually modify the tutorial files, or copy the database file to the required directory.

We also assume that three ActiveX controls are included in all projects: ComponentOne Query Control 8.0 (C1Query, C1QueryFrame), Microsoft DataGrid Control 6.0 (OLEDB) (DataGrid), and Microsoft ADO Data Control 6.0. To add a control to your project you must select Components... from the Project menu to display the list of available components. Check the box representing the desired control, then press the OK button. The control icons are added to the Visual Basic toolbox.

Tutorial 1 - Using C1Query in DataSource Mode

Tutorial 2 - Using C1Query Schema Designer

Tutorial 3 - Query Result Fields in C1QueryFrame Control

Tutorial 4 - C1Query Schema Features

Tutorial 5 - Using the Sample User Control C1QueryUI

Tutorial 6 - Customizing the User Interface With Templates

Tutorial 7 - Customizing the User Interface With Scripts

Tutorial 8 - Using C1Query engine with non-C1Query user interface


Tutorial 1 - Using C1Query in DataSource Mode

In this tutorial, you will see how easy it is to add ad hoc query functionality to an application using C1Query DataSource mode. In this case, C1Query and c1QueryFrame controls can be used “as is”, in a very straightforward way. You don’t need to specify a schema or any other settings. You will also see in this tutorial how the end user interacts with C1Query at run time.

Step 1.

Start a new project.

Step 2.

After adding the C1Query and C1QueryFrame controls to the toolbox, place the following controls on the form as shown in the figure: a C1Query control (C1Query1), a C1QueryFrame control (C1QueryFrame1), a Microsoft ADODC control (Adodc1), a Microsoft DataGrid control (DataGrid1) and a command button (Command1).

Step 3.

Connect the C1QueryFrame1 control to C1Query1 by setting the C1QueryFrame1 SchemaControl property to C1Query1.

Step 4.

Connect the C1Query1 control DataSource property to the data source Adodc1.

Step 5.

Set the FilterMode property of the C1Query1 control to True.

Step 6.

Connect the Adodc1 control to the database, specifying, in its Property Pages or in the Visual Basic Properties window. Set Adodc1 control ConnectionString to:

Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Program Files\Microsoft Visual Studio\VB98\Nwind.mdb;Persist Security Info=False.

Set the Adodc1 CommandType property to 2 – adCmdTable and the RecordSource property to Orders.

Step 7.

To show the query results, connect the DataSource property of the DataGrid control to Adodc1.

Step 8.

Add the following code to the Click event of the command button:

C1Query1.BuildSQL

Adodc1.Recordset.Filter = C1Query1.ClauseWhere

Step 9.

Run the program. Enter a query in the C1QueryFrame control (shown on the figure):

Change all to any : click all and select any from the menu (connective menu) that opens on click.

Press the menu button in the control (the ellipsis button) or the right mouse button. That will open an action menu (main menu). Select Add a new elementary condition.

In the newly added condition click the blank space to the left of is equal to and select OrderDate from the field menu that opens on click.

Change is equal to to is greater than or equal to : click is equal to and select greater or equal from the menu (comparison menu).

Enter the date: click the blank space to the right of is greater than or equal to and type 1/1/96 in the text box that opens on click.

Press the menu button in the control (the ellipsis button) or the right mouse button. That will open an action menu (main menu). Select Add a new complex condition. Select the newly created complex condition (make it current) by clicking on it or with the ArrowDown key.

Add two elementary conditions under the newly created complex condition, using the main menu’s Add a new elementary condition item, as above.

Specify field names (ShipCity, ShipCountry) and values (London, UK) in the newly created conditions, using the instructions above.

Step 10.

Press the command button. You will see the result of the query displayed in the data grid.

Using C1Query in DataSource mode is very easy and straightforward, because you do not need to specify database schema, all the schema (fields) information is retrieved automatically from the data source. However, this mode cannot be used for queries that span multiple database tables. For example, if your users need to query Customers and OrderDetails tables in addition to the Orders table, and all that should be possible in a single query with no predetermined structure (so it’s up to the user which tables to include in a query), then you need more advanced capabilities of C1Query that are presented in the following tutorial.


Tutorial 2 - Using C1Query Schema Designer

Tutorial 2 – Using C1Query Schema Designer

In this tutorial, you will see how C1Query enables end users to pose queries spanning multiple database tables, and learn how to use the Schema Designer to specify a schema describing the database, its tables and inter-table relationships.

Step 1.

Repeat steps 1–3 of Tutorial 1, or just copy the Tutorial 1 project to another directory (if you copied the project, return the C1Query1 control FilterMode property setting to its default: False and clear the DataSource property).

Set the C1QueryFrame1 control FullFieldNames property to True.

Step 2.

Add one more Command button to the form. Change the caption of the first button to “Apply Query”, the caption of the second button – to “Show SQL”. Add the following code to the buttons’ Click event:

Private Sub Command1_Click()

OK = C1Query1.BuildSQL

If OK Then

Adodc1.CommandType = adCmdText

Adodc1.RecordSource = C1Query1.SQL

Adodc1.Refresh

Set DataGrid1.DataSource = Adodc1

End If

End Sub

Private Sub Command2_Click()

C1Query1.BuildSQL

MsgBox C1Query1.SQL

End Sub

Step 3.

Press the right mouse button over the C1Query1 control and select Schema Designer from the context menu. ComponentOne Query Schema Designer will open.

Step 4.

In the Schema Designer, select Import database structure from the Schema menu. That will open the Import Wizard dialog.

Step 5.

In the Import Wizard dialog, specify the connection string to connect to the NWIND.MDB database. Use the standard DataLink Properties dialog that can be opened by pressing the ellipsis button to the right of the connection string edit box, or just enter the following string:

Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Program Files\Microsoft Visual Studio\VB98\Nwind.mdb;Persist Security Info=False

Step 6.

Press the Next button. On the Import Wizard’s second step, press the “>>” button moving all table names from Available tables to Create views. Press Finish. This will create a schema based on the database structure information.

Step 7.

Now take some time to explore the schema. You can see that a schema is created, three palette windows on the sides: Folders, Views and Relationships, originally empty, are now filled with information. You can double click on objects in these palettes, opening editors (designers) for each object.

Step 8.

For each database table, there is a view in the imported schema. By default, a C1Query view is essentially the same as a database table, but, in general, you can create multi-table views and add other enhancements – see Tutorial 4.

For each database table, there is also a folder in the imported schema. Folders form a layer between the end user and database structure. They isolate the user from cryptic field names and other complexities of database structure. By default, after import, folders represent views (which, in their turn, represent database tables), folder names and field names are simply table names and database field names. However, you can rename them afterwards, and rearrange the folders to present a consistent business view of the data to the user. See Tutorial 4 for examples.

You also see relationships joining database tables together. These relationships were generated during import, from foreign key constraints present in the database. You can modify the relationships later, if necessary.

Step 9.

Run the program and experiment with various queries that you can now formulate. See Tutorial 1 for instructions how to interact with a C1QueryFrame control creating a query.

You are now able to formulate queries spanning multiple tables. For example:

C1QueryFrame shows field names qualified with table name because we set its FullFieldNames property to True.

Step 10.

Applying your queries, try pressing the Show SQL button to see SQL statements generated by C1Query.

In this tutorial, you saw the C1Query engine at work. In the following tutorials you will learn how to customize its behavior and user interface.


Tutorial 3 - Query Result Fields in C1QueryFrame Control

Tutorial 3 – Query Result Fields in C1QueryFrame Control

In this tutorial, you will learn how to attach two C1QueryFrame controls to a C1Query control. One of them manages filter conditions, the other – result fields, with optional sort and aggregation function.

Step 1.

Start a new project.

Step 2.

Place the following controls on the form as shown in the figure: a C1Query control (C1Query1), two C1QueryFrame control (C1QueryFrame1,2), a TabStrip control (add reference to Microsoft Windows Common Controls to the project), Microsoft ADODC control (Adodc1), a Microsoft DataGrid control (DataGrid1) and two command buttons (Command1,2).

Step 3.

Set C1QueryFrame1 control SchemaControl property to C1Query1 and the ContentsType property to 2 – c1qResultFields.

Set C1QueryFrame2 control SchemaControl property to C1Query1 and the ContentsType property to 2 – 2 – c1qConditions.

Set Adodc1 control ConnectionString to Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Program Files\Microsoft Visual Studio\VB98\Nwind.mdb;Persist Security Info=False

Step 4.

Specify the schema for C1Query1, repeating steps 3-8 of Tutorial 2.

Step 5.

Add the following code managing visibility of the C1QueryFrame controls on TabStrip1:

Private Sub Form_Load()

C1QueryFrame1.Visible = True

C1QueryFrame2.Visible = False

End Sub

Private Sub TabStrip1_Click()

C1QueryFrame1.Visible = TabStrip1.SelectedItem.Index = 1

C1QueryFrame2.Visible = TabStrip1.SelectedItem.Index = 2

End Sub

Step 6.

Add the following code to the buttons’ Click event:

Private Sub Command1_Click()

OK = C1Query1.BuildSQL

If OK Then

Adodc1.CommandType = adCmdText

Adodc1.RecordSource = C1Query1.SQL

Adodc1.Refresh

Set DataGrid1.DataSource = Adodc1

End If

End Sub

Private Sub Command2_Click()

C1Query1.BuildSQL

MsgBox C1Query1.SQL

End Sub

Run the Program and Observe the Following:

Now you can specify conditions in the Conditions tab, and result fields in the Fields tab. The C1QueryFrame1 control with ContentsType = 2 – c1qResultFields allows the user to specify result fields and, for each field, optional sort and aggregation function.


Tutorial 4 - C1Query Schema Features

Tutorial 4 – C1Query Schema Features

In the previous tutorials, you did not use most of the features of C1Query schema, you only imported a schema from database and used it as is.

In this tutorial you will learn how to use C1Query Schema Designer to customize user queries. You will create a custom folder structure to hide the complexities of database structure from the users. You will also explore some more advanced capabilities of C1Query schema views, such as multi-table views and calculated fields.

Step 1.

Repeat steps 1–6 of Tutorial 3.

Step 2.

Press the right mouse button over the C1Query1 control and select Schema Designer from the context menu. ComponentOne Query Schema Designer will open. In Schema Designer, connect to the database, pressing the Connect to database button on the Tables palette, or selecting Connect to database from the Schema menu. When you press OK in the Connect to database dialog, the Tables palette is populated with the list of all database tables and their fields.

Step 3.

Remove all folders from the Folders palette except three: Customers, Order Details and Orders. To remove a folder, select it and choose Remove from the context menu or press the Delete key.

Step 4.

Rename the Order Details folder to Order Items. To rename an object, select it and choose Rename from the context menu or click on it twice with an interval.

Step 5.

Expand the Order Items folder and change the order of fields in it using drag and drop (no specific order is required).

Step 6.

Add the Products table to the Order Details view, making it a multi-table view consisting of two tables: Order Details and Products. To add a table to a view, drag the table from the Tables palette and drop it on the view in the Views palette.

Step 7.

Open the View Designer window by double-clicking the Order Details view in the Views palette. In the View Designer, select the Products table (added to the view on step 6). Here you must join the Products table to the Order Details table (main table). Press the New Condition button that will open a New join condition dialog. Select OrderDetails.ProductID in the left combo box and Products.ProductID in the right combo box. Press OK. The join condition will be added to the list box:

OrderDetails.ProductID = Products.ProductID

Step 8.

Add a calculated field ExtendedPrice to the Order Details view. Use the Add button on the top of the View Designer. For the newly added calculated field, specify Name: ExtendedPrice, Type: Currency, Expression:

[Order Details].[UnitPrice] * [Order Details].[Quantity] * (1 - [Order Details].[Discount])

Step 9.

Add two folder fields to the Order Items folder: ProductName and ExtendedPrice. To add the fields, open the folder for editing by double-clicking the folder in the Folders palette, and add the fields using the Add button on the top of the Folder Designer. Select the fields from the menu that opens when you press the Add button. The menu shows all view fields in submenus organized by view name. The ProductName field is in the Products submenu, the ExtendedPrice field is in the Order Details submenu. Selecting a view field adds a new folder field to the folder. The new folder field represents the selected view field.

Run the Program and Observe the Following:

•

Field menu presented to the end user show the folders and fields as they were defined in the schema, not database tables and fields. This allows you to isolate your users from database structure, to present them with choices consistent with their business view of the data.

•

You can query ProductName and ExtendedPrice fields from Order Items folder, although they don’t belong to the Order Details table. Specify conditions for these two fields in the Conditions tab and press the Show SQL button to see the SQL statement generated by C1Query. It contains the calculated field expression and the join between Products and Order Details that you specified in the Order Details view.


Tutorial 5 - Using the Sample User Control C1QueryUI

Tutorial 5 – Using the Sample User Control C1QueryUI

In this tutorial, you will use the C1QueryUI control, an ActiveX control created in Visual Basic. Full source code for this user control is provided in the USERCTL subdirectory. We encourage you to peruse the C1QueryUI code and experiment with your own modifications of the code. it will help you to learn more about useful C1Query features, especially about custom editing.

The user control code can serve as a sample showing how to use C1QueryFrame events for custom editing, BeforeEdit, ShowCustomEditor, EndEdit, HideCustomEditor, on a Visual Basic form. You don’t necessarily have to build a user control to use this functionality, it can be programmed on a form, if you need to use it in a single form in your application, or on a form-by-form basis. See the SAMPLES directory for a sample showing how to program custom editing in a Visual Basic form.

Attention: Tutorial 5 will not work right after you install ComponentOne Query on your computer. To use the C1QueryUI control, you can either register the C1Query80UI.ocx file located in the installation directory, or compile the user control yourself using the Visual Basic project supplied in the USERCTL directory. You need to add a C1QueryUI reference to your project selecting ComponentOne Query UI Control 8.0. It may also be a good idea to create a project group containing the C1Query10UI.vbp project and the tutorial project, it will allow you to set breakpoints in C1Query10UI code and explore how it works..

Step 1.

Start a new project.

Step 2.

Place the following controls on the form as shown in the figure: a C1QueryUI control (C1QueryUI1), a C1Query control (C1Query1), two Microsoft ADODC controls (Adodc1,2), a Microsoft DataGrid control (DataGrid1) and two command buttons (Command1,2).

Step 3.

Set C1QueryUI1 control SchemaControl property to C1Query1.

Set Adodc1 control ConnectionString to:

Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Program Files\Microsoft Visual Studio\VB98\Nwind.mdb;Persist Security Info=False

Set the Adodc1 CommandType property to 2 – adCmdTable and the RecordSource property to Customers

Step 4.

Specify the schema for C1Query1, repeating steps 3-8 of Tutorial 2.

Step 5.

Add the following code to the buttons’ Click event:

Private Sub Command1_Click()

OK = C1Query1.BuildSQL

If OK Then

Adodc1.CommandType = adCmdText

Adodc1.RecordSource = C1Query1.SQL

Adodc1.Refresh

Set DataGrid1.DataSource = Adodc1

End If

End Sub

Private Sub Command2_Click()

C1Query1.BuildSQL

MsgBox C1Query1.SQL

End Sub

Step 6.

Add the following code to the form’s Load event:

Private Sub Form_Load()

C1QueryUI1.SetLookup "Customers.CustomerID", Adodc2, "", "CompanyName", "CustomerID", True

C1QueryUI1.SetLookup "Customers.CompanyName", Adodc2, "", "CompanyName", "", True

End Sub

Run the Program and Observe the Following:

•

A split bar divides the two C1QueryFrame panels. You can resize the panels by drag and drop on that split bar. This functionality is built in the C1QueryUI user control.

•

Try editing values for fields of different data types. For example: Orders.OrderData – date type, Products.Discontinued – boolean type, [Order Details].Discount – numeric type. Dates will be edited with a date-time picker control, boolean values – with a Yes/No combo box, numeric values will be edited in a TextBox with masking functionality, not allowing the user to enter invalid characters. This functionality is implemented in the C1QueryUI user control.

•

Select the Customers.CustomerID or Customers.CustomerName field in an elementary condition, then click on the right side of the condition. You will see a combo box filled with company names for user selection.

•

Examine the source code of C1QueryUI user control in the USERCTL directory and try modifying the properties of the controls used as custom editors (date-time picker, combo boxes, etc). Then compile the user control project, open the tutorial project again and see how the changes to custom editors immediately affect the editors in the tutorial.


Tutorial 6 - Customizing the User Interface With Templates

Tutorial 6 – Customizing the User Interface With Templates

In this tutorial, you will learn how to customize C1QueryFrame user interface. Every visual aspect of the UI can be customized. This includes colors, fonts and many other visual styles, words and phrases used in query display, composition of condition elements (left part, comparison, right part), and others.

Step 1.

Repeat steps 1–6 of Tutorial 3, or just copy the Tutorial 3 project to a new location. Schema and code are not important for this tutorial. All we want to show here is how to customize user interface. You can do it with any project containing a C1QueryFrame control. We suggest the one from Tutorial 3, but that does not really matter.

Step 2.

Press the right mouse button over the C1Query1 control and select Save Templates from the context menu. Save the default template file. This file contains all customizable settings (called template attributes) and scripts in their default form. Customizing template attributes, you will find it useful to consult with the default template file.

Step 3.

Set the DesignTimeTemplates property of both C1QueryFrame controls to False. This is necessary because our changed templates will use special tags (see 6 below) that will not allow them to work at design time. Without setting the property DesignTimeTemplates to False, we would see garbled display on the surface of C1QueryFrame control at design time (after Step 4).

Step 4.

Press the right mouse button over the C1Query1 control and select Load Templates from the context menu. Select the TEMPLATE.TPL file supplied in the tutorial directory.

Step 5.

We will not explain every individual attribute in the TEMPLATE.TPL file here. You can refer to Customizing UI with Templates for the description of template attributes. We will only make some explanations about the changes made in the template file.

All display styles are changed so that all elements, when not in focus, are always drawn as normal window text, instead of the default underscored blue text. The default 3D current row highlighting is suppressed. See the attributes ending with ‘Style’ (CMPInactiveStyle, CMPActiveStyle, CONNInactiveStyle, etc).

Empty element is shown as ___ instead of the default underscored asterisk (see EmptyDisplayText).

Instead of menu button, we now use a filled black triangle as a current row pointer. See the IMG tag in ComplexTemplate, ElemTemplate, and other template attributes.

Strings shown in elementary and complex conditions are changed. A complex condition now says “ALL of the following” where it was saying “Select records where <connective> of the following apply:” An elementary condition is displayed simply as <field> = <constant> where it was “Records where <field> = <constant>”, etc. This is accomplished by changing the attributes that serve as template for complex and simple conditions and result field items: ComplexTemplate, ElemTemplate, etc.

Condition and comparison menus are changed as well. For example, comparison operators are now shown as =, >, <,… The attributes responsible for this are ConnMenu and CompMenu.

Changing the ConditionMenu attribute, we made advanced elementary conditions unavailable. All elementary conditions are now simple:

<field> <comparison> <constant>

Step 6.

Add the following code to the Form’s Load event procedure:

C1QueryFrame1.TemplateUserData("AppDir") = App.Path + "\pointer.gif"

C1QueryFrame2.TemplateUserData("AppDir") = App.Path + "\pointer.gif"

This code ensures that <C1Q_USERDATA Index="AppDir"> tags used in the template file are substituted with the full path to the application directory, so our tutorial does not depend on the absolute path to the POINTER.GIF file.

Step 7.

Copy the POINTER.GIF file supplied in the tutorial directory to your project directory.

Run the Program and Observe the Following:

Try the new look and feel of the C1QueryFrame control, and notice that its functionality did not change although it has a different look and feel now.


Tutorial 7 - Customizing the User Interface With Scripts

Tutorial 7 – Customizing the User Interface With Scripts

In this tutorial, you will learn how to customize C1QueryFrame user interface even further. Using C1QRender script, you can change the display layout completely. In this tutorial we will write a script making a query look as a formula with parentheses instead of the default row outline. User interaction with such query remains fully functional although its layout is completely changed.

Step 1.

Repeat steps 1–8 of Tutorial 2, or just copy the Tutorial 2 project to a new location. Schema and code are not important for this tutorial. All we want to show here is how to customize user interface with a script. You can do it with any project containing a C1QueryFrame control. We suggest the one from Tutorial 2, but that does not really matter.

Step 2.

Set the ManualRender property of the C1QueryFrame1 control to True, to enable C1QRender script. See Script attribute: RenderScript for details about defining display layout via scripting.

Step 3.

Press the right mouse button over the C1QueryFrame1 control and select Load Templates from the context menu. Select the TEMPLATE.TPL file supplied in the tutorial directory.

Run the Program and Observe the Following:

Now, this is a really new look and feel! Add some conditions (pressing the right mouse button invokes the control’s menu) and you will see that they now look like parts of a formula, with parentheses and logical operations:

Þ

Try editing constant values, applying queries, etc. You see that the control’s functionality did not change although it now has a completely different display layout.


Tutorial 8 - Using C1Query engine with non-C1Query user interface

Tutorial 8 – Using C1Query engine with non-C1Query user interface

In this tutorial we will make the ultimate customization of C1Query user interface: replace it completely with an interface built with standard Visual Basic controls, without C1QueryFrame. Still, the C1Query engine, the C1Query control can be used to generate SQL statements, although the user interface is built with other means.

Step 1.

Open Tutorial 8 project (its default location is \Program Files\ComponentOne\Query 8.0\tutorials\Tutorial08). You see that C1QueryFrame1.Visible is set to False. We don’t use C1QueryFrame user interface, our UI is built with standard Visual Basic controls: list boxes, combo boxes and an edit box. We use a C1Query control in the project, with schema imported from the sample database, NWIND.MDB, as in Tutorial 2.

Step 2.

Look at the FillQueryFrame procedure. It uses C1QueryFrame object model, the AddItem method and properties of the Item object to fill the C1QueryFrame1 control with condition items specified by the user in the Visual Basic UI controls. Once C1QueryFrame1 is filled with data representing the user query, we call C1Query1.BuildSQL to generate the SQL statement.

Run the Program and Observe the Following:

Add some conditions with the “Add to query” button and press Show SQL and/or Apply Query. You see how C1Query engine generates SQL statements based on the data supplied from other Visual Basic controls.


Simple Queries - DataSource Mode

Simple Queries – DataSource Mode

ComponentOne Query can be used in two modes:

•

For ad hoc queries limited to a single recordset, use DataSource mode described in this chapter. It is the easiest way to implement ad hoc query functionality. In this mode, you don’t need Schema Designer. This mode is limited in that your queries cannot span multiple tables.

•

For ad hoc queries spanning multiple tables, leave the DataSource property empty and define a schema using Schema Designer.


Easy Implementation of Simple Ad Hoc Query Functionality

Using a C1Query control in DataSource mode allows the developer to add ad hoc query functionality to an application in a very simple and straightforward way, without invoking schema designer and creating a schema. In fact, ad hoc functionality can be implemented simply by dropping two controls on a form and setting one property. In this case, however, the C1Query engine is restricted to filtering a single recordset. Queries cannot span multiple tables.

Setting the C1Query DataSource property to a valid ADO/OLE DB data source (such as a ComponentOne True DataControl, an ADODC control, or a DataEnvironment command) activates the DataSource mode. Attached C1QueryFrame controls show the selection of fields according to the field structure of the DataSource recordset. Once the user has specified a query in C1QueryFrame controls, calling the C1Query.BuildSQL method will build the corresponding filter condition.

In most cases, you will use DataSource mode in conjunction with filter mode, setting the C1Query.FilterMode to True. If FilterMode=True, C1Query generates an ADO Filter condition in response to a BuildSQL method call. This condition can be retrieved from the C1Query.ClauseWhere property and assigned to the DataSource recordset (or another ADO recordset), thus restricting the set of rows to only those satisfying the query criteria. When FilterMode=True, C1Query uses ADO syntax rules for the Filter property. You can also use the C1Query control with FilterMode=False, in which case it uses regular SQL syntax. Use C1Query in DataSource mode with FilterMode=False if you want to create an SQL statement’s WHERE condition rather than ADO Filter condition. In this case, you can retrieve the resulting WHERE condition from the C1Query.ClauseWhere property, and also, if needed, you can retrieve ORDER BY and GROUP BY clauses from ClauseOrderBy, ClauseGroupBy. Properties SQL, ClauseSelect and ClauseFrom do not have meaningful values in DataSource mode.

Both FilterMode=True and FilterMode=False are enabled in DataSource mode as well as when DataSource is empty (the regular, schema-governed mode of operation of a C1Query control).


Customizing the DataSourceFields Collection

A special collection property, C1Query DataSourceFields enables you to customize the set of fields exposed to the end user in DataSource mode. It consists of Field objects. If the DataSourceFields collection is empty at startup time or on setting the DataSource property, it is filled automatically with Field objects retrieved from the DataSource recordset. If you need to perform this action in code, retrieve fields from the DataSource recordset and fill the DataSourceFields collection, call the RetrieveFieldsFromDataSource method.

Modifying the DataSourceFields collection changes the selection of fields available to the end user in the attached C1QueryFrame controls. Field.FullFolderName determines the name by which the field is exposed to the user. Field.DataSourceName determines the field in DataSource to which this field is associated. Setting these properties in code allows you to rearrange the fields order and even associate more than one field with a single DataSource field. It is also possible to hide a field from to the user, setting its DataSourceFields property to empty string. In this case the read-only property Field.Exists is set to False.

The Alias property determines the name by which this field appears in the generated Filter condition or in the SQL WHERE condition. By default, it is the same as Field.FullFolderName.


Schema Designer

ComponentOne Query uses schema as the description of your database structure, fields and folders that you want to expose to the end user, relationships between tables (views), and other information. Every C1Query control stores its own schema. You create and modify the schema at design time, using the C1Query schema designer. It is also possible to modify schema at run time, see Modifying Schema and Field List at Run Time.

All necessary information is stored in the schema, so ComponentOne Query does not have to connect to the database to perform its tasks of interacting with the user and generating SQL statements.

To start the schema designer, select Schema Designer from the context menu of a C1Query control.

The schema designer can also be started as a standalone application: C1QSCHD1.EXE.

A schema can be saved in a file and restored from a file, selecting Save and Open in the File menu of the schema designer).

Connecting to Database and Importing Database Structure

Views

Folders

Relationships

Extensions


Connecting to Database and Importing Database Structure

Normally, a schema is initially created by importing it from a database structure. Use the Import database structure menu item from the Schema menu, and follow the Import Wizard to connect to the database and specify the objects that you want to import and other parameters. A schema will be created complete with views, folders and relationships.

To clear the existing schema before importing a new one, select Clear schema from the Schema menu.

After database import, the Tables palette window shows the list of all tables in the database.

When you start schema designer, it is not connected to the database, unless you import database structure or explicitly re-connect to the database. This allows you to work in disconnected environment when you modify an existing schema. If you need to connect to the database (for example, to add a new table to the schema), select Connect to database in the Schema menu, or press the Refresh Tables button in the tables palette. Once you successfully connected to the database, the Tables palette shows the list of all tables in the database.


Views

In ComponentOne Query, the main unit of information stored in a database is called a view. This concept is different from the usual database view, although there are certain similarities. To distinguish a C1Query view from a database view, we will sometimes refer to it as a schema view.

In simple cases, a schema view is just a database table. You will see schema views in one-to-one correspondence with database tables in a schema just imported from a database structure. Unless you need the advanced functionality of multi-table views or multiple views representing a single table, you can leave it at that and just consider the word «view» synonimous to the word «table».

To edit a view, double click on a view in the Views palette, or select a view and choose Edit from the context menu. A View Designer window will open as an MDI child. You can have multiple designer windows open simultaneously in the schema designer. To add a new view to the schema, use the Add new view button on the Views palette.

A single table can be represented by multiple views. In this case, when two views refer to a signle table, and both views are used in a user query, the generated SQL statement will include this table twice, with different aliases. This is useful in special situations, for example, in representing self-joins, as with the «is managed by» relationship between the records in an Employee table.

Views can contain calculated fields. A calculated field has an SQL expression which is used in the generated SQL statement. In an expression, use SQL syntax for functions and operators, and the following syntax for table fields:

[table_name].[field_name]

For example,

[Order Details].[UnitPrice] * [Order Details].[Quantity] * (1 - [Order Details].[Discount])

To add a calculated field to a view, use the Add field button on the top of the View Designer, or select New field from the context menu. Specify the field's Name, Type (and optionally, Size, for fixed length string fields), and the Expression.

You can also specify an arbitrary SQL condition for a view in the Advanced tab of the View Designer. This optional SQL condition will be included in the WHERE clause of the generated SQL statement. To reference view fields in the SQL condition, use the same syntax as in calculated field expressions described above.


Multi-Table Views

After importing a database structure, you can create multi-table views. To add a table to a view, drag a table from the tables palette and drop it on a view in the Views palette or use the Add table button in a View Designer window.

Creating a multi-table view, you can represent a closely related group of tables as a single view, a single information unit. For example, you may need to add the ProductName field to the OrderDetails table, but the ProductName field is stored in another table, Products. Then you can add the Products table to the OderDetails view, so it will become a multi-table view with two tables: OrderDetails and Products. The OrderDetails table is the main table, the Products table is connected (joined) to it with the following join condition: OrderDetails.ProductID = Products.ProductID.

By selecting a table node you can review/modify properties that specify how multiple tables are joined to form a single view: Required, Join type and Conditions. The first table, being the main table of the view does not have these properties. The order of tables in a view is essential: every table except the first one is joined to the preceding tables.

Using a multi-table view in a query includes the view tables into the generated SQL, with joins specified in the View Designer. By unchecking the Required check box, you can make a table optional, that is, included in the generated SQL statement only if its field are directly specified or indirectly referenced in the user query. By default, all tables of a multi-table view are required, meaning that they are all included in the generated SQL once a field belonging to this view is requested in the user query.

Join conditions joining a table to the preceding tables are shown in the Conditions list box. You must specify at least one join condition for every table in a view except the first (main) table. To add a join condition, use the Add button to the left of the Conditions list box. Use the Edit and Remove buttons to edit/remove a join condition. The Join type combo box controls the type of the join connecting a table to the preceding tables: inner, outer or full join.


Join Groups

When a user query contains multiple tables (views), C1Query needs additional information to join these tables together in a single SQL statement. This information is usually provided by relationships. A relationship defines joins between two or more views, see Relationships.

However, in simpler cases you can use an easier alternative to relationships: join groups.

Often, when you need to join two tables, the join is established simply by putting into correspondence two (or more) fields, one from the first table, the other from the second table. Usually, such fields have the same name.

Instead of using relationships, you can specify join groups for certain view fields. Use the Join groups tab in the View Designer window to specify the join group name for a field. Usually, join group name is just the name of the field. However, you can use any string as a join group name.

Caution: Although join groups are intended for simpler cases, you must exercise caution using them. The alternative mechanism of joining views, Relationships, gives you more control over the way C1Query joins views in queries. Using join groups, you can inadvertently allow C1Query to join views that you did not mean to be joined, if you assign their fields to the same join group by mistake. Therefore, it is recommended to avoid using join group unless you thoroughly understand how they work.

Two fields with identical non-empty join group names can be joined by C1Query even if there is no relationship joining their corresponding views.

More exactly, there are two join group names for each field: foreign join group and primary join group. Two fields, t1.f1 and t2.f2, can be joined together by the C1Query SQL generation algorithm, if the foreign join group name of t1.f1 equals the primary join group of t2.f2. The resulting SQL statement will be

…FROM… t1.f1 LEFT JOIN t2.f2 ON t1.f1 = t2.f2…

So, if you want to join two views using a common field (actually, two fields, a field in the first view and a field in the second view), set the first (main) field's foreign join group name and the second (dependent) field's primary group name to the same string. Setting both primary and secondary join group names for a field, you allow that field to be used both on the main (left) and on the dependent (right) side of a join.

There is also a combo box in the Advanced tab: Use join groups as. This combo box specifies the types of the joins generated by the join groups of the view's fields when they are used on the «dependent» (right) side of a join. It can be either inner or outer join.


Folders

Folders define the set of fields exposed to the user at run time. They are called folder fields. The rationale for a separate definition of folder fields is to shield the user from the complexities of database structure. Folders form a hierarchical structure with unlimited nesting, so you can organize field names and containment according to your business domain. End users will see friendly names and hierarchical structure, not necessarily related in any way to the structure in which the fields are organized in database tables.

Each folder field represents a single view field, but there are no restrictions on how you organize folder fields into folders. A schema imported from database structure contains a single folder for each table. After you have imported the schema from database, you can add new folders, delete existing folders, move fields between folders, change fields order in a folder, move folders around, changing their order and making one folder a descendent of another.

Folders are shown to the end user as sub-menus in the field selection menu.

In some cases, it may be preferable not to have sub-menus, but rather show all available fields in a single menu. This can be done placing fields in the root folder. To move a folder field or a whole folder to the root folder, drag it to the left side of the palette, and drop it outside the folders.

To edit a folder, double click on a folder in the Folders palette, or select a folder and choose Edit from the context menu. A Folder Designer window will open as an MDI child. You can have multiple designer windows open simultaneously in schema designer.

To add a new folder to the schema, use the Add new folder button on the Folders palette. To add a view field to a folder, drag a field from a View Designer window to the Folder Designer window or to the Folders palette and drop it on a folder.

To change the order of fields, use drag and drop in a Folder Designer window or in the Folders palette. With drag and drop, you can also move fields between folders.

To change the hierarchy structure of folders, that is, to make one folder a child of another or to change the parent-child relationships, drag the child folder in the Folders palette and drop it on the desired parent. Dropping a sub-folder or a field on the left side of the palette, you can move it to the root, see above.

To change the order of folders, use drag and drop in the Folders palette holding the Control key when you drop the folder.

To rename a folder, choose Rename from the context menu.

To rename a field, you can either use Rename in the context menu, or edit the Name property of the field in the Folder Designer. This name will be shown to the end user in the field selection menu and in the query.

You can also specify the Alias name of a field, then it will be used as the field’s alias in generated SQL statements. By default, if you leave the Alias name empty, the field’s alias is the same as its Name. See also the UseNameAsFieldAlias property.


Field Lookup List

A special Lookup tab in the Folder Designer window allows you to specify lookup value lists for fields. Lookup values will be used at run time to allow the end user to choose a value from a list of predefined values. To enable lookup for a field, check the Use lookup values check box. Then you can specify a list of values in the grid below. You also have an option of leaving this grid empty and specifying the lookup list dynamically, at run time, in the LookupValues event, see Lookup Value Lists for details.

For each lookup value, you can specify the Value and, optionally, ValueText. ValueText determines the string representation of the value in the user query, if you need a non-default string representation. The Value column is the actual value used in the generated SQL statement. See Lookup Value Lists for details.


Relationships

When a user query contains multiple tables, C1Query needs some additional information to join these tables together in a single SQL statement. This information is provided by relationships. A relationship defines joins between two (in the case of a binary relationship, the common case) or more (in the case of a ternary or higher relationship, an advanced case) views.

As an alternative to using relationships, you can use join groups. Join groups allows you to join views in a simpler manner, but they provide less control and can be error-prone if used without caution.

Importing database structure from the database, C1Query creates join relationships based on the foreign key constraints present in the database. In many cases, this will suffice to join views (tables) together in SQL generation, and you will not need to modify the imported relationships. In more involved cases, when the database does not provide enough foreign key information, or when you need to customize the relationships, you can modify existing relationships and add new ones.

To edit a relationship, double click on it in the Relationships palette, or select a relationship and choose Edit from the context menu. A Relationship Designer window will open as an MDI child. You can have multiple designer windows open simultaneously in schema designer.

To add a new relationship to the schema, use the Add new relationship button on the Relationships palette.

Binary Join Relationships

Join Type

Ternary and Higher Order Relationships

Condition Relationships


Binary Join Relationships

In a Relationship Designer window, choose the two views you want to join in the corresponding combo boxes. Use the Add, Edit and Delete buttons to modify the join conditions. Editing a join condition in the Join Condition Editor dialog, choose a field of the first view in the Field1 combo box, a field of the second view in the Field2 combo box, and the join comparison operator in the Operator combo box (in most cases you will use the equality '=' operator in joins). In advanced cases where you need an expression in a join, you can check the Use expression in right part check box and enter an expression instead of Field2. In an expression, use SQL syntax for functions and operators, and the following syntax for fields:

[view_name]![table_name].[field_name]

In even more advanced cases, if you need to join tables using a more complicated condition that cannot be expressed in terms of simple joins between fields of the participating views, check the Use SQL condition check box. In this case the join is just a single string that represents the entire SQL condition. Use regular SQL syntax in the condition, and the same syntax for fields as above:

[view_name]![table_name].[field_name]


Join Type

The join type combo box allows you to specify one of the four join types: inner, outer, full and two-way outer. Inner, outer and full joins have their usual SQL meaning.

•

Inner join (supported by all databases) means that only matching records present in both views (tables) will appear in the result.

•

Outer join (supported by most but not all databases) means that records of the first view (table) will apear in the result even if there are no matching records in the second view (table). First is the view selected in the left combo box, second – the one selected in the right combo box.

•

Full join (unsupported by some databases) means that records from both tables will appear in the result, regardless of whether or not they have matches in the other table.


Two-Way Joins

A two-way outer join is an outer join where C1Query can change the order of the participating views (tables). The default order in an outer join is:

A LEFT OUTER JOIN B

where A is the view in the left combo box, and B is the view in the right combo box. Here each of the two, A and B, corresponds to a single table if the corresponding view is a single table view, and to all the constituent tables if it is a multi-table view.

If the selected join type is outer, inner or full, C1Query will always apply this join in the specified order. For inner and full joins the order does not make any difference, changing the order produces an SQL statement equivalent to the original one, always yielding the same result. For outer joins, however, the order is sometimes essential.

In some cases, it is desirable to allow the end user to specify the order explicitly. In these cases, the order of a join may depend on the end user query, it is determined by the order of result fields with non-empty sort (ascending or descending). For join relationships with two-way outer joins, C1Query takes the sort order into consideration when it generates the SQL statement. It attempts to add tables to the SQL statement in the order specified by the end user. Then the order of tables in the generated FROM clause reflects the order of result fields with non-empty sort in the user query. When this is impossible, C1Query generates the best possible approximation, where sorted fields occurring earlier in the list of result fields take precedence over fields occurring later.

Considering the necessity of two-way outer joins, keep in mind that in most cases the order of tables in the FROM clause does not make any substantial difference, it is only important in special cases. It does not make any difference with inner joins. And the sort conditions specified by the end user are always guaranteed to produce the correct sorting of the result, regardless of the join type. If you are not worried about the implications of changing the order of tables in the FROM clause, there is no need to be concerned about the join type.


Ternary and Higher Order Relationships

Ternary and higher relationships is an advanced feature of C1Query allowing you to exercise finer control over joins applied to three or more tables (views) appearing in a query.

In most cases, when three or more tables appear in a query, they can be joined by corresponding binary relationships between pairs of tables. Sometimes, however, joins between two tables may depend on which of the other tables is actually present in the query. In this cases, you may consider defining a higher order relationship. Select the Advanced (ternary or higher) radio button to indicate that a relationship is a higher order one.

A higher order relationship is applied only if all its constituent views are present in the query. The joins of a higher order relationship are specified in exactly the same way as in a binary relationship. The only differences are that you add views using the Add view button in the Relationship Designer (not in combo boxes, since there are more than two views), and there is a separate value in the join type combo box for every adjacent pair of views in the relationship.


Condition Relationships

Condition Relationships is an advanced feature of C1Query allowing you to specify a custom SQL condition instead or in addition to joins.

Condition relationships are not used to join tables when C1Query analyzes the set of tables used in a query and joins all these tables together. Only join relationships are used for that purpose. Condition relationships come into play later, when all tables are joined. They add their custom SQL conditions to the WHERE clause of the generated SQL statement.

Use the Add condition relationship menu item in the context menu or the Add relationship button to create a condition relationship.

In the Condition Relationship Designer window, specify the two (or more, in the case of a ternary or higher order relationship) views, and the text of the custom SQL condition.

In the SQL condition, use SQL syntax for functions and operators, and the following syntax for fields:

[view_name]![table_name].[field_name]


Extensions

Extensions is an advanced feature of C1Query schema. In most cases, you will find the default behavior satisfactory, without specifying extensions. In more complex cases, or when you need more control, you can use schema extensions in conjunction with the C1Query.ApplyExtensions property.

In many cases, two tables cannot be joined together directly, but they can be joined through a third table. For example, Customers and OrderDetails cannot be joined together without an intermediate Orders table. When all three tables, Customers, Orders and OrderDetails are present in a query, then they can be joined with:

Customers.CustomerID = Orders.CustomerID AND Orders.OrderID = OrderDetails.OrderID

But if only two of them, Customers and OrderDetails are present, C1Query will need to add the third table, Orders, to the query in order to complete it. This process is called query extension.

Extending a query, C1Query first applies schema extensions, and only if that does not help, performs autoextension, adding views to the query using a special algorithm. Both schema extensions (specified in the schema and autoextension) are applied only if enabled in the ApplyExtensions property setting.

Specifying a schema extension, the developer gives C1Query a direct indication that certain set of views can be extended, if necessary, by adding certain views to the query.

To add an extension to the schema, use the Add new extension button on the Extensions palette. To edit an existing extension, double click on it in the Extensions palette, or choose Edit from the context menu. An Extension Designer window will open as an MDI child. You can have multiple designer windows open simultaneously in schema designer.

Specifying an extension is very simple: just add some views to the left list box (Extend views) and to the right list box (Extend with). At run time, C1Query will add the views from the right list to a query, provided that all views from the left lest are already present, and that the query cannot be completed without extension. In our example, views on the left will be Customers and OrderDetails, and there will be a single view on the right: Orders.


Using C1Query Control to Generate SQL

C1Query control is the engine of ComponentOne Query. Its BuildSQL method generates SQL statements, allowing the generated SQL statement to be retrieved from the SQL property. A C1Query control stores the schema. Schema designer, a GUI application used to create and modify the schema stored in a C1Query control, can be launched from the C1Query context menu.

Generating SQL Statements

Changing Query Items for the Duration of SQL Generation

Including/Excluding Query Items in the Resulting SQL

Database-Dependent Aspects of SQL Generation

SQL Syntax Properties

Managing Query Extensions


Generating SQL Statements

To generate an SQL statement, call the BuildSQL method. It generates an SQL statement based on the information entered in the user query in C1QueryFrame controls attached to the C1Query control.

The BuildSQL method returns True if generation was successful. After successful generation, the generated SQL statement can be retrieved from the SQL property. Constituent clauses of the SQL statement can be retrieved from the properties ClauseSelect, ClauseFrom, ClauseWhere, ClauseOrderBy, and ClauseGroupBy.


Errors in SQL Generation

If generation fails, the BuildSQL method returns False. SQL generation can fail for the following reasons (for a complete list of possible errors, see Error Codes):

•

There is an error in the schema. Schema errors are detected in the schema designer when you save a schema or select Verify schema from the Schema menu. To avoid such errors, it is recommended that you correct all schema errors before using the control to generate SQL. Schema errors trigger the C1Query Error event in the C1Query control.

•

There is an error in the user query. For example, the field name has not been specified in a query item. Such errors trigger the Error event in the C1QueryFrame control where the incorrect item ha been found. To find out which item is responsible for the error, use the ErrorItemID property.

•

The user query contains fields that are unrelated one to another, there is no natural SQL statement including all these fields. This error triggers the Error event in the C1Query control. This error usually means that the user query is incomplete, can be completed by adding an additional field(s), usually from another folder, connecting the existing fields, or it may be the opposite: the user could mistakenly enter a field that does not relate to other fields in the query. If your schema is correct and contains enough relationships to connect all fields that are supposed to be connected, this error will occur only in situations where the user makes an obvious mistake, specifies a query that does not make sense. For details about relating fields to each other and managing the “unrelated fields” situations, see Managing Query Extensions. See also Relationships, Join Groups and Extensions in Schema Designer.

The Error event allows the programmers to intercept the error and replace the default error handling (message box) with one of their own.


Error Codes

See Errors in SQL Generation for description of possible errors in SQL generation. The following list describes all error conditions triggering the Error event, not only the errors occurring in SQL generation.

11

“Could not create XML DOM object. Make sure that Microsoft XML parser is properly installed.” This error occurs at startup if Microsoft XML parser cannot be found. C1Query depends on the XML parser for its functionality.

12

“Error loading XML file. The path may be incorrect or the file may not be a valid XML file.” This error occurs in the LoadSchemaFromFile method if the file does not exist or is not a valid XML file.

13

“Error parsing XML file. The schema file format is incorrect.” This error occurs loading a schema from file or loading a form, if the schema information is corrupted.

14

“Error saving schema file.” Physical error while saving schema in a file.

15

“Invalid schema format.” Occurs when schema information is corrupted or inconsistent with the current control version.

16-21, 28

“Schema error” Errors that can be detected by schema verification in schema designer.

23

“Selected fields are unrelated, cannot generate a valid query.” See Managing Query Extensions. See also Relationships, Join Groups and Extensions in Schema Designer. User error.

25

“Query is empty.” User error.

26

“Query with aggregation function contains non-aggregated calculated fields.” SQL does not support calculated fields (expressions) in GROUP BY. User error.

106

“More than one attached C1QueryFrame control with ContentsType=c1qCondition.” Programmer error.

107

“More than one attached C1QueryFrame control with ContentsType=c1qResultFields” Programmer error.

109

“No C1QueryFrame control attached. Use the C1QueryFrame.SchemaControl property.” Programmer error.

501

“Invalid data format.” Entered value does not satisfy the data format for the current field (numeric, date, etc). User error.

502

“Field not specified or invalid.” User left the field name empty in a condition. User error.

503

“Field not specified or invalid.” User left the field name empty in a result field. User error.

504

“Comparison operation not allowed for a field of this type”. Some comparisons are only allowed for specific types (for example, “contains” is only valid for strings). This error can only be caused by programmer’s intervention, since C1QueryFrame does not allow the user to select invalid comparison, unless it is done in code.

505

“Sort not allowed for a field of this type”. Some data types don’t support sorting. This error can only be caused by programmer’s intervention, since C1QueryFrame does not allow the user to select sort for these types, unless it is done in code.

506

“Function not allowed for a field of this type.” Some functions are only allowed for specific types (for example, SUM is only valid for numeric types). This error can only be caused by programmer’s intervention, since C1QueryFrame does not allow the user to select invalid function, unless it is done in code.

507

“Complex condition is empty, does not contain nested conditions.” By default, the presence of empty conditions in a user query is considered an error. User error.


Changing Query Items for the Duration of SQL Generation

To enable full control over the process of generating SQL statements, C1Query allows the developer to modify the collection of query items for the duration of SQL generation. Developers can modify the whole collection of query items modifying any property of any query item and also adding and removing items. This can be done in the following events: BeforeSQLGeneration, BeforeSQLGeneration and SQLGenerationItem.

All modifications to query items made in these events are temporary. They have effect only for the current SQL generation process. SQL generation is initiated when the BuildSQL method is called. After this method returns, all changes to query items made in the aforementioned events are retracted. This enables programmatic control over the SQL generation process without affecting the user query shown in C1QueryFrame controls.

Calling the BuildSQL method triggers the following sequence of events (assuming there are two C1QueryFrame controls attached to a C1Query control):

C1QueryFrame1.BeforeSQLGeneration

C1QueryFrame1.SQLGenerationItem for the 1st query item

C1QueryFrame1.SQLGenerationItem for the 2nd query item

...

C1QueryFrame2.BeforeSQLGeneration

C1QueryFrame2.SQLGenerationItem for the 1st query item

C1QueryFrame2.SQLGenerationItem for the 2nd query item

...

C1Query.BeforeSQLGeneration

BeforeSQLGeneration events can be used to modify the collection of query items as a whole, adding and deleting items. Note that it is not necessary to delete an item in order to exclude it from generation, you can set its Checked property to False instead.

The SQLGenerationItem event provides a simplified way of modifying query items. It is fired for every query item, so you don't need to navigate through query items to make modifications (which is necessary if you do it in BeforeSQLGeneration event). In most cases, it is sufficient to use the SQLGenerationItem event, write some simple code modifying a query item passed to that event. In more complicated cases, when you need to manipulate the query items collection as a whole, use BeforeSQLGenerationand BeforeSQLGeneration events.

For an example how to modify query items during SQL generation, see the SQLGenerationItem sample in the SAMPLES directory.


Including/Excluding Query Items in the Resulting SQL

Setting Checkboxes property to True, you will allow the end user to control which query items are included in the resulting SQL statement. In this case, every query item contains a checkbox. Checking it includes the item in SQL, unchecking it excludes the item.

Including/excluding items can also be done programmatically, using the Checked property and Checked (ItemID) property. The two properties have the same effect.

You can use the item's Checked property programmatically even if Checkboxes=False. The item will be included/excluded in SQL although there won't be visual indication in the form of a checkbox.


Database-Dependent Aspects of SQL Generation

Different databases use different SQL dialects, making it necessary for C1Query SQL generation to adjust its syntax rules to the database requirements. Even with the same database, you may need different formats depending on the current settings in your database.

Properties of a special object, C1Query.SQLInfo determine various parameters affecting the syntax of generated SQL queries, for various aspects of the SQL language that are database-dependent. C1Query fills these properties with default values suiting the database from which the schema was imported, for three OLE DB providers: Microsoft OLE DB providers for SQL Server, Access and Oracle. For other databases and OLE DB providers, it is the responsibility of the developer to set the appropriate values of these properties in code. See SQL Syntax Properties.

Another source of dependencies is representing literal (constant) values for different data types. Databases use different syntax for date, time and number values in SQL. As with general SQL syntax rules, C1Query tries to resolve this issue automatically for the three popular OLE DB providers, see above. But it may be necessary for the developer to intervene, if they use a different OLE DB provider, or have special settings in their database.

C1Query provides two levels of control over literal values in SQL. In most cases, you can use SQLInfo.FormatDate/FormatFloat/FormatTime properties. These are properties of the C1Query.SQLInfo object. Set these properties in code if their default values do not satisfy your database requirements. Their values are valid format strings as in the Visual Basic Format function. There are also two additional values:

Default

Values are formatted using the default Windows rules (as in Visual Basic function CStr), according to the current regional settings.

US Default

Values are formatted as in regional setting “English (United States)”.

Note: FormatDate/FormatFloat/FormatTime properties have effect only in Visual Basic application. When using C1Query in containers other than Visual Basic, you need to use the FormatLiteral event.

The FormatLiteral event gives developers full control over generating literal strings in the resulting SQL statement. If FormatDate/FormatFloat/FormatTime properties do not solve your formatting problems, you can use the FormatLiteral event to specify the text for every literal in the generated SQL statement dynamically. This event is triggered for every constant value in the user query. The Value argument gives you the value that needs to be formatted. If you set the Text argument before exiting the event procedure, the specified string is used for the formatted literal value in the resulting SQL statement.


SQL Syntax Properties

Properties governing syntax of the resulting SQL statement are assembled in a special SQLInfo object, C1Query.SQLInfo. These properties can be modified in code to tune SQL generation. They are mostly used to adjust to database-specific requirements, and there are also properties of general nature, such as Distinct, for example, used to modify the generated SQL.

SQL Statement Features

Database-Specific SQL Syntax

Formatting Literal Values

Database Limitations on SQL


SQL Statement Features

Distinct

If True, add the DISTINCT keyword to the SQL statement.

UseNameAsFieldAlias

If True (default), folder field’s Name is used as its alias in SELECT. If False, fields appear in SELECT with their database names only.


Database-Specific SQL Syntax

Syntax

Specifies the type of SQL syntax supported by the database, determining the syntax for outer and inner joins.

TableQuote

Quotation mark used to escape table names with blanks and special characters.

TableQuoteCriteria

Conditions under which a table name needs escaping (quoting).

FieldQuote

Quotation mark used to escape field names with blanks and special characters.

FieldQuoteCriteria

Conditions under which a field name needs escaping (quoting).

AddASToTableAlias

Whether to add the AS keyword before table alias.

StringLiteralQuote

Quotation mark used to enclose string literals.

DateTimeQuote

Quotation mark used to enclose date/time literals.


Formatting Literal Values

FormatDate

Format string for date values.

FormatTime

Format string for time values.

FormatFloat

Format string for floating point values.

FormatBooleanTrue

String representing boolean True value.

FormatBooleanFalse

String representing boolean False value.


Database Limitations on SQL

AllowExpressionInGroupBy

True, if the database allows calculated fields (expressions) in GROUP BY.

UseFieldAliasInOrderBy

If True, a calculated field (expression) can be represented in ORDER BY by its alias, otherwise, the full expression must be used in ORDER BY (or integer index, see UseIndexInOrderBy).

UseFieldAliasInGroupBy

If True, a calculated field (expression) can be represented in GROUP BY by its alias, otherwise, the full expression must be used in GROUP BY.

UseFieldAliasInWhere

If True, a calculated field (expression) can be represented in WHERE by its alias, otherwise, the full expression must be used in WHERE.

UseIndexInOrderBy

If True, the field’s integer index (its ordinal position in SELECT) is used in ORDER BY, instead of the field’s name.

CreateAliasForAggregatedField

If True (default), C1Query creates an alias for fields with aggregation. Example: alias Sum_of_Price for SUM(Price). You may have to set this property to False, if your database does not allow aliases for aggregated fields.

MaxNameLength

Determines maximum identifier length allowed in the database.


Managing Query Extensions

The ApplyExtensions property allows the developer to control how C1Query engine manages extensions: situations where, in order to complete a query, it is necessary to add some views to the query in addition to the views selected by the end user. Possible extensions can be specified in the schema, and there is also so called autoextension, applied by C1Query automatically, if allowed. For details, see Extensions in Schema Designer.

Possible values of the ApplyExtensions property are:

c1qExtensionsDisabled = 0

Don’t use any extensions, don’t add any views unless explicitly selected by the user.

c1qExtensionsEnabled = 1

Use extensions specified in the schema. This setting gives the developer full control over extensions, makes this process completely deterministic.

c1qAutoExtensionsRestricted= 2

(Default) Use schema extensions, and if they are not enough, use autoextension, that is, add any views that are necessary to the query, but the main view (the one to which all other views are joined) must be explicitly selected by the user. This setting is preferable in most cases. It allows C1Query to complete queries for the user, but does not allow query completion when participating views appear unrelated.

c1qAutoExtensionsUnrestricted= 3

Use schema extensions, and if they are not enough, use autoextension, that is, add any views that are necessary to the query, without restrictions. This setting gives C1Query full discretion over the extension process. All user queries will be completed, but some can produce unexpected results, because C1Query can add views to the query that the end user did not have in mind.

For example, the following queries issued against the standard sample database NWIND.MDB (see Tutorial 2), will succeed or fail (with error message “Selected fields are unrelated, cannot generate a valid query”) depending on the value of the ApplyExtensions property:

Customers.City = ‘London’ and OrderDetails.Discount > 0

•

With c1qExtensionsDisabled, this query will fail, since there is no relationship joining Customers and OrderDetails directly. These two tables are joined through a third table, Orders: Customers Orders OrderDetails.

•

With c1qExtensionsEnabled, this query will succeed if the schema contains extension (Customers, OrderDetails) (Orders).

•

With c1qAutoExtensionsRestricted or c1qAutoExtensionsUnrestricted, this query will succeed. C1Query will add Orders to the query, making the query complete. The main view here is OrderDetails, and it is already in the query, so the difference between c1qAutoExtensionsRestricted or c1qAutoExtensionsUnrestricted does not matter here.

Customers.City = ‘London’ and Categories.CategoryName = ‘Condiments’

•

With c1qExtensionsDisabled, this query will fail, since there is no relationship joining Customers and Categories.

•

With c1qExtensionsEnabled, this query will succeed if the schema contains extension (Customers, Categories) (OrderDetails, Orders, Products)

•

With c1qAutoExtensionsRestricted, but without the necessary extension in the schema (see above), this query will fail, since the main view, OrderDetails, needs to be added to the query, OrderDetails is not specified explicitly by the user.

•

With c1qAutoExtensionsUnrestricted, this query will succeed. C1Query will add all three missing views, OrderDetails, Orders, and Products to the query, making the query complete.


Developing a User Interface

ComponentOne Query user interface is provided by the C1QueryFramecontrol.

C1QueryFrame Control

Customizing User Interface

Creating Your Own UI

Using C1Query on the Web

Maintaining, Saving and Restoring Queries

Modifying Schema and Field List at Run Time

Accessing and Modifying Query Items

Custom Editing and Lookup

Customizing Functions and Comparison Operators


C1QueryFrame Control

C1QueryFrame control is responsible for user interface. It displays query conditions and result fields, and allows the end user to enter and edit them. Its ContentsType property determines whether a C1QueryFrame control displays filter conditions (resulting in the WHERE clause of the generated statement) or result fields (resulting in the SELECT part of the generated statement).

You can access individual query items (conditions and result fields) programmatically, using the C1QueryFrame.Item object, see Accessing and Modifying Query Items.

A C1QueryFrame control is associated with a C1Query control, “the engine”, via the SchemaControl property. You can associate either one or two C1QueryFrame controls with a single C1Query control. If there are two associated controls, one of them must display filter conditions, the other – result fields, according to their ContentsType property. If there is no C1QueryFrame control with result fields, C1Query generates a SELECT * statement, selecting all fields from the tables appearing in the query.

The value of the SchemaControl property is the Name of a C1Query control residing in the same form. Some environments, such as Visual C++, do not support the Name property. In this case, set the NameSubstitute property of the C1Query control to the name you want to reference it by in the C1QueryFrame controls. There are also environments (such as Delphi, for example) where the mechanism attaching C1QueryFrame controls to a C1Query control at design time won’t work. In such environments, you have to associate the controls at run time, setting the SchemaControlObject property.


Using C1QueryFrame Properties, Methods and Events

This section describes general features of the C1QueryFramecontrol. More specific features are covered in separate sections.

General Appearance/Behavior Features

Item Navigation

Editing Values

Events on Changing a Query Item

Modifying Templates at Run Time

Handling Errors


General Appearance/Behavior Features

The standard Border, BackColor, ForeColor, Font properties define the control’s colors, font and border. These are only the basic display properties. Much more powerful customization features are available in C1QueryFrame in the form of templates that allow you to customize every possible display aspect of the control, and more. See Customizing UI with Templates for details.

The standard Enabled property works as with all other controls, it disables/enables user interaction with the control.

The FullFieldNames property set to True makes the control show folder fields with full dot-separated folder path.

The TabInQuery property specifies whether the Tab key navigates between controls (default) or between query item elements.

The AfterRender event occurs when the control’s contents is rendered (displayed), at startup and after every change made to the control’s contents (as a result of user interaction or calling the Render method). This event is necessary mainly because the Render method works asynchronously: when you call Render, it returns immediately without actually repainting the control’s surface. If you need to perform some action after the control has been repainted, use the AfterRender event.

The DebugContextMenu property (default: False) allows you to disable the control’s context menu and enable the browser’s standard context menu. It can be useful for debug purposes, for example when you want to examine the HTML source shown by the control.

A C1QueryFrame control also fires the standard mouse and keyboard events: Click, DblCLick, MouseMove, MouseDown, MouseUp, KeyDown, KeyPress, KeyUp.


Item Navigation

A C1QueryFrame control’s contents is a collection of items, conditions or result fields, depending on the value of the ContentsType property. Each item has its own unique identifier – the item id, uniquely determining its position in the hierarchy of query items.

Special methods of the C1QueryFrame.Item object allow the programmer to access an item by its id and to navigate the item hierarchy, see Accessing and Modifying Query Items.

The id of the current (currently selected by the user) item is returned by the CurrentItemID property. To access the properties of the currently selected item, use the following code (see Accessing and Modifying Query Items for details):

C1QueryFrame1.Item.FindByID C1QueryFrame1.CurrentItemID

If (Not C1QueryFrame1.Item.Complex) And (Not C1QueryFrame1.Item.Advanced) Then

‘ If it is a simple elementary condition, do something

End If

The CurrentItemID property can be set programmatically, moving the selection to a desired item.

When the end user changes the selection, moves to another item, the ItemFocusChange event is fired. This event is also fired when the end user moves between elements of the same item (for example, from left side to comparison, or from comparison to right side).

To find out which element of the current item is currently selected by the end user, use the CurrentElement property of the Item object, as in the following code:

C1QueryFrame1.Item.FindByID C1QueryFrame1.CurrentItemID

If C1QueryFrame1.Item.CurrentElement = c1qElemTypeConn Then

‘ If it is a connective, do something

End If

In order to programmatically move the selection to an element inside the currently selected item, use the SetCurrentElement method.


Editing Values

The EndEdit event occurs when the end user finishes editing a constant value. It gives the developer an opportunity to correct possible user errors and/or to specify what string will be shown in the query for this value (setting the ValueText argument) and what value will be used for this constant in SQL generation (setting the Value argument). Setting the EditedValue and EditedValueText properties also specifies the text and the value for the edited constant, and these properties can be set at any time during editing, not only in the EndEdit event.

The StartEdit method allows the programmer to initiate editing of the currently selected element (constant) programmatically. The ExitEdit method allows the programmer to programmatically finish the editing of a constant value.

The Editing boolean property returns True if the end user is currently editing a constant value.

See more about customizing the process of editing constant values in Custom Editing and Lookup.


Events on Changing a Query Item

Change event occurs after every change made by the end user in a C1QueryFrame control: field selection, comparison selection, value editing, etc. There are also more specific change notification events:

When the end user opens a menu to change one of the elements of an item, or opens the control’s main menu, the BeforeMenu event is fired, giving the developer an opportunity to replace the default action (showing the menu), with another action (for example, showing a custom menu or a dialog).

When the end user selects an item from the menu, the MenuSelected event is fired, giving the developer an opportunity to override the default menu action.

When the end user selects an item from the menu, the AfterMenu event is fired, where the developer can perform some action after menu selection.

If you want to perform some actions before or after the user changes a constant value, use BeforeEdit and AfterEdit events.


Modifying Templates at Run Time

Most aspects of C1QueryFrame display presentation are controlled by templates, see Customizing UI with Templates. Although normally all template attributes that need customization are defined at design time in a template file, sometimes it can be necessary to change templates at run time.

Calling the LoadTemplatesFromFile method, the whole set of customized template attributes can be replaced with new templates from a file.

The SetTemplateAttribute method allows you to change a single template attribute without affecting others.

Finally, it is possible to parameterize template attributes, to use a special tag, C1Q_USERDATA, a placeholder that is substituted for a real value at run time. This is necessary in cases where some information, such as file locations, etc, is unavailable at design time. Setting the TemplateUserData indexed property, you can specify the values that must be substituted in templates instead of the C1Q_USERDATA tag. Templates with C1Q_USERDATA will usually not work properly at design time. Although it does not cause real problems (it only results in a garbled display on your control at design time), you can set the DesignTimeTemplates property to False to prevent this from happening.

Calling the SetTemplateAttribute and setting the TemplateUserData property, call the Render method if you need the changes to take effect immediately. Otherwise, they will take effect when the query contents will be rendered for display.


Handling Errors

The Error event of the C1QueryFrame control is triggered on error conditions, such as when the user enters data in incorrect format and the problem is not resolved by the code in the EndEdit event. The ErrorItemID property identifies the affected item.


Customizing User Interface

ComponentOne Query supplies a built-in user interface, making implementing ad hoc functionality as easy as dropping a control on a form. In addition to that, ComponentOne Query allows developers to customize user interface in a virtually unrestricted variety of ways:

•

If you need to localize or customize C1Query strings and menus, or customize colors, fonts and other presentation styles, it can be easily done using a special template mechanism, see Customizing UI with Templates. This method is demonstrated in Tutorial 6.

•

If you want to change the general layout of query display, it can be done modifying the script responsible for query display, see Customizing UI with Scripts. Tutorial 7 shows how to do this.

•

You can create your own UI on a Visual Basic form using any available controls and other means. See Creating Your Own UI. This is demonstrated in Tutorial 8.

•

You can use C1Query in a web application for generating SQL from user query data submitted from browser client, see Using C1Query on the Web.

•

ComponentOne Query object model allows you to programmatically access and set fields and conditions specified by the user, see Accessing and Modifying Query Items.

•

Using special events, you can provide your own custom editing and lookup for condition values based on data type and other attributes, such as special editors for date/time/currency and other types, custom lookup lists, etc. See Custom Editing and Lookup for details.

•

ComponentOne Query object model allows you to customize different aspects of UI behavior with properties, methods and events, see Customizing User Interface.


Customizing UI with Templates

Every user interface aspect of a C1QueryFrame control can be customized using a special template mechanism. A C1QueryFrame control contains templates. Default templates are provided in the product and work without programmer’s interference. To customize templates, developers modify default templates in a text file and import the modified templates to the control.

A template text files have special structure. It consists of attributes.

Some of the template attributes are HTML display styles, some are item templates, some determine menus and messages, and there are also some that are HTML scripts.

Using display style attributes, you can change colors, fonts, borders and all other display characteristics of C1QueryFrame items.

Using item template attributes, you can change the display of query items. You can change the order of the elements in an item, hide some elements, change the texts accompanying item elements, add images and other display elements to item display.

Using menu attributes, you can customize C1QueryFrame menus.

One of the script attributes is the C1QRender attribute – the script used to render HTML on the control surface. Changing this script, you can completely change the layout, customize it to your users’ needs, see Customizing UI with Scripts.

Examples of customizing both display styles and the whole layout are presented in Tutorials.

Each attribute has a name and an HTML snippet text. The text of an attribute in a template file begins with a special tag

<C1QProperty:attribute_name>

and ends with the tag

</C1QProperty: attribute_name >

All template attributes with their names are described below.

For example, the CurrentRowStyle attribute determines the display style for the currently selected item. Its default value is

<C1QProperty:CurrentRowStyle>

pixelHeight:10;border-bottom-style:inset;border-top-style:inset;border-color:white;border-width:thin; </C1QProperty:CurrentRowStyle>

To modify C1QueryFrame templates, first obtain the default template file selecting Save Default Templates… in a C1QueryFrame control’s context menu. Then modify the desired attributes, or create a separate template file containing only the attributes that you need to change (recommended). Once you have the modified template file, import it to the C1QueryFrame control selecting Load Templates… from the control’s context menu.

You can also modify templates in a C1Query control, selecting Load Templates in its context menu. This modification will affect the C1QueryFrame controls attached to this C1Query control.

Usually, templates are modified at design time importing from a template file. But they can also be imported at run time, using the LoadTemplatesFromFile method. There is also a SetTemplateAttribute method that allows to set an individual template attribute dynamically, without affecting other attributes. For example, you can change the CurrentRowStyle attribute in the ItemFocusChange event so that the currently selected item will be show in different color depending on its contents. After calling SetTemplateAttribute, you need to call the Render method to update C1QueryFrame display.

The C1QueryFrame template attributes are described below. We recommend obtaining the default template file, selecting Save Default Templates… from a C1QueryFrame control’s context menu and browse through its contents using the description below as a guide.

Display style attributes

Message and Text Attributes

Menu attributes

Item Template Attributes

Comparison and Function Attributes

Special Tags

Tag Substitution Rules

Using Macros in Item Templates


Display style attributes

MainStyle

Style inherited by default by all display elements

CurrentRowStyle

Item currently selected by the end user

InactiveRowStyle

All items except the item selected by the end user

CONNInactiveStyle

Connective in a complex condition item that is not selected

CONNActiveStyle

Connective in a selected complex condition item

CONNCurrentStyle

Connective in focus

CMPInactiveStyle

Comparison in an elementary condition item that is not selected

CMPActiveStyle

Comparison in a selected elementary condition item

CMPCurrentStyle

Comparison in focus

LSInactiveStyle

Left side in an elementary condition item that is not selected, or field in a result field item that is not selected

LSActiveStyle

Left side in a selected elementary condition item, or field in a selected result field item

LSCurrentStyle

Left side in focus, for a condition item. Field in focus, for a result field item

LSKindInactiveStyle

Left side kind (one of the two values: field, constant) in an advanced condition item that is not selected

LSKindActiveStyle

Left side kind in a selected advanced condition item

LSKindCurrentStyle

Left side kind in focus

RSKindInactiveStyle

Right side kind (one of the two values: field, constant) in an advanced condition item that is not selected

RSKindActiveStyle

Right side kind in a selected advanced condition item

RSKindCurrentStyle

Right side kind in focus

RSInactiveStyle

Right side in an elementary condition item that is not selected

RSActiveStyle

Right side in a selected elementary condition item

RSCurrentStyle

Right side in focus

SortInactiveStyle

Sort in a result field item that is not selected

SortActiveStyle

Sort in a selected result field item

SortCurrentStyle

Sort in focus

FunctionInactiveStyle

Function in a result field item that is not selected

FunctionActiveStyle

Function in a selected result field item

FunctionCurrentStyle

Function in focus

CheckBoxInactiveStyle

Checkbox in a result field item that is not selected

CheckBoxActiveStyle

Checkbox in a selected result field item

CheckBoxCurrentStyle

Checkbox in focus


Message and Text Attributes

EmptyDisplayText

Text displayed in an empty (unspecified) element of an item

MessageErrorCaption

The caption of an error message box


Menu attributes

Every menu attribute specifies a menu shown when the end user clicks one of the query elements editable with a menu. A menu specification is a string encoding menu items separated with double colon “::”. Example:

<C1QProperty:SortMenu>

0@none@@1::1@ascending@ascending@1::2@descending@descending@1

</C1QProperty:SortMenu>

A menu item is represented by a string containing four fields separated with “@”:

action_id@menu_text@display_text@enabled

Here:

action_id | Integer number identifying the action. Modifying menu template attributes, use the action ids from the default template file. You can reorder menu items, hide some of them, change item texts, but the action id will always perform the same action as it does in the default template file. For menus that determine the value of an item element (such as the SortMenu above), action_id determines the value of the element when the user selects the item
menu_text | The item text as it is shown in the menu.
display_text | For menus that determine the value of an item element, the text shown in the element when the user selects the item.
enabled | 1 means the item is enabled, 0 means it is disabled.

C1QueryFrame templates have the following menu attributes:

ConditionMenu

Main menu of a C1QueryFrame control with ContentsType=c1qCondition

ResfieldMenu

Main menu of a C1QueryFrame control with ContentsType=c1qResultFields

ConnMenu

Connective menu in a complex condition item

KindMenu

Left/right field kind menu (two values: function, constant) in an advanced elementary condition item

SortMenu

Sort menu in a result field item

BooleanValues

Yes/No menu for boolen constants

The menus of functions and comparison operators can also be customized, but that is done using the general customization mechanism, see Customizing Functions and Comparison Operators.


Item Template Attributes

Using item template attributes, you can change the display of query items. You can change the order of the elements in an item, hide some elements, change the texts accompanying item elements, add images and other display elements to item display.

For example, the default template for elementary condition items is (simplified):

Records where <C1Q_LEFT> <C1Q_COMPARISON> <C1Q_RIGHT>

It means that condition CustomerID = ‘ALFKI’ is displayed as

Records where CustomerID equals ALFKI

Changing the elementary condition template to

Field <C1Q_LEFT> <C1Q_COMPARISON> <C1Q_RIGHT>

renders the same condition as

Field CustomerID equals ALFKI

Changing the CompMenu attribute (see Menu attributes) we can also replace the word ‘equals’ with some other text, for example, ‘=’.

C1QueryFramesupports the following item template attributes:

ComplexTemplate

Complex condition item

ComplexResFieldTemplate

The root item in a C1QueryFrame control with ContentsType=c1qResultFields

ElemTemplate

Elementary condition item

AdvElemTemplate

Advanced elementary condition item

ResFieldTemplate

Result field item


Comparison and Function Attributes

Comparison and function attributes define all comparison operators and functions supported by the C1QueryFrame control. Modifying these attributes, you can modify the set of comparisons and functions used by the control. You can also add your own custom comparisons and functions. For details of modifying comparisons and functions, see Customizing Functions and Comparison Operators.

Comparison attributes are records defining comparison operators, all enclosed between the opening tag <C1QProperty:Comparisons> and closing tag </C1QProperty:Comparisons>. Each record starts with an opening tag <COMPARISON>, ends with the closing tag </COMPARISON> and contains the following attributes: Id, Caption, Text, Types, Enabled, Templates. See description of these attributes in Custom Comparison Operators.

Function attributes are records defining functions, all enclosed between the opening tag <C1QProperty:Functions> and closing tag </C1QProperty:Functions>. Each record starts with an opening tag <FUNCTION>, ends with the closing tag </FUNCTION> and contains the following attributes: Id, Caption, Text, Types, Enabled, Aggregation, Templates. See description of these attributes in Custom Functions.


Special Tags

Item templates contain special tags, placeholders representing item elements. When a C1QueryFramecontrol renders HTML for display, these tags are substituted with the values of corresponding elements. The following tags are supported in item templates:

<C1Q_CONNECTIVE>

Connective in a complex condition item

< C1Q_LEFT>

Left side of an elementary condition item; field in a result field item

< C1Q_COMPARISON>

Comparison in an elementary condition item

< C1Q_RIGHT>

Right side of an elementary condition item

< C1Q_LS_KIND>

Left side kind (one of the two values: field, constant) in an advanced condition item

< C1Q_RS_KIND>

Right side kind (one of the two values: field, constant) in an advanced condition item

< C1Q_SORT>

Sort in a result field item

< C1Q_FUNCTION>

Function in a result field item

< C1Q_CHILDREN>

All condition items belonging to a complex condition item

< C1Q_LEVEL>

Integer number, the level of an item in the item hierarchy (the root item has level 0)

< C1Q_UID>

Integer number, the item’s unique id


Tag Substitution Rules

Generating HTML, C1QueryFrame control substitutes special tags with HTML text according to the rules described here. These substitution rules provide

•

Interactive functionality, see the scripts attached to OnClick. The scripts can be found in the same template file.

•

Display style, see the styles attached to the Class property, those are styles defined in Display style attributes.

•

HTML element ID. Item elements must have specific IDs defined here, because these IDs are used in the scripts and in C1QueryFrame code.

Knowing these rules, you can use the reserved IDs, script function names and display styles to write your own HTML in item templates. You can use special tags and rely on the substitution rules, or you can write your own HTML without special tags.

In the following substitution rules, itemid represents the item id for the current item (the item being processed), text represents the string contents of the element. C1Q*CurrentStyle must be replaced with C1Q*ActiveStyle or C1Q*InactiveStyle if the element is not in focus and belongs to a selected or unselected item.

<C1Q_CONNECTIVE>

<A HREF=nowhere ID=C1QConnective Class=C1QCONNCurrentStyle OnClick=C1QShowCONNMenu(itemid) text </A>

<C1Q_LEFT>

A HREF=nowhere ID=C1QLeftside Class=C1QLSCurrentStyle OnClick=C1QInteractLS(itemid) text </A>

<C1Q_COMPARISON>

<A HREF=nowhere ID=C1QComparison Class=C1QCMPCurrentStyle OnClick=C1QShowCMPMenu(itemid) text </A>

<C1Q_RIGHT>

<A HREF=nowhere ID=C1QLeftside Class=C1QRSCurrentStyle OnClick=C1QInteractRS(itemid) text </A>

<C1Q_LS_KIND>

<A HREF=nowhere ID=C1QLeftSideKind Class=C1QLSKindCurrentStyle OnClick=C1QShowLSKindMenu(itemid) text </A>

<C1Q_RS_KIND>

<A HREF=nowhere ID=C1QRightSideKind Class=C1QRSKindCurrentStyle OnClick=C1QShowRSKindMenu(itemid) text </A>

<C1Q_SORT>

<A HREF=nowhere ID=C1QSort Class=C1QSortCurrentStyle OnClick=C1QShowSortMenu(itemid) text </A>

<C1Q_FUNCTION>

<A HREF=nowhere ID=C1QFunction Class=C1QFunctionCurrentStyle OnClick=C1QShowFunctionMenu(itemid) text </A>


Using Macros in Item Templates

You can define special macros (scripts) and include macro calls in item template HTML. They are useful when you have a substantial chunk of HTML (usually, a script) that you want to reuse in several template attributes. An example of such macro (script) is C1Q_Indent used in the default template file.

Every macro (script) must be defined in the template file as a separate attribute with a special name: Script:script_name

Example (from the default template file):

<C1QProperty:Script:C1Q_Indent>

for (i=0; I < <C1Q_LEVEL>; i++)

document.write("&nbsp&nbsp&nbsp&nbsp&nbsp");

</C1QProperty:Script:C1Q_Indent>

To include a script call (a macro) into an item template, write the following in the template attribute’s HTML:

<C1Q_SCRIPT Name='script_name'>


Customizing UI with Scripts

One of the script attributes is the C1QRender attribute – the script used to render HTML on the control surface. Changing this script, you can completely change the layout, customize it to your users’ needs.

If you want to write your own C1QRender script, we recommend to obtain the default template file, selecting Save Default Templates… from a C1QueryFrame control’s context menu and use the C1Qrender script included there as your guide. The default C1QRender script generates exactly the same HTML as the C1QueryFrame control itself.


Script Attribute: RenderScript

Using the C1QRender script, you can completely change the layout of items in a C1QueryFrame control, customize it to your users’ needs. You can change the rules of query composition, as it appears on display. One of C1Query tutorials shows how to do it by presenting a sample script making the query display look as a formula with parentheses instead of the default row outline. User interaction with such query remains fully functional although its layout is completely different.

There is a special C1QueryFrame property, ManualRender, that is False by default. Setting it to True enables the C1QRender script. In this case, rendering HTML for display is performed not by the C1QueryFrame control itself, but by the C1QRender script.

Replacing the C1QRender attribute with your own script, and setting ManualRender to True, you can render the items in whatever way you prefer. See Tutorials for an example how to use this powerful customization functionality.

Two special methods of C1QueryFrame are useful implementing C1QRender script:

The GenerateHTML method performs tag substitution as described in Tag substitution rules. So you can use special tags in your C1QRender script and apply GenerateHTML to substitute the tags. The WrapHTML method wraps a text in <DIV> or <SPAN> tags with special id and other properties. This method is required to turn an HTML text into a query item. It must always be applied to HTML representing a query item before adding it to the generated HTML text. See the default C1QRender script and the tutorial for examples of how to use the GenerateHTML and WrapHTML methods.


Script Attribute: HtmlHead

The default template file also contains an HtmlHead attribute with a long script text with many functions. This is actually a part of C1QueryFrame software, but it is written in JavaScript instead of C++ (which is the language of the rest of C1Query implementation). This is where all the functions are implemented, such as C1QShowCONNMenu, C1QInteractLS and others, mentioned in Tag substitution rules.

Advanced users can change the HtmlHead script just like any other template attribute customizing C1QueryFrame behavior event further. But beware, changing this script without due caution can break the C1QueryFrame control.


Creating Your Own UI

ComponentOne Query consists of the query engine, C1Query control, and the user interface control – C1QueryFrame. C1QueryFrame provides a built-in user interface, which can be easily customized, see Customizing User Interface. However, in many cases, developers need to create their own user interface to satisfy user requirements. For example, you may need to provide a series of combo boxes where the user will be able to choose fields, conditions, etc.

C1Query allows you to create your own user interface and connect it to the powerful C1Query SQL generation engine. This option is demonstrated in Tutorial 8.

Create a user interface form using any controls you need. Then write code filling a C1QueryFrame control with query items specified by the user in that form. Make the C1QueryFrame control invisible at run time, since you need it only as a programmatic container of the user-specified data and a conduit between your UI form and the engine, the C1Query control. C1QueryFrame object model allows you to set query fields and conditions, see Accessing and Modifying Query Items, so that they become available to the C1Query control. Then you call C1Query.BuildSQL to generate SQL from the user input.


Using C1Query on the Web

ComponentOne Query can be used in web applications to submit queries from a thin browser-based client to the server and generate SQL statement on the server. In this scenario, C1Query is used only on the server. The client is a generic HTML browser, no ActiveX or other plug-ins required. Sample WebQueryASP (subdirectory Samples\ASP) shows how to do that using ASP (Active Server Pages). To host the ComponentOne Query controls, C1Query and C1QueryFrame, it uses an ActiveX DLL created in Visual Basic (see the Dll subdirectory). This ActiveX DLL exposes a SchemaContainer class that returns all necessary objects, including the C1Query control itself, as its properties so they can be used in the ASP script. The controls themselves are hosted on an invisible form.

Another possible scenario of using C1Query on the web is hosting C1Query controls directly in the browser. This is easier to do, and you can use the built-in UI provided by C1QueryFrame, but in this case you are limited to browsers that can host ActiveX controls, that is, mainly, to Internet Explorer. See Samples\HTML subdirectory for the tutorials implemented as controls hosted in HTML pages.


Maintaining, Saving and Restoring Queries

It is often needed to allow the user to save queries in a repository so that they can be reused later. Such repository can be a database, a file directory, or an XML file storing multiple queries, or another kind of storage. C1Query does not limit developer’s choice to a specific storage or media. It provides general-purpose methods for saving/restoring a query. Using these methods, you can easily program a query repository or any other form of query maintenance facilities required in your application.

SaveToXMLFile and LoadFromXMLFile methods allow you to save/restore queries in a file.

SaveToXML and LoadFromXML methods allow you to save/restore a query as a String value. The saved query is structured in a standard XML form, but what matters is that the query is now represented by a single String. That string can be stored in a database or another storage, together with query description and other attributes, if you need them.

Restoring a query does not automatically update the control display. It is intentional, since in some cases it is needed to modify the query contents after restoring it to a control (see Accessing and Modifying Query Items about how to do it). When you are done with restoring/modifying the query, call the Render method to update display. If you forget to call Render, the control will remain in unstable state and unpredictable results can follow.

An example showing how to maintain a repository of queries in an XML file can be found in the SAMPLES directory. You can easily modify that sample to store queries in a database or another storage.


Modifying Schema and Field List at Run Time

A C1Query control stores a schema that is used to present folder fields to the user in the associated C1QueryFrame controls. There are also provisions in the C1Query control allowing you to modify the end user view of the schema dynamically.

Calling the LoadSchemaFromFile method, the schema can be replaced at run time with the schema stored in a file. The schema can be created at design time in schema designer, and saved in a file, or it can be created at run time.

Alternatively, you can also assign the string representing a schema to the Schema property. The schema string is simply the contents of a text file containing a schema. To obtain it, you can save a schema to a file in schema designer, or you can create a schema programmatically at run time.

If you need to create a schema at run time, you can use XML DOM. A schema is an XML document with fixed structure, so it can be created at run time programmatically using Microsoft XML parser, the MSXML.IXMLDOMElement interface. The structure of schema XML is defined in the HTML file c1query_schema_format.htm. For an example of programmatic schema creation, see RunTimeSchemaInit sample in the Samples\VB directory.

You can also hide/show specific fields and/or entire folders from the end user, calling the ShowFolderFields method.

Another option is to create a schema with multiple independent set of views. It is possible that a schema consists of multiple sets of views so that these sets are unrelated to each other. It means that a user query cannot span different unrelated sets of views, the user is enabled only to choose fields from a single, fixed set of views. In this situation, the schema designer will show a warning in schema verification (Verify schema in the Schema menu), but such schemas can still be valid and useful.

A set of interrelated views independent of other sets of views is identified by its main view name. All other views from the same set are related (with relationships and/or join groups) to the set’s main view. Every set of interrelated views has one and only one main view.

For a multi-viewset schema, you can set the MainViewName property of the C1Query control to determine the currently active set of views. Only fields belonging to the active set will be shown to the end user in the associated C1QueryFrame controls. The MainViewCount property returns the number of sets. MainViewNames(Index) returns the main view name of the set number Index.


Accessing and Modifying Query Items

To access individual query items (conditions or result fields, depending on the value of the ContentsType property), use the C1QueryFrame.Item object.

Before using the Item object, it is important to understand that it represents all query items at once, it does not represent any single particular item. There is always only one Item object associated with a C1QueryFrame control. The Item object works similar to a cursor or recordset, you navigate it through the tree of items. Once you have positioned on an item, you can get/set its properties.

You can either navigate through the item tree, or position to a single item.

To navigate through the item tree, use the following methods: MoveToRoot, MoveToChild and properties: ChildrenCount, IndexInParent. Alternatively, you can use methods MoveToNext, MoveToPrevious, MoveToFirstChild. Using the last three methods, test the existence of the destination item with boolean properties HasNext, HasPrevious, HasChildren.

To position on a single item, you must know its id. Each query item has its own unique identifier – the item id, uniquely determining its position in the item tree. To position to an item with known id, use the FindByID method. For example, the following code positions the Item object on the item currently selected by the end user.

C1QueryFrame1.Item.FindByID C1QueryFrame1.CurrentItemID

To retrieve the unique id of the item on which the Item object is currently positioned, use the ID property. The ParentID property returns the id of the item’s parent in the hierarchy. The root item id is always 0.

All properties of the Item object return/set properties of the item on which the Item object is currently positioned.

The Advanced and Complex read-only properties return boolean values determining whether the item is an advanced elementary condition and whether it is a complex condition.

The following properties return/set the enumeration values for query item elements that can be selected by the user in corresponding menus: Comparison, Connective, Function, and Sort.

The LeftSideField and RightSideField properties return/set the strings, field names displayed on the left and right sides of a condition. The RightSideField property is applicable only to advanced conditions (those that can have fields on the left and right side). For result field items, only the LeftSideField property has a valid value determining the string shown as the field name.

The actual field used in a query item is not necessarily determined by the LeftSideField/RightSideField properties. By default, these properties contain the field name, but their values can be changed for UI customization purposes (using the AfterMenu event) without affecting the actual field.

The LeftFieldID property determines the field (it’s id, see below) selected on the left side. For an advanced elementary condition item with a field on the right side, the RightFieldID property determines the id of the field selected on the right side

Every field in a C1Query schema has its own unique identifier – field id. To obtain field id, use the FieldNameToFieldID method. If you want to retrieve field’s properties given a field id, use the FieldByID method that returns a Field object where you can get the field’s name and other properties.

Constant values in an elementary condition item are determined by the LeftSideValue and RightSideValue properties. The LeftSideValue property is applicable only to advanced conditions (those that can have constants on the left side). These properties determine the constant values used in SQL generation.

The LeftSide and RightSide properties return/set the strings displayed on the left and right sides of a condition. The LeftSideValue property is applicable only to advanced conditions.

By default, string presentation of a value is obtained from the value itself. However, the string presentation (LeftSide/RightSide properties) can be changed for UI customization purposes (using the EndEdit event) without affecting the actual value.

For an advanced elementary condition, the LeftSideKind and RightSideKind properties determine whether the left/right side is a field or a constant.

To modify the collection of query items programmatically, add/ delete items, use the following methods of the C1QueryFramecontrol: Clear, AddItem, DeleteItem, and PerformMainMenuAction. Adding an item, specify its parent’s id and condition type, whether it is simple, advanced or complex (for result field items, the condition type argument is ignored).

Modifying query items does not in itself update the control display. It is intentional, since item contents are usually modified in batches and display refresh on each assignment would be undesirable. After modifying query items, you must call the Render method to update display. If you forget to call Render, the control will remain in unstable state and unpredictable results can follow.


Custom Editing and Lookup

Editing constant values in a query, end users need special editors for specific data types, such as special editor for date/time values, lookup combo boxes or menus for selection from a lookup list of options, etc.

Default Editing

Custom Editing

Modal Editing

Lookup Value Lists


Default Editing

By default, C1QueryFrame provides special editors for the following cases:

•

Date-time picker control for date/time data types.

•

Special editing for numeric data types, ignoring characters that are not allowed in a number.

•

Combo box for boolean data type.

•

Combo box for fields with lookup values defined in the schema (the Use lookup values check box checked) or dynamically in the LookupValues event or using the SetLookup method.

This editing behavior is built in, you don’t have to implement it in code.

If you want to disable special editing of date/time, numeric and boolean types, set the TypedEditing property to False. Then all data types will be edited in a simple edit box. The special typed editing can also be disabled on a field-by-field basis. To disable typed editing for a particular field, set the TypedEditing argument of the BeforeEdit event to False.

A special property of the C1QueryFrame control, FormatDate specifies date format. Default editing supports long and short date, with or without time. If you want more sophisticated formats for dates or other data types, implement your own custom editors, see Custom Editing.


Custom Editing

If you are not satisfied with the default editors, you can implement your own editors as shown in the SAMPLES directory and in the C1QueryUI user control in the USERCTL directory.

Custom editors can be defined on a field-by-field basis. You can use different controls (editors) for different fields. This is done dynamically, in special events, so it can even depend on the properties of a particular item being edited.

A custom editor is an ActiveX or intrinsic control residing in the same form with the C1QueryFrame control. It is usually invisible at run time, made visible only when it is activated. A custom editor must always be a single control. If you need multiple controls (for example, an edit box with a spin button), put them in a container control and use the container as your custom editor. There is also a restriction that custom editor controls must be window controls, so windowless controls, such as Label, cannot be used as custom editors.

To implement custom editing, you need to handle the following events: BeforeEdit, ShowCustomEditor, EndEdit, HideCustomEditor.

In the BeforeEdit event, indicate that this item uses custom editing (if this is the case), setting the ShowCustomEditor argument to True, and specify the dimensions of your custom editor setting the ControlWidth and ControlHeight arguments. Deciding which custom editor to use, you can examine the Field argument for data type (Field.Type) and other properties. To convert Field.Type to a variant data type, use the VarTypeFromDataType method.

In the ShowCustomEditor event, assign the control object and the control window handle to the ControlObj and ControlHWND arguments, initialize the editor control with the current value and text using the Value and ValueText arguments, and, finally, show the editor control (set it’s Visible property to True). You don’t have to move the control, C1QueryFrame will automatically position it for in-place editing.

In the EndEdit event, that will be triggered when the user exits the editor, set the Value argument to the current value entered in the control by the user. Set the ValueText argument to the string representation of the value. Whatever you set ValueText to, will be shown in the query as the text of the constant, without affecting the actual value of the constant. You can use this to display the value with formatting required by your users (note that this feature of the EndEdit event is applicable in all cases, not only in custom editing).

Finally, in the HideCustomEditor event, hide the editor control setting its Visible property to False.


Modal Editing

It may be necessary to implement editing of some constants with a special menu, dialog or modal form. In this case, the user cannot leave the constant being edited until the editing is done, the dialog or menu closed. This is called modal editing.

Modal editing can be implemented in the BeforeEdit and EndEdit event procedures. There is no need in other events, because in this case the editing process as such does not take place. Upon return from the user code (dialog, menu, etc), the constant’s value and text are immediately changed and the editing process ends.

To implement modal editing, write your code in the BeforeEdit event, open a dialog, menu, etc. Before leaving the BeforeEdit code, you set the ModalEditing argument to True. In the EndEdit event, set the Value and ValueText arguments to, respectively, the value entered by the user and its display (string) representation.


Lookup Value Lists

In many cases, end users need to be able to select values from a list of options, a lookup list. Such list can be pre-defined or composed dynamically, for example, retrieved from a database. A lookup list consists of lookup items, each having two values: Value and ValueText. Value is the selected value of the constant. ValueText is its string representation displayed in the query. ValueText can be different from Value. For example, you may want to show customer names in a lookup list and in the query, but use a customer code in the generated SQL statement.

There are five ways to specify a lookup list for a field in C1QueryFrame:

•

Check the Use lookup values check box in the schema designer (in Folder Designer) and fill the grid with Value/ValueText pairs. The list specified in the schema will be shown in a combo box when the user edits the field in C1QueryFrame.

•

If you need to modify the lookup list at run time, check the Use lookup values check box in the schema designer and write code handling the LookupValues event, modifying the lookup list. It is also possible to leave the lookup list empty in the schema and specify it from scratch in the LookupValues event. In the LookupValues event procedure, assign arrays of the equal dimension to the Values and ValueCaptions arguments. The Values argument determines the values as they are stored in the user query and will be used for SQL generation, the ValueCaptions argument determines the strings that appear in the list for user selection. By default, lookup lists are shown in a combo box. Setting the EditorType argument in the LookupValues event, you can specify the desired presentation: selection combo, editable combo, or menu. If you need other presentation techniques, use Custom Editing or Modal Editing, see below.

•

Use the SetLookup method to retrieve a list of lookup values from the database. This method is a convenient shortcut for retrieving lookup lists. See an example in the SAMPLES directory. However, if your lookup list is a large table (thousands of records or more), this method may be not efficient enough, because it pre-fetches all the records every time you open the combo box. In such cases, you may consider using custom editing, see below.

•

Use Custom Editing implementing your custom editor as a combo box or another selection control filled with lookup data. An example of such code using standard DataCombo control can be found in the C1QueryUI user control in the USERCTL directory. If your lookup list is a large table (thousands of records or more), you must bear in mind that DataCombo may be not efficient enough, because it pre-fetches all the records. In such cases, you may consider using more optimized data-aware controls, such as TDBCombo, a part of ComponentOne True DBList product, see an example in the SAMPLES directory.

•

Use Modal Editingif you want to select values from a menu or in a modal dialog with list boxes or other selection controls.


Customizing Functions and Comparison Operators

C1Query 1.1 allows developers to define custom functions and comparison operators in addition to the standard ones, and also modify all function and comparison attributes on a per control and per query item basis.

Custom Functions

Custom comparison operators

Specifying Function and Comparison Attributes for a Particular Query Item

Type Checking in Condition Items


Custom Functions

The Function element of a result field query item can contain custom functions, in addition to standard ones: SUM, COUNT, AVERAGE, MIN, MAX. The five standard functions are all aggregation functions. Custom functions can be both aggregated and non-aggregated. For example, you can add an aggregated VAR function (statistical variance) and a non-aggregated YEAR function (the year part of a date field).

Custom functions can be added both at design time, using a template file, and at run time, setting the TemplateAttributes array property.

To add a custom function to the templates (see Customizing UI with Templates), add a record to the <C1QProperty:Functions> template attribute. All standard functions are defined in the default template file, so you can use their definitions as guidance in defining your own functions.

A custom function definition contains the following attributes:

Id

Function identifier, must be greater than maximum standard function id (greater than 5).

Caption

Text appearing in the function menu.

Text

Text appearing in the Function element of a query item when this function is selected.

Types

Comma-delimited list of data types allowed to be used with this function; the function will be available only for fields having one of these types. Specifying Types="..." makes it available for all data types.

Aggregation

True/False. If True, this is an aggregation function (like SUM, COUNT, etc), so it is evaluated on a group level, using the GROUP BY clause. Otherwise, it's a regular function, evaluated as an expression in the SELECT clause, unaffected by GROUP BY.

Enabled

True/False. This attribute can be set at run time to control the enabled state of the function's menu item. If it is False, the menu item is disabled.

Template

The string used in the resulting SQL statement. It can be specified in a template, parameterized form, with a special tag <C1Q_FIELD1> that will be substituted with the field name in SQL generation. For example, a template for the YEAR function can be Template="Year(<C1Q_FIELD1>)". If there is no special tag in the template string, it is used in generated SQL as is.

To add a custom function at run time, set the TemplateAttributes property. It is an indexed property, the index must be a specially formatted string as follows:

C1QueryFrame.TemplateAttributes("Functions:<id>")

where <id> is the integer id of the function (see the Id attribute above).

To define or change a function definition at run time, set the TemplateAttributes property, with an appropriate index, to a function definition string consisting of the attributes defined above.

You can use the TemplateAttributes property to modify attributes of standard functions as well, not just to define custom functions.

See also: Specifying Function and Comparison Attributes for a Particular Query Item.

For an example of how to add custom functions, see the CustomFunctions sample.


Custom comparison operators

Developers can define custom comparison operators in addition to the standard ones: "equal", "greater than", etc. Custom comparisons can be added both at design time, using a template file, and at run time, setting the TemplateAttributes array property.

To add a custom comparison to the templates (see Customizing UI with Templates), add a record to the <C1QProperty:Comparisons> template attribute. All standard comparisons are defined in the default template file, so you can use their definitions as guidance in defining your own comparisons. A custom comparison definition contains the following attributes:

Id

Comparison identifier, must be greater than maximum standard comparison id (use the c1qFirstUserComparisonID constant, or just start from 100).

Caption

Text appearing in the comparison menu.

Text

Text appearing in the comparison element of a query item when this comparison is selected.

Types

Comma-delimited list of data types allowed to be used with this comparison. The comparison will be available only for fields having one of these types. Specifying Types="..." makes it available for all data types.

Enabled

True/False. This attribute can be set at run time to control the enabled state of the comparison's menu item. If it is False, the menu item is disabled.

Template

The string used in the resulting SQL statement. It can be specified in a template, parameterized form, with special tags: <C1Q_FIELD1>, <C1Q_FIELD2> and some others (see below) that will be substituted with field names and constant values in SQL generation. If there are no special tags in the template string, it is used in generated SQL as is.

Tags in Template attribute:

<C1Q_FIELD1>, <C1Q_FIELD2>: left and right parts of the comparison. In a simple condition, <C1Q_FIELD1> is always a field and <C1Q_FIELD2> is a constant value. In an advanced condition, they both can be either a field or a constant value.

<C1Q_FIELD1_LEFTQUOTE>, <C1Q_FIELD1_RIGHTQUOTE>, <C1Q_FIELD2_LEFTQUOTE>, <C1Q_FIELD2_RIGHTQUOTE>: quotation marks used with a constant value. These tags are substituted with a quotation mark appropriate for the constant's data type. For a string constant, they are usually single quotes. For a field or a numeric constant, they are substituted with empty strings.

<C1Q_LIKE_PERCENT>: wildcard matching any string in LIKE (standard SQL character: %).

<C1Q_LIKE_UNDERSCORE>: wildcard matching a single character in LIKE (standard SQL character: _).

To add a custom comparison at run time, set the TemplateAttributes property. It is an indexed property, the index must be a specially formatted string as follows:

C1QueryFrame.TemplateAttributes("Comparisons:<id>")

where <id> is the integer id of the comparison (see the Id attribute above).

To define or change a comparison definition at run time, set the TemplateAttributes property, with an appropriate index, to a comparison definition string consisting of the attributes defined above.

You can use the TemplateAttributes property to modify attributes of standard comparisons as well, not just to define custom comparisons.

See also: Specifying Function and Comparison Attributes for a Particular Query Item and Type checking in condition items.

For an example of how to add custom comparisons, see samples: CustomComarisons, CustomComparisons2.


Specifying Function and Comparison Attributes for a Particular Query Item

To gain even more control over custom functions and comparisons, you can specify all function and comparison attributes on a per item basis, using the following QueryItem properties: ComparisonAttributes and ComparisonTemplate for comparisons and FunctionAttributes, FunctionTemplate for functions.

In this case, the custom function or comparison operator does not have to be defined in templates and does not have to be given any specific Id. Each item can have its own comparison attributes: Caption, Text, Enabled and Template -see Custom Functions and Custom Comparison Operators.

Set C1QueryFrame.Item.ComparisonAttributes (or FunctionAttributes) to a string formatted as a comparison (or function) definition, with the attributes described in Custom Functions and Custom Comparison Operators.

Especially useful is setting the Template attribute for an item's comparison or function, which is usually done in the SQLGenerationItem event, see Changing Query Items for the Duration of SQL Generation. This way you can specify the conditions and expressions that are generated in the SQL statement for every particular item. To do that, set the ComparisonTemplate (or FunctionTemplate) property, which is a shortcut to the ComparisonAttributes (FunctionAttributes)' Template attribute.

Setting QueryItem.Comparison (Function) property resets the item's custom comparison (function) attributes to empty string so that default attributes of the newly assigned comparison (function) take effect.


Type Checking in Condition Items

Using custom comparisons, a problem can arise with the constant value (right part of the comparison) data type. In all standard comparisons, its data type is determined by the field type. With custom comparisons, it is not necessarily the case. For example, in comparison Year(Field)=Value, the Value's type must be Integer, although the Field's type is Date.

To deal with cases like this, use a special property: EditTypeChecking. It is True by default. If set to False, it disables type checking after the user enters a constant value. Using the EndEdit event, the developer can set the value in the query item to a value of any required type.

If EditTypeChecking=True, and the value in the item has data type different from that of the field, and the developer does not change the edited value in BeforeEdit and EndEdit events, then an "Invalid data format" error is generated before and after editing, correspondingly.


Object Reference

C1Query Object

C1QueryFrame Object

Field Object

Fields Object

QueryItem Object

SQLInfo Object


C1Query Object

C1Query Object Properties

ApplyExtensions | Determines how schema extensions can be applied if necessary in SQL generation.
ClauseFrom | Returns the FROM clause of the last generated SQL statement.
ClauseGroupBy | Returns the GROUP BY clause of the last generated SQL statement.
ClauseOrderBy | Returns the ORDER BY clause of the last generated SQL statement.
ClauseSelect | Returns the SELECT clause of the last generated SQL statement.
ClauseWhere | Returns the WHERE clause of the last generated SQL statement, or the Filter text in data source mode.
DataMember | Sets/returns the DataMember for the OLE DB DataSource.
DataSource | Specifies the source of schema information in data source mode.
DataSourceFields | Returns the collection of Field objects in data source mode.
FilterMode | If True, the control is in Filter mode.
MainViewCount | Returns the number of main views in the schema.
MainViewName | Returns/sets the name of the currently active schema main view.
MainViewNames | Returns the name of a main view from the collection of the schema main views.
NameSubstitute | Used as a substitute for the control's Name property in environments that do not support standard property such as Name or Id.
SaveSchemaAsString | If True, schema is saved as string instead of byte array.
Schema | Returns/sets the control's schema as a string.
SQL | Returns the SQL statement generated by the last BuildSQL call.
SQLInfo | Object used for customizing SQL syntax settings and parameters.
Templates | Returns/sets the string modifying HTML templates in C1QueryFrame controls attached to the control, defining their look and UI.

C1Query Object Methods

BuildSQL | Builds SQL statement.
LoadSchemaFromFile | Loads the schema from a file to the control.
RetrieveFieldsFromDataSource | Retrieves the field list from DataSource to the Fields collection, in data source mode.
ShowFolderFields | Shows or hides folders/fields in schema and field menu.

C1Query Object Events

BeforeSQLGeneration | Occurs before SQL generation and allows to change query items and syntax rules affecting resulting SQL.
Error | Occurs as a result of an error condition.
FormatLiteral | Occurs before inserting a literal value in SQL statement.


C1QueryFrame Object

C1QueryFrame Object Properties

BackColor | Returns/sets the background color of the control.
Border | Returns/sets a value that determines whether the control has 3D border.
Checkboxes | If set to True, checkbox is displayed in query items, its state defining whether to include or ignore the item.
Checked | Determines whether to include or ignore the specified query item.
ContentsType | Returns/sets the type of the control, whether it is used for specifying conditions or result fields.
CurrentItemID | Returns/sets the current (selected) item. It is unique ID.
DebugContextMenu | If True, the standard Internet Explorer context menu is used instead of the control's context menu at run time, for debug purposes.
DesignTimeTemplates | If set to False, template modification is ignored in control display at design time.
EditedValue | Sets/returns the value of a constant being edited by a custom editor.
EditedValueText | Sets/returns the textual representation value of a constant being edited by a custom editor.
Editing | Returns a value indicating whether editing of a constant is in progress.
EditTypeChecking | Determines whether an error is raised when a constant value cannot be converted to the required type.
Enabled | Returns/sets a value that determines whether an object can respond to user-generated events.
ErrorItemID | Returns the unique ID of the item affected by an error condition.
Font | Returns/sets the font used in the control.
ForeColor | Returns/sets the foreground color used in the control.
FormatDate | Formatting string for date values.
FullFieldNames | If True, the control shows full dot-separated field names containing folder names.
Item | Object providing access to individual items (conditions and result fields) of the control.
ManualRender | If True, HTML rendering is performed by the C1QRender() function in the script defined in HTML Templates.
SchemaControl | Returns/sets the name of the C1Query control containing the schema and performing SQL generation.
SchemaControlObject | Returns/sets (at run time) the C1Query control containing the schema and performing SQL generation.
TabInQuery | If True, the Tab key navigates between the control's items rather than between different controls.
TemplateAttributes | Returns/sets the template attribute with specified name.
Templates | Returns/sets the string modifying HTML templates defining control's look and UI.
TemplateUserData | Custom template parameters.
TypedEditing | If set to True, the control uses special editors for data types such as date/time, boolean, numeric.
Wrap | Enables/disables wordwrap in the control. Used in C1QRender() script with ManualRender=True.

C1QueryFrame Object Methods

AddItem | Adds a new query item to the control.
Clear | Removes all query items from the control.
DeleteItem | Deletes a query item from the control.
ExitEdit | Ends editing of a constant.
FieldByID | Returns information about the folder field specified by its unique ID.
FieldNameToFieldID | Returns the field's unique schema ID given the field name.
GenerateHTML | Generates HTML for an item. Used in C1QRender() script with ManualRender=True.
GetItemIDAt | Returns the ID of the item at specified point coordinates (X,Y).
LoadFromXML | Loads query from a string.
LoadFromXMLFile | Loads query from a file.
LoadTemplatesFromFile | Loads templates from a file.
PerformMainMenuAction | Performs the action that would have been triggered by a main menu selection.
Render | Renders the current state of the query items on the control surface.
SaveToXML | Saves query to a string.
SaveToXMLFile | Saves query to a file.
SetCurrentElement | Makes an element current (selected) in the current item.
SetLookup | Retrieves lookup list of values from a data source.
SetTemplateAttribute | Modifies an attribute in HTML templates defining control's look and UI.
StartEdit | Activates editing of the active item's selected element.
VarTypeFromDataType | Returns the variant data type corresponding to a field data type.
WrapHTML | Adds the enclosing tags to an HTML representing an item. Used in C1QRender() script with ManualRender=True.

C1QueryFrame Object Events

AfterEdit | Occurs after a constant value has been modified by the user.
AfterMenu | Occurs after a menu item has been chosen from a menu.
AfterRender | Occurs when rendering is completed after change or Render call.
BeforeEdit | Occurs before editing a constant.
BeforeMenu | Occurs before a menu is opened.
BeforeSQLGeneration | Occurs before SQL generation and allows to change query items and syntax rules affecting resulting SQL.
Change | Occurs when an item element has been modified by the user.
Click | Occurs when the user presses and then releases a mouse button over the control.
DblClick | Occurs when the user doubleclicks the control with the mouse.
EndEdit | Occurs on closing a custom editor.
Error | Occurs as a result of an error condition.
HideCustomEditor | Occurs when a custom editor is being hidden.
ItemFocusChange | Occurs after a different item and/or item element becomes current.
KeyDown | Occurs when the user presses a key.
KeyPress | Occurs when the user presses and releases an ANSI key.
KeyUp | Occurs when the user releases a key.
LookupValues | Occurs before showing the lookup list for a field.
MenuSelected | Occurs when a menu item is selected.
MouseDown | Occurs when a mouse button is pressed.
MouseMove | Occurs when the mouse pointer is moved across the control.
MouseUp | Occurs when the user releases the mouse button.
ShowCustomEditor | Occurs when a custom editor is being activated
SQLGenerationItem | Occurs before an item is included into the resulting SQL statement.


Field Object

Field Object Properties

Alias | In data source mode, the alias of a field in the generated SQL statement.
DataSourceName | In data source mode, the name of a field in DataSource represented by this Field object.
DisplayName | Returns/sets the display name of the field represented by a Field object.
Exists | In data source mode, indicates whether the field specified in DataSourceName exists in DataSource.
Expression | Returns/sets the expression for a calculated field.
FullFolderName | Full dot-separated folder name of a field represented by this Field object.
HasLookup | Gets/sets whether the field has value list and whether LookupValues event should be fired for this field or not
Precision | Precision of a numeric field.
Size | Field's maximum data size.
TableName | The table name of a view field represented by this Field object.
Tag | Stores arbitrary additional information for the field.
Type | Field's data type.
ViewFieldName | The name of a view field represented by this Field object, or the name of a DataSourceFields field in data source mode.
ViewName | The view name of a view field represented by this Field object.


Fields Object

Fields Object Properties

Count | Returns the number of items in a collection.
Item | Returns a single collection item.

Fields Object Methods

Add | Adds a new item to the collection.
Remove | Removes an existing item from the collection.


QueryItem Object

QueryItem Object Properties

Advanced | Returns True if the item represents an advanced elementary condition.
Alias | For a result field, sets/returns an alias to be used in the resulting SQL statement.
Checked | Determines whether to include or ignore the specified query item.
ChildrenCount | Returns the number of child items.
Comparison | Returns/sets the comparison operation of an elementary condition item.
ComparisonAttributes | Comparison attributes of a query item.
ComparisonTemplate | Comparison template string of a query item.
Complex | Returns True if the item can contain other items.
Connective | Returns/sets the connective operation of a complex condition item.
CurrentElement | Returns the element of an item which is currently selected (in focus) in that item.
Function | Returns/sets the function of a result field query item.
FunctionAttributes | Function attributes of a result field query item.
FunctionTemplate | Function template string of a result field query item.
HasChildren | Returns the value indicating whether the item has children in the item tree.
HasNext | Returns the value indicating whether the item has next sibling in the item tree.
HasPrevious | Returns the value indicating whether the item has previous sibling in the item tree.
ID | Returns the ID of a query item uniquely identifying it in the query tree.
IndexInParent | Returns the index of a query item in its parent.
LeftFieldID | Returns/sets the unique schema ID for the field on the left side of a query item.
LeftSide | Returns/sets the textual representation of the left side of a query item.
LeftSideField | Returns/sets the Field object representing the left side of a query item.
LeftSideKind | Returns/sets the value that determines whether the left side of a query item is 'field' or 'constant'.
LeftSideValue | Returns/sets the value of the left side of a query item.
Level | Returns the level of a query item in the item tree.
ParentID | Returns the parent ID of the a query item.
RightFieldID | Returns/sets the unique schema ID for the field on the right side of a query item.
RightSide | Returns/sets the textual representation of the right side of a query item.
RightSideField | Returns/sets the Field object representing the right side of a query item.
RightSideKind | Returns/sets the value that determines whether the left side of a query item is 'field' or 'constant'.
RightSideValue | Returns/sets the textual representation of the right side of a query item.
Sort | Returns/sets the sort of a result field query item.
Tag | Stores arbitrary additional information accosiated with the query item.

QueryItem Object Methods

FindByID | Positions the Item object on the item specified by its unique ID in the item tree.
MoveToChild | Positions the Item object on the specified child item.
MoveToFirstChild | Positions the Item object on the first child of the item on which it is currently positioned.
MoveToNext | Positions the Item object on the next sibling of the item on which it is currently positioned.
MoveToPrevious | Positions the Item object on the previous sibling of the item on which it is currently positioned.
MoveToRoot | Positions the Item object on the root of the item tree.


SQLInfo Object

SQLInfo Object Properties

AddASToTableAlias | Sets/returns the value that determines whether the AS keyword is to be used before table alias.
AllowExpressionInGroupBy | If True, calculated fields can be used in GROUP BY.
CreateAliasForAggregatedField | If True, aliases are created for aggregated fields.
DateTimeQuote | Sets/returns the quotation mark used with date/time literals.
Distinct | Sets/returns the value that determines whether the DISTINCT keyword must be added to the generated SQL statement.
FieldQuote | Sets/returns the quotation mark used to quote field names containing special characters.
FieldQuoteCriteria | Sets/returns the flags that determines when a field name must be quoted.
FormatBooleanFalse | Sets/returns the custom format for boolean False value.
FormatBooleanTrue | Sets/returns the custom format for boolean True value.
FormatDate | Sets/returns the custom format for date literals
FormatFloat | Sets/returns the custom format for floating point literals.
FormatTime | Sets/returns the custom format for time literals.
LikePercent | Sets/returns the character to be used as wildcard matching zero or more characters.
LikeUnderscore | Sets/returns the character to be used as wildcard matching a single character.
MaxNameLength | Sets/returns the maximum name length allowed in generated SQL statement.
StringLiteralQuote | Sets/returns the quotation mark used with string literals.
Syntax | Sets/returns the value that determines the join syntax in generated SQL statement.
TableQuote | Sets/returns the quotation mark used to quote table names containing special characters.
TableQuoteCriteria | Sets/returns the flags that determines when a table name must be quoted.
UseFieldAliasInGroupBy | If True, calculated field's name or alias is used in GROUP BY, instead of the expression.
UseFieldAliasInOrderBy | If True, calculated field's name or alias is used in ORDER BY, instead of the expression.
UseFieldAliasInWhere | If True, calculated field's name or alias is used in WHERE, instead of the expression.
UseIndexInOrderBy | If True, column index is used in ORDER BY instead of column name.
UseNameAsFieldAlias | If True, a folder field's Name is used as the field's alias.


Property Reference


Quick Reference for All Properties

AddASToTableAlias | Sets/returns the value that determines whether the AS keyword is to be used before table alias.
Advanced | Returns True if the item represents an advanced elementary condition.
Alias | The alias of a field in the generated SQL statement.
Alias | For a result field, sets/returns an alias to be used in the resulting SQL statement.
AllowExpressionInGroupBy | If True, calculated fields can be used in GROUP BY.
ApplyExtensions | Determines how schema extensions can be applied if necessary in SQL generation.
BackColor | Returns/sets the background color of the control.
Border | Returns/sets a value that determines whether the control has 3D border.
Checkboxes | If set to True, checkbox is displayed in query items, its state defining whether to include or ignore the item.
Checked | Determines whether to include or ignore the specified query item.
Checked | Determines whether to include or ignore the specified query item.
ChildrenCount | Returns the number of child items.
ClauseFrom | Returns the FROM clause of the last generated SQL statement.
ClauseGroupBy | Returns the GROUP BY clause of the last generated SQL statement.
ClauseOrderBy | Returns the ORDER BY clause of the last generated SQL statement.
ClauseSelect | Returns the SELECT clause of the last generated SQL statement.
ClauseWhere | Returns the WHERE clause of the last generated SQL statement, or the Filter text in data source mode.
Comparison | Returns/sets the comparison operation of an elementary condition item.
ComparisonAttributes | Comparison attributes of a query item.
ComparisonTemplate | Comparison template string of a query item.
Complex | Returns True if the item can contain other items.
Connective | Returns/sets the connective operation of a complex condition item.
ContentsType | Returns/sets the type of the control, whether it is used for specifying conditions or result fields.
Count | Returns the number of items in a collection.
CreateAliasForAggregatedField | If True, aliases are created for aggregated fields.
CurrentElement | Returns the element of an item which is currently selected (in focus) in that item.
CurrentItemID | Returns/sets the current (selected) item, its unique ID.
DataMember | Sets/returns the DataMember for the OLE DB DataSource.
DataSource | Specifies the source of schema information in data source mode.
DataSourceFields | Returns the collection of Field objects in data source mode.
DataSourceName | In data source mode, the name of a field in DataSource represented by this Field object.
DateTimeQuote | Sets/returns the quotation mark used with date/time literals.
DebugContextMenu | If True, the standard Internet Explorer context menu is used instead of the control's context menu at run time, for debug purposes.
DesignTimeTemplates | If set to False, template modification is ignored in control display at design time.
DisplayName | Returns/sets the display name of the field represented by a Field object.
Distinct | Sets/returns the value that determines whether the DISTINCT keyword must be added to the generated SQL statement.
EditedValue | Sets/returns the value of a constant being edited by a custom editor.
EditedValueText | Sets/returns the textual representation value of a constant being edited by a custom editor.
Editing | Returns a value indicating whether editing of a constant is in progress.
EditTypeChecking | Determines whether an error is raised when a constant value cannot be converted to the required type.
Enabled | Returns/sets a value that determines whether an object can respond to user-generated events.
ErrorItemID | Returns the unique ID of the item affected by an error condition.
Exists | In data source mode, indicates whether the field specified in DataSourceName exists in DataSource.
Expression | Returns/sets the expression for a calculated field.
FieldQuote | Sets/returns the quotation mark used to quote field names containing special characters.
FieldQuoteCriteria | Sets/returns the flags that determines when a field name must be quoted.
FilterMode | If True, the control is in Filter mode.
Font | Returns/sets the font used in the control.
ForeColor | Returns/sets the foreground color used in the control.
FormatBooleanFalse | Sets/returns the custom format for boolean False value.
FormatBooleanTrue | Sets/returns the custom format for boolean True value.
FormatDate | Formatting string for date values.
FormatDate | Sets/returns the custom format for date literals.
FormatFloat | Sets/returns the custom format for floating point literals.
FormatTime | Sets/returns the custom format for time literals.
FullFieldNames | If True, the control shows full dot-separated field names containing folder names.
FullFolderName | Full dot-separated folder name of a field represented by this Field object.
Function | Returns/sets the function of a result field query item.
FunctionAttributes | Function attributes of a result field query item.
FunctionTemplate | Function template string of a result field query item.
HasChildren | Returns the value indicating whether the item has children in the item tree.
HasLookup | Gets/sets whether the field has value list and whether LookupValues event should be fired for this field or not.
HasNext | Returns the value indicating whether the item has next sibling in the item tree.
HasPrevious | Returns the value indicating whether the item has previous sibling in the item tree.
ID | Returns the ID of a query item uniquely identifying it in the query tree.
IndexInParent | Returns the index of a query item in its parent.
Item | Returns a single collection item.
Item | Object providing access to individual items (conditions and result fields) of the control.
LeftFieldID | Returns/sets the unique schema ID for the field on the left side of a query item.
LeftSide | Returns/sets the textual representation of the left side of a query item.
LeftSideField | Returns/sets the Field object representing the left side of a query item.
LeftSideKind | Returns/sets the value that determines whether the left side of a query item is 'field' or 'constant'.
LeftSideValue | Returns/sets the value of the left side of a query item.
Level | Returns the level of a query item in the item tree.
LikePercent | Sets/returns the character to be used as wildcard matching zero or more characters.
LikeUnderscore | Sets/returns the character to be used as wildcard matching a single character.
MainViewCount | Returns the number of main views in the schema.
MainViewName | Returns/sets the name of the currently active schema main view.
MainViewNames | Returns the name of a main view from the collection of the schema main views.
ManualRender | If True, HTML rendering is performed by the C1QRender() function in the script defined in HTML Templates.
MaxNameLength | Sets/returns the maximum name length allowed in generated SQL statement.
NameSubstitute | Used as a substitute for the control's Name property in environments that don't support standard property such as Name or Id.
ParentID | Returns the parent ID of the a query item.
Precision | Precision of a numeric field.
RightFieldID | Returns/sets the unique schema ID for the field on the right side of a query item.
RightSide | Returns/sets the textual representation of the right side of a query item.
RightSideField | Returns/sets the Field object representing the right side of a query item.
RightSideKind | Returns/sets the value that determines whether the left side of a query item is 'field' or 'constant'.
RightSideValue | Returns/sets the value of the right side of a query item.
SaveSchemaAsString | If True, schema is saved as string instead of byte array.
Schema | Returns/sets the control's schema as a string.
SchemaControl | Returns/sets the name of the C1Query control containing the schema and performing SQL generation.
SchemaControlObject | Returns/sets (at run time) the C1Query control containing the schema and performing SQL generation.
Size | Field's maximum data size.
Sort | Returns/sets the sort of a result field query item.
SQL | Returns the SQL statement generated by the last BuildSQL call.
SQLInfo | Object used for customizing SQL syntax settings and parameters.
StringLiteralQuote | Sets/returns the quotation mark used with string literals.
Syntax | Sets/returns the value that determines the join syntax in generated SQL statement.
TabInQuery | If True, the Tab key navigates between the control's items rather than between different controls.
TableName | The table name of a view field represented by this Field object.
TableQuote | Sets/returns the quotation mark used to quote table names containing special characters.
TableQuoteCriteria | Sets/returns the flags that determines when a table name must be quoted.
Tag | Stores arbitrary additional information for the field.
Tag | Stores arbitrary additional information accosiated with the query item.
TemplateAttributes | Returns/sets the template attribute with specified name.
Templates | Returns/sets the string modifying HTML templates defining control's look and UI.
TemplateUserData | Custom template parameters.
Type | Field's data type.
TypedEditing | If set to True, the control uses special editors for data types such as date/time, boolean, numeric.
UseFieldAliasInGroupBy | If True, calculated field's name or alias is used in GROUP BY, instead of the expression.
UseFieldAliasInOrderBy | If True, calculated field's name or alias is used in ORDER BY, instead of the expression.
UseFieldAliasInWhere | If True, calculated field's name or alias is used in WHERE, instead of the expression.
UseIndexInOrderBy | If True, column index is used in ORDER BY instead of column name.
UseNameAsFieldAlias | If True, a folder field's Name is used as the field's alias.
ViewFieldName | The name of a view field represented by this Field object, or the name of a DataSourceFields field in data source mode.
ViewName | The view name of a view field represented by this Field object.
Wrap | Enables/disables wordwrap in the control. Used in C1QRender() script with ManualRender=True.

AddASToTableAlias Property

Advanced Property

Alias Property (Field)

Alias Property (QueryItem)

AllowExpressionInGroupBy Property

ApplyExtensions Property

BackColor Property

Border Property

Checkboxes Property

Checked Property (C1QueryFrame)

Checked Property (QueryItem)

ChildrenCount Property

ClauseFrom Property

ClauseGroupBy Property

ClauseOrderBy Property

ClauseSelect Property

ClauseWhere Property

Comparison Property

ComparisonAttributes Property

ComparisonTemplate Property

Complex Property

Connective Property

ContentsType Property

Count Property

CreateAliasForAggregatedField Property

CurrentElement Property

CurrentItemID Property

DataMember Property

DataSource Property

DataSourceFields Property

DataSourceName Property

DateTimeQuote Property

DebugContextMenu Property

DesignTimeTemplates Property

DisplayName Property

Distinct Property

EditedValue Property

EditedValueText Property

Editing Property

EditTypeChecking Property

Enabled Property

ErrorItemID Property

Exists Property

Expression Property

FieldQuote Property

FieldQuoteCriteria Property

FilterMode Property

Font Property (C1QueryFrame)

ForeColor Property

FormatBooleanFalse Property

FormatBooleanTrue Property

FormatDate Property

FormatDate Property (SQLInfo)

FormatFloat Property

FormatTime Property

FullFieldNames Property

FullFolderName Property

Function Property

FunctionAttributes Property

FunctionTemplate Property

HasChildren Property

HasLookup Property

HasNext Property

HasPrevious Property

IndexInParent Property

ID Property

Item Property (C1QueryFrame)

Item Property

LeftFieldID Property

LeftSide Property

LeftSideField Property

LeftSideKind Property

LeftSideValue Property

Level Property

LikePercent Property

LikeUnderscore Property

MainViewCount Property

MainViewName Property

MainViewNames Property

ManualRender Property

MaxNameLength Property

NameSubstitute Property

ParentID Property

Precision Property

RightFieldID Property

RightSide Property

RightSideField Property

RightSideKind Property

RightSideValue Property

SaveSchemaAsString Property

Schema Property

SchemaControl Property

SchemaControlObject Property

Size Property

Sort Property

SQL Property

SQLInfo Property

StringLiteralQuote Property

Syntax Property

TabInQuery Property

TableName Property

TableQuote Property

TableQuoteCriteria Property

Tag Property (Field)

Tag Property (QueryItem)

TemplateAttributes Property

Templates Property

TemplateUserData Property

Type Property

TypedEditing Property

UseFieldAliasInGroupBy Property

UseFieldAliasInOrderBy Property

UseFieldAliasInWhere Property

UseIndexInOrderBy Property

UseNameAsFieldAlias Property

ViewFieldName Property

ViewName Property

Wrap Property


AddASToTableAlias Property

Syntax

C1Query.SQLInfo.AddASToTableAlias = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

Specifies whether to add the AS keyword before table alias, as in

SELECT … FROM table AS a_table …

See Also

SQL Syntax Properties


Advanced Property

Syntax

C1QueryFrame.Item.Advanced

Notes

Read-only at run time. Unavailable at design time. Type: Boolean. Property applies to QueryItem object.

Description

This property returns True if the item represents an advanced elementary condition, one that can have fields on the left and right side, as opposed to a simple elementary condition that always has field on the left side. This property applies to condition items. For result field items, it is always False. This property is read-only, it cannot be changed at run time. If you create an item with C1QueryFrame.AddItem method, its ConditionType argument specifies whether the item is an elementary or an advanced elementary condition.

See Also

Accessing and Modifying Query Items


Alias Property (Field)

Syntax

Field.Alias = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to Field object.

Description

This property determines the alias of the field in the SQL statement, as in

SELECT …, field AS alias, … FROM …

By default, it returns the Alias name specified for a view field in Schema Designer. Setting this property at run time changes the alias used in generated SQL statements for all folder fields representing the same view field.

This property has a special meaning in DataSource mode, if FilterMode=True. In that case, it determines the name by which the field appears in the Filter condition (in ClauseWhere).

See Also

Folders

Customizing the DataSourceFields collection


Alias Property (QueryItem)

Syntax

C1QueryFrame.Item.Alias = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property applies only to result field items. It determines the alias of the field in the SQL statement, as in

SELECT …, field AS alias, … FROM …

By default, it returns the Alias name specified for a view field in Schema Designer.

See Also

Accessing and Modifying Query Items


AllowExpressionInGroupBy Property

Syntax

C1Query.SQLInfo.AllowExpressionInGroupBy = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

Specifies whether the SQL dialect supported by the target database allows calculated fields (expressions) in GROUP BY, as in

SELECT …, A + B,… FROM … GROUP BY A + B

See Also

SQL Syntax Properties


ApplyExtensions Property

Syntax

C1Query.ApplyExtensions = value

Notes

Read/Write at run time and design time. Property applies to C1Query control.

Values

Constant Value | Name
0 | c1qExtensionsDisabled
1 | c1qExtensionsEnabled
2 | c1qAutoExtensionsRestricted (default)
3 | c1qAutoExtensionsUnrestricted

Description

This property determines the actions that C1Query engine takes when a user query is incomplete, i.e., the views (tables) specified by the user cannot be connected with relationships and/or join groups to form a single SQL statement. If allowed, C1Query can complete the query, adding some views to the query in addition to the views selected by the end user. This can be done using schema extensions (extensions explicitly specified in the schema), and, if necessary, using autoextension (adding views implicitly). Using schema extensions is tried first, if allowed, and only if this fails C1Query uses autoextension (if allowed).

When this property is set to 0 – c1qExtensionsDisabled, no extensions are used. C1Query does not add any views not explicitly specified by the end user.

When this property is set to 1 – c1qExtensionsEnabled, C1Query applies extensions specified in the schema, if necessary. Autoextension is not applied.

When this property is set to 2 – c1qAutoExtensionsRestricted, C1Query applies schema extensions and autoextension, if necessary. However, the main view (the one to which all other views are joined) must be one of the views explicitly specified by the user. If the user does not specify such main view, C1Query does not attempt to find it adding more views.

When this property is set to 3 – c1qAutoExtensionsUnrestricted, C1Query applies schema extensions and autoextension, if necessary, without the above restriction. That is, if all other attempts failed, and C1Query finds a view that can play the role of the main view for this query, it is allowed to add this view to the query.

See Also

Managing Query Extensions


BackColor Property

Syntax

C1QueryFrame.BackColor = color

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property controls the background color of the control. Colors may be specified as RGB values or system default colors.

This property defines the color inherited by default by all query item elements. Colors and other display attributes of any specific element can be customized and defined separately in template attributes, see Customizing UI with Templates.


Border Property

Syntax

C1QueryFrame.Border = boolean

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property determines whether the control has 3D border.

Changing this property does not take effect immediately. For this property to take effect, at design time – close and re-open the form, at run time – call the Render method.


Checkboxes Property

Syntax

C1QueryFrame.Checkboxes = boolean

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property is False by default. If set to True, checkbox is displayed in query items, its state defining whether to include or ignore the item

See Also

Including/excluding Query Items in the Resulting SQL


Checked Property (C1QueryFrame)

Syntax

C1QueryFrame.Checked(ItemId) = boolean

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property determines whether to include or ignore the query item specified by its ItemId in the resulting SQL statement. It has exactly the same effect as Checked property.

See Also

Including/excluding Query Items in the Resulting SQL


Checked Property (QueryItem)

Syntax

C1QueryFrame.Item.Checked = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property determines whether to include or ignore the query item in the resulting SQL statement. It has exactly the same effect as Checked property.

See Also

Including/excluding Query Items in the Resulting SQL


ChildrenCount Property

Syntax

C1QueryFrame.Item.ChildrenCount

Notes

Read-only at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property returns the number of child items of a query item.

See Also

Accessing and Modifying Query Items


ClauseFrom Property

Syntax

C1Query.ClauseFrom

Notes

Read-only at run time. Unavailable at design time. Type: String. Property applies to C1Query control.

Description

This property returns the FROM clause of the last generated SQL statement.

See Also

SQL

ClauseSelect

ClauseWhere

ClauseGroupBy

ClauseOrderBy


ClauseGroupBy Property

Syntax

C1Query.ClauseGroupBy

Notes

Read-only at run time. Unavailable at design time. Type: String. Property applies to C1Query control.

Description

This property returns the GROUP BY clause of the last generated SQL statement.

See Also

SQL

ClauseSelect

ClauseFrom

ClauseWhere

ClauseOrderBy


ClauseOrderBy Property

Syntax

C1Query.ClauseOrderBy

Notes

Read-only at run time. Unavailable at design time. Type: String. Property applies to C1Query control.

Description

This property returns the ORDER BY clause of the last generated SQL statement.

See Also

SQL

ClauseSelect

ClauseFrom

ClauseWhere

ClauseGroupBy


ClauseSelect Property

Syntax

C1Query.ClauseSelect

Notes

Read-only at run time. Unavailable at design time. Type: String. Property applies to C1Query control.

Description

This property returns the SELECT clause of the last generated SQL statement.

See Also

SQL

ClauseFrom

ClauseWhere

ClauseGroupBy

ClauseOrderBy


ClauseWhere Property

Syntax

C1Query.ClauseWhere

Notes

Read-only at run time. Unavailable at design time. Type: String. Property applies to C1Query control.

Description

This property returns the WHERE clause of the last generated SQL statement.

See Also

SQL

ClauseSelect

ClauseFrom

ClauseGroupBy

ClauseOrderBy.


Comparison Property

Syntax

C1QueryFrame.Item.Comparison = value

Notes

Read-write at run time. Unavailable at design time. Property applies to QueryItem object.

Values

Constant Value | Name | Meaning
0 | c1qComparisonEQ | = (equal)
1 | c1qComparisonGT | >= (greater than)
2 | c1qComparisonLT | < (less than)
3 | c1qComparisonGE | >= (greater than or equal)
4 | c1qComparisonLE | <= (less than or equal)
5 | c1qComparisonNEQ | <> (not equal)
6 | c1qComparisonIsNull | is NULL
7 | c1qComparisonIsNotNull | is not NULL
8 | c1qComparisonContains | contains
9 | c1qComparisonStartsWith | starts with

Description

This property returns/sets the comparison operation of an elementary condition item. Not all comparisons are applicable to all data types: “contains: and “starts with” are only applicable to strings; booleans can only be compared with = and <>.

See Also

Accessing and Modifying Query Items


ComparisonAttributes Property

Syntax

C1QueryFrame.Item.ComparisonAttributes = string

Notes

Read-write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property returns/sets a string containing all atttributes describing the comparison operation used in a condition item. See attribute list in Custom Comparison Operators.

Setting this property at run time, developers can specify or change any comparison attributes (affecting user query appearance and generated SQL) for each query item independently. In this case, there is no need to define a custom comparison operator. Each item can have its own comparison attributes: Caption, Text, Enabled and Template.

See Also

Specifying Function and Comparison Attributes for a Particular Query Item

ComparisonTemplate


ComparisonTemplate Property

Syntax

C1QueryFrame.Item.ComparisonTemplate = string

Notes

Read-write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property determines the Template attribute of a condition item’s comparison operator. It determines the SQL condition generated in the resulting SQL statement for this item.

For more information, see Specifying Function and Comparison Attributes for a Particular Query Item.

See Also

ComparisonAttributes


Complex Property

Syntax

C1QueryFrame.Item.Complex

Notes

Read-only at run time. Unavailable at design time. Type: Boolean.
Property applies to QueryItem object.

Description

This property returns True if the item represents a complex condition, one that contains elementary conditions connecting them with one of the four connectives (all, any, not all, none). This property applies to condition items. For result field items, it is always False. This property is read-only, it cannot be changed at run time. If you create an item with C1QueryFrame.AddItem method, its ConditionType argument specifies whether the item is a complex or an elementary condition.

See Also

Accessing and Modifying Query Items


Connective Property

Syntax

C1QueryFrame.Item.Connective = value

Notes

Read-write at run time. Unavailable at design time. Property applies to QueryItem object.

Values

Constant Value and Name | Meaning
1 – c1qConnectiveAnd | AND (all conditions are True)
2 – c1qConnectiveOr | OR (any one of the conditions is True)
3 – c1qConnectiveNone | Not (OR) (none of the conditions is True)
4 – c1qConnectiveNotAll | Not (AND) (some condition is False)

Description

This returns/sets the connective of a complex condition item.

See Also

Accessing and Modifying Query Items


ContentsType Property

Syntax

C1QueryFrame.ContentsType = value

Notes

Read-write at run time. Unavailable at design time. Property applies to C1QueryFrame control.

Values

Constant Value | Name
1 | c1qCondition
2 | c1qResultFields

Description

This property determines whether the C1QueryFrame control’s items represent filter conditions of the query, or the query’s result fields. You can associate either one or two C1QueryFrame controls with a single C1Query control. If there are two associated controls, one of them must display filter conditions, the other – result fields. If there is no C1QueryFrame control with result fields, C1Query generates a SELECT * statement, selecting all fields from the tables appearing in the query.

See Also

C1QueryFrame Control.


Count Property

Syntax

collection.Count

Notes

Read-only at run time. Not available at design time. Type: Long. Property applies to DataSourceFields collection.

Description

This property returns the number of items in a collection.

Collections are zero-based, which means that the items in a collection are indexed from 0 to Count - 1.


CreateAliasForAggregatedField Property

Syntax

C1Query.SQLInfo.CreateAliasForAggregatedField = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

If this property is set to True (default), C1Query creates an alias for fields with aggregation. For example: alias Sum_of_Price for SUM(Price). This is the normal behavior and you may need to override it only for databases that don’t support aliases for aggregated fields. In this case, to avoid syntax errors on SQL execution, set this property to False.

See Also

SQL Syntax Properties


CurrentElement Property

Syntax

C1QueryFrame.Item.CurrentElement

Notes

Read-only at run time. Unavailable at design time. Type: Enumeration. Property applies to QueryItem object.

Values

Constant Value and Name | Meaning
0 – c1qElemTypeNone | No element in focus
1 – c1qElemTypeConn | Connective in a complex condition
2 – c1qElemTypeLS | Left side of an elementary condition item, or field in a result field item
3 – c1qElemTypeComp | Comparison in elementary condition
4 – c1qElemTypeRS | Right side of elementary condition
5 – c1qElemTypeLSKind | Left side kind in advanced elementary condition
6 – c1qElemTypeRSKind | Right side kind in advanced elementary condition
7 – c1qElemTypeSort | Sort in a result field item
8 – c1qElemTypeFunction | Function in a result field item

Description

This property returns the item’s element in focus, that is, currently selected by the user. This property is read-only, to change the element selected in the current item, call the SetCurrentElement method.

See Also

Accessing and Modifying Query Items


CurrentItemID Property

Syntax

C1QueryFrame.CurrentItemID = long

Notes

Read-write at run time. Unavailable at design time. Property applies to C1QueryFrame control.

Description

This property returns the unique ID of the item in focus, currently selected by the user. See Accessing and Modifying Query Items for information on accessing query items by their ID.

Setting this property changes user selection, moves focus to the specified item.


DataMember Property

Syntax

C1Query.DataMember = string

Notes

Read/Write at design time and run time. Property applies to C1Query control.

Description

This property qualifies the DataSource property setting for ADO/OLE DB data sources exposing multiple recordsets. It defines which recordset (member) is used.

See Also

DataSource property


DataSource Property

Syntax

Set C1Query.DataSource = object

Notes

Read/Write at design time and run time.
Property applies to C1Query control.

Description

This property specifies is used to bind a C1Query control to an ADO/OLE DB data source, such as ComponentOne True DataControl, an ADODC control or Visual Basic DataEnvironment.

Leave this property empty, if you want to use the C1Query control in a regular way, with schema. If the DataSource property is non-empty, the C1Query control functions in a special mode, where it ignores the schema and takes the field information directly from the DataSource. See Simple Queries - DataSource Mode for details.

See Also

DataMember property

DataSourceFields property


DataSourceFields Property

Syntax

C1Query.DataSourceFields

Notes

Read-only at run time. Not available at design time. Property applies to C1Query control.

Description

In DataSource mode, this property returns a collection of Field objects defining the selection of fields available to the end user. If the DataSourceFields collection is empty at startup time or on setting the DataSource property, it is filled automatically with Field objects retrieved from the DataSource recordset. You can fill this collection in code if you want to modify the selection of fields available to the end user.

See Also

Customizing the DataSourceFields collection


DataSourceName Property

Syntax

Field.DataSourceName = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to Field object.

Description

This property applies to DataSource mode. It determines the field in the DataSource recordset represented by this Field object.

See Also

Customizing the DataSourceFields collection


DateTimeQuote Property

Syntax

C1Query.SQLInfo.DateTimeQuote = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Values

Constant Value and Name | Meaning
0 – c1qQuoteNone | No quotation
1 – c1qQuoteSingle | ‘…’
2 – c1qQuoteDouble | “…”
3 – c1qQuoteBrackets | […]
4 – c1qQuoteSharp | #…#

Description

This property sets/returns the quotation mark used with date/time literals.

See Also

SQL Syntax Properties


DebugContextMenu Property

Syntax

C1QueryFrame.DebugContextMenu = boolean

Notes

Read/Write at design time, read-only at run time.
Property applies to C1QueryFrame control.

Description

This property is used only for debug purposes. Sometimes, when you customize user interface with script, you will want to see the generated HTML code. It can be done with the View Source option of the standard Internet Explorer context menu. However, the standard context menu is normally overridden by the C1QueryFrame context menu (main menu). To enable the standard context menu, set this property to True.

See Also

Customizing UI with Scripts


DesignTimeTemplates Property

Syntax

C1QueryFrame.DesignTimeTemplates = boolean

Notes

Read/Write at design time. Unavailable at run time. Property applies to C1QueryFrame control.

Description

This property is used in customizing user interface with scripts. If your script uses dynamic data known only at run time (for example, using the TemplateUserData property), set this property to False to prevent the control from displaying garbled image at design time. The property has no effect on run time behavior.

See Also

Customizing UI with Scripts

TemplateUserData property


DisplayName Property

Syntax

Field.DisplayName = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to Field object.

Description

This property determines the field's name as it appears in the field menu and in query items.


Distinct Property

Syntax

C1Query.SQLInfo.Distinct = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

Setting this property to True adds the DISTINCT keyword to the generated SQL statement. Default: False.

See Also

SQL Syntax Properties


EditedValue Property

Syntax

C1QueryFrame.EditedValue = Variant

Notes

Read/Write at run time. Unavailable at design time. Property applies to C1QueryFrame control.

Description

This property can be used while editing constant values (when Editing=True) to programmatically set the value stored in the query item. Normally, setting this property is not necessary. The new value will be assigned to the item’s RightSideValue/LeftSideValue in the end of the editing process, without setting this property. However, if you want to keep the values in the item synchronized with the value entered by the user at all times, you can set the EditedValue, EditedValueText properties from code.

See Also

EditedValueText property

Editing values


EditedValueText Property

Syntax

C1QueryFrame.EditedValueText = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to C1QueryFrame control.

Description

This property can be used while editing constant values (when Editing=True) to programmatically set the constant’s textual representation stored in the query item. Normally, setting this property is not necessary. The new value will be assigned to the item’s RightSide/LeftSide in the end of the editing process, without setting this property. However, if you want to keep the values and texts in the item synchronized with the value entered by the user at all times, you can set the EditedValueText, EditedValue properties from code.

See Also

EditedValue property

Editing values


Editing Property

Syntax

C1QueryFrame.Editing

Notes

Read-only at run time. Unavailable at design time. Type: Boolean.
Property applies to C1QueryFrame control.

Description

This property indicates whether the control is in edit mode, that is, whether the end user is editing a constant value.

See Also

Editing values


EditTypeChecking Property

Syntax

C1QueryFrame.EditTypeChecking = boolean

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property determines whether an error is raised when a constant value cannot be converted to the required type. If it is set to True (default), the value of a constant entered by the user is always converted to the field type, and an error is raised if such conversion is impossible. If it is set to False, conversion is not performed.

See Also

Type Checking in Condition Items


Enabled Property

Syntax

C1QueryFrame.Enabled = boolean

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property determines whether the control can respond to end-user interaction.


ErrorItemID Property

Syntax

C1QueryFrame.ErroritemID

Notes

Read-only at run time. Unavailable at design time. Type: Long. Property applies to C1QueryFrame control.

Description

This property has a meaningful value only an Error event procedure. It returns the unique ID of the item that has triggered the error condition, if such an item was identified. Outside Error event, and for errors that cannot be localized in a particular item, the value of this property is –1.

See Also

Error event


Exists Property

Syntax

Field.Exists

Notes

Read-only at run time. Unavailable at design time. Type: Boolean. Property applies to Field object.

Description

This property returns True if the field specified by the DataSourceName property exists in the DataSource recordset, and False otherwise.

See Also

Customizing the DataSourceFields collection


Expression Property

Syntax

Field.Expression = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to Field object.

Description

This property determines the expression used for a calculated field in the generated SQL statement. It has effect only for calculated fields. Setting this property at run time changes the SQL expression for a calculated field for all folder fields referring to the same view field.

See Also

Views


FieldQuote Property

Syntax

C1Query.SQLInfo.FieldQuote = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Values

Constant Value and Name | Meaning
0 – c1qQuoteNone | No quotation
1 – c1qQuoteSingle | ‘…’
2 – c1qQuoteDouble | “…”
3 – c1qQuoteBrackets | […]
4 – c1qQuoteSharp | #…#

Description

This property sets/returns the quotation mark used to escape field names containing special characters.

See Also

FieldQuoteCriteria property

SQL Syntax Properties


FieldQuoteCriteria Property

Syntax

C1Query.SQLInfo.FieldQuoteCriteria = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Values

This property can be a combination (sum) of the following values (including 0, meaning that quotation is never applied),

Constant Value and Name | Meaning
1 – c1qQuoteBlanks | Quote only if there are blanks in the name
2 – c1qQuoteNonAlpha | Quote if there are non-alphanumeric characters in the name
4 – c1qQuoteExtendedASCII | Quote if there are extended ASCII (non-English) characters in the name
8 – c1qQuoteAlways | Quote always

Description

This property determines the criteria when field names must be quoted. Default: c1qQuoteBlanks + c1qQuoteNonAlpha.

See Also

FieldQuote property

SQL Syntax Properties


FilterMode Property

Syntax

C1QueryFrame.FilterMode = boolean

Notes

Read/Write at run time and design time. Property applies to C1Query control.

Description

This property determines whether the control uses normal SQL syntax rules generating the WHERE condition (if FilterMode=False, default), or the ADO Filter rules. Setting this property to True is most useful in (but not restricted to) DataSource mode.

See Also

Simple Queries - DataSource Mode


Font Property (C1QueryFrame)

Syntax

C1QueryFrame.Font = font

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property defines the font used in the control.

This property defines the font inherited by default by all query item elements. Fonts and other display attributes of any specific element can be customized and defined separately in template attributes, see Customizing UI with Templates.


ForeColor Property

Syntax

C1QueryFrame.ForeColor = color

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property controls the text color of the control. Colors may be specified as RGB values or system default colors.

This property defines the color inherited by default by all query item elements. Colors and other display attributes of any specific element can be customized and defined separately in template attributes, see Customizing UI with Templates.


FormatBooleanFalse Property

Syntax

C1Query.SQLInfo.FormatBooleanFalse = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

This property determines the string that is used in the generated SQL statement to represent the boolean value False.

See Also

FormatBooleanTrue property

SQL Syntax Properties


FormatBooleanTrue Property

Syntax

C1Query.SQLInfo.FormatBooleanTrue = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

This property determines the string that is used in the generated SQL statement to represent the boolean value True.

See Also

FormatBooleanFalse property

SQL Syntax Properties


FormatDate Property

Syntax

C1QueryFrame.FormatDate = string

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Values

Constant Value and Name | Meaning
0 - c1qFormatLongDate | Long date without time
1 - c1qFormatLongDateTime | Long date with time
2 - c1qFormatShortDate | Short date without time
3 - c1qFormatShortDateTime | Short date with time

Description

This property specifies the date format used in the C1QueryFrame control displaying date values.

See Also

Default Editing


FormatDate Property (SQLInfo)

Syntax

C1Query.SQLInfo.FormatDate = string

Description

This property specifies the format string for date values applied when a constant (literal) date value is written to the generated SQL statement. The representation of the date in the SQL statement is obtained by formatting the date value using the Visual Basic Format function.

Possible values for this property are all valid format strings as in the Visual Basic Format function, applicable to dates, and also two additional values:

“Default” – values are formatted using the default Windows rules (as in Visual Basic function CStr), according to the current regional settings.

“US Default” – values are formatted as in regional setting “English (United States)”.

Empty string is equivalent to “Default”.

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object. FormatDate/FormatFloat/FormatTime properties have effect only in a Visual Basic application. Using C1Query in containers other than Visual Basic, you need to use the FormatLiteral event.

See Also

SQL Syntax Properties


FormatFloat Property

Syntax

C1Query.SQLInfo.FormatFloat = string

Description

This property specifies the format string for floating point numeric values applied when a constant (literal) date value is written to the generated SQL statement. The representation of the date in the SQL statement is obtained by formatting the numeric value using the Visual Basic Format function.

Possible values for this property are all valid format strings as in the Visual Basic Format function, applicable to numeric values, and also two additional values:

“Default” – values are formatted using the default Windows rules (as in Visual Basic function CStr), according to the current regional settings.

“US Default” – values are formatted as in regional setting “English (United States)”.

Empty string is equivalent to “Default”.

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object. FormatDate/FormatFloat/FormatTime properties have effect only in a Visual Basic application. Using C1Query in containers other than Visual Basic, you need to use the FormatLiteral event.

See Also

SQL Syntax Properties


FormatTime Property

Syntax

C1Query.SQLInfo.FormatTime = string

Description

This property specifies the format string for time values applied when a constant (literal) time value is written to the generated SQL statement. The representation of the time in the SQL statement is obtained by formatting the time value using the Visual Basic Format function.

Possible values for this property are all valid format strings as in the Visual Basic Format function, applicable to time values, and also two additional values:

“Default” – values are formatted using the default Windows rules (as in Visual Basic function CStr), according to the current regional settings.

“US Default” – values are formatted as in regional setting “English (United States)”.

Empty string is equivalent to “Default”.

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object. FormatDate/FormatFloat/FormatTime properties have effect only in a Visual Basic application. Using C1Query in containers other than Visual Basic, you need to use the FormatLiteral event.

See Also

SQL Syntax Properties


FullFieldNames Property

Syntax

C1QueryFrame.FullFieldNames = string

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

If this property is set to True, full dot-separated names including full folder name are used in query display.

If it is set to False (default), only the field’s Name is shown.

If you specify meaningful descriptive Name for every field in the schema, and keep these descriptive names unique, so there are no two fields with the same Name in different folders, then it is recommended to keep the default False value for this property.

See Also

Folders


FullFolderName Property

Syntax

Field.FullFolderName

Notes

Read-only at run time (unless in DataSource mode). Unavailable at design time. Type: String. Property applies to Field object.

Description

This property returns full dot-separated folder name of a field represented by the Field object

In DataSource mode, for a Field object belonging to the DataSourceFields collection, this property can be set, changing the name of the field as it is shown to the end user. In all other cases, this property is read-only.


Function Property

Syntax

C1QueryFrame.Item.Function = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Values

Constant Value and Name | Meaning
0 – c1qAsIs | No function
1 – c1qSUM | SUM
2 – c1qCOUNT | COUNT
3 – c1qAVERAGE | AVERAGE
4 – c1qMIN | MIN
5 – c1qMAX | MAX

Description

This property is only applicable to result field items. It returns/sets the aggregation function applied to the result field.

See Also

Accessing and Modifying Query Items


FunctionAttributes Property

Syntax

C1QueryFrame.Item.FunctionAttributes = string

Notes

Read-write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property returns/sets a string containing all atttributes describing the function used in a result field item. See attribute list in Custom Functions.

Setting this property at run time, developers can specify or change any function attributes (affecting user query appearance and generated SQL) for each query item independently. In this case, there is no need to define a custom function. Each item can have its own function attributes: Caption, Text, Enabled, Aggregation and Template.

See Also

Specifying Function and Comparison Attributes for a Particular Query Item

FunctionTemplate


FunctionTemplate Property

Syntax

C1QueryFrame.Item.FunctionTemplate = string

Notes

Read-write at run time. Unavailable at design time.
Property applies to QueryItem object.

Description

This property determines the Template attribute of a result field item’s function. It determines the SQL expression generated in the SELECT clause of the resulting SQL statement for this item.

For more information, see Specifying Function and Comparison Attributes for a Particular Query Item.

See Also

FunctionAttributes


HasChildren Property

Syntax

C1QueryFrame.Item.HasChildren

Notes

Read-only at run time. Unavailable at design time. Type: Boolean. Property applies to QueryItem object.

Description

This property returns True if the item represents a complex condition with one or more conditions (children) inside, and False in all other cases. If this property is True, you can call the MoveToFirstChild method to position on the first child.

See Also

Accessing and Modifying Query Items


HasLookup Property

Gets/sets whether the field has value list and whether LookupValues event should be fired for this field or not.

Syntax

Field.HasLookup

See Also

Field Object


HasNext Property

Syntax

C1QueryFrame.Item.HasNext

Notes

Read-only at run time. Unavailable at design time. Type: Boolean. Property applies to QueryItem object.

Description

This property returns True if the item is not the last child of its parent. If this property is True, you can call the MoveToNext method to position to the next item.

See Also

Accessing and Modifying Query Items


HasPrevious Property

Syntax

C1QueryFrame.Item.HasPrevios

Notes

Read-only at run time. Unavailable at design time. Type: Boolean.Property applies to QueryItem object.

Description

This property returns True if the item is not the first child of its parent. If this property is True, you can call the MoveToPrevious method to position to the previous item.

See Also

Accessing and Modifying Query Items


IndexInParent Property

Syntax

C1QueryFrame.Item.IndexInParent

Notes

Read-only at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property returns the index of a query item in its parent item.

See Also

Accessing and Modifying Query Items


ID Property

Syntax

C1QueryFrame.Item.ID

Notes

Read-only at run time. Unavailable at design time. Type: Long. Property applies to QueryItem object.

Description

This property returns the unique ID identifying the item in the query tree.

See Also

Accessing and Modifying Query Items


Item Property (C1QueryFrame)

Syntax

C1QueryFrame.Item

Notes

Read-only at run time. Unavailable at design time. Property applies to C1QueryFrame control.

Description

This property returns the QueryItem object used to programmatically navigate and access query items.

See Also

Accessing and Modifying Query Items


Item Property

Syntax

collection.Item (index)

Arguments

index is an expression that specifies the collection member to be accessed.

Return Value

A reference to the specified object.

Description

Use the Item property to access a specific member of a collection. All collections accept a zero-based index argument.

Notes

The Item property is not required. The following expressions are equivalent:

C1Query.DataSourceFields.Item(0)

C1Query.DataSourceFields(0)

Property applies to DataSourceFields collection.


LeftFieldID Property

Syntax

C1QueryFrame.Item.LeftFieldID = long

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property returns/set the unique id identifying the folder field on the left side of an elementary condition item or the field in a result field item. To access the corresponding Field object and its properties, use the LeftSideField property.

See Also

Accessing and Modifying Query Items


LeftSide Property

Syntax

C1QueryFrame.Item.LeftSide = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property returns/set the text on the left side of an item. This is a field name shown on the left side of an elementary condition item or in a result field item, or the left side of an advanced elementary condition item.

Changing the LeftSide property has no effect on the actual field (or value, in case of an advanced condition item) specified in the item, which is determined by the LeftFieldID property. This can be used to customize texts on display.

See Also

Accessing and Modifying Query Items


LeftSideField Property

Syntax

C1QueryFrame.Item.LeftSideField

Notes

Read-only at run time. Unavailable at design time. Type: Field. Property applies to QueryItem object.

Description

This property returns the Field object representing the folder field on the left side of an elementary condition item or the field in a result field item.

See Also

Accessing and Modifying Query Items


LeftSideKind Property

Syntax

C1QueryFrame.Item.LeftSideKind = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Values

Constant Value and Name | Meaning
1 – c1qConstant | Constant value
2 – c1qField | Field

Description

This property is only applicable to advanced elementary condition items. It determines whether the left side of the item is a constant (c1qConstant) or a field (c1qField).

See Also

Accessing and Modifying Query Items


LeftSideValue Property

Syntax

C1QueryFrame.Item.LeftSideValue = Variant

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property is only applicable to advanced elementary condition items (simple elementary conditions have a field, not a constant on the left side). This property returns/set the value on the left side of an item, if LeftSideKind=c1qConstant.

The text shown on the left side can differ from the actual value, which allows customization of display texts, see LeftSide property.

See Also

Accessing and Modifying Query Items


Level Property

Syntax

C1QueryFrame.Item.Level

Notes

Read-only at run time. Unavailable at design time. Type: Field.
Property applies to QueryItem object.

Description

This property returns the nesting level of a condition item. The root item has level 0, children of the root item have level 1, their children have level 2, and so on.

For result field items, this property always returns 1.

See Also

Accessing and Modifying Query Items.


LikePercent Property

Syntax

C1Query.SQLInfo.LikePercent = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

This property specifies the character to be used as wildcard matching zero or more characters. The standard SQL wildcard is % (percent sign). Some SQL dialects use other wildcards. For example, Microsoft Access uses * (asterisk).

See Also

SQL Syntax Properties


LikeUnderscore Property

Syntax

C1Query.SQLInfo.LikeUnderscore = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

This property specifies the character to be used as wildcard matching a single character. The standard SQL wildcard is _ (underscore). Some SQL dialects use other wildcards. For example, Microsoft Access uses ? (question mark).

See Also

SQL Syntax Properties


MainViewCount Property

Syntax

C1Query.MainViewCount

Notes

Read-only at run time and design time. Type: Long. Property applies to C1Query control.

Description

This property returns the number of viewsets (sub-schemas) in a multi-viewset schema. A multi-viewset schema is a schema consisting of multiple sets of views independent of each other. Views belonging to different viewsets cannot be joined together in a single SQL statement.

See Also

MainViewName property

MainViewNames property

Modifying Schema and Field List at Run Time


MainViewName Property

Syntax

C1Query.MainViewName = string

Notes

Read/Write at run time and design time. Property applies to C1Query control.

Description

This property sets/returns the main view name identifying the currently active viewset (sub-schema) in a multi-viewset schema. A multi-viewset schema is a schema consisting of multiple sets of views independent of each other. Views belonging to different viewsets cannot be joined together in a single SQL statement. Only fields belonging to the active viewset will be shown to the end user in the associated C1QueryFrame controls.

Set the MainViewName property when you need to switch from one viewset to another.

See Also

MainViewCount property

MainViewNames property

Modifying Schema and Field List at Run Time


MainViewNames Property

Syntax

C1Query.MainViewNames (index)

Notes

Property applies to C1Query collection.

Arguments

index is an integer index from 0 to MainViewCount.

Return Value

The name of the main view of a viewset. This name uniquely identifies a viewset (sub-schema).

Description

A multi-viewset schema is a schema consisting of multiple sets of views independent of each other. Views belonging to different viewsets cannot be joined together in a single SQL statement.

This property can be used to enumerate all viewsets (sub-schemas) in a schema.

See Also

MainViewCount property

MainViewName property

Modifying Schema and Field List at Run Time


ManualRender Property

Syntax

C1QueryFrame.ManualRender = boolean

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property is False by default. Setting it to True enables the C1Qrender() script. In this case, rendering HTML for display on the control surface is performed not by the C1QueryFrame control itself, but by the C1Qrender() script.

Set this property to True if you want to customize user interface with your own rendering script. See Customizing UI with Scripts for details.


MaxNameLength Property

Syntax

C1Query.SQLInfo.MaxNameLength = Long

Notes

Read/Write at run time. Unavailable at design time.
Property applies to SQLInfo object.

Description

This property returns/sets the maximum identifier length allowed by the target database.

See Also

SQL Syntax Properties


NameSubstitute Property

Syntax

C1Query.NameSubstitute (index)

Notes

Read/Write at run time and design time. Property applies to C1Query collection.

Description

Used as a substitute for the control's Name property in environments that don't support standard property such as Name or Id, for example, in VC++.

See Also

C1QueryFrame Control


ParentID Property

Syntax

C1QueryFrame.Item.ParentID

Notes

Read-only at run time. Unavailable at design time. Type: Long. Property applies to QueryItem object.

Description

This property returns the unique ID identifying the item’s parent in the query tree.

See Also

Accessing and Modifying Query Items


Precision Property

Syntax

Field.Precision

Description

This property returns the numeric precision (maximum number of digits used to represent values) of the database field represented by this Field object.

Notes

Read-only at run time. Unavailable at design time. Type: Long. Property applies to Field object.This property is not used in the current C1Query version.


RightFieldID Property

Syntax

C1QueryFrame.Item.RightFieldID = long

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property returns/set the unique id identifying the folder field on the right side of an advanced elementary condition item. To access the corresponding Field object and its properties, use the RightSideField property.

See Also

Accessing and Modifying Query Items


RightSide Property

Syntax

C1QueryFrame.Item.RightSide = string

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property returns/set the text on the right side of an item.

Changing the RightSide property has no effect on the actual value (or field, in case of an advanced condition item) specified in the item, which is determined by the RightFieldID property. This can be used to customize texts on display.

See Also

Accessing and Modifying Query Items


RightSideField Property

Syntax

C1QueryFrame.Item.LeftField

Notes

Read-only at run time. Unavailable at design time. Type: Field. Property applies to QueryItem object.

Description

This property is only applicable to advanced elementary condition items (simple elementary conditions have a constant, not a field on the left side). If RightSideKind=c1qField, this property returns the Field object representing the folder field on the right side of an advanced elementary condition item.

The text shown on the right side can differ from the actual field name, which allows customization of display texts, see RightSide property.

See Also

Accessing and Modifying Query Items


RightSideKind Property

Syntax

C1QueryFrame.Item.RightSideKind = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Values

Constant Value and Name | Meaning
1 – c1qConstant | Constant value
2 – c1qField | Field

Description

This property is only applicable to advanced elementary condition items. It determines whether the right side of the item is a constant (c1qConstant) or a field (c1qField).

See Also

Accessing and Modifying Query Items


RightSideValue Property

Syntax

C1QueryFrame.Item.RightSideValue = Variant

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Description

This property returns/set the value on the right side of a simple elementary condition item or an advanced elementary condition item with RightSideKind=c1qConstant.

The text shown on the right side can differ from the actual value, which allows customization of display texts, see RightSide property.

See Also

Accessing and Modifying Query Items


SaveSchemaAsString Property

Syntax

C1Query.SaveSchemaAsString = boolean

Notes

Read/Write at design time. Unavailable at run time. Property applies to C1Query control.

Description

This property is False by default.

By default, schema is saved in a binary format in the form file. Some containers do not support binary format saving/restoring control properties. One of such containers is Microsoft Visual InterDev. Storing schema in a binary format crashes Visual InterDev. To use C1Query in containers that do not support binary properties, set this property to True in every newly created C1Query control.


Schema Property

Syntax

C1Query.Schema = string

Notes

Read/Write at run time and design time. Property applies to C1Query control.

Description

This property defines the schema stored in the C1Query control.

At design time, the schema is specified using the Schema Designer.

At run time, you can read the contents of a text file containing a C1Query schema (schema can be saved in a file in schema designer), or download the string representing a schema from the Internet, or obtain the schema string in any other convenient way (for example, you can store various schemas in a single XML file), and assign that string to the Schema property.

To load schema directly from a disk file, call the LoadSchemaFromFile method.


SchemaControl Property

Syntax

C1QueryFrame.SchemaControl = string

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property specifies the name of a C1Query control associated with the C1QueryFrame control. In order to make the C1QueryFrame control functional, you need to set this property to the name of a C1Query control residing on the same form.

See Also

C1QueryFrame Control.


SchemaControlObject Property

Syntax

Set C1QueryFrame.Schema = control

Notes

Read/Write at run time. Unavailable at design time. Property applies to C1QueryFrame control.

Description

This property can be used at run time to associate the C1QueryFrame control with a C1Query control. If you cannot use the design-time association (the SchemaControl property), because the environment does not support such association (for example, using C1Query in Delphi), or if you need to change the association dynamically at run time, set this property to a C1Query control object in code.

See Also

C1QueryFrame Control


Size Property

Syntax

Field.Size

Description

This property returns the size, as a number of bytes, of the database field represented by this Field object.

Notes

Read-only at run time. Unavailable at design time. Type: Long. Property applies to Field object.This property is not used in the current C1Query version.


Sort Property

Syntax

C1QueryFrame.Item.Sort = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to QueryItem object.

Values

Constant Value and Name | Meaning
0 – c1qSortNone | No sort
1 – c1qSortAscending | Ascending sort order
2 – c1qSortDescending | Descending sort order

Description

This property is only applicable to result field items. It returns/sets the sort defined for the result field.

See Also

Accessing and Modifying Query Items


SQL Property

Syntax

C1Query.SQL

Notes

Read-only at run time. Type: String. Property applies to C1Query control.

Description

This property returns the SQL statement generated by the last BuildSQL call.

See Also

Using C1Query Control to Generate SQL


SQLInfo Property

Syntax

C1Query.SQLInfo

Notes

Read-only at run time. Unavailable at design time. Property applies to C1QueryFrame control.

Description

This property returns the SQLInfo object used programmatically to specify various properties affecting the syntax and composition of generated SQL. Typically, this property is used to adjust to the target database requirements, see Database-Dependent Aspects of SQL Generation.


StringLiteralQuote Property

Syntax

C1Query.SQLInfo.StringLiteralQuote = value

Notes

Read/Write at run time. Unavailable at design time.
Property applies to SQLInfo object.

Values

Constant Value and Name | Meaning
1 – c1qQuoteSingle | ‘…’
2 – c1qQuoteDouble | “…”

Description

This property sets/returns the quotation mark used with string literals (constants).

See Also

SQL Syntax Properties


Syntax Property

Syntax

C1Query.SQLInfo.Syntax = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Values

Constant Value and Name | Meaning
0 – c1qSQL2 | SQL2 standard: JOIN keyword supported
1 – c1qSQL1 | SQL1 standard: no JOIN, no outer joins
2 – c1qOracle | Oracle dialect: no JOIN, outer join supported

Description

This property sets/returns the SQL dialect of the target database.

See Also

SQL Syntax Properties


TabInQuery Property

Syntax

Set C1QueryFrame.TabInQuery = boolean

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

If this property is set to False (default), the Tab key is used in its usual function: to navigate between controls.

If this property is set to True, the Tab key navigates between elements of a query item, inside the C1QueryFrame control.

See Also

C1QueryFrame Control


TableName Property

Syntax

Field.TableName

Notes

Read-only at run time. Unavailable at design time. Type: String. Property applies to Field object.

Description

This property returns the table name of the view field represented by the Field object.

See Also

Folders

Views


TableQuote Property

Syntax

C1Query.SQLInfo.TableQuote = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Values

Constant Value and Name | Meaning
0 – c1qQuoteNone | No quotation
1 – c1qQuoteSingle | ‘…’
2 – c1qQuoteDouble | “…”
3 – c1qQuoteBrackets | […]
4 – c1qQuoteSharp | #…#

Description

This property sets/returns the quotation mark used to escape table names containing special characters.

See Also

TableQuoteCriteria property

SQL Syntax Properties


TableQuoteCriteria Property

Syntax

C1Query.SQLInfo.TableQuoteCriteria = value

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Values

This property can be a combination (sum) of the following values (including 0, meaning that quotation is never applied),

Constant Value and Name | Meaning
1 – c1qQuoteBlanks | Quote if there are blanks in the name
2 – c1qQuoteNonAlpha | Quote if there are non-alphanumeric characters in the name
4 – c1qQuoteExtendedASCII | Quote if there are extended ASCII (non-English) characters in the name
8 – c1qQuoteAlways | Quote always

Description

This property determines the criteria when table names must be quoted. Default: c1qQuoteBlanks + c1qQuoteNonAlpha.

See Also

TableQuote property

SQL Syntax Properties


Tag Property (Field)

Stores arbitrary additional information for the field.

Syntax

object.Tag = string

Remarks

This string property can be used to store arbitrary additional information associated with the field. It can be set for folder fields in Schema Designer at design time and retrieved (and changed) at run time as Field.Tag.

See Also

Field Object


Tag Property (QueryItem)

Stores arbitrary additional information for the field.

Syntax

object.Tag = string

Remarks

It can be used to store arbitrary additional information associated with query items. This property is persisted along with other QueryItem properties by C1QueryFrame SaveToXML/LoadFromXML methods.

See Also

QueryItem Object


TemplateAttributes Property

Syntax

C1QueryFrame.TemplateAttributes(Index)= boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to C1QueryFrame control.

Argument

Index – template attribute name, or a string of the form “Functions:<id>” or “Comparisons:<id>”, where id is an integer id identifying a function or a comparison.

Description

This property allows to get or set a template attribute, see Customizing UI with Templates. Use attribute name as an index to this array property. For attributes with sub-attributes, such as Comparison and Function Attributes, add colon and the attribute id (the id of a function or comparison).

Setting this property produces the same effect as calling the SetTemplateAttribute method.

See Also

Customizing UI with Templates

Comparison and Function Attributes

Custom Functions

Custom Comparison Operators


Templates Property

Syntax

C1QueryFrame.Templates = string

Notes

Read/Write at run time and design time. Property applies to C1QueryFrame control.

Description

This property defines the template attributes stored in the C1QueryFrame control. Template attributes are used to customize C1QueryFrame user interface, see Customizing User Interface.

At design time, the templates can be imported from a text file, see Customizing UI with Templates.

At run time, you can read the contents of a text file containing C1QueryFrame templates, or download a string with template attributes from the Internet, or obtain it in any other convenient way, and assign that string to the Templates property.

To load templates directly from a disk file, call the LoadTemplatesFromFile method.

To change specific template attributes at run time without affecting other attributes, call the SetTemplateAttribute method.


TemplateUserData Property

Syntax

collection.TemplateUserData (index)

Notes

Property applies to C1QueryFrame control. Read/Write at run time. Unavailable at design time.

Arguments

index is a string expression

Return Value

String

Description

The TemplateUserData indexed property is used at run time to specify strings that must be substituted instead of special C1Q_USERDATA tags in templates, see Modifying templates at run time.


Type Property

Syntax

Field.Type

Notes

Read-only at run time. Unavailable at design time. Return type: enumeration (see below). Property applies to Field object. See OLE DB or ADO documentation for detailed description of these data types.

Description

This property returns the data type of the database field represented by this Field object.

Possible values of this property are the data types defined in OLE DB and ADO:

c1qTypeI2 = 2 | Integer 16 bit
c1qTypeI4 = 3 | Integer 32 bit
c1qTypeR4 = 4 | Real 32 bit
c1qTypeR8 = 5 | Real 64 bit
c1qTypeCurrency = 6 | Currency
c1qTypeDateTime = 7 | Date
c1qTypeBSTR = 8 | String variable length
c1qTypeBool = 11 | Boolean
c1qTypeVariant = 12 | Variant
c1qTypeDecimal = 14 | Decimal
c1qTypeI1 = 16 | Integer 8 bit
c1qTypeUI1 = 17 | Unsigned integer 8 bit
c1qTypeUI2 = 18 | Unsigned integer 16 bit
c1qTypeUI4 = 19 | Unsigned integer 32 bit
c1qTypeI8 = 20 | Integer 64 bit
c1qTypeUI8 = 21 | Unsigned integer 64 bit
c1qTypeGUID = 72 | GUID
c1qTypeString = 129 | String fixed length
c1qTypeWideString = 130 | Wide string fixed length
c1qTypeNumeric = 131 | Numeric
c1qTypeDate = 133 | DB Date
c1qTypeTime = 134 | DB Time
c1qTypeTimeStamp = 135 | Time stamp
c1qTypeFileTime = 64 | File time
c1qTypeDBFileTime = 137 | DB file time


TypedEditing Property

Syntax

collection.TypedEditing = boolean

Notes

Property applies to C1QueryFrame control. Read/Write at run time and design time.

Description

If this property is set to True (default), C1QueryFrame uses special editors for different data types, such as date-time picker with dropdown calendar for date/time, combo box for boolean, etc.

If this property is set to False, regular edit box is used for editing all values, unless the programmer specifies custom editing or lookup.

See Also

Custom Editing and Lookup


UseFieldAliasInGroupBy Property

Syntax

C1Query.SQLInfo.UseFieldAliasInGroupBy = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

Specifies whether the SQL dialect supported by the target database allows using aliases in GROUP BY instead of full expressions, as in

SELECT …, A + B AS S,… FROM … GROUP BY S

If this property is set to True, a calculated field (expression) can be represented in GROUP BY by its alias.

If this property is set to False, the full expression must be used in GROUP BY.

See Also

SQL Syntax Properties


UseFieldAliasInOrderBy Property

Syntax

C1Query.SQLInfo.UseFieldAliasInOrderBy = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

Specifies whether the SQL dialect supported by the target database allows using aliases in ORDER BY instead of full expressions, as in

SELECT …, A + B AS S,… FROM … ORDER BY S

If this property is set to True, a calculated field (expression) can be represented in ORDER BY by its alias.

If this property is set to False, the full expression or index (see UseIndexInOrderBy property) must be used in ORDER BY.

See Also

SQL Syntax Properties


UseFieldAliasInWhere Property

Syntax

C1Query.SQLInfo.UseFieldAliasInWhere = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

Specifies whether the SQL dialect supported by the target database allows using aliases in WHERE instead of full expressions, as in

SELECT …, A + B AS S,… FROM … WHERE S > 10

If this property is set to True, a calculated field (expression) can be represented in WHERE by its alias.

If this property is set to False, the full expression must be used in WHERE.

See Also

SQL Syntax Properties


UseIndexInOrderBy Property

Syntax

C1Query.SQLInfo.UseIndexInOrderBy = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

Specifies whether the SQL dialect supported by the target database allows using names in ORDER BY, as in

SELECT A, B FROM … ORDER BY A, B

or it requires ordinal positions, indexes, as in

SELECT A, B FROM … ORDER BY 1, 2

If this property is set to True, names can be used in ORDER BY.

If this property is set to False, numeric indexes must be used.

See Also

SQL Syntax Properties


UseNameAsFieldAlias Property

Syntax

C1Query.SQLInfo.UseNameAsFieldAlias = boolean

Notes

Read/Write at run time. Unavailable at design time. Property applies to SQLInfo object.

Description

If this property is set to True (default), folder field’s Name is used as its alias in SELECT.

If this property is set to False, fields appear in SELECT with their database names only.

See Also

SQL Syntax Properties

Folders


ViewFieldName Property

Syntax

Field.ViewFieldName

Notes

Read-only at run time. Unavailable at design time. Type: String. Property applies to Field object.

Description

This property returns the name of the view field represented by the Field object.

See Also

Folders

Views


ViewName Property

Syntax

Field.ViewName

Notes

Read-only at run time. Unavailable at design time. Type: String. Property applies to Field object.

Description

This property returns the view name of the view field represented by the Field object.

See Also

Folders

Views


Wrap Property

Syntax

collection.Wrap = boolean

Notes

Property applies to C1QueryFrame control. Read/Write at run time. Unavailable at design time.

Description

This property is used only in C1QRender() script when ManualRender=True, see Customizing UI with Scripts. It enables/disables wordwrap in the control.

This property is False by default, wordrap is disabled, and the control shows a horizontal scrollbar when text overflows its width. Set this property to True in your C1QRender() script if you need to override this behavior, enable wordwrap. See Tutorial 7 for example.

See Also

Custom Editing and Lookup


Event Reference


Quick Reference for All Events

AfterEdit | Occurs after a constant value has been modified by the user.
AfterMenu | Occurs after a menu item has been chosen from a menu.
AfterRender | Occurs when rendering is completed after change or Render call.
BeforeEdit | Occurs before editing a constant.
BeforeMenu | Occurs before a menu is opened.
BeforeSQLGeneration | Occurs before SQL generation and allows to change query items and syntax rules affecting resulting SQL.
BeforeSQLGeneration | Occurs before SQL generation and allows to change query items and syntax rules affecting resulting SQL.
Change | Occurs when an item element has been modified by the user.
Click | Occurs when the user presses and then releases a mouse button over the control.
DblClick | Occurs when the user doubleclicks the control with the mouse.
EndEdit | Occurs on closing an editor.
Error | Occurs as a result of an error condition.
FormatLiteral | Occurs before inserting a literal value in SQL statement.
HideCustomEditor | Occurs when a custom editor is being hidden.
ItemFocusChange | Occurs after a different item and/or item element becomes current.
KeyDown | Occurs when the user presses a key.
KeyPress | Occurs when the user presses and releases an ANSI key.
KeyUp | Occurs when the user releases a key.
LookupValues | Occurs before showing the lookup list for a field.
MenuSelected | Occurs when a menu item is selected.
MouseDown | Occurs when a mouse button is pressed.
MouseMove | Occurs when the mouse pointer is moved across the control.
MouseUp | Occurs when the user releases the mouse button.
ShowCustomEditor | Occurs when a custom editor is being activated.
SQLGenerationItem | Occurs before an item is included into the resulting SQL statement.

AfterEdit Event

AfterMenu Event

AfterRender Event

BeforeEdit Event

BeforeMenu Event

BeforeSQLGeneration Event (C1Query)

BeforeSQLGeneration Event (C1QueryFrame)

Change Event

Click Event

DblClick Event

EndEdit Event

Error Event

FormatLiteral Event

HideCustomEditor Event

ItemFocusChange Event

KeyDown Event

KeyPress Event

KeyUp Event

LookupValues Event

ShowCustomEditor Event

MenuSelected Event

MouseDown Event

MouseMove Event

MouseUp Event

SQLGenerationItem Event


AfterEdit Event

Syntax

C1QueryFrame_AfterEdit ()

Arguments

None

Description

The AfterEdit event occurs after a constant value has been modified by the user. This event can be used to perform actions on query change.

See Also

Events on changing a query item


AfterMenu Event

Syntax

C1QueryFrame_AfterMenu (MenuType As MenuTypeEnum)

Arguments

MenuType specifies the menu that has been used for user selection. It is one of the following values:

Constant Value and Name

0 – c1qMenuMain
1 – c1qMenuConnective
2 – c1qMenuComparison
3 – c1qMenuFields
4 – c1qMenuSort
5 – c1qMenuFunction
6 – c1qMenuKind

Description

The AfterMenu event occurs after a menu item has been chosen from a menu. This event can be used to perform actions on query change.

See Also

Events on changing a query item


AfterRender Event

Syntax

C1QueryFrame_AfterRender ()

Arguments

None

Description

The AfterRender event occurs each time when rendering is completed and the control contents is displayed on the control’s surface. It happens at startup, after every change made by the end user, and after every Render call.

This event is necessary mainly because the Render method works asynchronously: when you call Render, it returns immediately without actually repainting the control’s surface. If you need to perform some action after the control has been repainted, use the AfterRender event.

See Also

Events on changing a query item


BeforeEdit Event

Syntax

C1QueryFrame_BeforeEdit (Field As Field, Value, ValueText As String, ModalEditing As Boolean, ShowCustomEditor As Boolean, TypedEditing As Boolean, ControlWidth As Double, ControlHeight As Double)

Arguments

Field is the Field object describing the field whose constant value is about to be edited.

Value is the value of the constant, stored in the query item, as it is before editing.

ValueText is the textual representation of the constant, displayed in the query item, as it is before editing. You can change this argument in your event procedure, setting it to a string that you want to show up in the editor.

ModalEditing is set to False on entering the event procedure. You can set it to True to indicate that you perform Modal Editing. In this case, you show a dialog box, a modal form or a menu in your event code, and modify the query item in the EndEdit event. See Modal Editing for details.

ShowCustomEditor is set to False on entering the event procedure. If you leave the event procedure without setting it to True, C1QueryFrame uses Default Editing (typed editing, according to the field’s data type), or just shows the standard edit box, depending on the value of the TypedEditing argument. If you set ShowCustomEditor to True, C1QueryFrame starts the process of Custom Editing triggering the ShowCustomEditor event.

TypedEditing is set to True on entering the event procedure. If you leave the event procedure without setting it to False, and don’t set ShowCustomEditor and ModalEditing, C1QueryFrame uses typed editing, a specialized editor according to the field’s data type, see Default Editing for details. If you set TypedEditing to False, C1QueryFrame uses the standard edit box to edit the value, regardless of the data type.

ControlWidth, ControlHeight are set to 0 on entering the event procedure. You can set these arguments to any desired values, if you want to specify the width and height of the editor. This works for all kinds of editing: Default Editing (both Typed Editing and the standard edit box) and Custom Editing. The difference is only that in default editing setting ControlWidth/ControlHeight is optional, C1QueryFrame uses reasonable defaults if they are not set, whereas in custom editing, setting these arguments is mandatory.

Description

The BeforeEdit event occurs when the user starts editing a constant value. This event gives the programmer an opportunity to change some aspects of the editing process, or completely override the standard editing with Modal Editing or Custom Editing.

If you do not need modal or custom editing, you can still influence certain aspects of the standard editing process setting the ValueText, TypedEditing and ControlWidth/ControlHeight arguments.

To implement modal editing, set ModalEditing to True.

To implement custom editing, set CustomEditing to True.

See Also

Custom Editing and Lookup


BeforeMenu Event

Syntax

C1QueryFrame_BeforeMenu (MenuType As MenuTypeEnum, ShowCustomMenu As Boolean, X As Double, Y As Double)

Arguments

MenuType specifies the menu that has been used for user selection. It is one of the following values:

Constant Value and Name

0 – c1qMenuMain
1 – c1qMenuConnective
2 – c1qMenuComparison
3 – c1qMenuFields
4 – c1qMenuSort
5 – c1qMenuFunction
6 – c1qMenuKind

ShowCustomMenu is a boolean value that is set to False when the event is triggered. You can set it to true in you event procedure to override the default menu. If you set ShowCustomMenu to True, your event procedure can open its own menu or a dialog box. In this case you perform all necessary changes to the query item in code, when your menu or dialog is closed, see Accessing and Modifying Query Items.

X, Y are the screen coordinates where the menu is about to be shown. If you set ShowCustomMenu to True, you can use these coordinates to show your own menu or dialog.

Description

The BeforeMenu event occurs after a menu item has been chosen from a menu. This event can be used to perform actions on query change.

See Also

Events on changing a query item


BeforeSQLGeneration Event (C1Query)

Syntax

C1Query_BeforeSQLGeneration ()

Arguments

None

Description

This event occurs when BuildSQL method is called. The BeforeSQLGeneration event is triggered in a C1Query control after BeforeSQLGeneration in C1QueryFrame controls attached to it

The purpose of this event is to allow developers to change query items and syntax rules affecting the resulting SQL.

See Also

Changing Query Items for the Duration of SQL Generation


BeforeSQLGeneration Event (C1QueryFrame)

Syntax

C1QueryFrame_BeforeSQLGeneration ()

Arguments

None

Description

This event occurs when BuildSQL method is called. The BeforeSQLGeneration event in C1QueryFrame controls is triggered before SQLGenerationItem events (triggered for each query item) and before BeforeSQLGeneration in C1Query control to which they are attached.

The purpose of this event is to allow developers to change query items and syntax rules affecting the resulting SQL.

See Also

Changing Query Items for the Duration of SQL Generation


Change Event

Syntax

C1QueryFrame_Change ()

Arguments

None

Description

This event occurs after every change made by the end user in a C1QueryFrame control: field selection, comparison selection, value editing, etc.

See Also

Events on changing a query item


Click Event

Syntax

C1QueryFrame_Click ()

Arguments

None

Description

The Click event occurs when the user presses then releases a mouse button over the control. Clicking the control also generates MouseDown and MouseUp events in addition to the Click event. The order of events is MouseDown, MouseUp, and Click.


DblClick Event

Syntax

C1QueryFrame_CDblClick ()

Arguments

None

Description

The DblClick event occurs when the user presses then releases a mouse button twice in rapid succession over the control.

Double clicking the control also generates MouseDown, MouseUp, and Click events in addition to the DblClick event. The order of events is MouseDown, MouseUp, Click, DblClick, and MouseUp.


EndEdit Event

Syntax

C1QueryFrame_EndEdit (Field As Field, Value, ValueText As String)

Arguments

Field is the Field object describing the field whose constant value is about to be edited.

Value is the modified value of the constant, stored in the query item. On entering the event procedure, it is set to the value entered by the end user in the editor. You can set this argument to any desired value to modify the editing result.

ValueText is the modified textual representation of the constant, displayed in the query item. On entering the event procedure, it is set to the text entered by the end user in the editor. You can set this argument to any desired value to modify the edited text. This string can differ from the standard textual representation of the Value argument, if you want to show a custom text without affecting the value itself.

Description

The EndEdit event occurs before ending the editing process, before the editor is hidden. It occurs in all kinds of editing: Default Editing (both Typed Editing and the standard edit box), Modal Editing and Custom Editing.

This event gives the programmer an opportunity to modify the value entered by the end user, setting the Value and ValueText arguments. One of the main applications of this event is correcting end user errors. If the end user entered a value that cannot be converted to the Field’s data type (for example, if ValueText contains letters and the data type is numeric), you can set Value and ValueText to correct the error. If the error is not corrected, the Error event is fired after EndEdit.

See Also

Custom Editing and Lookup


Error Event

Syntax

control_Error (ErrorNumber As Long, Description As String, CancelDisplay As Boolean)

Notes

Event applies to both C1Query and C1QueryFrame control.

Arguments

ErrorNumber is the error code identifying the error condition, see Error Codes.

Description is the error message text. You can change the error message text setting this argument.

CancelDisplay is set to false on entering the event procedure. Setting it to True prevents the control from showing the standard error message. Set this argument to True if you want to show your own message or just ignore the error.

Description

Errors occur under following circumstances:

Error in the value entered by the end user while editing a constant value. ErrorNumber: 501, Description: “Invalid data format”. The Error event is fired in the C1QueryFrame control.

Error in the end user query or schema detected while executing the BuildSQL method. Error conditions described in Error Codes belong to this category, if their description in Error Codes does not state otherwise. The Error event is fired in C1QueryFrame control if it is an error in the end user query, and in C1Query control for other errors.

Errors occurring during reading and writing files and other operations specified in Error Codes.

Using the Error event, you can change the Description shown in the standard error message box, or completely override the standard error handling (the error message box) by showing your own message or simply ignoring the error. To override the standard error message box, set the CancelDisplay argument to True.

See Also

Error Codes


FormatLiteral Event

Syntax

C1Query_FormatLiteral (Field As Field, Value, Text As String)

Arguments

Field is the Field object describing the field to which the constant value belongs. The field’s data type can be obtained from Field.Type.

Value is the constant value generating a literal in the SQL statement.

Text is the literal text. This argument can be set to a desired value if you want to specify the literal text programmatically.

Description

FormatLiteral event occurs before a literal value is inserted into SQL statement during SQL generation executing BuildSQL. It provides an opportunity to change the literal text, format it according to your database requirements or other considerations.

After this event, the literal text is enclosed in quotation marks if it is required by its data type. Quotation is performed for date/time and string data types. If you need to suppress the quotation, set StringLiteralQuote and/or DateTimeQuote properties of C1Query.SQLInfo to c1qQuoteNone (=0).

See Also

Database-Dependent Aspects of SQL Generation


HideCustomEditor Event

Syntax

C1QueryFrame_HideCustomEditor (Field As Field, ControlObj As Object, ControlHWND As Long)

Arguments

Field is the Field object describing the field whose constant value has been edited.

ControlObj is the custom editor control that you specified in BeforeEdit..

ControlHWND is the custom editor window handle that you specified in BeforeEdit.

Description

The HideCustomEditor event occurs in the end of custom editing process, after EndEdit. In response to this event you must hide your custom editor control setting its Visible property to False.

See Also

Custom Editing


ItemFocusChange Event

Syntax

C1QueryFrame_ItemFocusChange (FromItem As Long, FromItemElement As ElementTypeEnum, ToItem As Long, ToItemElement As ElementTypeEnum)

Arguments

FromItem is the unique item ID (see Item Navigation) identifying the item that had focus before focus change.

FromItemElement specifies which element in the FromItem item was current (in focus) before focus change. See the list of possible values in CurrentElement property of QueryItem object

ToItem is the unique item ID (see Item Navigation) identifying the item that received focus.

ToItemElement specifies which element in the ToItem has become current (received focus). See the list of possible values in CurrentElement property of QueryItem object

Description

The ItemFocusChange event occurs on focus changes, after a different item and/or item element becomes current.

See Also

Item Navigation


KeyDown Event

Syntax

C1QueryFrame_KeyDown (KeyCode As Long, Shift As Long)

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.

Description

The KeyDown (KeyUp) event occurs when the user presses (releases) a key.

See Also

KeyUp


KeyPress Event

Syntax

C1QueryFrame_KeyPress (KeyAscii As Long)

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.

Description

The KeyPress event occurs when the user presses and releases a printable keyboard character.


KeyUp Event

Syntax

C1QueryFrame_KeyUp (KeyCode As Long, Shift As Long)

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.

Description

The KeyDown (KeyUp) event occurs when the user presses (releases) a key.

See Also

KeyDown


LookupValues Event

Syntax

C1QueryFrame_LookupValues (Field As Field, Values, ValueCaptions, EditorType As EditorTypeEnum, ShowCaption As Boolean)

Arguments

Field is the Field object describing the field whose constant value is about to be edited by selecting from a list of values.

Values is an array of variant values. When the user selects a value (one of ValueCaptions strings), the corresponding value from the Values array is saved in the query item and later used in SQL generation.

ValueCaptions is the array of strings shown to the user in the combo box list or menu. The user selects one of these strings. Value and ValueCaptions must have the same dimensions, the same lower and upper bounds.

EditorType determines how the lookup list is presented to the end user

Constant Value and Name

Meaning

0 – c1qEditorMenu

The list is shown as a menu

1 – c1qEditorComboEditable

The list is shown in the list portion of a

combo box. The user can select from the

list, and it is also possible to type the value

directly in the edit box portion of the

combo.

2 – c1qEditorComboNoneditable

The list is shown in the list portion of a

combo box. The user can only select from

the list.

ShowCaption determines how the selected value is displayed in the query item. If ShowCaption =True, the control shows the ValueCaptions string. If ShowCaption =False, the Values value is shown in the control.

Description

The LookupValues event is fired before showing a lookup list when the end user starts editing a field with Use lookup values check box checked in the schema designer (in Folder Designer). It gives the programmer an opportunity to modify the lookup list specified in the schema, or to create a lookup list from scratch. To modify or create a lookup list, set the Values and ValueCaptions arguments. Setting the EditorType argument you can determine whether the list is shown in a combo box or in a menu.

See Also

Lookup Value Lists


ShowCustomEditor Event

Syntax

C1QueryFrame_ShowCustomEditor (Field As Field, Value, ValueText As String, ControlObj As Object, ControlHWND As Long)

Arguments

Field is the Field object describing the field whose constant value is about to be edited.

Value is the value of the constant, stored in the query item, as it is before editing.

ValueText is the textual representation of the constant, displayed in the query item, as it is before editing.

ControlObj is empty on entering the event procedure. You must set it to the control object that you want to use as your custom editor. Custom editor must always be a single control residing on the same form with your C1QueryFrame control. It must be a window control (have the hWnd property). If you want to use multiple controls (for example, an edit box and a spin button), put them inside a container control (for example, a PictureBox) and use the container as your custom editor.

ControlHWND is 0 on entering the event procedure. You must set it to the window handle of the control that you want to use as your custom editor. Usually, you can write ControlHWND = ControlObj.hWnd.

Description

The ShowCustomEditor event occurs immediately after the BeforeEdit event, if you set the CustomEditing argument to True in BeforeEdit.

In response to this event you must initialize your custom editor control with the value you want to display to the user, using Value and ValueText arguments, and show the custom editor control setting its Visible property to True.

You do not need to position the custom editor control. C1QueryFrame will automatically position it for in-place editing.

See Also

Custom Editing


MenuSelected Event

Syntax

C1QueryFrame_MenuSelected (Menu As MenuTypeEnum, Action As Long, Cancel As Boolean)

Arguments

Menu specifies the menu that has been used for user selection. It is one of the following values:

Constant Value and Name

0 – c1qMenuMain
1 – c1qMenuConnective
2 – c1qMenuComparison
3 – c1qMenuFields
4 – c1qMenuSort
5 – c1qMenuFunction
6 – c1qMenuKind

Action is a numeric identifier of the default action associated with the selected menu item. By default, Action is simply the 0-based index of the menu item in the menu. But it can be changed modifying the control’s templates, see Menu attributes in Customizing UI with Templates.

Cancel is set to False on entering the event procedure. Setting it to True prevents the control from performing the default menu action. Set this argument to True if you want to override default and perform your own action instead.

Description

This event occurs when the end user selects a menu item, before the AfterMenu event. It developers an opportunity to override default menu actions with their own actions.

See Also

Events on changing a query item


MouseDown Event

Syntax

C1QueryFrame_MouseDown (Button As Long, Shift As Long, X As Double, Y As Double)

C1QueryFrame_MouseUp (Button As Long, Shift As Long, X As Double, Y As Double)

C1QueryFrame_MouseMove (Button As Long, Shift As Long, X As Double, Y As Double)

Arguments

Button is a number that identifies the button that was pressed or released to cause the event. The Button argument is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

Shift is an integer that corresponds to the state of the Shift, Ctrl, and Alt keys when the button specified in the Button argument is pressed or released. A bit is set if the key is down. The Shift argument is a bit field with the least-significant bits corresponding to the Shift key (bit 0), the Ctrl key (bit 1), and the Alt key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For example, if both Ctrl and Alt are pressed, the value of Shift is 6.

X and Y are 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.

Description

Use a MouseDown or MouseUp event procedure to specify actions that will occur when a given mouse button is pressed or released. 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.

The MouseMove event is generated continually as the mouse pointer moves across the control.


MouseMove Event

Syntax

C1QueryFrame_MouseDown (Button As Long, Shift As Long, X As Double, Y As Double)

C1QueryFrame_MouseUp (Button As Long, Shift As Long, X As Double, Y As Double)

C1QueryFrame_MouseMove (Button As Long, Shift As Long, X As Double, Y As Double)

Arguments

Button is a number that identifies the button that was pressed or released to cause the event. The Button argument is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

Shift is an integer that corresponds to the state of the Shift, Ctrl, and Alt keys when the button specified in the Button argument is pressed or released. A bit is set if the key is down. The Shift argument is a bit field with the least-significant bits corresponding to the Shift key (bit 0), the Ctrl key (bit 1), and the Alt key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For example, if both Ctrl and Alt are pressed, the value of Shift is 6.

X and Y are 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.

Description

Use a MouseDown or MouseUp event procedure to specify actions that will occur when a given mouse button is pressed or released. 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.

The MouseMove event is generated continually as the mouse pointer moves across the control.


MouseUp Event

Syntax

C1QueryFrame_MouseDown (Button As Long, Shift As Long, X As Double, Y As Double)

C1QueryFrame_MouseUp (Button As Long, Shift As Long, X As Double, Y As Double)

C1QueryFrame_MouseMove (Button As Long, Shift As Long, X As Double, Y As Double)

Arguments

Button is a number that identifies the button that was pressed or released to cause the event. The Button argument is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

Shift is an integer that corresponds to the state of the Shift, Ctrl, and Alt keys when the button specified in the Button argument is pressed or released. A bit is set if the key is down. The Shift argument is a bit field with the least-significant bits corresponding to the Shift key (bit 0), the Ctrl key (bit 1), and the Alt key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For example, if both Ctrl and Alt are pressed, the value of Shift is 6.

X and Y are 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.

Description

Use a MouseDown or MouseUp event procedure to specify actions that will occur when a given mouse button is pressed or released. 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.

The MouseMove event is generated continually as the mouse pointer moves across the control.


SQLGenerationItem Event

Syntax

C1QueryFrame_SQLGenerationItem (ItemID As Long)

Arguments

ItemID is the id identifying a query item (see Accessing and Modifying Query Items about item ids).

Description

This event occurs when BuildSQL method is called. It is triggered for each query item in the C1QueryFrame control.

In this event, developers can modify properties of query items that affect SQL generation.

See Also

Changing Query Items for the Duration of SQL Generation


Method Reference


Quick Reference for All Methods

Add | Adds a new item to the collection
AddItem | Adds a new query item to the control
BuildSQL | Builds SQL statement
Clear | Removes all query items from the control
DeleteItem | Deletes a query item from the control
ExitEdit | Ends editing of a constant
FieldByID | Returns information about the folder field specified by its unique ID
FieldNameToFieldID | Returns the field's unique schema ID given the field name
FindByID | Positions the Item object on the item specified by its unique ID in the item tree
GenerateHTML | Generates HTML for an item. Used in C1QRender() script with ManualRender=True
GetItemIDAt | Returns the ID of the item at specified point coordinates (X,Y)
LoadFromXML | Loads query from a string
LoadFromXMLFile | Loads query from a file
LoadSchemaFromFile | Loads the schema from a file to the control
LoadTemplatesFromFile | Loads templates from a file
MoveToChild | Positions the Item object on the specified child item
MoveToFirstChild | Positions the Item object on the first child of the item on which it is currently positioned
MoveToNext | Positions the Item object on the next sibling of the item on which it is currently positioned
MoveToPrevious | Positions the Item object on the previous sibling of the item on which it is currently positioned
MoveToRoot | Positions the Item object on the root of the item tree
PerformMainMenuAction | Performs the action that would have been triggered by a main menu selection
Remove | Removes an existing item from the collection
Render | Renders the current state of the query items on the control surface
RetrieveFieldsFromDataSource | Retrieves the field list from DataSource to the Fields Collection, in data source mode
SaveToXML | Saves query to a string
SaveToXMLFile | Saves query to a file
ShowFolderFields | Shows or hides folders/fields in schema and field menu
SetCurrentElement | Makes an element current (selected) in the current item
SetLookup | Retrieves lookup list of values from a data source
SetTemplateAttribute | Modifies an attribute in HTML templates defining control's look and UI
StartEdit | Activates editing of the active item's selected element
VarTypeFromDataType | Returns the variant data type corresponding to a field data type
WrapHTML | Adds the enclosing tags to an HTML representing an item. Used in C1QRender() script with ManualRender=True

Add Method

AddItem Method

BuildSQL Method

Clear Method

DeleteItem Method

ExitEdit Method

FieldById Method

FieldNameToFieldID Method

FindByID Method

GenerateHTML Method

GetItemIDAt Method

LoadFromXML Method

LoadFromXMLFile Method

LoadSchemaFromFile Method

LoadTemplatesFromFile Method

MoveToChild Method

MoveToFirstChild Method

MoveToNext Method

MoveToPrevious Method

MoveToRoot Method

PerformMainMenuAction Method

Remove Method

Render Method

RetrieveFieldsFromDataSource Method

SaveToXML Method

SaveToXMLFile Method

ShowFolderFields Method

SetCurrentElement Method

SetLookup Method

SetTemplateAttribute Method

StartEdit Method

VarTypeFromDataType Method

WrapHTML Method


Add Method

Syntax

collection.Add (Index)

Notes

Method applies to DataSourceFields collection.

Arguments

Index is the integer ordinal position in the collection on which to place the newly created object.

Return Value

A reference to the newly created object.

Description

This method creates a new instance of the appropriate object, adds it to the collection, and returns it to the caller.

The newly created object’s properties have default values that you need to set in order to make the object useful. The newly created object is placed on the Index position in the collection, and all other items with collection indexes greater than or equal to Index are shifted up by 1 to create the place for the newly inserted item.

If Index is greater than or equal to Count (the number of items already in the collection), the new object is appended to the end of the collection.


AddItem Method

Syntax

C1QueryFrame.AddItem (ParentID, ConditionType)

Notes

Method applies to C1QueryFrame control.

Arguments

ParentID is unique ID of the parent item (0 for root).

ConditionType is one of the ConditionTypeEnum constants defining the type of the newly created item.

Return Value

The unique ID of the newly created item.

Description

This method creates a new query item and adds it to the C1QueryFrame control as the last child of the specified parent. To add an item to the root, specify ParentID=0.

Possible values of the ConditionType argument are:

c1qCondElementarySimple = 0 - elementary simple condition.

c1qCondElementaryAdvanced = 1 - elementary advanced condition.

c1qCondComplex = 2 - complex condition.

After adding, removing and modifying query items, you must call the Render method to update display.

See Also

Accessing and Modifying Query Items

Clear

DeleteItem


BuildSQL Method

Syntax

C1Query.BuildSQL

Notes

Method applies to C1Query control.

Arguments

None

Return Value

Boolean value: True if SQL generation was successful, False otherwise.

Description

This method generates an SQL statement based on the information entered in the user query in C1QueryFrame controls attached to the C1Query control, and on the schema stored in the C1Query control.

See Also

Generating SQL Statements


Clear Method

Syntax

C1QueryFrame.Clear

Notes

Method applies to C1QueryFrame control.

Arguments

None

Return Value

None

Description

This method clears the contents of a C1QueryFrame control, removes all query items from the control.

After adding, removing and modifying query items, you must call the Render method to update display.

See Also

Accessing and Modifying Query Items

AddItem

DeleteItem


DeleteItem Method

Syntax

C1QueryFrame.DeleteItem (ItemID)

Notes

Method applies to C1QueryFrame control.

Arguments

ItemID is the unique ID of the item to be deleted.

Return Value

Boolean value: True if ItemID identifies an existing item, False otherwise.

Description

This method removes the specified item and all its children from a C1QueryFrame control.

After adding, removing and modifying query items, you must call the Render method to update display.

See Also

Accessing and Modifying Query Items

Clear

AddItem


ExitEdit Method

Syntax

C1QueryFrame.ExitEdit (SetNewValue, Value, ValueText)

Notes

Method applies to C1QueryFrame control.

Arguments

SetNewValue is an optional boolean argument (default: False). If it is True, Value and ValueText arguments define the value and the text of the constant after editing.

Value is an optional variant argument (default: Empty). If SetNewValue=True, it defines the value of the constant after editing, the value used in generated SQL statement. If Value is Empty, the value is determined by the ValueText argument, converted to the corresponding field data type.

ValueText is an optional string argument (default: empty string). If SetNewValue=True, it defines the text of the constant shown in the control after editing. If ValueText is an empty string, the text is determined by the Value argument.

Return Value

Long value indicating the error code, Error Codes. 0, if there were errors. The only error possible in the current version is 501 - “Invalid data format.”

Description

If C1QueryFrame.Editing=False, this method does nothing. If Editing=True, this method ends editing of a constant value, closes the current editor. If SetNewValue=False, the new value and its textual representation is determined by user input in the editor. If SetNewValue=True, they are determined by the Value and ValueText arguments.

See Also

StartEdit method

Editing property

Custom Editing and Lookup


FieldById Method

Syntax

C1QueryFrame.FieldByID (FieldID)

Notes

Method applies to C1QueryFrame control.

Arguments

FieldID is the unique ID identifying a schema field. Field ID can be retrieved from a query item using the LeftFieldID and RightFieldID properties.

Return Value

A Field object describing the folder field identified by FieldID.

Description

This method is used to get information about a folder field when the field is identified by its ID, as in LeftFieldID/RightFieldID properties.

See Also

FieldNameToFieldID method

Accessing and Modifying Query Items

Folders


FieldNameToFieldID Method

Syntax

C1QueryFrame.FieldNameToFieldID (FullName)

Notes

Method applies to C1QueryFrame control.

Arguments

FullName is the full dot-separated name of a folder field in a C1Query schema. Includes the field’s Name and the folder name(s) to which this field belongs, see Folders.

Return Value

Long number, the ID uniquely identifying the field in the schema.

Description

Use this method to obtain the ID when you need a field’s ID to assign to or compare with LeftFieldID/RightFieldID properties.

See Also

LeftFieldID property

RightFieldID property

FindByID method

Accessing and Modifying Query Items

Folders


FindByID Method

Syntax

C1QueryFrame.Item.FindByID (ID)

Notes

Method applies to QueryItem object.

Arguments

ID is unique ID of a query item.

Return Value

None

Description

This method positions the Item object on the item specified by its unique ID in the item tree.

See Also

Accessing and Modifying Query Items


GenerateHTML Method

Syntax

C1QueryFrame.GenerateHtml (Text, Item)

Notes

Method applies to C1QueryFrame control.

Arguments

Text is an HTML text, possibly containing special C1Query tags, see Special tags.

Item is a QueryItem object defining the item context for tag substitution. The Item argument is always the same object passed to C1QRender() script as its argument. Passing the Item argument to this method, use item navigation methods to position the Item object, see Accessing and Modifying Query Items.

Return Value

HTML text where all special tags are substituted with their values in the item specified by the Item argument.

Description

This method is used exclusively in C1QRender() scripts, see Customizing UI with Scripts.

Using this method you can substitute special tags, denoting various item elements, with HTML texts used by C1Query to represent these elements. See Customizing UI with Scripts for details.

See Also

Tutorial 7 - Customizing the User Interface With Scripts


GetItemIDAt Method

Syntax

C1QueryFrame.GetItemIDAt (X, Y)

Notes

Method applies to C1QueryFrame control.

Arguments

X, Y are coordinates of a point in the control’s window (client coordinates).

Return Value

Long integer ID of a query item.

Description

This method returns the ID of the query item occupying point (X, Y). See Accessing and Modifying Query Items about item ID. If (X, Y) is not occupied by any item, the method returns –1.


LoadFromXML Method

Syntax

C1QueryFrame.LoadFromXML (XMLString)

Notes

Method applies to C1QueryFrame control.

Arguments

XMLString is a string defining a query, the contents of a C1QueryFrame controls. This string encodes the whole query, all its items. Since it has special format, you must use only strings obtained by a previous call to the SaveToXML method.

Return Value

None

Description

This method reads a query from its string representation and fills the C1QueryFrame control, creating all corresponding items. The previous contents of the C1QueryFrame control are cleared.

Using this method, you can restore queries saved as strings in a database, an XML file, or any other storage, see Maintaining, Saving and Restoring Queries.

After adding, removing and modifying query items, you must call the Render method to update display.

See Also

SaveToXML method

Maintaining, Saving and Restoring Queries


LoadFromXMLFile Method

Syntax

C1QueryFrame.LoadFromXMLFile (FileName)

Notes

Method applies to C1QueryFrame control.

Arguments

FileName specifies a text file. The file was created with a call to the SaveToXMLFile method.

Return Value

None

Description

This method reads a query from a text file and fills the C1QueryFrame control, creating all corresponding items. The previous contents of the C1QueryFrame control are cleared.

After adding, removing and modifying query items, you must call the Render method to update display.

See Also

SaveToXMLFile method

Maintaining, Saving and Restoring Queries


LoadSchemaFromFile Method

Syntax

C1Query.LoadSchemaFromFile (FileName)

Notes

Method applies to C1Query control.

Arguments

FileName specifies a text file obtained by saving a schema in Schema Designer.

Return Value

None

Description

This method replaces the schema currently stored in the control with the schema stored in a text file.

See Also

Modifying Schema and Field List at Run Time


LoadTemplatesFromFile Method

Syntax

C1QueryFrame.LoadTemplatesFromFile (FileName)

Notes

Method applies to C1QueryFrame control.

Arguments

FileName specifies a text file containing HTML styles and templates and other template attributes, see Customizing UI with Templates.

Return Value

None

Description

This method reads template attribute values from a file. Its effect at run time is equivalent with the effect of the Load Templates context menu item at design time.

See Also

Modifying templates at run time


MoveToChild Method

Syntax

C1QueryFrame.Item.MoveToChild (ParentID, ChildIndex)

Notes

Method applies to QueryItem object.

Arguments

ParentID specifies the id of the parent item (long integer).

ChildIndex (long integer) specifies the 0-based index of a child item in the parent.

Return Value

None

Description

This method positions the Item object on the child number ChildIndex in the parent item.

See Also

Accessing and Modifying Query Items


MoveToFirstChild Method

Syntax

C1QueryFrame.Item.MoveToFirstChild

Notes

Method applies to QueryItem object.

Arguments

None

Return Value

None

Description

This method positions the Item object on the first child of the item on which it is currently positioned. Before calling this method, test the HasChildren property to make sure children exist.

See Also

Accessing and Modifying Query Items


MoveToNext Method

Syntax

C1QueryFrame.Item.MoveToNext

Notes

Method applies to QueryItem object.

Arguments

None

Return Value

None

Description

This method positions the Item object on the next sibling of the item on which it is currently positioned. Before calling this method, test the HasNext property to make sure the current item is not the last in its parent.

See Also

Accessing and Modifying Query Items


MoveToPrevious Method

Syntax

C1QueryFrame.Item.MoveToPrevious

Notes

Method applies to QueryItem object.

Arguments

None

Return Value

None

Description

This method positions the Item object on the previous sibling of the item on which it is currently positioned. Before calling this method, test the HasPrevious property to make sure the current item is not the first in its parent.

See Also

Accessing and Modifying Query Items


MoveToRoot Method

Syntax

C1QueryFrame.Item.MoveToFirstChild

Notes

Method applies to QueryItem object.

Arguments

None

Return Value

None

Description

This method positions the Item object on the root of the item tree.

See Also

Accessing and Modifying Query Items


PerformMainMenuAction Method

Syntax

C1QueryFrame.PerformMainMenuAction (MainMenuItem)

Notes

Method applies to C1QueryFrame control.

Arguments

MainMenuItem specifies the action corresponding to one of the items of the controls’ main menu:

Constant Value and Name

Meaning

1 – c1qMenuAddElementary

Add a new elementary condition

2 – c1qMenuAddAdvanced

Add a new advanced elementary condition

3 – c1qMenuAddComplex

Add a new complex condition

4 – c1qMenuDeleteCurrent

Delete current condition

5 – c1qMenuAddResField

Add a new result field

6 – c1qMenuMoveForward

Move current condition forward

7 – c1qMenuMoveBackward

Move current condition backward

Return Value

None

Description

This method changes the control’s contents, adds, deletes and moves items programmatically, simulating menu selection.

After adding, removing and modifying query items, you must call the Render method to update display.

See Also

Accessing and Modifying Query Items


Remove Method

Syntax

collection.Remove (Index)

Notes

Method applies to DataSourceFields collections.

Arguments

Index is an index (zero-based integer ordinal position) in the collection.

Return Value

None

Description

Use the Remove method to delete a specific member of a collection.


Render Method

Syntax

C1QueryFrame.Render

Notes

Method applies to C1QueryFrame control.

Arguments

None

Return Value

None

Description

This method generates HTML and renders it on the control’s surface changing control display.

When the end user modifies the query by menu selection or constant value editing, the changes are reflected (rendered) on the control display surface automatically, you don’t need to call Render.

After modifying query items from code, programmatically, you need to call Render to update display. This allows you to avoid flickering, updating display after each separate change, while you are performing batch changes.

Make sure you call Render when you are done with programmatic changes. Failure to call Render leaves the control in an unstable state and causes unpredictable behavior.

See Also

Accessing and Modifying Query Items


RetrieveFieldsFromDataSource Method

Syntax

C1Query.RetrieveFieldsFromDataSource

Notes

Method applies to C1Query control.

Arguments

None

Return Value

None

Description

This method is used only in DataSource mode, see Simple Queries - DataSource Mode. It fills the DataSourceFields collection with the fields from the DataSource recordset. The previous contents of the collection is discarded.

You do not always have to call this method in DataSource mode. If the DataSourceFields collection is empty at startup time or on setting the DataSource property, the fields are retrieved from DataSource automatically. You need to cal RetrieveFieldsFromDataSource if you want to retrieve fields and then modify the collection, add, remove or rearrange fields.

See Also

Customizing the DataSourceFields collection.


SaveToXML Method

Syntax

C1QueryFrame.SaveToXML

Notes

Method applies to C1QueryFrame control.

Arguments

None

Return Value

String encoding the query, all its items, the contents of a C1QueryFrame control in a single string. Queries are encoded in XML form.

Description

This method is used to save a query in a single string that subsequently can be used to store the query in a database, in an XML file, or in any other storage.

See Also

LoadFromXML method

Maintaining, Saving and Restoring Queries


SaveToXMLFile Method

Syntax

C1QueryFrame.SaveToXMLFile (FileName)

Notes

Method applies to C1QueryFrame control.

Arguments

FileName specifies a text file.

Return Value

None

Description

This method saves a query in a text file. The query can later be restored using the LoadFromXMLFile method.

See Also

LoadFromXMLFile method

Maintaining, Saving and Restoring Queries


ShowFolderFields Method

Syntax

C1QueryFrame.ShowFolderFields (FolderPath, Show)

Notes

Method applies to C1Query control.

Arguments

FolderPath specifies a dot-separated name of a folder field or an entire folder in a C1Query schema. Includes the field’s Name and the folder name(s) to which this field belongs, see Folders.

Return Value

None

Description

This method allows to make separate fields or/and entire folders visible/invisible to attached C1QueryFrame controls at run time. Invisible fields and folders do not appear in field selection menus shown to the end user.

See Also

Modifying Schema and Field List at Run Time

Folders


SetCurrentElement Method

Syntax

C1QueryFrame.SetCurrentElement (Element)

Notes

Method applies to C1QueryFrame control.

Arguments

Element is an enumerated value specifying an element of a query item (left side, right side, comparison, etc). See the list of possible values in CurrentElement property of QueryItem object.

Return Value

None

Description

This method allows you to move the focus in the current query item programmatically. It moves focus to the element specified by the Element argument.

See Also

CurrentElement property of QueryItem


SetLookup Method

Syntax

C1QueryFrame.SetLookup (FullFieldName, DataSource, DataMember, ListField, ValueField, ShowListField, EditorType)

Notes

Method applies to C1QueryFrame control.

Arguments

FullFieldName is a string argument specifying the full dot-separated name of a folder field in a C1Query schema. Includes the field’s Name and the folder name(s) to which this field belongs, see Folders.

DataSource is an OLE DB/ADO data source to retrieve values from. It can be an ADO recordset, a ComponentOne True DataControl, a Visual Basic DataEnvironment, etc.

DataMember is a string argument specializing the DataSource argument, if necessary. Some data sources, such as Visual Basic DataEnvironment, support multiple recordsets. In this case, it is required to specify a non-empty DataMember to select a particular recordset. For DataEvironment, it is a command name.

ListField is a string argument specifying the name of a recordset field used as the source of values shown to the user in the combo box list or menu. The user selects one of the ListField values.

ValueField is a string argument specifying the name of a recordset field used as the source of the value that is saved in the query item when the user makes a selection. This value is later used in SQL generation.

ShowListField is a boolean argument that determines how the selected value is shown in the query item. If ShowListField=True, the control shows the ListField value. If ShowListField=False, the ValueField value is shown in the control.

EditorType is an enumerated value determining how the list is presented to the end user.

Constant Value and Name | Meaning
0 – c1qEditorMenu | The list is shown as a menu.
1 – c1qEditorComboEditable | The list is shown in the list portion of a combo box. The user can select from the list, and it is also possible to type the value directly in the edit box portion of the combo. This setting is available only if ValueField and ListField is the same field.
2 – c1qEditorComboNoneditable | The list is shown in the list portion of a combo box. The user can only select from the list.

Return Value

None

Description

This method retrieves a lookup list of values from a data source. After SetLookup call, values for the specified field (FullFieldName argument) become editable with selection of options (lookup list) in a combo box or menu, see Lookup Value Lists. The EditorType argument determines if it is a combo box or a menu.

Values are retrieved from the DataSource recordset (with optional DataMember specialization, if necessary). Values shown in the list are taken from the ListField recordset field. When the user makes a selection, the ValueField recordset field value is saved in the query item, to be used in SQL generation. Depending on the ShowListField argument, the string shown in the item after selection can be the ListField value (if ShowListField=True) or the ValueField value (if ShowListField=False).

This method is a “shortcut”, it helps you to specify lookup lists in one of the most common cases, when you have a lookup table in a database. In other cases, or if you need more control, use the LookupValues event.

See Also

Lookup Value Lists


SetTemplateAttribute Method

Syntax

C1QueryFrame.SetTemplateAttribute (AttributeName, AttributeValue)

Notes

Method applies to C1QueryFrame control.

Arguments

AttributeName is a string specifying the name of a template attribute to be changed programmatically. See Customizing UI with Templates about template attributes.

AttributeValue is a string specifying the new attribute value.

Return Value

None

Description

This method allows you to modify template attributes controlling C1QueryFrame display presentation.

After modifying template attributes from code, you need to call Render to update display.

See Also

Modifying templates at run time


StartEdit Method

Syntax

C1QueryFrame.StartEdit

Notes

Method applies to C1QueryFrame control.

Arguments

None

Return Value

None

Description

This method starts editing of the current element in the current query item. If you need to position to a particular query item element before editing, use the SetCurrentElement method.

See Also

Custom Editing and Lookup


VarTypeFromDataType Method

Syntax

C1QueryFrame.VarTypeFromDataType (DataType)

Notes

Method applies to C1QueryFrame control.

Arguments

DataType is a long number representing an ADO/OLE DB data type. See Field.Type for the list of all possible data types.

Return Value

The method returns one of variant data types, such as vbString, vbLong, vbDate, etc, corresponding to DataType.

Description

C1Query uses ADO/OLE DB data types (see Field.Type), which include variant data types customary to a Visual Basic programmer, but they also include other types. ADO/OLE DB type system is richer, allows finer type distinctions than the system of variant types, such as vbString(=8), vbDate(=7), etc.

If you need to find a variant type that can be used to represent an ADO/OLE DB data type, use this method.


WrapHTML Method

Syntax

C1QueryFrame.WrapHtml (Text, Item, LineBreak)

Notes

Method applies to C1QueryFrame control.

Arguments

Text is an HTML text generated from a query item, usually produced by the GenerateHTML method.

Item is a QueryItem object defining the item context. The Item argument is always the same object passed to C1QRender() script as its argument. Passing the Item argument to this method, use item navigation methods to position the Item object, see Accessing and Modifying Query Items.

LineBreak is a boolean argument specifying whether the resulting HTML starts a new line. If LineBreak=True, a <DIV> tag is used to enclose the HTML text, otherwise, a <SPAN> tag is used.

Return Value

HTML text representing an item, enclosed in <DIV> or <SPAN> tags according to the rules required by C1QueryFrame scripts, complete with special id and style.

Description

This method is used exclusively in C1QRender() scripts, see Customizing UI with Scripts.

You must use this method to ensure that your HTML text representing an item follows the rules required by C1QueryFrame. Calling this method encloses the item in <DIV> or <SPAN>, complete with special id and style required by C1QueryFrame.

Usually, this method is called immediately after calling GenerateHTML.

See Also

Tutorial 7 - Customizing the User Interface With Scripts